toosoon-utils 1.0.0

package/lib/maths.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Check if a number is even
+ *
+ * @param {number} value Value to check
+ * @returns {boolean} True if the given number is even, false otherwise
+ */
+export declare function isEven(value: number): boolean;
+/**
+ * Check if a number is odd
+ *
+ * @param {number} value Value to check
+ * @returns {boolean} True if the given number is odd, false otherwise
+ */
+export declare function isOdd(value: number): boolean;
+/**
+ * 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 declare function isPowerOf2(value: number): boolean;
+/**
+ * Find smallest/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 declare function toPowerOf2(value: number, mode?: 'floor' | 'ceil' | 'round'): number;
+/**
+ * Return the sign (positive or negative) of a number
+ *
+ * @param {number} number Value to check
+ * @returns {number} 1 if the given number is positive, -1 if it is negative, otherwise 0
+ */
+export declare function sign(number: number): number;
+/**
+ * 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 declare function clamp(value: number, min?: number, max?: number): number;
+/**
+ * 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 declare function lerp(value: number, min: number, max: number): number;
+/**
+ * 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 declare function triLerp(value: number, min: number, max: number, target: number): number;
+/**
+ * Exponential interpolation between two values
+ *
+ * @param {number} value Normalized value to interpolate
+ * @param {number} min   Minimum value
+ * @param {number} max   Maximum value
+ * @returns {number} Interpolated value
+ */
+export declare function expLerp(value: number, min: number, max: number): number;
+/**
+ * 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 declare function normalize(value: number, min: number, max: number): number;
+/**
+ * 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 declare function map(value: number, currentMin: number, currentMax: number, targetMin: number, targetMax: number): number;
+/**
+ * Round a number up to a nearest multiple
+ *
+ * @param {number} value        Value to round
+ * @param {number} [multiple=1] Multiple
+ * @returns {number} Closest multiple
+ */
+export declare function roundTo(value: number, multiple?: number): number;
+/**
+ * Modulo absolute a value based on a length
+ *
+ * @param {number} value  Value to modulate
+ * @param {number} length Total length
+ * @returns {number} Modulated value
+ */
+export declare function modAbs(value: number, length: number): number;
+/**
+ * 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 declare function pingPong(value: number, length: number): number;
+/**
+ * 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 declare function smoothstep(value: number, min?: number, max?: number): number;
+/**
+ * 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 declare function parabola(x: number, power?: number): number;
+/**
+ * Return the sum of numbers
+ *
+ * @param {number[]} array Array of number
+ * @returns {number} Total sum
+ */
+export declare function sum(array: number[]): number;
+/**
+ * Return the average of numbers
+ *
+ * @param {number[]} array Array of number
+ * @returns {number} Total average
+ */
+export declare function average(array: number[]): number;
+/**
+ * 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 declare function damp(value: number, target: number, damping: number, delta: number): number;

package/lib/maths.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.damp = exports.average = exports.sum = exports.parabola = exports.smoothstep = exports.pingPong = exports.modAbs = exports.roundTo = exports.map = exports.normalize = exports.expLerp = exports.triLerp = exports.lerp = exports.clamp = exports.sign = exports.toPowerOf2 = exports.isPowerOf2 = exports.isOdd = exports.isEven = void 0;
+/**
+ * Check if a number is even
+ *
+ * @param {number} value Value to check
+ * @returns {boolean} True if the given number is even, false otherwise
+ */
+function isEven(value) {
+    return !(value & 1);
+}
+exports.isEven = isEven;
+/**
+ * Check if a number is odd
+ *
+ * @param {number} value Value to check
+ * @returns {boolean} True if the given number is odd, false otherwise
+ */
+function isOdd(value) {
+    return !!(value & 1);
+}
+exports.isOdd = isOdd;
+/**
+ * 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
+ */
+function isPowerOf2(value) {
+    return (value & (value - 1)) === 0;
+}
+exports.isPowerOf2 = isPowerOf2;
+/**
+ * Find smallest/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
+ */
+function toPowerOf2(value, mode) {
+    if (mode === void 0) { mode = 'ceil'; }
+    return Math.pow(2, Math[mode](Math.log(value) / Math.log(2)));
+}
+exports.toPowerOf2 = toPowerOf2;
+/**
+ * Return the sign (positive or negative) of a number
+ *
+ * @param {number} number Value to check
+ * @returns {number} 1 if the given number is positive, -1 if it is negative, otherwise 0
+ */
+function sign(number) {
+    if (number > 0)
+        return 1;
+    else if (number < 0)
+        return -1;
+    return 0;
+}
+exports.sign = sign;
+/**
+ * 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
+ */
+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));
+}
+exports.clamp = clamp;
+/**
+ * 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
+ */
+function lerp(value, min, max) {
+    return min + (max - min) * value;
+}
+exports.lerp = lerp;
+/**
+ * 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
+ */
+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));
+}
+exports.triLerp = triLerp;
+/**
+ * Exponential interpolation between two values
+ *
+ * @param {number} value Normalized value to interpolate
+ * @param {number} min   Minimum value
+ * @param {number} max   Maximum value
+ * @returns {number} Interpolated value
+ */
+function expLerp(value, min, max) {
+    return Math.pow(min, 1 - value) * Math.pow(max, value);
+}
+exports.expLerp = expLerp;
+/**
+ * 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
+ */
+function normalize(value, min, max) {
+    return (value - min) / (max - min);
+}
+exports.normalize = normalize;
+/**
+ * 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
+ */
+function map(value, currentMin, currentMax, targetMin, targetMax) {
+    return ((value - currentMin) / (currentMax - currentMin)) * (targetMax - targetMin) + targetMin;
+}
+exports.map = map;
+/**
+ * Round a number up to a nearest multiple
+ *
+ * @param {number} value        Value to round
+ * @param {number} [multiple=1] Multiple
+ * @returns {number} Closest multiple
+ */
+function roundTo(value, multiple) {
+    if (multiple === void 0) { multiple = 1; }
+    if (multiple === 0)
+        return value;
+    return Math.round(value / multiple) * multiple;
+}
+exports.roundTo = roundTo;
+/**
+ * Modulo absolute a value based on a length
+ *
+ * @param {number} value  Value to modulate
+ * @param {number} length Total length
+ * @returns {number} Modulated value
+ */
+function modAbs(value, length) {
+    if (value < 0) {
+        return length + (value % length);
+    }
+    return value % length;
+}
+exports.modAbs = modAbs;
+/**
+ * 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
+ */
+function pingPong(value, length) {
+    value = modAbs(value, length * 2);
+    return length - Math.abs(value - length);
+}
+exports.pingPong = pingPong;
+/**
+ * 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
+ */
+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);
+}
+exports.smoothstep = smoothstep;
+/**
+ * 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
+ */
+function parabola(x, power) {
+    if (power === void 0) { power = 1; }
+    return Math.pow(4 * x * (1 - x), power);
+}
+exports.parabola = parabola;
+/**
+ * Return the sum of numbers
+ *
+ * @param {number[]} array Array of number
+ * @returns {number} Total sum
+ */
+function sum(array) {
+    return array.reduce(function (previous, current) { return previous + current; });
+}
+exports.sum = sum;
+/**
+ * Return the average of numbers
+ *
+ * @param {number[]} array Array of number
+ * @returns {number} Total average
+ */
+function average(array) {
+    return sum(array) / array.length;
+}
+exports.average = average;
+/**
+ * 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
+ */
+function damp(value, target, damping, delta) {
+    return lerp(1 - Math.exp(-damping * delta), value, target);
+}
+exports.damp = damp;

package/lib/now.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Polyfill for "now()" functions
+ */
+declare let now: () => number;
+export default now;

package/lib/now.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Polyfill for "now()" functions
+ */
+var now;
+// In node.js, use process.hrtime
+if (typeof process !== 'undefined' && process.hrtime) {
+    now = function () {
+        // Convert [seconds, nanoseconds] to milliseconds
+        var time = process.hrtime();
+        return time[0] * 1000 + time[1] / 1000000;
+    };
+}
+// In a browser use performance or Date
+else if (typeof performance !== 'undefined') {
+    // This must be bound, because directly assigning this function leads to an invocation exception in Chrome
+    now = performance.now.bind(performance);
+}
+else if (typeof Date.now !== 'undefined') {
+    now = Date.now;
+}
+else {
+    now = function () {
+        return new Date().getTime();
+    };
+}
+exports.default = now;

package/lib/random.d.ts

@@ -0,0 +1,91 @@
+import { Vector2, Vector3 } from './types';
+/**
+ * Generate 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 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 float
+ *
+ * @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
+ *
+ * @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} Hexadecimal color
+ */
+export declare function randomHexColor(): string;
+/**
+ * Pick a random item from an array
+ *
+ * @param {I[]} [array=[]] Array to pick the item from
+ * @returns {I|undefined} Random item picked
+ */
+export declare function randomItem<I = unknown>(array?: I[]): I | undefined;
+/**
+ * Pick a random property from an object
+ *
+ * @param {object} [object={}] Object to pick the property from
+ * @returns {unknown|undefined} Random item picked
+ */
+export declare function randomObjectProperty(object?: object): unknown | undefined;
+/**
+ * Return a random index from an array of weights
+ *
+ * @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;

package/lib/random.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.insideSphere = exports.onSphere = exports.insideCircle = exports.onCircle = exports.randomIndex = exports.randomObjectProperty = exports.randomItem = exports.randomHexColor = exports.randomInt = exports.randomFloat = exports.randomSign = exports.randomBoolean = void 0;
+var geometry_1 = require("./geometry");
+/**
+ * Generate random boolean (true or false)
+ *
+ * @param {number} [probability=0.5] Probability to get true
+ * @returns {boolean} Either true or false
+ */
+function randomBoolean(probability) {
+    if (probability === void 0) { probability = 0.5; }
+    return Math.random() < probability;
+}
+exports.randomBoolean = randomBoolean;
+/**
+ * Generate random sign (1 or -1)
+ *
+ * @param {number} [probability=0.5] Probability to get 1
+ * @returns {number} Either 1 or -1
+ */
+function randomSign(probability) {
+    if (probability === void 0) { probability = 0.5; }
+    return randomBoolean(probability) ? 1 : -1;
+}
+exports.randomSign = randomSign;
+/**
+ * Generate a random float
+ *
+ * @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
+ */
+function randomFloat(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 + Math.random() * (max - min), max).toFixed(precision));
+}
+exports.randomFloat = randomFloat;
+/**
+ * Generate a random integer
+ *
+ * @param {number} min Minimum boundary
+ * @param {number} max Maximum boundary
+ * @returns {number} Generated integer
+ */
+function randomInt(min, max) {
+    return Math.floor(Math.random() * (max - min + 1) + min);
+}
+exports.randomInt = randomInt;
+/**
+ * Generate a random hexadecimal color
+ *
+ * @returns {string} Hexadecimal color
+ */
+function randomHexColor() {
+    return '#' + ('00000' + ((Math.random() * (1 << 24)) | 0).toString(16)).slice(-6);
+}
+exports.randomHexColor = randomHexColor;
+/**
+ * Pick a random item from an array
+ *
+ * @param {I[]} [array=[]] Array to pick the item from
+ * @returns {I|undefined} Random item picked
+ */
+function randomItem(array) {
+    if (array === void 0) { array = []; }
+    if (array.length === 0)
+        return undefined;
+    return array[randomInt(0, array.length - 1)];
+}
+exports.randomItem = randomItem;
+/**
+ * Pick a random property from an object
+ *
+ * @param {object} [object={}] Object to pick the property from
+ * @returns {unknown|undefined} Random item picked
+ */
+function randomObjectProperty(object) {
+    if (object === void 0) { object = {}; }
+    var keys = Object.keys(object);
+    var key = randomItem(keys);
+    if (key && object.hasOwnProperty(key)) {
+        return object[key];
+    }
+}
+exports.randomObjectProperty = randomObjectProperty;
+/**
+ * Return a random index from an array of weights
+ *
+ * @param {number[]} weights Array of weights
+ * @returns {number} Random index based on weights
+ */
+function randomIndex(weights) {
+    if (weights === void 0) { weights = []; }
+    if (weights.length === 0)
+        return -1;
+    var totalWeight = 0;
+    for (var _i = 0, weights_1 = weights; _i < weights_1.length; _i++) {
+        var weight = weights_1[_i];
+        totalWeight += weight;
+    }
+    if (totalWeight <= 0) {
+        console.warn('randomIndex()', 'Weights must sum to > 0', totalWeight);
+    }
+    var random = Math.random() * totalWeight;
+    for (var i = 0; i < weights.length; i++) {
+        if (random < weights[i])
+            return i;
+        random -= weights[i];
+    }
+    return 0;
+}
+exports.randomIndex = randomIndex;
+// *********************
+// Geometry
+// *********************
+/**
+ * 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
+ */
+function onCircle(radius, target) {
+    if (radius === void 0) { radius = 1; }
+    if (target === void 0) { target = { x: 0, y: 0 }; }
+    var angle = Math.random() * 2.0 * Math.PI;
+    target.x = radius * Math.cos(angle);
+    target.y = radius * Math.sin(angle);
+    return target;
+}
+exports.onCircle = onCircle;
+/**
+ * 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
+ */
+function insideCircle(radius, target) {
+    if (radius === void 0) { radius = 1; }
+    if (target === void 0) { target = { x: 0, y: 0 }; }
+    radius *= Math.random();
+    return onCircle(radius, target);
+}
+exports.insideCircle = insideCircle;
+/**
+ * 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
+ */
+function onSphere(radius, target) {
+    if (radius === void 0) { radius = 1; }
+    if (target === void 0) { target = { x: 0, y: 0, z: 0 }; }
+    var u = Math.random() * Math.PI * 2;
+    var v = Math.random() * 2 - 1;
+    var phi = u;
+    var theta = Math.acos(v);
+    return (0, geometry_1.radToSphere)(radius, phi, theta, target);
+}
+exports.onSphere = onSphere;
+/**
+ * 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
+ */
+function insideSphere(radius, target) {
+    if (radius === void 0) { radius = 1; }
+    if (target === void 0) { target = { x: 0, y: 0, z: 0 }; }
+    radius *= Math.random();
+    return onSphere(radius, target);
+}
+exports.insideSphere = insideSphere;