utils | Foundry Virtual Tabletop - API Documentation

Utility functions providing helpful functionality.

Functions

orient2dFast

orient2dFast(a: Point, b: Point, c: Point): number

Determine the relative orientation of three points in two-dimensional space. The result is also an approximation of twice the signed area of the triangle defined by the three points. This method is fast - but not robust against issues of floating point precision. Best used with integer coordinates. Adapted from https://github.com/mourner/robust-predicates

memberof
helpers

Parameters
- a: Point
  
  An endpoint of segment AB, relative to which point C is tested
- b: Point
  
  An endpoint of segment AB, relative to which point C is tested
- c: Point
  
  A point that is tested relative to segment AB
Returns number
The relative orientation of points A, B, and C A positive value if the points are in counter-clockwise order (C lies to the left of AB) A negative value if the points are in clockwise order (C lies to the right of AB) Zero if the points A, B, and C are collinear.

lineSegmentIntersects

lineSegmentIntersects(a: Point, b: Point, c: Point, d: Point): boolean

Quickly test whether the line segment AB intersects with the line segment CD. This method does not determine the point of intersection, for that use lineLineIntersection

memberof
helpers

Parameters
- a: Point
  
  The first endpoint of segment AB
- b: Point
  
  The second endpoint of segment AB
- c: Point
  
  The first endpoint of segment CD
- d: Point
  
  The second endpoint of segment CD
Returns boolean
Do the line segments intersect?

lineLineIntersection

lineLineIntersection(a: Point, b: Point, c: Point, d: Point, [options]?: { t1: boolean }): LineIntersection

An internal helper method for computing the intersection between two infinite-length lines. Adapted from http://paulbourke.net/geometry/pointlineplane/

memberof
helpers

Parameters
- a: Point
  
  The first endpoint of segment AB
- b: Point
  
  The second endpoint of segment AB
- c: Point
  
  The first endpoint of segment CD
- d: Point
  
  The second endpoint of segment CD
- [options]: { t1: boolean } = {}
  
  Options which affect the intersection test
  - t1: boolean
Returns LineIntersection
An intersection point, or null if no intersection occurred

lineSegmentIntersection

lineSegmentIntersection(a: Point, b: Point, c: Point, d: Point, epsilon?: number): LineIntersection

An internal helper method for computing the intersection between two finite line segments. Adapted from http://paulbourke.net/geometry/pointlineplane/

memberof
helpers

Parameters
- a: Point
  
  The first endpoint of segment AB
- b: Point
  
  The second endpoint of segment AB
- c: Point
  
  The first endpoint of segment CD
- d: Point
  
  The second endpoint of segment CD
- epsilon: number = 1e-8
Returns LineIntersection
An intersection point, or null if no intersection occurred

lineCircleIntersection

lineCircleIntersection(a: Point, b: Point, center: Point, radius: number, epsilon?: number): LineCircleIntersection

Determine the intersection between a candidate wall and the circular radius of the polygon.

memberof
helpers

Parameters
- a: Point
  
  The initial vertex of the candidate edge
- b: Point
  
  The second vertex of the candidate edge
- center: Point
  
  The center of the bounding circle
- radius: number
  
  The radius of the bounding circle
- epsilon: number = 1e-8
  
  A small tolerance for floating point precision
Returns LineCircleIntersection
The intersection of the segment AB with the circle

closestPointToSegment

closestPointToSegment(c: Point, a: Point, b: Point): Point

Identify the point closest to C on segment AB

memberof
helpers

Parameters
- c: Point
  
  The reference point C
- a: Point
  
  Point A on segment AB
- b: Point
  
  Point B on segment AB
Returns Point
The closest point to C on segment AB

quadraticIntersection

quadraticIntersection(p0: Point, p1: Point, center: Point, radius: number, epsilon?: number): { x: any; y: any }[]

Determine the points of intersection between a line segment (p0,p1) and a circle. There will be zero, one, or two intersections See https://math.stackexchange.com/a/311956

memberof
helpers

Parameters
- p0: Point
  
  The initial point of the line segment
- p1: Point
  
  The terminal point of the line segment
- center: Point
  
  The center of the circle
- radius: number
  
  The radius of the circle
- epsilon: number = 0
Returns { x: any; y: any }[]

benchmark

benchmark(func: Function, iterations: number, ...args: any[]): Promise<void>

Benchmark the performance of a function, calling it a requested number of iterations.

Parameters
- func: Function
  
  The function to benchmark
- iterations: number
  
  The number of iterations to test
- Rest ...args: any[]
  
  Additional arguments passed to the benchmarked function
Returns Promise<void>

threadLock

threadLock(ms: number, debug?: boolean): Promise<void>

A debugging function to test latency or timeouts by forcibly locking the thread for an amount of time.

Parameters
- ms: number
  
  A number of milliseconds to lock
- debug: boolean = false
Returns Promise<void>

debounce

debounce(callback: Function, delay: number): Function

Wrap a callback in a debounced timeout. Delay execution of the callback function until the function has not been called for delay milliseconds

Parameters
- callback: Function
  
  A function to execute once the debounced threshold has been passed
- delay: number
  
  An amount of time in milliseconds to delay
Returns Function
A wrapped function which can be called to debounce execution

deepClone

deepClone(original: any, [options]?: { strict: boolean }): any

Quickly clone a simple piece of data, returning a copy which can be mutated safely. This method DOES support recursive data structures containing inner objects or arrays. This method DOES NOT support advanced object types like Set, Map, or other specialized classes.

Parameters
- original: any
  
  Some sort of data
- [options]: { strict: boolean } = {}
  
  Options to configure the behaviour of deepClone
  - strict: boolean
Returns any
The clone of that data

diffObject

diffObject(original: any, other: any, [options={}]?: { inner: boolean; deletionKeys: boolean }): any

Deeply difference an object against some other, returning the update keys and values.

Parameters
- original: any
  
  An object comparing data against which to compare
- other: any
  
  An object containing potentially different data
- [options={}]: { inner: boolean; deletionKeys: boolean } = {}
  
  Additional options which configure the diff operation
  - inner: boolean
  - deletionKeys: boolean
Returns any
An object of the data in other which differs from that in original

objectsEqual

objectsEqual(a: any, b: any): boolean

Test if two objects contain the same enumerable keys and values.

Parameters
- a: any
  
  The first object.
- b: any
  
  The second object.
Returns boolean

duplicate

duplicate(original: any): any

A cheap data duplication trick which is relatively robust. For a subset of cases the deepClone function will offer better performance.

Parameters
- original: any
  
  Some sort of data
Returns any

isSubclass

isSubclass(cls: Function, parent: Function): boolean

Test whether some class is a subclass of a parent. Returns true if the classes are identical.

Parameters
- cls: Function
  
  The class to test
- parent: Function
  
  Some other class which may be a parent
Returns boolean
Is the class a subclass of the parent?

encodeURL

encodeURL(path: string): string

Encode a url-like string by replacing any characters which need encoding To reverse this encoding, the native decodeURIComponent can be used on the whole encoded string, without adjustment.

Parameters
- path: string
  
  A fully-qualified URL or url component (like a relative path)
Returns string
An encoded URL string

expandObject

expandObject(obj: any, _d?: number): any

Expand a flattened object to be a standard nested Object by converting all dot-notation keys to inner objects.

Parameters
- obj: any
  
  The object to expand
- _d: number = 0
Returns any
An expanded object

filterObject

filterObject(source: any, template: any, [options={}]?: { deletionKeys: boolean; templateValues: boolean }): any

Filter the contents of some source object using the structure of a template object. Only keys which exist in the template are preserved in the source object.
example
Filter an object
```
const source = {foo: {number: 1, name: "Tim", topping: "olives"}, bar: "baz"};
const template = {foo: {number: 0, name: "Mit", style: "bold"}, other: 72};
filterObject(source, template); // {foo: {number: 1, name: "Tim"}};
filterObject(source, template, {templateValues: true}); // {foo: {number: 0, name: "Mit"}};
```
Parameters
- source: any
  
  An object which contains the data you wish to filter
- template: any
  
  An object which contains the structure you wish to preserve
- [options={}]: { deletionKeys: boolean; templateValues: boolean } = {}
  
  Additional options which customize the filtration
  - deletionKeys: boolean
  - templateValues: boolean
Returns any

flattenObject

flattenObject(obj: any, _d?: number): any

Flatten a possibly multi-dimensional object to a one-dimensional one by converting all nested keys to dot notation

Parameters
- obj: any
  
  The object to flatten
- _d: number = 0
Returns any
A flattened object

getParentClasses

getParentClasses(cls: Function): Function[]

Obtain references to the parent classes of a certain class.

Parameters
- cls: Function
  
  An ES6 Class definition
Returns Function[]
An array of parent Classes which the provided class extends

getRoute

getRoute(path: string, [prefix]?: string): string

Get the URL route for a certain path which includes a path prefix, if one is set

Parameters
- path: string
  
  The Foundry URL path
- [prefix]: string = {}
  
  A path prefix to apply
Returns string
The absolute URL path

getType

getType(variable: any): string

Learn the underlying data type of some variable. Supported identifiable types include: undefined, null, number, string, boolean, function, Array, Set, Map, Promise, Error, HTMLElement (client side only), Object (catchall for other object types)

Parameters
- variable: any
  
  A provided variable
Returns string
The named type of the token

hasProperty

hasProperty(object: any, key: string): boolean

A helper function which tests whether an object has a property or nested property given a string key. The method also supports arrays if the provided key is an integer index of the array. The string key supports the notation a.b.c which would return true if object[a][b][c] exists

Parameters
- object: any
  
  The object to traverse
- key: string
  
  An object property with notation a.b.c
Returns boolean
An indicator for whether the property exists

getProperty

getProperty(object: any, key: string): any

A helper function which searches through an object to retrieve a value by a string key. The method also supports arrays if the provided key is an integer index of the array. The string key supports the notation a.b.c which would return object[a][b][c]

Parameters
- object: any
  
  The object to traverse
- key: string
  
  An object property with notation a.b.c
Returns any
The value of the found property

setProperty

setProperty(object: any, key: string, value: any): boolean

A helper function which searches through an object to assign a value using a string key This string key supports the notation a.b.c which would target object[a][b][c]

Parameters
- object: any
  
  The object to update
- key: string
  
  The string key
- value: any
  
  The value to be assigned
Returns boolean
Whether the value was changed from its previous value

invertObject

invertObject(obj: any): any

Invert an object by assigning its values as keys and its keys as values.

Parameters
- obj: any
  
  The original object to invert
Returns any
The inverted object with keys and values swapped

isNewerVersion

isNewerVersion(v1: string | number, v0: string | number): boolean

Return whether a target version (v1) is more advanced than some other reference version (v0). Supports either numeric or string version comparison with version parts separated by periods.

Parameters
- v1: string | number
  
  The target version
- v0: string | number
  
  The reference version
Returns boolean
Is v1 a more advanced version than v0?

isObjectEmpty

isObjectEmpty(obj: any): boolean

A simple function to test whether an Object is empty

deprecated
since v10, will be removed in v11 - Use isEmpty instead.

Parameters
- obj: any
  
  The object to test
Returns boolean
Is the object empty?

isEmpty

isEmpty(value: any): boolean

Test whether a value is empty-like; either undefined or a content-less object.

Parameters
- value: any
  
  The value to test
Returns boolean
Is the value empty-like?

mergeObject

mergeObject(original: any, other?: any, [options={}]?: { insertKeys: boolean; insertValues: boolean; overwrite: boolean; recursive: boolean; inplace: boolean; enforceTypes: boolean; performDeletions: boolean }, _d?: number): any

Update a source object by replacing its keys and values with those from a target object.
example
Control how new keys and values are added
```
mergeObject({k1: "v1"}, {k2: "v2"}, {insertKeys: false}); // {k1: "v1"}
mergeObject({k1: "v1"}, {k2: "v2"}, {insertKeys: true});  // {k1: "v1", k2: "v2"}
mergeObject({k1: {i1: "v1"}}, {k1: {i2: "v2"}}, {insertValues: false}); // {k1: {i1: "v1"}}
mergeObject({k1: {i1: "v1"}}, {k1: {i2: "v2"}}, {insertValues: true}); // {k1: {i1: "v1", i2: "v2"}}
```
example
Control how existing data is overwritten
```
mergeObject({k1: "v1"}, {k1: "v2"}, {overwrite: true}); // {k1: "v2"}
mergeObject({k1: "v1"}, {k1: "v2"}, {overwrite: false}); // {k1: "v1"}
```
example
Control whether merges are performed recursively
```
mergeObject({k1: {i1: "v1"}}, {k1: {i2: "v2"}}, {recursive: false}); // {k1: {i1: "v2"}}
mergeObject({k1: {i1: "v1"}}, {k1: {i2: "v2"}}, {recursive: true}); // {k1: {i1: "v1", i2: "v2"}}
```
example
Deleting an existing object key
```
mergeObject({k1: "v1", k2: "v2"}, {"-=k1": null});   // {k2: "v2"}
```
Parameters
- original: any
  
  The initial object which should be updated with values from the target
- other: any = {}
- [options={}]: { insertKeys: boolean; insertValues: boolean; overwrite: boolean; recursive: boolean; inplace: boolean; enforceTypes: boolean; performDeletions: boolean } = {}
  
  Additional options which configure the merge
  - insertKeys: boolean
  - insertValues: boolean
  - overwrite: boolean
  - recursive: boolean
  - inplace: boolean
  - enforceTypes: boolean
  - performDeletions: boolean
- _d: number = 0
Returns any
The original source object including updated, inserted, or overwritten records.

parseS3URL

parseS3URL(key: string): { bucket: string; keyPrefix: string }

Parse an S3 key to learn the bucket and the key prefix used for the request.

Parameters
- key: string
  
  A fully qualified key name or prefix path.
Returns { bucket: string; keyPrefix: string }
- bucket: string
- keyPrefix: string

randomID

randomID(length?: number): string

Generate a random string ID of a given requested length.

Parameters
- length: number = 16
  
  The length of the random ID to generate
Returns string
Return a string containing random letters and numbers

timeSince

timeSince(timeStamp: string | Date): string

Express a timestamp as a relative string

Parameters
- timeStamp: string | Date
  
  A timestamp string or Date object to be formatted as a relative time
Returns string
A string expression for the relative time

fetchWithTimeout

fetchWithTimeout(url: string, data?: any, __namedParameters?: number): Promise<Response>

A wrapper method around fetch that attaches an AbortController signal to the fetch call for clean timeouts

see
https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal

throws
{HttpError}

Parameters
- url: string
  
  The URL to make the Request to
- data: any = {}
  
  The data of the Request
- __namedParameters: number = {}
Returns Promise<Response>

fetchJsonWithTimeout

fetchJsonWithTimeout(url: string, data?: any, __namedParameters?: int): Promise<any>

A small wrapper that automatically asks for JSON with a Timeout

Parameters
- url: string
  
  The URL to make the Request to
- data: any = {}
  
  The data of the Request
- __namedParameters: int = {}
Returns Promise<any>

logCompatibilityWarning

logCompatibilityWarning(message: string, [options={}]?: { mode: number; since: string | number; until: string | number; details: string; stack: boolean }): void

Log a compatibility warning which is filtered based on the client's defined compatibility settings.

throws
An Error if the mode is ERROR

Parameters
- message: string
  
  The original warning or error message
- [options={}]: { mode: number; since: string | number; until: string | number; details: string; stack: boolean } = {}
  
  Additional options which customize logging
  - mode: number
  - since: string | number
  - until: string | number
  - details: string
  - stack: boolean
Returns void

Index

Classes

Functions

Interfaces

Variables

Type Aliases

Functions

orient2dFast

Parameters

a: Point

b: Point

c: Point

Returns number

lineSegmentIntersects

Parameters

a: Point

b: Point

c: Point

d: Point

Returns boolean

lineLineIntersection

Parameters

a: Point

b: Point

c: Point

d: Point

[options]: { t1: boolean } = {}

t1: boolean

Returns LineIntersection

lineSegmentIntersection

Parameters

a: Point

b: Point

c: Point

d: Point

epsilon: number = 1e-8

Returns LineIntersection

lineCircleIntersection

Parameters

a: Point

b: Point

center: Point

radius: number

epsilon: number = 1e-8

Returns LineCircleIntersection

closestPointToSegment

Parameters

c: Point

a: Point

b: Point

Returns Point

quadraticIntersection

Parameters

p0: Point

p1: Point

center: Point

radius: number

epsilon: number = 0

Returns { x: any; y: any }[]

benchmark

Parameters

func: Function

iterations: number

Rest ...args: any[]

Returns Promise<void>

threadLock

Parameters

ms: number

debug: boolean = false

Returns Promise<void>

debounce

Parameters

callback: Function

delay: number

Returns Function

deepClone

Parameters

original: any

[options]: { strict: boolean } = {}

strict: boolean