@basementuniverse/commonjs

A collection of useful functions

Usage no npm install needed!

<script type="module">
  import basementuniverseCommonjs from 'https://cdn.skypack.dev/@basementuniverse/commonjs';
</script>

README

common.js

A small library of useful functions

Usage

Node:

const { vec, mat } = require('@basementuniverse/commonjs');

Browser:

<script src="common.js"></script>

Typescript:

import { vec, mat } from '@basementuniverse/commonjs';

Contents

Classes

Math
Array

Functions

vec([x], [y]) ⇒ vec

Create a new vector

mat([m], [n], [entries]) ⇒ mat

Create a new matrix

Typedefs

interpolationCallback ⇒ number

An interpolation function

timesCallback ⇒ *

A function for generating array values

vec : Object

A 2d vector

vectorMapCallback ⇒ number

A function to call on each component of a vector

mat : Object

A matrix

matrixMapCallback ⇒ number

A function to call on each entry of a matrix

Math

Kind: global class

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

Check if two numbers are approximately equal

Kind: static method of Math
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

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

Clamp a number between min and max

Kind: static method of Math
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

Math.frac(a) ⇒ number

Get the fractional part of a number

Kind: static method of Math
Returns: number - The fractional part of the number

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

Math.lerp(a, b, i) ⇒ number

Do a linear interpolation between a and b

Kind: static method of Math
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]

Math.unlerp(a, b, i) ⇒ number

Get the position of i between a and b

Kind: static method of Math
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]

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

Do a bilinear interpolation

Kind: static method of Math
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

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

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

Kind: static method of Math

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

Math.smoothstep(a, b, i) ⇒ number

Do a smooth interpolation between a and b

Kind: static method of Math
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

Math.radians(degrees) ⇒ number

Get an angle in radians

Kind: static method of Math
Returns: number - The angle in radians

Param Type Description
degrees number The angle in degrees

Math.degrees(radians) ⇒ number

Get an angle in degrees

Kind: static method of Math
Returns: number - The angle in degrees

Param Type Description
radians number The angle in radians

Math.randomBetween(min, max) ⇒ number

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

Kind: static method of Math
Returns: number - A random float in the interval [min, max)

Param Type Description
min number Inclusive min
max number Exclusive max

Math.randomIntBetween(min, max) ⇒ number

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

Kind: static method of Math
Returns: number - A random integer in the interval [min, max]

Param Type Description
min number Inclusive min
max number Inclusive max

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

Get a normally-distributed random number

Kind: static method of Math
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

Math.cltRandomInt(min, max) ⇒ number

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

Kind: static method of Math
Returns: number - A normally-distributed random integer

Param Type Description
min number Inclusive min
max number Inclusive max

Math.weightedRandom(w) ⇒ number

Return a weighted random integer

Kind: static method of Math
Returns: number - An index from w

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

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

Return an interpolated value from an array

Kind: static method of Math
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] interpolationCallback Math.lerp The interpolation function to use

Math.dot(a, b) ⇒ number

Get the dot product of two vectors

Kind: static method of Math
Returns: number - a ∙ b

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

Math.factorial(a) ⇒ number

Get the factorial of a number

Kind: static method of Math
Returns: number - a!

Param Type
a number

Math.permutation(n, r) ⇒ number

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

Kind: static method of Math
Returns: number - nPr

Param Type
n number
r number

Math.combination(n, r) ⇒ number

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

Kind: static method of Math
Returns: number - nCr

Param Type
n number
r number

Array

Kind: global class

array.at(i) ⇒ *

Return array[i] with positive and negative wrapping

Kind: instance method of Array
Returns: * - An element from the array

Param Type Description
i number The positively/negatively wrapped array index

array.chunk(n) ⇒ Array.<Array.<*>>

Chop an array into chunks of size n

Kind: instance method of Array
Returns: Array.<Array.<*>> - An array of array chunks

Param Type Description
n number The chunk size

array.shuffle() ⇒ Array.<*>

Randomly shuffle an array in-place

Kind: instance method of Array
Returns: Array.<*> - The shuffled array

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

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

Kind: static method of Array

Param Type Description
f timesCallback
n number The size of the array

Array.range(n) ⇒ Array.<number>

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

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

Param Type Description
n number The size of the array

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

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

Kind: static method of Array

Param Type
a Array.<*>
b Array.<*>

vec([x], [y]) ⇒ vec

Create a new vector

Kind: global function
Returns: vec - A new vector

Param Type Description
[x] number | vec The x component of the vector, or a vector to copy
[y] number The y component of the vector

Example (Various ways to initialise a vector)

let a = vec(3, 2);  // (3, 2)
let b = vec(4);     // (4, 4)
let c = vec(a);     // (3, 2)
let d = vec();      // (0, 0)

vec.components(a) ⇒ Array.<number>

Get the components of a vector as an array

Kind: static method of vec
Returns: Array.<number> - The vector components as an array

Param Type Description
a vec The vector to get components from

vec.ux() ⇒ vec

Return a unit vector (1, 0)

Kind: static method of vec
Returns: vec - A unit vector (1, 0)

vec.uy() ⇒ vec

Return a unit vector (0, 1)

Kind: static method of vec
Returns: vec - A unit vector (0, 1)

vec.add(a, b) ⇒ vec

Add vectors

Kind: static method of vec
Returns: vec - a + b

Param Type Description
a vec Vector a
b vec Vector b

vec.mul(a, b) ⇒ vec

Scale a vector

Kind: static method of vec
Returns: vec - a * b

Param Type Description
a vec Vector a
b number Scalar b

vec.sub(a, b) ⇒ vec

Subtract vectors

Kind: static method of vec
Returns: vec - a - b

Param Type Description
a vec Vector a
b vec Vector b

vec.len(a) ⇒ number

Get the length of a vector

Kind: static method of vec
Returns: number - |a|

Param Type Description
a vec Vector a

vec.manhattan(a) ⇒ number

Get the length of a vector using taxicab geometry

Kind: static method of vec
Returns: number - |a|

Param Type Description
a vec Vector a

vec.nor(a) ⇒ vec

Normalise a vector

Kind: static method of vec
Returns: vec - ^a

Param Type Description
a vec The vector to normalise

vec.dot(a, b) ⇒ number

Get a dot product of vectors

Kind: static method of vec
Returns: number - a ∙ b

Param Type Description
a vec Vector a
b vec Vector b

vec.rot(a, r) ⇒ vec

Rotate a vector by r radians

Kind: static method of vec
Returns: vec - A rotated vector

Param Type Description
a vec The vector to rotate
r number The angle to rotate by, measured in radians

vec.eq(a, b) ⇒ boolean

Check if two vectors are equal

Kind: static method of vec
Returns: boolean - True if vectors a and b are equal, false otherwise

Param Type Description
a vec Vector a
b vec Vector b

vec.rad(a) ⇒ number

Get the angle of a vector

Kind: static method of vec
Returns: number - The angle of vector a in radians

Param Type Description
a vec Vector a

vec.cpy(a) ⇒ vec

Copy a vector

Kind: static method of vec
Returns: vec - A copy of vector a

Param Type Description
a vec The vector to copy

vec.map(a, f) ⇒ vec

Call a function on each component of a vector and build a new vector from the results

Kind: static method of vec
Returns: vec - Vector a mapped through f

Param Type Description
a vec Vector a
f vectorMapCallback The function to call on each component of the vector

vec.str(a, [s]) ⇒ string

Convert a vector into a string

Kind: static method of vec
Returns: string - A string representation of the vector

Param Type Default Description
a vec The vector to convert
[s] string "', '" The separator string

mat([m], [n], [entries]) ⇒ mat

Create a new matrix

Kind: global function
Returns: mat - A new matrix

Param Type Default Description
[m] number 4 The number of rows
[n] number 4 The number of columns
[entries] Array.<number> [] Matrix values in reading order

mat.identity(n) ⇒ mat

Get an identity matrix of size n

Kind: static method of mat
Returns: mat - An identity matrix

Param Type Description
n number The size of the matrix

mat.get(a, i, j) ⇒ number

Get an entry from a matrix

Kind: static method of mat
Returns: number - The value at position (i, j) in matrix a

Param Type Description
a mat Matrix a
i number The row offset
j number The column offset

mat.set(a, i, j, v)

Set an entry of a matrix

Kind: static method of mat

Param Type Description
a mat Matrix a
i number The row offset
j number The column offset
v number The value to set in matrix a

mat.row(a, m) ⇒ Array.<number>

Get a row from a matrix as an array

Kind: static method of mat
Returns: Array.<number> - Row m from matrix a

Param Type Description
a mat Matrix a
m number The row offset

mat.col(a, n) ⇒ Array.<number>

Get a column from a matrix as an array

Kind: static method of mat
Returns: Array.<number> - Column n from matrix a

Param Type Description
a mat Matrix a
n number The column offset

mat.add(a, b) ⇒ mat

Add matrices

Kind: static method of mat
Returns: mat - a + b

Param Type Description
a mat Matrix a
b mat Matrix b

mat.sub(a, b) ⇒ mat

Subtract matrices

Kind: static method of mat
Returns: mat - a - b

Param Type Description
a mat Matrix a
b mat Matrix b

mat.mul(a, b) ⇒ mat | boolean

Multiply matrices

Kind: static method of mat
Returns: mat | boolean - ab or false if the matrices cannot be multiplied

Param Type Description
a mat Matrix a
b mat Matrix b

mat.scale(a, b) ⇒ mat

Scale a matrix

Kind: static method of mat
Returns: mat - a * b

Param Type Description
a mat Matrix a
b number Scalar b

mat.trans(a) ⇒ mat

Transpose a matrix

Kind: static method of mat
Returns: mat - A transposed matrix

Param Type Description
a mat The matrix to transpose

mat.minor(a, i, j) ⇒ mat | boolean

Get the minor of a matrix

Kind: static method of mat
Returns: mat | boolean - The (i, j) minor of matrix a or false if the matrix is not square

Param Type Description
a mat Matrix a
i number The row offset
j number The column offset

mat.det(a) ⇒ number | boolean

Get the determinant of a matrix

Kind: static method of mat
Returns: number | boolean - |a| or false if the matrix is not square

Param Type Description
a mat Matrix a

mat.nor(a) ⇒ mat | boolean

Normalise a matrix

Kind: static method of mat
Returns: mat | boolean - ^a or false if the matrix is not square

Param Type Description
a mat The matrix to normalise

mat.adj(a) ⇒ mat

Get the adjugate of a matrix

Kind: static method of mat
Returns: mat - The adjugate of a

Param Type Description
a mat The matrix from which to get the adjugate

mat.inv(a) ⇒ mat | boolean

Get the inverse of a matrix

Kind: static method of mat
Returns: mat | boolean - a^-1 or false if the matrix has no inverse

Param Type Description
a mat The matrix to invert

mat.eq(a, b) ⇒ boolean

Check if two matrices are equal

Kind: static method of mat
Returns: boolean - True if matrices a and b are identical, false otherwise

Param Type Description
a mat Matrix a
b mat Matrix b

mat.cpy(a) ⇒ mat

Copy a matrix

Kind: static method of mat
Returns: mat - A copy of matrix a

Param Type Description
a mat The matrix to copy

mat.map(a, f) ⇒ mat

Call a function on each entry of a matrix and build a new matrix from the results

Kind: static method of mat
Returns: mat - Matrix a mapped through f

Param Type Description
a mat Matrix a
f matrixMapCallback The function to call on each entry of the matrix

mat.str(a, [ms], [ns]) ⇒ string

Convert a matrix into a string

Kind: static method of mat
Returns: string - A string representation of the matrix

Param Type Default Description
a mat The matrix to convert
[ms] string "', '" The separator string for columns
[ns] string "'\n'" The separator string for rows

interpolationCallback ⇒ 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]

timesCallback ⇒ *

A function for generating array values

Kind: global typedef
Returns: * - The array value

Param Type Description
i number The array index

vec : Object

A 2d vector

Kind: global typedef
Properties

Name Type Description
x number The x component of the vector
y number The y component of the vector

vec.components(a) ⇒ Array.<number>

Get the components of a vector as an array

Kind: static method of vec
Returns: Array.<number> - The vector components as an array

Param Type Description
a vec The vector to get components from

vec.ux() ⇒ vec

Return a unit vector (1, 0)

Kind: static method of vec
Returns: vec - A unit vector (1, 0)

vec.uy() ⇒ vec

Return a unit vector (0, 1)

Kind: static method of vec
Returns: vec - A unit vector (0, 1)

vec.add(a, b) ⇒ vec

Add vectors

Kind: static method of vec
Returns: vec - a + b

Param Type Description
a vec Vector a
b vec Vector b

vec.mul(a, b) ⇒ vec

Scale a vector

Kind: static method of vec
Returns: vec - a * b

Param Type Description
a vec Vector a
b number Scalar b

vec.sub(a, b) ⇒ vec

Subtract vectors

Kind: static method of vec
Returns: vec - a - b

Param Type Description
a vec Vector a
b vec Vector b

vec.len(a) ⇒ number

Get the length of a vector

Kind: static method of vec
Returns: number - |a|

Param Type Description
a vec Vector a

vec.manhattan(a) ⇒ number

Get the length of a vector using taxicab geometry

Kind: static method of vec
Returns: number - |a|

Param Type Description
a vec Vector a

vec.nor(a) ⇒ vec

Normalise a vector

Kind: static method of vec
Returns: vec - ^a

Param Type Description
a vec The vector to normalise

vec.dot(a, b) ⇒ number

Get a dot product of vectors

Kind: static method of vec
Returns: number - a ∙ b

Param Type Description
a vec Vector a
b vec Vector b

vec.rot(a, r) ⇒ vec

Rotate a vector by r radians

Kind: static method of vec
Returns: vec - A rotated vector

Param Type Description
a vec The vector to rotate
r number The angle to rotate by, measured in radians

vec.eq(a, b) ⇒ boolean

Check if two vectors are equal

Kind: static method of vec
Returns: boolean - True if vectors a and b are equal, false otherwise

Param Type Description
a vec Vector a
b vec Vector b

vec.rad(a) ⇒ number

Get the angle of a vector

Kind: static method of vec
Returns: number - The angle of vector a in radians

Param Type Description
a vec Vector a

vec.cpy(a) ⇒ vec

Copy a vector

Kind: static method of vec
Returns: vec - A copy of vector a

Param Type Description
a vec The vector to copy

vec.map(a, f) ⇒ vec

Call a function on each component of a vector and build a new vector from the results

Kind: static method of vec
Returns: vec - Vector a mapped through f

Param Type Description
a vec Vector a
f vectorMapCallback The function to call on each component of the vector

vec.str(a, [s]) ⇒ string

Convert a vector into a string

Kind: static method of vec
Returns: string - A string representation of the vector

Param Type Default Description
a vec The vector to convert
[s] string "', '" The separator string

vectorMapCallback ⇒ number

A function to call on each component of a vector

Kind: global typedef
Returns: number - The mapped component

Param Type Description
value number The component value
label 'x' | 'y' The component label (x or y)

mat : Object

A matrix

Kind: global typedef
Properties

Name Type Description
m number The number of rows in the matrix
n number The number of columns in the matrix
entries Array.<number> The matrix values

mat.identity(n) ⇒ mat

Get an identity matrix of size n

Kind: static method of mat
Returns: mat - An identity matrix

Param Type Description
n number The size of the matrix

mat.get(a, i, j) ⇒ number

Get an entry from a matrix

Kind: static method of mat
Returns: number - The value at position (i, j) in matrix a

Param Type Description
a mat Matrix a
i number The row offset
j number The column offset

mat.set(a, i, j, v)

Set an entry of a matrix

Kind: static method of mat

Param Type Description
a mat Matrix a
i number The row offset
j number The column offset
v number The value to set in matrix a

mat.row(a, m) ⇒ Array.<number>

Get a row from a matrix as an array

Kind: static method of mat
Returns: Array.<number> - Row m from matrix a

Param Type Description
a mat Matrix a
m number The row offset

mat.col(a, n) ⇒ Array.<number>

Get a column from a matrix as an array

Kind: static method of mat
Returns: Array.<number> - Column n from matrix a

Param Type Description
a mat Matrix a
n number The column offset

mat.add(a, b) ⇒ mat

Add matrices

Kind: static method of mat
Returns: mat - a + b

Param Type Description
a mat Matrix a
b mat Matrix b

mat.sub(a, b) ⇒ mat

Subtract matrices

Kind: static method of mat
Returns: mat - a - b

Param Type Description
a mat Matrix a
b mat Matrix b

mat.mul(a, b) ⇒ mat | boolean

Multiply matrices

Kind: static method of mat
Returns: mat | boolean - ab or false if the matrices cannot be multiplied

Param Type Description
a mat Matrix a
b mat Matrix b

mat.scale(a, b) ⇒ mat

Scale a matrix

Kind: static method of mat
Returns: mat - a * b

Param Type Description
a mat Matrix a
b number Scalar b

mat.trans(a) ⇒ mat

Transpose a matrix

Kind: static method of mat
Returns: mat - A transposed matrix

Param Type Description
a mat The matrix to transpose

mat.minor(a, i, j) ⇒ mat | boolean

Get the minor of a matrix

Kind: static method of mat
Returns: mat | boolean - The (i, j) minor of matrix a or false if the matrix is not square

Param Type Description
a mat Matrix a
i number The row offset
j number The column offset

mat.det(a) ⇒ number | boolean

Get the determinant of a matrix

Kind: static method of mat
Returns: number | boolean - |a| or false if the matrix is not square

Param Type Description
a mat Matrix a

mat.nor(a) ⇒ mat | boolean

Normalise a matrix

Kind: static method of mat
Returns: mat | boolean - ^a or false if the matrix is not square

Param Type Description
a mat The matrix to normalise

mat.adj(a) ⇒ mat

Get the adjugate of a matrix

Kind: static method of mat
Returns: mat - The adjugate of a

Param Type Description
a mat The matrix from which to get the adjugate

mat.inv(a) ⇒ mat | boolean

Get the inverse of a matrix

Kind: static method of mat
Returns: mat | boolean - a^-1 or false if the matrix has no inverse

Param Type Description
a mat The matrix to invert

mat.eq(a, b) ⇒ boolean

Check if two matrices are equal

Kind: static method of mat
Returns: boolean - True if matrices a and b are identical, false otherwise

Param Type Description
a mat Matrix a
b mat Matrix b

mat.cpy(a) ⇒ mat

Copy a matrix

Kind: static method of mat
Returns: mat - A copy of matrix a

Param Type Description
a mat The matrix to copy

mat.map(a, f) ⇒ mat

Call a function on each entry of a matrix and build a new matrix from the results

Kind: static method of mat
Returns: mat - Matrix a mapped through f

Param Type Description
a mat Matrix a
f matrixMapCallback The function to call on each entry of the matrix

mat.str(a, [ms], [ns]) ⇒ string

Convert a matrix into a string

Kind: static method of mat
Returns: string - A string representation of the matrix

Param Type Default Description
a mat The matrix to convert
[ms] string "', '" The separator string for columns
[ns] string "'\n'" The separator string for rows

matrixMapCallback ⇒ number

A function to call on each entry of a matrix

Kind: global typedef
Returns: number - The mapped entry

Param Type Description
value number The entry value
index number The entry index
entries Array.<number> The array of matrix entries