toosoon-utils 4.2.2 → 4.3.0

package/lib/extras/paths/PathSVG.js

@@ -16,10 +16,10 @@ export default class PathSVG extends PathContext {
     /**
      * Serialize this path into a SVG path string
      *
-     * @param {object} [params]
+     * @param {PathSVGSerializationParameters} [params] Serialization parameters
      * @returns {string}
      */
-    toString(params = {}) {
+    toString(params) {
         return PathSVG.serialize(this, params);
     }
     /**
@@ -37,42 +37,40 @@ export default class PathSVG extends PathContext {
      * Serialize a {@link Curve}
      *
      * @param {Curve} curve Curve to serialize
-     * @param {object} [params] Serialization parameters
-     * @param {boolean} [params.approximate]    Flag indicating if given curve should be approximated into straight lines
-     * @param {number} [params.curveResolution] Resolution used for curve approximations
-     * @returns string
+     * @param {PathSVGSerializationParameters} [params] Serialization parameters
+     * @returns {string}
      */
-    static serialize(curve, { approximate, curveResolution } = {}) {
+    static serialize(curve, { approximate, resolution } = {}) {
         if (curve instanceof Path) {
-            return PathSVG.serializePath(curve, { approximate, curveResolution });
+            return this.serializePath(curve, { approximate, resolution });
         }
         if (approximate === true) {
-            const points = PathSVG.approximate(curve, curveResolution);
+            const points = this.approximate(curve, resolution);
             return points.map(([x, y]) => `L${x},${y}`).join(' ');
         }
         if (curve instanceof LineCurve) {
-            return PathSVG.serializeLineCurve(curve);
+            return this.serializeLineCurve(curve);
         }
         if (curve instanceof PolylineCurve) {
-            return PathSVG.serializePolylineCurve(curve);
+            return this.serializePolylineCurve(curve);
         }
         if (curve instanceof QuadraticBezierCurve) {
-            return PathSVG.serializeQuadraticBezierCurve(curve);
+            return this.serializeQuadraticBezierCurve(curve);
         }
         if (curve instanceof CubicBezierCurve) {
-            return PathSVG.serializeCubicBezierCurve(curve);
+            return this.serializeCubicBezierCurve(curve);
         }
         if (curve instanceof CatmullRomCurve) {
-            return PathSVG.serializeCatmullRomCurve(curve, curveResolution);
+            return this.serializeCatmullRomCurve(curve, resolution);
         }
         if (curve instanceof SplineCurve) {
-            return PathSVG.serializeSplineCurve(curve, curveResolution);
+            return this.serializeSplineCurve(curve, resolution);
         }
         if (curve instanceof EllipseCurve) {
-            return PathSVG.serializeEllipseCurve(curve);
+            return this.serializeEllipseCurve(curve);
         }
         if (curve instanceof ArcCurve) {
-            return PathSVG.serializeArcCurve(curve);
+            return this.serializeArcCurve(curve);
         }
         return '';
     }
@@ -80,7 +78,7 @@ export default class PathSVG extends PathContext {
      * Serialize a {@link LineCurve}
      *
      * @param {LineCurve} curve LineCurve to serialize
-     * @returns string
+     * @returns {string}
      */
     static serializeLineCurve(curve) {
         const { x2, y2 } = curve;
@@ -90,7 +88,7 @@ export default class PathSVG extends PathContext {
      * Serialize a {@link PolylineCurve}
      *
      * @param {PolylineCurve} curve PolylineCurve to serialize
-     * @returns string
+     * @returns {string}
      */
     static serializePolylineCurve(curve) {
         const { points } = curve;
@@ -100,7 +98,7 @@ export default class PathSVG extends PathContext {
      * Serialize a {@link QuadraticBezierCurve}
      *
      * @param {QuadraticBezierCurve} curve QuadraticBezierCurve to serialize
-     * @returns string
+     * @returns {string}
      */
     static serializeQuadraticBezierCurve(curve) {
         const { cpx, cpy, x2, y2 } = curve;
@@ -110,7 +108,7 @@ export default class PathSVG extends PathContext {
      * Serialize a {@link CubicBezierCurve}
      *
      * @param {CubicBezierCurve} curve CubicBezierCurve to serialize
-     * @returns string
+     * @returns {string}
      */
     static serializeCubicBezierCurve(curve) {
         const { cp1x, cp1y, cp2x, cp2y, x2, y2 } = curve;
@@ -120,29 +118,29 @@ export default class PathSVG extends PathContext {
      * Serialize a {@link CatmullRomCurve} by approximating it into straight lines
      *
      * @param {CatmullRomCurve} curve CatmullRomCurve to serialize
-     * @param {number} [curveResolution] Approximation resolution
-     * @returns string
+     * @param {number} [resolution] Approximation resolution
+     * @returns {string}
      */
-    static serializeCatmullRomCurve(curve, curveResolution) {
-        const points = PathSVG.approximate(curve, curveResolution);
+    static serializeCatmullRomCurve(curve, resolution) {
+        const points = this.approximate(curve, resolution);
         return points.map(([x, y]) => `L${x},${y}`).join(' ');
     }
     /**
      * Serialize a {@link SplineCurve} by approximating it into straight lines
      *
      * @param {SplineCurve} curve SplineCurve to serialize
-     * @param {number} [curveResolution] Approximation resolution
-     * @returns string
+     * @param {number} [resolution] Approximation resolution
+     * @returns {string}
      */
-    static serializeSplineCurve(curve, curveResolution) {
-        const points = PathSVG.approximate(curve, curveResolution);
+    static serializeSplineCurve(curve, resolution) {
+        const points = this.approximate(curve, resolution);
         return points.map(([x, y]) => `L${x},${y}`).join(' ');
     }
     /**
      * Serialize an {@link EllipseCurve}
      *
      * @param {EllipseCurve} curve EllipseCurve to serialize
-     * @returns string
+     * @returns {string}
      */
     static serializeEllipseCurve(curve) {
         const { cx, cy, rx, ry, rotation, startAngle, endAngle, counterclockwise } = curve;
@@ -167,29 +165,28 @@ export default class PathSVG extends PathContext {
      * Serialize an {@link ArcCurve}
      *
      * @param {ArcCurve} curve ArcCurve to serialize
-     * @returns string
+     * @returns {string}
      */
     static serializeArcCurve(curve) {
-        return PathSVG.serializeEllipseCurve(curve);
+        return this.serializeEllipseCurve(curve);
     }
     /**
      * Serialize an {@link Path}
      *
      * @param {Path} path Path to serialize
-     * @param {object} [params]
-     * @param {object} [params.curveResolution] Resolution used for curves approximations
-     * @returns string
+     * @param {PathSVGSerializationParameters} [params] Serialization parameters
+     * @returns {string}
      */
-    static serializePath(path, params = {}) {
-        return path.subpaths
+    static serializePath(path, params) {
+        return path.curves
             .map((curve, index) => {
             let commands = ``;
-            const previousPoint = path.subpaths[index - 1]?.getPoint(1);
+            const previousPoint = path.curves[index - 1]?.getPoint(1);
             const newPoint = curve.getPoint(0);
             if (index === 0 || !previousPoint?.equals(newPoint)) {
                 commands += `M${newPoint.x},${newPoint.y}`;
             }
-            commands += PathSVG.serialize(curve, params);
+            commands += this.serialize(curve, params);
             return commands;
         })
             .join(' ');

package/lib/extras/paths/index.d.ts

@@ -1,3 +1,3 @@
 export { default as Path } from './Path';
 export { default as PathContext } from './PathContext';
-export { default as PathSVG, type PathSVGSerializationParams } from './PathSVG';
+export { default as PathSVG, type PathSVGSerializationParameters } from './PathSVG';

package/lib/geometry.js

@@ -69,7 +69,7 @@ export function diagonal(width, height) {
  *
  * @param {object} target    Dimensions of the target
  * @param {object} container Dimensions of the container
- * @param {'contain'|'cover'} mode      Can be 'contain' | 'cover'
+ * @param {string} mode      Can be 'contain' | 'cover'
  * @returns {object}
  */
 function fit(target, container, mode) {

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('/'))