toosoon-utils 4.2.3 → 4.3.1

package/lib/geometry.d.ts

@@ -25,18 +25,18 @@ export declare function angle(x1: number, y1: number, x2: number, y2: number): n
 /**
  * Find the closest angle between to angles
  *
- * @param {number} source Source angle (in radians)
- * @param {number} target Target angle (in radians)
+ * @param {number} startAngle Start angle (in radians)
+ * @param {number} endAngle End angle (in radians)
  * @returns {number} Closest angle
  */
-export declare function closestAngle(source: number, target: number): number;
+export declare function closestAngle(startAngle: number, endAngle: number): number;
 /**
  * Calculate the distance between two points
  *
- * @param {number} x1 X-axis coordinate of the first point
- * @param {number} y1 Y-axis coordinate of the first point
- * @param {number} x2 X-axis coordinate of the second point
- * @param {number} y2 Y-axis coordinate of the second point
+ * @param {number} x1 X-axis coordinate of the start point
+ * @param {number} y1 Y-axis coordinate of the start point
+ * @param {number} x2 X-axis coordinate of the end point
+ * @param {number} y2 Y-axis coordinate of the end point
  * @returns {number} Computed distance
  */
 export declare function distance(x1: number, y1: number, x2: number, y2: number): number;

package/lib/geometry.js

@@ -32,21 +32,21 @@ export function angle(x1, y1, x2, y2) {
 /**
  * Find the closest angle between to angles
  *
- * @param {number} source Source angle (in radians)
- * @param {number} target Target angle (in radians)
+ * @param {number} startAngle Start angle (in radians)
+ * @param {number} endAngle End angle (in radians)
  * @returns {number} Closest angle
  */
-export function closestAngle(source, target) {
-    const delta = target - source;
-    return delta > PI ? target - 2 * PI : target < -PI ? delta + 2 * PI : target;
+export function closestAngle(startAngle, endAngle) {
+    const delta = endAngle - startAngle;
+    return delta > PI ? endAngle - 2 * PI : endAngle < -PI ? delta + 2 * PI : endAngle;
 }
 /**
  * Calculate the distance between two points
  *
- * @param {number} x1 X-axis coordinate of the first point
- * @param {number} y1 Y-axis coordinate of the first point
- * @param {number} x2 X-axis coordinate of the second point
- * @param {number} y2 Y-axis coordinate of the second point
+ * @param {number} x1 X-axis coordinate of the start point
+ * @param {number} y1 Y-axis coordinate of the start point
+ * @param {number} x2 X-axis coordinate of the end point
+ * @param {number} y2 Y-axis coordinate of the end point
  * @returns {number} Computed distance
  */
 export function distance(x1, y1, x2, y2) {
@@ -67,10 +67,10 @@ export function diagonal(width, height) {
 /**
  * Make a target fit a container
  *
- * @param {object} target    Dimensions of the target
- * @param {object} container Dimensions of the container
- * @param {'contain'|'cover'} mode      Can be 'contain' | 'cover'
- * @returns {object}
+ * @param {FitInput} target    Dimensions of the target
+ * @param {FitInput} container Dimensions of the container
+ * @param {string} mode        Can be 'contain' | 'cover'
+ * @returns {FitOutput}
  */
 function fit(target, container, mode) {
     const ratioWidth = container.width / target.width;

package/lib/maths.d.ts

@@ -24,7 +24,7 @@ export declare function isPowerOf2(value: number): boolean;
  *
  * @param {number} value         Incoming value
  * @param {string} [mode='ceil'] Can be 'floor' | 'ceil' | 'round'
- * @returns {number} Power of 2
+ * @returns {number} Computed power of 2
  */
 export declare function toPowerOf2(value: number, mode?: 'floor' | 'ceil' | 'round'): number;
 /**
@@ -83,24 +83,29 @@ export declare function map(value: number, currentMin: number, currentMax: numbe
 /**
  * Interpolate a value between two values using Triangular interpolation
  *
- * @param {number} t      Normalized time value to interpolate
- * @param {number} min    Minimum value
- * @param {number} max    Maximum value
- * @param {number} target Triangle target value
+ * @param {number} t    Normalized time value to interpolate
+ * @param {number} min  Minimum value
+ * @param {number} max  Maximum value
+ * @param {number} peak Peak value controling the interpolation triangle shape
+ *                        - peak <= min : linear (same as lerp)
+ *                        - peak <= max : linear (same as lerp)
+ *                        - peak > min && peak > max : triangular
  * @returns {number} Interpolated value
  */
-export declare function triLerp(t: number, min: number, max: number, target: number): number;
+export declare function triLerp(t: number, min: number, max: number, peak: number): number;
 /**
  * Interpolate a value using Exponential interpolation
  *
- * @param {number} t          Normalized time 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
+ * @param {number} t     Normalized time value to interpolate
+ * @param {number} min   Minimum value
+ * @param {number} max   Maximum value
+ * @param {number} power Exponent controling the interpolation curve shape
+ *                         - power > 1 : ease-in
+ *                         - power < 1 : ease-out
+ *                         - power = 1 : linear (same as lerp)
  * @returns {number} Interpolated value
  */
-export declare function expLerp(t: number, currentMin: number, currentMax: number, targetMin: number, targetMax: number): number;
+export declare function expLerp(t: number, min: number, max: number, power: number): number;
 /**
  * Interpolate a value using Quadratic Bézier interpolation
  *
@@ -160,7 +165,8 @@ export declare function pingPong(value: number, length: number): number;
 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
+ *  - parabola(0) = parabola(1) = 0
+ *  - parabola(0.5) = 1
  *
  * @param {number} x         Normalized coordinate on X axis
  * @param {number} [power=1] Parabola power

package/lib/maths.js

@@ -30,7 +30,7 @@ export function isPowerOf2(value) {
  *
  * @param {number} value         Incoming value
  * @param {string} [mode='ceil'] Can be 'floor' | 'ceil' | 'round'
- * @returns {number} Power of 2
+ * @returns {number} Computed power of 2
  */
 export function toPowerOf2(value, mode = 'ceil') {
     return Math.pow(2, Math[mode](Math.log(value) / Math.log(2)));
@@ -109,29 +109,34 @@ export function map(value, currentMin, currentMax, targetMin, targetMax) {
 /**
  * Interpolate a value between two values using Triangular interpolation
  *
- * @param {number} t      Normalized time value to interpolate
- * @param {number} min    Minimum value
- * @param {number} max    Maximum value
- * @param {number} target Triangle target value
+ * @param {number} t    Normalized time value to interpolate
+ * @param {number} min  Minimum value
+ * @param {number} max  Maximum value
+ * @param {number} peak Peak value controling the interpolation triangle shape
+ *                        - peak <= min : linear (same as lerp)
+ *                        - peak <= max : linear (same as lerp)
+ *                        - peak > min && peak > max : triangular
  * @returns {number} Interpolated value
  */
-export function triLerp(t, min, max, target) {
-    const x = Math.pow(1 + Math.abs(target - max) / Math.abs(target - min), -1);
-    return t <= x ? min - (min - target) * (t / x) : target - (target - max) * ((t - x) / (1 - x));
+export function triLerp(t, min, max, peak) {
+    const x = Math.pow(1 + Math.abs(peak - max) / Math.abs(peak - min), -1);
+    return t <= x ? min - (min - peak) * (t / x) : peak - (peak - max) * ((t - x) / (1 - x));
 }
 /**
  * Interpolate a value using Exponential interpolation
  *
- * @param {number} t          Normalized time 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
+ * @param {number} t     Normalized time value to interpolate
+ * @param {number} min   Minimum value
+ * @param {number} max   Maximum value
+ * @param {number} power Exponent controling the interpolation curve shape
+ *                         - power > 1 : ease-in
+ *                         - power < 1 : ease-out
+ *                         - power = 1 : linear (same as lerp)
  * @returns {number} Interpolated value
  */
-export function expLerp(t, currentMin, currentMax, targetMin, targetMax) {
-    return (targetMin *
-        Math.pow(targetMax / targetMin, (clamp(t, currentMin, currentMax) - currentMin) / (currentMax - currentMin)));
+export function expLerp(t, min, max, power) {
+    const factor = Math.pow(t, power);
+    return min + (max - min) * factor;
 }
 /**
  * Interpolate a value using Quadratic Bézier interpolation
@@ -221,7 +226,8 @@ export function smoothstep(value, min = 0, max = 1) {
 }
 /**
  * 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
+ *  - parabola(0) = parabola(1) = 0
+ *  - parabola(0.5) = 1
  *
  * @param {number} x         Normalized coordinate on X axis
  * @param {number} [power=1] Parabola power

package/lib/prng.d.ts

@@ -60,7 +60,7 @@ export declare function random(prng: PRNGParameters): number;
  *
  * @param {PRNGParameters} prng PRNG parameters
  * @param {number} [probability=0.5] Probability to get true
- * @returns {boolean} Either `true` or `false`
+ * @returns {boolean} Either true or false
  */
 export declare function randomBoolean(prng: PRNGParameters, probability?: number): boolean;
 /**
@@ -101,8 +101,8 @@ 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
+ * @param {unknown[]} array     Array to pick the item from
+ * @returns {unknown|undefined} Random item picked
  */
 export declare function randomItem<T = unknown>(prng: PRNGParameters, array: T[]): T | undefined;
 /**
@@ -110,7 +110,7 @@ export declare function randomItem<T = unknown>(prng: PRNGParameters, array: T[]
  *
  * @param {PRNGParameters} prng PRNG parameters
  * @param {object} object       Object to pick the property from
- * @returns {T|undefined} Random item picked
+ * @returns {unknown|undefined} Random item picked
  */
 export declare function randomObjectProperty<T = unknown>(prng: PRNGParameters, object: Record<string, T>): T | undefined;
 /**

package/lib/prng.js

@@ -129,7 +129,7 @@ export function random(prng) {
  *
  * @param {PRNGParameters} prng PRNG parameters
  * @param {number} [probability=0.5] Probability to get true
- * @returns {boolean} Either `true` or `false`
+ * @returns {boolean} Either true or false
  */
 export function randomBoolean(prng, probability = 0.5) {
     return random(prng) < probability;
@@ -180,8 +180,8 @@ export function randomHexColor(prng) {
  * 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
+ * @param {unknown[]} array     Array to pick the item from
+ * @returns {unknown|undefined} Random item picked
  */
 export function randomItem(prng, array) {
     if (array.length === 0)
@@ -193,7 +193,7 @@ export function randomItem(prng, array) {
  *
  * @param {PRNGParameters} prng PRNG parameters
  * @param {object} object       Object to pick the property from
- * @returns {T|undefined} Random item picked
+ * @returns {unknown|undefined} Random item picked
  */
 export function randomObjectProperty(prng, object) {
     const keys = Object.keys(object);

package/lib/random.d.ts

@@ -3,7 +3,7 @@ import type { Point2, Point3 } from './types';
  * Generate a random boolean (true or false)
  *
  * @param {number} [probability=0.5] Probability to get true
- * @returns {boolean} Either `true` or `false`
+ * @returns {boolean} Either true or false
  */
 export declare function randomBoolean(probability?: number): boolean;
 /**
@@ -39,15 +39,15 @@ 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
+ * @param {unknown[]} array Array to pick the item from
+ * @returns {unknown|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
+ * @returns {unknown|undefined} Random item picked
  */
 export declare function randomObjectProperty<T = unknown>(object: Record<string, T>): T | undefined;
 /**

package/lib/random.js

@@ -3,7 +3,7 @@ import { Vector2, Vector3 } from './extras/geometry';
  * Generate a random boolean (true or false)
  *
  * @param {number} [probability=0.5] Probability to get true
- * @returns {boolean} Either `true` or `false`
+ * @returns {boolean} Either true or false
  */
 export function randomBoolean(probability = 0.5) {
     return Math.random() < probability;
@@ -49,8 +49,8 @@ export function randomHexColor() {
 /**
  * Pick a random item from a given array
  *
- * @param {T[]} array Array to pick the item from
- * @returns {T|undefined} Random item picked
+ * @param {unknown[]} array Array to pick the item from
+ * @returns {unknown|undefined} Random item picked
  */
 export function randomItem(array) {
     if (array.length === 0)
@@ -61,7 +61,7 @@ export function randomItem(array) {
  * Pick a random property value from a given object
  *
  * @param {object} object Object to pick the property from
- * @returns {T|undefined} Random item picked
+ * @returns {unknown|undefined} Random item picked
  */
 export function randomObjectProperty(object) {
     const keys = Object.keys(object);

package/lib/strings.d.ts

@@ -6,42 +6,48 @@
  */
 export declare function capitalize(string: string): string;
 /**
- * Convert a string to kebab-case: 'Hello world' -> 'hello-world'
+ * Convert a string to kebab-case
+ *  - 'Hello world' -> 'hello-world'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
  */
 export declare function toKebabCase(string: string): string;
 /**
- * Convert a string to snake_case: 'Hello world' -> 'hello_world'
+ * Convert a string to snake_case
+ *   - 'Hello world' -> 'hello_world'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
  */
 export declare function toSnakeCase(string: string): string;
 /**
- * Convert a string to camelCase: 'Hello world' -> 'helloWorld'
+ * Convert a string to camelCase
+ *   - 'Hello world' -> 'helloWorld'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
  */
 export declare function toCamelCase(string: string): string;
 /**
- * Convert a string to PascalCase: 'Hello world' -> 'HelloWorld'
+ * Convert a string to PascalCase
+ *   - 'Hello world' -> 'HelloWorld'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
  */
 export declare function toPascalCase(string: string): string;
 /**
- * Convert a string to Train-Case: 'Hello world' -> 'Hello-World'
+ * Convert a string to Train-Case
+ *   - 'Hello world' -> 'Hello-World'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
  */
 export declare function toTrainCase(string: string): string;
 /**
- * Convert a string to CONSTANT_CASE: 'Hello world' -> 'HELLO_WORLD'
+ * Convert a string to CONSTANT_CASE
+ *   - 'Hello world' -> 'HELLO_WORLD'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
@@ -58,13 +64,13 @@ export declare function cleanPath(path: string): string;
  * Convert a path by ensuring it has a trailing slash
  *
  * @param {string} path Path to convert
- * @returns {string}
+ * @returns {string} Converted path
  */
 export declare function addTrailingSlash(path: string): string;
 /**
  * Convert a path by ensuring it has not a trailing slash
  *
  * @param {string} path Path to convert
- * @returns {string}
+ * @returns {string} Converted path
  */
 export declare function removeTrailingSlash(path: string): string;

package/lib/strings.js

@@ -11,7 +11,8 @@ export function capitalize(string) {
     return string.charAt(0).toUpperCase() + string.slice(1);
 }
 /**
- * Convert a string to kebab-case: 'Hello world' -> 'hello-world'
+ * Convert a string to kebab-case
+ *  - 'Hello world' -> 'hello-world'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
@@ -25,7 +26,8 @@ export function toKebabCase(string) {
         .toLowerCase());
 }
 /**
- * Convert a string to snake_case: 'Hello world' -> 'hello_world'
+ * Convert a string to snake_case
+ *   - 'Hello world' -> 'hello_world'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
@@ -39,7 +41,8 @@ export function toSnakeCase(string) {
         .toLowerCase());
 }
 /**
- * Convert a string to camelCase: 'Hello world' -> 'helloWorld'
+ * Convert a string to camelCase
+ *   - 'Hello world' -> 'helloWorld'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
@@ -52,7 +55,8 @@ export function toCamelCase(string) {
         .replace(/^([A-Z])/, (c) => c.toLowerCase()));
 }
 /**
- * Convert a string to PascalCase: 'Hello world' -> 'HelloWorld'
+ * Convert a string to PascalCase
+ *   - 'Hello world' -> 'HelloWorld'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
@@ -65,7 +69,8 @@ export function toPascalCase(string) {
         .replace(/^([a-z])/, (c) => c.toUpperCase()));
 }
 /**
- * Convert a string to Train-Case: 'Hello world' -> 'Hello-World'
+ * Convert a string to Train-Case
+ *   - 'Hello world' -> 'Hello-World'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
@@ -81,7 +86,8 @@ export function toTrainCase(string) {
         .replace(/\b\w/g, (c) => c.toUpperCase()));
 }
 /**
- * Convert a string to CONSTANT_CASE: 'Hello world' -> 'HELLO_WORLD'
+ * Convert a string to CONSTANT_CASE
+ *   - 'Hello world' -> 'HELLO_WORLD'
  *
  * @param {string} string String to convert
  * @returns {string} Converted string
@@ -110,7 +116,7 @@ export function cleanPath(path) {
  * Convert a path by ensuring it has a trailing slash
  *
  * @param {string} path Path to convert
- * @returns {string}
+ * @returns {string} Converted path
  */
 export function addTrailingSlash(path) {
     if (path.match(/\.[a-z]{2,4}$/i) || path.match(/^mailto:/) || path.endsWith('/'))
@@ -121,7 +127,7 @@ export function addTrailingSlash(path) {
  * Convert a path by ensuring it has not a trailing slash
  *
  * @param {string} path Path to convert
- * @returns {string}
+ * @returns {string} Converted path
  */
 export function removeTrailingSlash(path) {
     if (path.endsWith('/'))