Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/basementuniverse/utils

A collection of useful functions
https://github.com/basementuniverse/utils

Last synced: 23 days ago
JSON representation

A collection of useful functions

Awesome Lists containing this project

README 

        
# 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







## Typedefs







InterpolationFunction ⇒ number





An interpolation function






TimesFunction ⇒ *





A function for generating array values






SplitPredicate ⇒ boolean





A split 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](#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](#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](#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 |






## 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 |