utils

A small library of useful functions

Usage

Node:

``javascript
const utils = require('@basementuniverse/utils');
`

Browser:

`html

`

Typescript:

`typescript
import * as utils from '@basementuniverse/utils';
`

Contents

Functions

memoize(f) ⇒ function

Memoize a function

floatEquals(a, b, [p]) ⇒ boolean

Check if two numbers are approximately equal

clamp(a, [min], [max]) ⇒ number

Clamp a number between min and max

frac(a) ⇒ number

Get the fractional part of a number

round(n, [d]) ⇒ number

Round n to d decimal places

lerp(a, b, i) ⇒ number

Do a linear interpolation between a and b

unlerp(a, b, i) ⇒ number

Get the position of i between a and b

blerp(c00, c10, c01, c11, ix, iy) ⇒ number

Do a bilinear interpolation

remap(i, a1, a2, b1, b2) ⇒ number

Re-map a number i from range a1...a2 to b1...b2

smoothstep(a, b, i) ⇒ number

Do a smooth interpolation between a and b

radians(degrees) ⇒ number

Get an angle in radians

degrees(radians) ⇒ number

Get an angle in degrees

randomBetween(min, max) ⇒ number

Get a random float in the interval [min, max)

randomIntBetween(min, max) ⇒ number

Get a random integer in the interval [min, max]

cltRandom([mu], [sigma], [samples]) ⇒ number

Get a normally-distributed random number

cltRandomInt(min, max) ⇒ number

Get a normally-distributed random integer in the interval [min, max]

weightedRandom(w) ⇒ number

Return a weighted random integer

lerpArray(a, i, [f]) ⇒ number

Return an interpolated value from an array

dot(a, b) ⇒ number

Get the dot product of two vectors

factorial(a) ⇒ number

Get the factorial of a number

npr(n, r) ⇒ number

Get the number of permutations of r elements from a set of n elements

ncr(n, r) ⇒ number

Get the number of combinations of r elements from a set of n elements

permutations(a, r) ⇒ Array.<Array.<*>>

Generate all permutations of r elements from an array

combinations(a, r) ⇒ Array.<Array.<*>>

Generate all combinations of r elements from an array

cartesian()

Get a cartesian product of arrays

times(f, n) ⇒ Array.<*>

Return a new array with length n by calling function f(i) on each element

range(n) ⇒ Array.<number>

Return an array containing numbers 0->(n - 1)

zip(...a) ⇒ Array.<Array.<*>>

Zip multiple arrays together, i.e. ([1, 2, 3], [a, b, c]) => [[1, a], [2, b], [3, c]]

at(a, i) ⇒ *

Return array[i] with positive and negative wrapping

peek(a) ⇒ *

Return the last element of an array without removing it

ind(x, y, w) ⇒ number

Return the index for a given position in an unrolled 2d array

pos(i, w) ⇒ Array.<number>

Return the position for a given index in an unrolled 2d array

chunk(a, n) ⇒ Array.<Array.<*>>

Chop an array into chunks of size n

shuffle(a) ⇒ Array.<*>

Randomly shuffle a shallow copy of an array

flat(o, concatenator) ⇒ object

Flatten an object

unflat(o, concatenator) ⇒ object

Unflatten an object

split(array, predicate) ⇒ Array.<Array.<*>>

Split an array into sub-arrays based on a predicate

pluck(o, ...keys) ⇒ object

Pluck keys from an object

exclude(o, ...keys) ⇒ object

Exclude keys from an object

transform(o, [kf], [vf]) ⇒ object

Recursively transform the keys and values of an object

Typedefs

InterpolationFunction ⇒ number

An interpolation function

TimesFunction ⇒ *

A function for generating array values

SplitPredicate ⇒ boolean

A split predicate

KeyTransformFunction ⇒ string | null

A key transform predicate

ValueTransformFunction ⇒ any

A value transform predicate

memoize(f) ⇒ function

Memoize a function

Kind: global function
Returns: function - A memoized version of the function

| Param | Type | Description |
| --- | --- | --- |
| f | function | The function to memoize |

floatEquals(a, b, [p]) ⇒ boolean

Check if two numbers are approximately equal

Kind: global function
Returns: boolean - True if numbers a and b are approximately equal

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| a | number | | Number a |
| b | number | | Number b |
| [p] | number | Number.EPSILON | The precision value |

clamp(a, [min], [max]) ⇒ number

Clamp a number between min and max

Kind: global function
Returns: number - A clamped number

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| a | number | | The number to clamp |
| [min] | number | 0 | The minimum value |
| [max] | number | 1 | The maximum value |

frac(a) ⇒ number

Get the fractional part of a number

Kind: global function
Returns: number - The fractional part of the number

| Param | Type | Description |
| --- | --- | --- |
| a | number | The number from which to get the fractional part |

round(n, [d]) ⇒ number

Round n to d decimal places

Kind: global function
Returns: number - A rounded number

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| n | number | | The number to round |
| [d] | number | 0 | The number of decimal places to round to |

lerp(a, b, i) ⇒ number

Do a linear interpolation between a and b

Kind: global function
Returns: number - An interpolated value in the interval [a, b]

| Param | Type | Description |
| --- | --- | --- |
| a | number | The minimum number |
| b | number | The maximum number |
| i | number | The interpolation value, should be in the interval [0, 1] |

unlerp(a, b, i) ⇒ number

Get the position of i between a and b

Kind: global function
Returns: number - The position of i between a and b

| Param | Type | Description |
| --- | --- | --- |
| a | number | The minimum number |
| b | number | The maximum number |
| i | number | The interpolated value in the interval [a, b] |

blerp(c00, c10, c01, c11, ix, iy) ⇒ number

Do a bilinear interpolation

Kind: global function
Returns: number - A bilinear interpolated value

| Param | Type | Description |
| --- | --- | --- |
| c00 | number | Top-left value |
| c10 | number | Top-right value |
| c01 | number | Bottom-left value |
| c11 | number | Bottom-right value |
| ix | number | Interpolation value along x |
| iy | number | Interpolation value along y |

remap(i, a1, a2, b1, b2) ⇒ number

Re-map a number i from range a1...a2 to b1...b2

Kind: global function

| Param | Type | Description |
| --- | --- | --- |
| i | number | The number to re-map |
| a1 | number | |
| a2 | number | |
| b1 | number | |
| b2 | number | |

smoothstep(a, b, i) ⇒ number

Do a smooth interpolation between a and b

Kind: global function
Returns: number - An interpolated value in the interval [a, b]

| Param | Type | Description |
| --- | --- | --- |
| a | number | The minimum number |
| b | number | The maximum number |
| i | number | The interpolation value |

radians(degrees) ⇒ number

Get an angle in radians

Kind: global function
Returns: number - The angle in radians

| Param | Type | Description |
| --- | --- | --- |
| degrees | number | The angle in degrees |

degrees(radians) ⇒ number

Get an angle in degrees

Kind: global function
Returns: number - The angle in degrees

| Param | Type | Description |
| --- | --- | --- |
| radians | number | The angle in radians |

randomBetween(min, max) ⇒ number

Get a random float in the interval [min, max)

Kind: global function
Returns: number - A random float in the interval [min, max)

| Param | Type | Description |
| --- | --- | --- |
| min | number | Inclusive min |
| max | number | Exclusive max |

randomIntBetween(min, max) ⇒ number

Get a random integer in the interval [min, max]

Kind: global function
Returns: number - A random integer in the interval [min, max]

| Param | Type | Description |
| --- | --- | --- |
| min | number | Inclusive min |
| max | number | Inclusive max |

cltRandom([mu], [sigma], [samples]) ⇒ number

Get a normally-distributed random number

Kind: global function
Returns: number - A normally-distributed random number

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [mu] | number | 0.5 | The mean value |
| [sigma] | number | 0.5 | The standard deviation |
| [samples] | number | 2 | The number of samples |

cltRandomInt(min, max) ⇒ number

Get a normally-distributed random integer in the interval [min, max]

Kind: global function
Returns: number - A normally-distributed random integer

| Param | Type | Description |
| --- | --- | --- |
| min | number | Inclusive min |
| max | number | Inclusive max |

weightedRandom(w) ⇒ number

Return a weighted random integer

Kind: global function
Returns: number - An index from w

| Param | Type | Description |
| --- | --- | --- |
| w | Array.<number> | An array of weights |

lerpArray(a, i, [f]) ⇒ number

Return an interpolated value from an array

Kind: global function
Returns: number - An interpolated value in the interval [min(a), max(a)]

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| a | Array.<number> | | An array of values interpolate |
| i | number | | A number in the interval [0, 1] |
| [f] | InterpolationFunction | Math.lerp | The interpolation function to use |

dot(a, b) ⇒ number

Get the dot product of two vectors

Kind: global function
Returns: number - a ∙ b

| Param | Type | Description |
| --- | --- | --- |
| a | Array.<number> | Vector a |
| b | Array.<number> | Vector b |

factorial(a) ⇒ number

Get the factorial of a number

Kind: global function
Returns: number - a!

| Param | Type |
| --- | --- |
| a | number |

npr(n, r) ⇒ number

Get the number of permutations of r elements from a set of n elements

Kind: global function
Returns: number - nPr

| Param | Type |
| --- | --- |
| n | number |
| r | number |

ncr(n, r) ⇒ number

Get the number of combinations of r elements from a set of n elements

Kind: global function
Returns: number - nCr

| Param | Type |
| --- | --- |
| n | number |
| r | number |

permutations(a, r) ⇒ Array.<Array.<\*>>

Generate all permutations of r elements from an array

Kind: global function
Returns: Array.<Array.<\*>> - An array of permutation arrays

| Param | Type | Description |
| --- | --- | --- |
| a | Array.<\*> | |
| r | number | The number of elements to choose in each permutation |

Example
`js
permutations([1, 2, 3], 2);
`

Output:
`json
[
[1, 2],
[1, 3],
[2, 1],
[2, 3],
[3, 1],
[3, 2]
]
`


combinations(a, r) ⇒ Array.<Array.<\*>>

Generate all combinations of r elements from an array

Kind: global function
Returns: Array.<Array.<\*>> - An array of combination arrays

| Param | Type | Description |
| --- | --- | --- |
| a | Array.<\*> | |
| r | number | The number of elements to choose in each combination |

Example
`js
combinations([1, 2, 3], 2);
`

Output:
`json
[
[1, 2],
[1, 3],
[2, 3]
]
`


cartesian()

Get a cartesian product of arrays

Kind: global function
Example
`js
cartesian([1, 2, 3], ['a', 'b']);
`

Output:
`json
[
[1, "a"],
[1, "b"],
[2, "a"],
[2, "b"],
[3, "a"],
[3, "b"]
]
``

times(f, n) ⇒ Array.<\*>

Return a new array with length n by calling function f(i) on each element

Kind: global function

| Param | Type | Description |
| --- | --- | --- |
| f | TimesFunction | |
| n | number | The size of the array |

range(n) ⇒ Array.<number>

Return an array containing numbers 0->(n - 1)

Kind: global function
Returns: Array.<number> - An array of integers 0->(n - 1)

| Param | Type | Description |
| --- | --- | --- |
| n | number | The size of the array |

zip(...a) ⇒ Array.<Array.<\*>>

Zip multiple arrays together, i.e. ([1, 2, 3], [a, b, c]) => [[1, a], [2, b], [3, c]]

Kind: global function

| Param | Type | Description |
| --- | --- | --- |
| ...a | Array.<\*> | The arrays to zip |

at(a, i) ⇒ \*

Return array[i] with positive and negative wrapping

Kind: global function
Returns: \* - An element from the array

| Param | Type | Description |
| --- | --- | --- |
| a | Array.<\*> | The array to access |
| i | number | The positively/negatively wrapped array index |

peek(a) ⇒ \*

Return the last element of an array without removing it

Kind: global function
Returns: \* - The last element from the array

| Param | Type |
| --- | --- |
| a | Array.<\*> |

ind(x, y, w) ⇒ number

Return the index for a given position in an unrolled 2d array

Kind: global function
Returns: number - The index in the unrolled array

| Param | Type | Description |
| --- | --- | --- |
| x | number | The x position |
| y | number | The y position |
| w | number | The width of the 2d array |

pos(i, w) ⇒ Array.<number>

Return the position for a given index in an unrolled 2d array

Kind: global function
Returns: Array.<number> - The position as a 2-tuple

| Param | Type | Description |
| --- | --- | --- |
| i | number | The index |
| w | number | The width of the 2d array |

chunk(a, n) ⇒ Array.<Array.<\*>>

Chop an array into chunks of size n

Kind: global function
Returns: Array.<Array.<\*>> - An array of array chunks

| Param | Type | Description |
| --- | --- | --- |
| a | Array.<\*> | |
| n | number | The chunk size |

shuffle(a) ⇒ Array.<\*>

Randomly shuffle a shallow copy of an array

Kind: global function
Returns: Array.<\*> - The shuffled array

| Param | Type |
| --- | --- |
| a | Array.<\*> |

flat(o, concatenator) ⇒ object

Flatten an object

Kind: global function
Returns: object - A flattened object

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| o | object | | |
| concatenator | string | "." | The string to use for concatenating keys |

unflat(o, concatenator) ⇒ object

Unflatten an object

Kind: global function
Returns: object - An un-flattened object

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| o | object | | |
| concatenator | string | "." | The string to check for in concatenated keys |

split(array, predicate) ⇒ Array.<Array.<\*>>

Split an array into sub-arrays based on a predicate

Kind: global function
Returns: Array.<Array.<\*>> - An array of arrays

| Param | Type |
| --- | --- |
| array | Array.<\*> |
| predicate | SplitPredicate |

pluck(o, ...keys) ⇒ object

Pluck keys from an object

Kind: global function
Returns: object - An object containing the plucked keys

| Param | Type | Description |
| --- | --- | --- |
| o | object | |
| ...keys | string | The keys to pluck from the object |

exclude(o, ...keys) ⇒ object

Exclude keys from an object

Kind: global function
Returns: object - An object containing all keys except excluded keys

| Param | Type | Description |
| --- | --- | --- |
| o | object | |
| ...keys | string | The keys to exclude from the object |

transform(o, [kf], [vf]) ⇒ object

Recursively transform the keys and values of an object

Kind: global function
Returns: object - The transformed object

| Param | Type | Description |
| --- | --- | --- |
| o | object | The object to transform |
| [kf] | KeyTransformFunction | Optional key transform |
| [vf] | ValueTransformFunction | Optional value transform |

InterpolationFunction ⇒ number

An interpolation function

Kind: global typedef
Returns: number - The interpolated value in the interval [a, b]

| Param | Type | Description |
| --- | --- | --- |
| a | number | The minimum number |
| b | number | The maximum number |
| i | number | The interpolation value, should be in the interval [0, 1] |

TimesFunction ⇒ \*

A function for generating array values

Kind: global typedef
Returns: \* - The array value

| Param | Type | Description |
| --- | --- | --- |
| i | number | The array index |

SplitPredicate ⇒ boolean

A split predicate

Kind: global typedef
Returns: boolean - True if the array should split at this index

| Param | Type | Description |
| --- | --- | --- |
| value | any | The current value |

KeyTransformFunction ⇒ string \| null

A key transform predicate

Kind: global typedef
Returns: string \| null - The transformed key, or null to omit the key

| Param | Type | Description |
| --- | --- | --- |
| o | object | The object being transformed |
| path | string | The current path in dot notation |
| key | string | The current key |
| value | any | The current value |

ValueTransformFunction ⇒ any

A value transform predicate

Kind: global typedef
Returns: any - The transformed value

| Param | Type | Description |
| --- | --- | --- |
| o | object | The object being transformed |
| path | string | The current path in dot notation |
| key | string | The current key |
| value | any | The current value |