helpers

Methods

(static) benchmark(func, iterations, …args)

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

Parameters:
Name Type Attributes Description
func function

The function to benchmark
iterations number

The number of iterations to test
args any <repeatable>

Additional arguments passed to the benchmarked function

(static) colorStringToHex(color) → {number|null}

Convert a string color to a hex integer

Parameters:
Name Type Description
color string

The string color
Returns:

The hexadecimal color code

Type
number | null

(static) debounce(callback, delay) → {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:
Name Type Description
callback function

A function to execute once the debounced threshold has been passed
delay number

An amount of time in milliseconds to delay
Returns:

A wrapped function which can be called to debounce execution

Type
function

(static) deepClone(original, optionsopt) → {*}

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:
Name Type Attributes Description
original *

Some sort of data
options object <optional>

Options to configure the behaviour of deepClone

Properties
Name Type Attributes Default Description
strict boolean <optional>
 false

Throw an Error if deepClone is unable to clone something instead of returning the original
Returns:

The clone of that data

Type
*

(static) diffObject(original, other, optionsopt) → {object}

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

Parameters:
Name Type Attributes Default Description
original object

An object comparing data against which to compare
other object

An object containing potentially different data
options object <optional>
 {}

Additional options which configure the diff operation

Properties
Name Type Attributes Default Description
inner boolean <optional>
 false

Only recognize differences in other for keys which also exist in original
Returns:

An object of the data in other which differs from that in original

Type
object

(static) duplicate(original)

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

Parameters:
Name Type Description
original Object

Some sort of data

(static) encodeURL(path) → {string}

Encode a url-like string by replacing any characters which need encoding

Parameters:
Name Type Description
path string

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

An encoded URL string

Type
string

(static) expandObject(obj, _dopt) → {object}

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

Parameters:
Name Type Attributes Default Description
obj object

The object to expand
_d Number <optional>
 0

Track the recursion depth to prevent overflow
Returns:

An expanded object

Type
object

(static) filterObject(source, template, optionsopt)

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
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:
Name Type Attributes Default Description
source object

An object which contains the data you wish to filter
template object

An object which contains the structure you wish to preserve
options object <optional>
 {}

Additional options which customize the filtration

Properties
Name Type Attributes Default Description
keepSpecial boolean <optional>
 false

Whether to keep special tokens like deletion keys
templateValues boolean <optional>
 false

Instead of keeping values from the source, instead draw values from the template

(static) flattenObject(obj, _dopt) → {object}

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

Parameters:
Name Type Attributes Default Description
obj object

The object to flatten
_d number <optional>
 0

Track the recursion depth to prevent overflow
Returns:

A flattened object

Type
object

(static) getParentClasses(cls) → {Array.<function()>}

Obtain references to the parent classes of a certain class.

Parameters:
Name Type Description
cls function

An ES6 Class definition
Returns:

An array of parent Classes which the provided class extends

Type
Array.<function()>

(static) getProperty(object, key) → {*}

A helper function which searches through an object to retrieve a value by a string key. The string key supports the notation a.b.c which would return object[a][b][c]

Parameters:
Name Type Description
object object

The object to traverse
key string

An object property with notation a.b.c
Returns:

The value of the found property

Type
*

(static) getRoute(path, prefixopt) → {string}

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

Parameters:
Name Type Attributes Description
path string

The Foundry URL path
prefix string | null <optional>

A path prefix to apply
Returns:

The absolute URL path

Type
string

(static) getType(token) → {string}

Learn the named type of a token - extending the functionality of typeof to recognize some core Object types

Parameters:
Name Type Description
token *

Some passed token
Returns:

The named type of the token

Type
string

(static) hasProperty(object, key) → {boolean}

A helper function which tests whether an object has a property or nested property given a string key. The string key supports the notation a.b.c which would return true if object[a][b][c] exists

Parameters:
Name Type Description
object object

The object to traverse
key string

An object property with notation a.b.c
Returns:

An indicator for whether the property exists

Type
boolean

(static) hexToRGB(hex) → {Array.<number>}

Convert a hex color code to an RGB array

Parameters:
Name Type Description
hex number

A hex color number
Returns:

An array of [r,g,b] colors normalized on the range of [0,1]

Type
Array.<number>

(static) hexToRGBAString(hex, alphaopt) → {string}

Convert a hex color code to an RGBA color string which can be used for CSS styling

Parameters:
Name Type Attributes Default Description
hex number

A hex color number
alpha number <optional>
 1.0

An optional level of transparency
Returns:

An rgba style string

Type
string

(static) hsvToRgb(h, s, v) → {Array.<number>}

Converts an HSV color value to RGB. Conversion formula adapted from http://en.wikipedia.org/wiki/HSV_color_space. Assumes h, s, and v are contained in the set [0, 1] and returns r, g, and b in the set [0, 1].

Parameters:
Name Type Description
h number

The hue
s number

The saturation
v number

The value
Returns:

The RGB representation

Type
Array.<number>

(static) invertObject(obj) → {object}

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

Parameters:
Name Type Description
obj object

The original object to invert
Returns:

The inverted object with keys and values swapped

Type
object

(static) isNewerVersion(v1, v0) → {boolean}

Return whether or not 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:
Name Type Description
v1 number | string

The target version
v0 number | string

The reference version
Returns:

Is v1 a more advanced version than v0?

Type
boolean

(static) isObjectEmpty(obj) → {boolean}

A simple function to test whether or not an Object is empty

Parameters:
Name Type Description
obj object

The object to test
Returns:

Is the object empty?

Type
boolean

(static) isSubclass(cls, parent) → {boolean}

Test whether some class is a subclass of a parent.

Parameters:
Name Type Description
cls function

The class to test
parent function

Some other class which may be a parent
Returns:

Is the class a subclass of the parent?

Type
boolean

(static) mergeObject(original, otheropt, optionsopt, _dopt) → {object}

Update a source object by replacing its keys and values with those from a target object.

Examples

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"}}

Control how existing data is overwritten

mergeObject({k1: "v1"}, {k1: "v2"}, {overwrite: true}); // {k1: "v2"}
mergeObject({k1: "v1"}, {k1: "v2"}, {overwrite: false}); // {k1: "v1"}

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"}}

Deleting an existing object key

mergeObject({k1: "v1", k2: "v2"}, {"-=k1": null});   // {k2: "v2"}
Parameters:
Name Type Attributes Default Description
original object

The initial object which should be updated with values from the target
other object <optional>
 {}

A new object whose values should replace those in the source
options object <optional>
 {}

Additional options which configure the merge

Properties
Name Type Attributes Default Description
insertKeys boolean <optional>
 true

Control whether to insert new top-level objects into the resulting structure which do not previously exist in the original object.
insertValues boolean <optional>
 true

Control whether to insert new nested values into child objects in the resulting structure which did not previously exist in the original object.
overwrite boolean <optional>
 true

Control whether to replace existing values in the source, or only merge values which do not already exist in the original object.
recursive boolean <optional>
 true

Control whether to merge inner-objects recursively (if true), or whether to simply replace inner objects with a provided new value.
inplace boolean <optional>
 true

Control whether to apply updates to the original object in-place (if true), otherwise the original object is duplicated and the copy is merged.
enforceTypes boolean <optional>
 false

Control whether strict type checking requires that the value of a key in the other object must match the data type in the original data to be merged.
_d number <optional>
 0

A privately used parameter to track recursion depth.
Returns:

The original source object including updated, inserted, or overwritten records.

Type
object

(static) randomID(length) → {string}

Generate a random string ID of a given requested length.

Parameters:
Name Type Description
length number

The length of the random ID to generate
Returns:

Return a string containing random letters and numbers

Type
string

(static) rgbToHex(rgb) → {number}

Converts a color as an [R, G, B] array of normalized floats to a hexadecimal number.

Parameters:
Name Type Description
rgb Array.<number>

Array of numbers where all values are normalized floats from 0.0 to 1.0.
Returns:

The numeric color as hexadecimal

Type
number

(static) rgbToHsv(r, g, b) → {Array.<number>}

Converts an RGB color value to HSV. Conversion formula adapted from http://en.wikipedia.org/wiki/HSV_color_space. Assumes r, g, and b are contained in the set [0, 1] and returns h, s, and v in the set [0, 1].

Parameters:
Name Type Description
r number

The red color value
g number

The green color value
b number

The blue color value
Returns:

The HSV representation

Type
Array.<number>

(static) setProperty(object, key, value) → {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:
Name Type Description
object object

The object to update
key string

The string key
value *

The value to be assigned
Returns:

Whether the value was changed from its previous value

Type
boolean

(static) timeSince(timeStamp) → {string}

Express a timestamp as a relative string

Parameters:
Name Type Description
timeStamp Date | string

A timestamp string or Date object to be formatted as a relative time
Returns:

A string expression for the relative time

Type
string