toosoon-utils 2.2.0 → 2.4.0

package/lib/maths.js

@@ -0,0 +1,219 @@
+/**
+ * Check if a number is even
+ *
+ * @param {number} value Value to check
+ * @returns {boolean} True if the given number is even, false otherwise
+ */
+export function isEven(value) {
+    return !(value & 1);
+}
+/**
+ * Check if a number is odd
+ *
+ * @param {number} value Value to check
+ * @returns {boolean} True if the given number is odd, false otherwise
+ */
+export function isOdd(value) {
+    return !!(value & 1);
+}
+/**
+ * Check if a number is a power of 2
+ *
+ * @param {number} value Value to check
+ * @returns {boolean} True if the given number is a power of 2, false otherwise
+ */
+export function isPowerOf2(value) {
+    return (value & (value - 1)) === 0;
+}
+/**
+ * Find closest power of 2 that fits a number
+ *
+ * @param {number} value         Incoming value
+ * @param {string} [mode='ceil'] Can be 'floor' | 'ceil' | 'round'
+ * @returns {number} Power of 2
+ */
+export function toPowerOf2(value, mode) {
+    if (mode === void 0) { mode = 'ceil'; }
+    return Math.pow(2, Math[mode](Math.log(value) / Math.log(2)));
+}
+/**
+ * Return the sign (positive or negative) of a number
+ *
+ * @param {number} value Value to check
+ * @returns {number} 1 if the given number is positive, -1 if it is negative, otherwise 0
+ */
+export function sign(value) {
+    if (value > 0)
+        return 1;
+    else if (value < 0)
+        return -1;
+    return 0;
+}
+/**
+ * Clamp a value between two bounds
+ *
+ * @param {number} value   Value to clamp
+ * @param {number} [min=0] Minimum boundary
+ * @param {number} [max=1] Maximum boundary
+ * @returns {number} Clamped value
+ */
+export function clamp(value, min, max) {
+    if (min === void 0) { min = 0; }
+    if (max === void 0) { max = 1; }
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Linear interpolation between two values (lerping)
+ *
+ * @param {number} value Normalized value to interpolate
+ * @param {number} min   Minimum value
+ * @param {number} max   Maximum value
+ * @returns {number} Lerped value
+ */
+export function lerp(value, min, max) {
+    return min + (max - min) * value;
+}
+/**
+ * Triangular interpolation between two values
+ *
+ * @param {number} value  Normalized value to interpolate
+ * @param {number} min    Minimum value
+ * @param {number} max    Maximum value
+ * @param {number} target Triangle target value
+ * @returns {number} Interpolated value
+ */
+export function triLerp(value, min, max, target) {
+    var x = Math.pow(1 + Math.abs(target - max) / Math.abs(target - min), -1);
+    return value <= x ? min - (min - target) * (value / x) : target - (target - max) * ((value - x) / (1 - x));
+}
+/**
+ * Exponential interpolation between two values
+ *
+ * @param {number} value      Value to interpolate
+ * @param {number} currentMin Lower bound of the value's current range
+ * @param {number} currentMax Upper bound of the value's current range
+ * @param {number} targetMin  Lower bound of the value's target range
+ * @param {number} targetMax  Upper bound of the value's target range
+ * @returns {number} Interpolated value
+ */
+export function expLerp(value, currentMin, currentMax, targetMin, targetMax) {
+    return (targetMin *
+        Math.pow(targetMax / targetMin, (clamp(value, currentMin, currentMax) - currentMin) / (currentMax - currentMin)));
+}
+/**
+ * Normalize a value between two bounds
+ *
+ * @param {number} value Value to normalize
+ * @param {number} min   Minimum boundary
+ * @param {number} max   Maximum boundary
+ * @returns {number} Normalized value
+ */
+export function normalize(value, min, max) {
+    return (value - min) / (max - min);
+}
+/**
+ * Re-map a number from one range to another
+ *
+ * @param {number} value      Value to re-map
+ * @param {number} currentMin Lower bound of the value's current range
+ * @param {number} currentMax Upper bound of the value's current range
+ * @param {number} targetMin  Lower bound of the value's target range
+ * @param {number} targetMax  Upper bound of the value's target range
+ * @returns {number} Re-mapped value
+ */
+export function map(value, currentMin, currentMax, targetMin, targetMax) {
+    return ((value - currentMin) / (currentMax - currentMin)) * (targetMax - targetMin) + targetMin;
+}
+/**
+ * Round a number up to a nearest multiple
+ *
+ * @param {number} value        Value to round
+ * @param {number} [multiple=1] Multiple to round to
+ * @returns {number} Closest multiple
+ */
+export function roundTo(value, multiple) {
+    if (multiple === void 0) { multiple = 1; }
+    if (multiple === 0)
+        return value;
+    return Math.round(value / multiple) * multiple;
+}
+/**
+ * Modulo absolute a value based on a length
+ *
+ * @param {number} value  Value to modulate
+ * @param {number} length Total length
+ * @returns {number} Modulated value
+ */
+export function modAbs(value, length) {
+    if (value < 0) {
+        return length + (value % length);
+    }
+    return value % length;
+}
+/**
+ * Move back and forth a value between 0 and length, so that it is never larger than length and never smaller than 0
+ *
+ * @param {number} value  Value to modulate
+ * @param {number} length Total length
+ * @returns {number} PingPonged value
+ */
+export function pingPong(value, length) {
+    value = modAbs(value, length * 2);
+    return length - Math.abs(value - length);
+}
+/**
+ * Smooth a value using cubic Hermite interpolation
+ *
+ * @param {number} value   Value to smooth
+ * @param {number} [min=0] Minimum boundary
+ * @param {number} [max=1] Maximum boundary
+ * @returns {number} Normalized smoothed value
+ */
+export function smoothstep(value, min, max) {
+    if (min === void 0) { min = 0; }
+    if (max === void 0) { max = 1; }
+    var x = clamp(normalize(value, min, max));
+    return x * x * (3 - 2 * x);
+}
+/**
+ * Re-map the [0, 1] interval into [0, 1] parabola, such that corners are remaped to 0 and the center to 1
+ * -> parabola(0) = parabola(1) = 0, and parabola(0.5) = 1
+ *
+ * @param {number} x         Normalized coordinate on X axis
+ * @param {number} [power=1] Parabola power
+ * @returns {number} Normalized re-mapped value
+ */
+export function parabola(x, power) {
+    if (power === void 0) { power = 1; }
+    return Math.pow(4 * x * (1 - x), power);
+}
+/**
+ * Return the sum of numbers
+ *
+ * @param {number[]} array Array of numbers
+ * @returns {number} Total sum
+ */
+export function sum(array) {
+    return array.reduce(function (previous, current) { return previous + current; });
+}
+/**
+ * Return the average of numbers
+ *
+ * @param {number[]} array Array of numbers
+ * @returns {number} Total average
+ */
+export function average(array) {
+    return sum(array) / array.length;
+}
+/**
+ * Smoothly interpolate a number toward another
+ *
+ * @param {number} value   Value to interpolate
+ * @param {number} target  Destination of the interpolation
+ * @param {number} damping A higher value will make the movement more sudden, and a lower value will make the movement more gradual
+ * @param {number} delta   Delta time (in seconds)
+ * @returns {number} Interpolated number
+ */
+export function damp(value, target, damping, delta) {
+    return lerp(1 - Math.exp(-damping * delta), value, target);
+}

package/lib/prng.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Produce a 128-bit hash value from a seed
+ *
+ * @param {string} seed Initial seed state
+ * @returns {[number, number, number, number]} Hash numbers
+ */
+export declare function cyrb128(seed: string): [number, number, number, number];
+/**
+ * Simple Fast Counter, Generator with a 128-bit state
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} d
+ * @returns {number} Pseudo-random number
+ */
+export declare function sfc32(a: number, b: number, c: number, d: number): number;
+/**
+ * SplitMix32, Generator with a 32-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export declare function splitmix32(a: number): number;
+/**
+ * Mulberry32, Generator with a 32-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export declare function mulberry32(a: number): number;
+/**
+ * Jenkins' Small Fast, Generator with a 32-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export declare function jsf32(a: number, b: number, c: number, d: number): number;
+/**
+ * xoshiro128**, Generator with a 128-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export declare function xoshiro128ss(a: number, b: number, c: number, d: number): number;
+export type PRNGParameters = string | {
+    seed: string;
+    algorithm: (...args: number[]) => number;
+};
+/**
+ * Generate a pseudo-random number in the interval [0, 1]
+ * PRNG equivalent of `Math.random()`
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @returns {number} Pseudo-random number
+ */
+export declare function random(prng: PRNGParameters): number;
+/**
+ * Generate a pseudo-random boolean (true or false)
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {number} [probability=0.5] Probability to get true
+ * @returns {boolean} Either `true` or `false`
+ */
+export declare function randomBoolean(prng: PRNGParameters, probability?: number): boolean;
+/**
+ * Generate a pseudo-random sign (1 or -1)
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {number} [probability=0.5] Probability to get 1
+ * @returns {number} Either 1 or -1
+ */
+export declare function randomSign(prng: PRNGParameters, probability?: number): number;
+/**
+ * Generate a pseudo-random floating-point number within a specified range
+ *
+ * @param {PRNGParameters} prng  PRNG parameters
+ * @param {number} [min=0]       Minimum boundary
+ * @param {number} [max=1]       Maximum boundary
+ * @param {number} [precision=2] Number of digits after the decimal point
+ * @returns {number} Generated float
+ */
+export declare function randomFloat(prng: PRNGParameters, min?: number, max?: number, precision?: number): number;
+/**
+ * Generate a pseudo-random integer number within a specified range
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {number} min          Minimum boundary
+ * @param {number} max          Maximum boundary
+ * @returns {number} Generated integer
+ */
+export declare function randomInt(prng: PRNGParameters, min: number, max: number): number;
+/**
+ * Generate a pseudo-random hexadecimal color
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @returns {string} Generated hexadecimal color
+ */
+export declare function randomHexColor(prng: PRNGParameters): string;
+/**
+ * Pick a pseudo-random item from a given array
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {T[]} array           Array to pick the item from
+ * @returns {T|undefined} Random item picked
+ */
+export declare function randomItem<T = unknown>(prng: PRNGParameters, array: T[]): T | undefined;
+/**
+ * Pick a pseudo-random property value from a given object
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {object} object       Object to pick the property from
+ * @returns {T|undefined} Random item picked
+ */
+export declare function randomObjectProperty<T = unknown>(prng: PRNGParameters, object: Record<string, T>): T | undefined;
+/**
+ * Select a pseudo-random index from an array of weighted items
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {number[]} weights    Array of weights
+ * @returns {number} Random index based on weights
+ */
+export declare function randomIndex(prng: PRNGParameters, weights: number[]): number;

package/lib/prng.js

@@ -0,0 +1,234 @@
+/**
+ * Produce a 128-bit hash value from a seed
+ *
+ * @param {string} seed Initial seed state
+ * @returns {[number, number, number, number]} Hash numbers
+ */
+export function cyrb128(seed) {
+    var h1 = 1779033703;
+    var h2 = 3144134277;
+    var h3 = 1013904242;
+    var h4 = 2773480762;
+    for (var i = 0, k = void 0; i < seed.length; i++) {
+        k = seed.charCodeAt(i);
+        h1 = h2 ^ Math.imul(h1 ^ k, 597399067);
+        h2 = h3 ^ Math.imul(h2 ^ k, 2869860233);
+        h3 = h4 ^ Math.imul(h3 ^ k, 951274213);
+        h4 = h1 ^ Math.imul(h4 ^ k, 2716044179);
+    }
+    h1 = Math.imul(h3 ^ (h1 >>> 18), 597399067);
+    h2 = Math.imul(h4 ^ (h2 >>> 22), 2869860233);
+    h3 = Math.imul(h1 ^ (h3 >>> 17), 951274213);
+    h4 = Math.imul(h2 ^ (h4 >>> 19), 2716044179);
+    return [(h1 ^ h2 ^ h3 ^ h4) >>> 0, (h2 ^ h1) >>> 0, (h3 ^ h1) >>> 0, (h4 ^ h1) >>> 0];
+}
+// *********************
+// PRNG Algorithms
+// *********************
+/**
+ * Simple Fast Counter, Generator with a 128-bit state
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} d
+ * @returns {number} Pseudo-random number
+ */
+export function sfc32(a, b, c, d) {
+    a >>>= 0;
+    b >>>= 0;
+    c >>>= 0;
+    d >>>= 0;
+    var t = (a + b) | 0;
+    a = b ^ (b >>> 9);
+    b = (c + (c << 3)) | 0;
+    c = (c << 21) | (c >>> 11);
+    d = (d + 1) | 0;
+    t = (t + d) | 0;
+    c = (c + t) | 0;
+    return (t >>> 0) / 4294967296;
+}
+/**
+ * SplitMix32, Generator with a 32-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export function splitmix32(a) {
+    a |= 0;
+    a = (a + 0x9e3779b9) | 0;
+    var t = a ^ (a >>> 16);
+    t = Math.imul(t, 0x21f0aaad);
+    t = t ^ (t >>> 15);
+    t = Math.imul(t, 0x735a2d97);
+    return ((t = t ^ (t >>> 15)) >>> 0) / 4294967296;
+}
+/**
+ * Mulberry32, Generator with a 32-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export function mulberry32(a) {
+    var t = (a += 0x6d2b79f5);
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+/**
+ * Jenkins' Small Fast, Generator with a 32-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export function jsf32(a, b, c, d) {
+    a |= 0;
+    b |= 0;
+    c |= 0;
+    d |= 0;
+    var t = (a - ((b << 27) | (b >>> 5))) | 0;
+    a = b ^ ((c << 17) | (c >>> 15));
+    b = (c + d) | 0;
+    c = (d + t) | 0;
+    d = (a + t) | 0;
+    return (d >>> 0) / 4294967296;
+}
+/**
+ * xoshiro128**, Generator with a 128-bit state
+ *
+ * @param {number} a
+ * @returns {number} Pseudo-random number
+ */
+export function xoshiro128ss(a, b, c, d) {
+    var t = b << 9;
+    var r = a * 5;
+    r = ((r << 7) | (r >>> 25)) * 9;
+    c ^= a;
+    d ^= b;
+    b ^= c;
+    a ^= d;
+    c ^= t;
+    d = (d << 11) | (d >>> 21);
+    return (r >>> 0) / 4294967296;
+}
+/**
+ * Generate a pseudo-random number in the interval [0, 1]
+ * PRNG equivalent of `Math.random()`
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @returns {number} Pseudo-random number
+ */
+export function random(prng) {
+    var seed = typeof prng === 'string' ? prng : prng.seed;
+    var algorithm = typeof prng === 'string' ? splitmix32 : prng.algorithm;
+    var hashes = cyrb128(seed);
+    return algorithm.apply(void 0, hashes);
+}
+/**
+ * Generate a pseudo-random boolean (true or false)
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {number} [probability=0.5] Probability to get true
+ * @returns {boolean} Either `true` or `false`
+ */
+export function randomBoolean(prng, probability) {
+    if (probability === void 0) { probability = 0.5; }
+    return random(prng) < probability;
+}
+/**
+ * Generate a pseudo-random sign (1 or -1)
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {number} [probability=0.5] Probability to get 1
+ * @returns {number} Either 1 or -1
+ */
+export function randomSign(prng, probability) {
+    if (probability === void 0) { probability = 0.5; }
+    return randomBoolean(prng, probability) ? 1 : -1;
+}
+/**
+ * Generate a pseudo-random floating-point number within a specified range
+ *
+ * @param {PRNGParameters} prng  PRNG parameters
+ * @param {number} [min=0]       Minimum boundary
+ * @param {number} [max=1]       Maximum boundary
+ * @param {number} [precision=2] Number of digits after the decimal point
+ * @returns {number} Generated float
+ */
+export function randomFloat(prng, min, max, precision) {
+    if (min === void 0) { min = 0; }
+    if (max === void 0) { max = 1; }
+    if (precision === void 0) { precision = 2; }
+    return parseFloat(Math.min(min + random(prng) * (max - min), max).toFixed(precision));
+}
+/**
+ * Generate a pseudo-random integer number within a specified range
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {number} min          Minimum boundary
+ * @param {number} max          Maximum boundary
+ * @returns {number} Generated integer
+ */
+export function randomInt(prng, min, max) {
+    return Math.floor(random(prng) * (max - min + 1) + min);
+}
+/**
+ * Generate a pseudo-random hexadecimal color
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @returns {string} Generated hexadecimal color
+ */
+export function randomHexColor(prng) {
+    return '#' + ('00000' + ((random(prng) * (1 << 24)) | 0).toString(16)).slice(-6);
+}
+/**
+ * Pick a pseudo-random item from a given array
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {T[]} array           Array to pick the item from
+ * @returns {T|undefined} Random item picked
+ */
+export function randomItem(prng, array) {
+    if (array.length === 0)
+        return undefined;
+    return array[randomInt(prng, 0, array.length - 1)];
+}
+/**
+ * Pick a pseudo-random property value from a given object
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {object} object       Object to pick the property from
+ * @returns {T|undefined} Random item picked
+ */
+export function randomObjectProperty(prng, object) {
+    var keys = Object.keys(object);
+    var key = randomItem(prng, keys);
+    if (key && object.hasOwnProperty(key)) {
+        return object[key];
+    }
+}
+/**
+ * Select a pseudo-random index from an array of weighted items
+ *
+ * @param {PRNGParameters} prng PRNG parameters
+ * @param {number[]} weights    Array of weights
+ * @returns {number} Random index based on weights
+ */
+export function randomIndex(prng, weights) {
+    if (weights.length === 0)
+        return -1;
+    var totalWeight = 0;
+    for (var _i = 0, weights_1 = weights; _i < weights_1.length; _i++) {
+        var weight_1 = weights_1[_i];
+        totalWeight += weight_1;
+    }
+    if (totalWeight <= 0)
+        console.warn('PRNG randomIndex()', 'Weights must sum to > 0', totalWeight);
+    var weight = random(prng) * totalWeight;
+    for (var i = 0; i < weights.length; i++) {
+        if (weight < weights[i])
+            return i;
+        weight -= weights[i];
+    }
+    return 0;
+}

package/lib/random.d.ts

@@ -0,0 +1,91 @@
+import { Vector2, Vector3 } from './types';
+/**
+ * Generate a random boolean (true or false)
+ *
+ * @param {number} [probability=0.5] Probability to get true
+ * @returns {boolean} Either `true` or `false`
+ */
+export declare function randomBoolean(probability?: number): boolean;
+/**
+ * Generate a random sign (1 or -1)
+ *
+ * @param {number} [probability=0.5] Probability to get 1
+ * @returns {number} Either 1 or -1
+ */
+export declare function randomSign(probability?: number): number;
+/**
+ * Generate a random floating-point number within a specified range
+ *
+ * @param {number} [min=0]       Minimum boundary
+ * @param {number} [max=1]       Maximum boundary
+ * @param {number} [precision=2] Number of digits after the decimal point
+ * @returns {number} Generated float
+ */
+export declare function randomFloat(min?: number, max?: number, precision?: number): number;
+/**
+ * Generate a random integer number within a specified range
+ *
+ * @param {number} min Minimum boundary
+ * @param {number} max Maximum boundary
+ * @returns {number} Generated integer
+ */
+export declare function randomInt(min: number, max: number): number;
+/**
+ * Generate a random hexadecimal color
+ *
+ * @returns {string} Generated hexadecimal color
+ */
+export declare function randomHexColor(): string;
+/**
+ * Pick a random item from a given array
+ *
+ * @param {T[]} array Array to pick the item from
+ * @returns {T|undefined} Random item picked
+ */
+export declare function randomItem<T = unknown>(array: T[]): T | undefined;
+/**
+ * Pick a random property value from a given object
+ *
+ * @param {object} object Object to pick the property from
+ * @returns {T|undefined} Random item picked
+ */
+export declare function randomObjectProperty<T = unknown>(object: Record<string, T>): T | undefined;
+/**
+ * Select a random index from an array of weighted items
+ *
+ * @param {number[]} weights Array of weights
+ * @returns {number} Random index based on weights
+ */
+export declare function randomIndex(weights: number[]): number;
+/**
+ * Produce a random 2D point around the perimiter of a unit circle
+ *
+ * @param  {number} [radius=1]        Radius of the circle
+ * @param  {Vector2} [target] Target vector
+ * @returns {Vector2} Random 2D point on circle
+ */
+export declare function onCircle(radius?: number, target?: Vector2): Vector2;
+/**
+ * Produce a random 2D point inside a unit circle
+ *
+ * @param  {number} [radius=1]        Radius of the circle
+ * @param  {Vector2} [target] Target vector
+ * @returns {Vector2} Random 2D point inside circle
+ */
+export declare function insideCircle(radius?: number, target?: Vector2): Vector2;
+/**
+ * Produce a random 3D point on the surface of a unit sphere
+ *
+ * @param  {number} [radius=1]        Radius of the sphere
+ * @param  {Vector3} [target] Target vector
+ * @returns {Vector3} Random 3D point on sphere
+ */
+export declare function onSphere(radius?: number, target?: Vector3): Vector3;
+/**
+ * Produce a random 3D point inside a unit sphere
+ *
+ * @param  {number} [radius=1]        Radius of the sphere
+ * @param  {Vector3} [target] Target vector
+ * @returns {Vector3} Random 3D point inside sphere
+ */
+export declare function insideSphere(radius?: number, target?: Vector3): Vector3;