@inglorious/utils 3.8.0 → 5.0.0

package/src/data-structures/object.js

@@ -1,3 +1,4 @@
+import { isFunction } from "../functions/function.js"
 import { v } from "../v.js"
 import { isArray } from "./array.js"
 
@@ -27,6 +28,57 @@ export function clone(obj) {
   return deserialize(serialize(obj))
 }
 
+/**
+ * Recursively merges properties from a source object into a target object.
+ * This is a helper function for `merge` and `extend`.
+ *
+ * @param {Object} target - The target object to merge into.
+ * @param {Object} source - The source object to merge from.
+ * @param {Function} [merger] - An optional function to customize merging behavior for specific keys.
+ * @returns {Object} - The modified target object.
+ */
+function deepMerge(target, source, merger) {
+  for (const [key, value] of Object.entries(source)) {
+    if (isFunction(merger)) {
+      const mergedValue = merger(target[key], value)
+      if (mergedValue !== undefined) {
+        target[key] = mergedValue
+        continue
+      }
+    }
+
+    if (isArray(value)) {
+      target[key] = value
+    } else if (isObject(value)) {
+      if (!isObject(target[key])) {
+        target[key] = {}
+      }
+      target[key] = deepMerge(target[key], value, merger)
+    } else {
+      target[key] = value
+    }
+  }
+  return target
+}
+
+/**
+ * Assigns default properties to a target object from a source object.
+ * For each key in `defaultProps`, if `target[key]` is `null` or `undefined`,
+ * it is set to `defaultProps[key]`.
+ *
+ * This function modifies the target object in place.
+ *
+ * @param {Object} target The object to apply defaults to.
+ * @param {Object} defaultProps The object containing the default properties.
+ * @returns {Object} The modified target object.
+ */
+export function defaults(target, defaultProps) {
+  for (const key in defaultProps) {
+    target[key] ??= defaultProps[key]
+  }
+  return target
+}
+
 /**
  * Deserializes an object, converting plain object representations back into
  * their original types, such as vector-like objects. This is the inverse
@@ -66,6 +118,35 @@ export function deserialize(str) {
   }
 }
 
+/**
+ * Creates a new object by deeply merging a target object with one or more source objects.
+ * This function is immutable; it does not modify the original `target` or `sources`.
+ * Nested objects are merged recursively.
+ * Arrays from a source object will overwrite arrays in the target object.
+ *
+ * @param {Object} target - The base object.
+ * @param {...Object} sources - The source objects to merge into the target object.
+ * @returns {Object} - A new object containing the merged properties.
+ * @see {@link merge} for a mutable version.
+ */
+export function extend(target, ...sources) {
+  return extendWith(undefined, target, ...sources)
+}
+
+/**
+ * Creates a new object by deeply merging a target object with one or more source objects,
+ * using a custom merger function to handle specific properties.
+ * This function is immutable.
+ *
+ * @param {Function} [merger] - A function to customize merging behavior. It receives `(targetValue, sourceValue)`. If it returns `undefined`, the default merge logic is used.
+ * @param {Object} target - The base object.
+ * @param {...Object} sources - The source objects to merge.
+ * @returns {Object} A new object with the merged properties.
+ */
+export function extendWith(merger, target, ...sources) {
+  return mergeWith(merger, {}, target, ...sources)
+}
+
 /**
  * Filters the properties of an object based on a callback function.
  *
@@ -138,6 +219,57 @@ export function get(obj, path, defaultValue = undefined) {
  * @param {*} value - The value to check.
  * @returns {boolean} True if the value is a plain object, false otherwise.
  */
+/**
+ * Whether two values are the same, all the way down.
+ *
+ * Written here rather than with `JSON.stringify` because stringify cannot tell a key
+ * that was left out from one that was set to nothing, and those are different: a key
+ * mapped to `undefined` is a key with nothing mapped to it, which is how a mapping is
+ * taken off.
+ *
+ * @param {*} left - The first value.
+ * @param {*} right - The second value.
+ * @param {WeakMap} [seen] - The pairs already compared, so a structure that contains
+ *   itself is not walked for ever. Passed along rather than asked for.
+ *
+ * What it does not settle is whether two structures *share* the same parts. One value
+ * used twice against two equal ones written out twice are reported as different, because
+ * only the pairs already met are remembered. That errs towards calling things changed
+ * when they are not, which is the safe way round for the thing this is asked about.
+ *
+ * @returns {boolean} Whether the two are the same.
+ */
+export function isDeepEqual(left, right, seen = new WeakMap()) {
+  if (Object.is(left, right)) return true
+
+  // `Object.is` has already said no to these two being the same object, and neither can be
+  // walked: a function is equal to itself and nothing else, and a key present in one and
+  // not the other is a difference even when both read as undefined.
+  if (typeof left !== "object" || typeof right !== "object") return false
+  if (left === null || right === null) return false
+
+  if (Array.isArray(left) !== Array.isArray(right)) return false
+
+  // A thing that contains itself would otherwise be walked for ever. Meeting the same
+  // thing twice means it has already been compared, and it was the same then or the walk
+  // would have stopped there -- so the only question left is whether it was matched to
+  // this one. A structure that loops back to itself differently is a difference, which is
+  // what stops this reporting two equal loops that are not.
+  if (seen.has(left)) return seen.get(left) === right
+
+  seen.set(left, right)
+
+  const leftKeys = Object.keys(left)
+  const rightKeys = Object.keys(right)
+
+  if (leftKeys.length !== rightKeys.length) return false
+
+  return leftKeys.every(
+    (key) =>
+      Object.hasOwn(right, key) && isDeepEqual(left[key], right[key], seen),
+  )
+}
+
 export function isObject(value) {
   return value != null && value.constructor === Object
 }
@@ -157,6 +289,36 @@ export function map(obj, callback) {
   }, {})
 }
 
+/**
+ * Merges multiple source objects into a target object.
+ * This function is mutable; it modifies the `target` object in place.
+ * Nested objects are merged recursively.
+ * Arrays from a source object will overwrite arrays in the target object.
+ *
+ * @param {Object} target - The target object to merge into.
+ * @param {...Object} sources - The source objects to merge from.
+ * @returns {Object} - The merged target object.
+ * @see {@link extend} for an immutable version.
+ */
+export function merge(target, ...sources) {
+  return mergeWith(undefined, target, ...sources)
+}
+
+/**
+ * Merges multiple source objects into a target object, using a custom merger function.
+ * This function is mutable; it modifies the `target` object in place.
+ *
+ * @param {Function} [merger] - A function to customize merging behavior. It receives `(targetValue, sourceValue)`. If it returns `undefined`, the default merge logic is used.
+ * @param {Object} target - The target object to merge into.
+ * @param {...Object} sources - The source objects to merge from.
+ * @returns {Object} The merged target object.
+ */
+export function mergeWith(merger, target, ...sources) {
+  return sources
+    .filter((source) => source != null)
+    .reduce((acc, source) => deepMerge(acc, source, merger), target)
+}
+
 /**
  * A utility function inspired by Immer's `produce` API. It provides a convenient
  * way to work with immutable data structures by allowing "mutations" on a
@@ -208,7 +370,7 @@ export function produce(baseState, recipe, ...args) {
  */
 export function serialize(obj) {
   function replacer(key, value) {
-    // Handle top-level vector
+    // Handle top-stage vector
     if (value?.__isVector__) {
       return {
         _type: "vector",
@@ -282,7 +444,7 @@ export function set(obj, path, value) {
  * Converts an object or array to a formatted string representation.
  *
  * @param {*} obj - The object or array to convert.
- * @param {number} [indentationLevel=INITIAL_LEVEL] - The current indentation level (used for nested structures).
+ * @param {number} [indentationLevel=INITIAL_LEVEL] - The current indentation stage (used for nested structures).
  * @returns {string} A string representation of the input object or array.
  */
 export function toString(obj, indentationLevel = INITIAL_LEVEL) {

package/src/data-structures/string.js

@@ -11,3 +11,80 @@ export function toCamelCase(input) {
 
   return [firstChar.toLowerCase(), ...rest].join("")
 }
+
+// How long a row or column is by one, which is the whole of what the offsets below mean.
+// The grid's own edges are counted by the same one.
+const ONE = 1
+const NONE = 0
+const FIRST = 0
+
+/**
+ * How far one string is from another, in single-character edits.
+ *
+ * The grid is built in full rather than in the one row that would do, because this is
+ * short and the short version is where an off-by-one hides.
+ *
+ * @example
+ * ```js
+ * import { editDistance } from "@inglorious/utils/data-structures/string.js"
+ *
+ * editDistance("audio", "audi") // 1
+ * ```
+ *
+ * @param {string} a - The string that was asked about.
+ * @param {string} b - The string to compare it with.
+ * @returns {number} How many edits turn one into the other.
+ */
+export function editDistance(a, b) {
+  const grid = Array.from({ length: a.length + ONE }, () =>
+    Array.from({ length: b.length + ONE }, () => NONE),
+  )
+
+  for (let i = FIRST; i <= a.length; i++) grid[i][FIRST] = i
+  for (let j = FIRST; j <= b.length; j++) grid[FIRST][j] = j
+
+  for (let i = ONE; i <= a.length; i++) {
+    for (let j = ONE; j <= b.length; j++) {
+      grid[i][j] = Math.min(
+        grid[i - ONE][j] + ONE,
+        grid[i][j - ONE] + ONE,
+        grid[i - ONE][j - ONE] + (a[i - ONE] === b[j - ONE] ? NONE : ONE),
+      )
+    }
+  }
+
+  return grid[a.length][b.length]
+}
+
+// How far a string may be from the one asked about and still be worth suggesting. A
+// mistyped name is nearly always one or two edits away from the right one; anything
+// further off is a different string rather than a wrong one.
+const NEAR_ENOUGH = 3
+
+/**
+ * The strings closest to one that was asked for, nearest first.
+ *
+ * Case is folded, because a name differing from a declared one only by a capital is the
+ * commonest kind of mistake and the one where saying nothing is least helpful.
+ *
+ * @example
+ * ```js
+ * import { namesNear } from "@inglorious/utils/data-structures/string.js"
+ *
+ * namesNear("audio", ["Game", "Audio"]) // ["Audio"]
+ * ```
+ *
+ * @param {string} wanted - The string that was asked for.
+ * @param {string[]} candidates - Every string that could have been meant.
+ * @returns {string[]} The ones worth suggesting, which may be none of them.
+ */
+export function namesNear(wanted, candidates) {
+  const target = wanted.toLowerCase()
+  const allowed = Math.max(ONE, Math.floor(target.length / NEAR_ENOUGH))
+
+  return candidates
+    .map((name) => [name, editDistance(target, name.toLowerCase())])
+    .filter(([, d]) => d <= allowed)
+    .sort(([, a], [, b]) => a - b)
+    .map(([name]) => name)
+}

package/src/data-structures/tree.js

@@ -1,4 +1,4 @@
-/** @typedef {import('../../types/data-structures').Tree} Tree */
+/** @typedef {import('../../types/data-structures/tree').Tree} Tree */
 
 /**
  * Performs a breadth-first search (BFS) traversal on a tree structure.

package/src/functions/function.js

@@ -1,3 +1,89 @@
+const DEFAULT_DELAY = 0
+
+/**
+ * Composes multiple functions from right to left, as if every function wraps the next one.
+ * The first function (rightmost) can take multiple arguments; the remaining functions must be unary.
+ *
+ * @param {...Function} fns - Functions to compose.
+ * @returns {Function} A function that takes the initial arguments and applies the composed functions.
+ */
+export function compose(...fns) {
+  if (!fns.length) {
+    return (x) => x
+  }
+
+  const [last, ...rest] = fns.reverse()
+  return (...args) => rest.reduce((acc, fn) => fn(acc), last(...args))
+}
+
+/**
+ * Creates a debounced function that delays invoking `fn` until after `delay`
+ * milliseconds have elapsed since the last call.
+ *
+ * @param {Function} fn - The function to debounce.
+ * @param {number} [delay=0] - The number of milliseconds to delay.
+ * @returns {Function & { cancel: Function, flush: Function, pending: Function }} The debounced function.
+ */
+export function debounce(fn, delay = DEFAULT_DELAY) {
+  let timeoutId
+  let lastArgs
+  let lastThis
+  let result
+
+  function clearPending() {
+    lastArgs = undefined
+    lastThis = undefined
+  }
+
+  function invoke() {
+    const args = lastArgs
+    const context = lastThis
+
+    clearPending()
+    result = fn.apply(context, args)
+    return result
+  }
+
+  function debounced(...args) {
+    lastArgs = args
+    lastThis = this
+
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId)
+    }
+
+    timeoutId = setTimeout(() => {
+      timeoutId = undefined
+      invoke()
+    }, delay)
+
+    return result
+  }
+
+  debounced.cancel = () => {
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId)
+    }
+
+    timeoutId = undefined
+    clearPending()
+  }
+
+  debounced.flush = () => {
+    if (timeoutId === undefined) {
+      return result
+    }
+
+    clearTimeout(timeoutId)
+    timeoutId = undefined
+    return invoke()
+  }
+
+  debounced.pending = () => timeoutId !== undefined
+
+  return debounced
+}
+
 /**
  * Checks if a value is a function.
  *
@@ -7,3 +93,107 @@
 export function isFunction(func) {
   return typeof func === "function"
 }
+
+/**
+ * Pipes multiple functions from left to right, as if the functions are applied one by one.
+ * The first function (leftmost) can take multiple arguments; the remaining functions must be unary.
+ *
+ * @param {...Function} fns - Functions to pipe.
+ * @returns {Function} A function that takes the initial arguments and applies the piped functions.
+ */
+export function pipe(...fns) {
+  if (!fns.length) {
+    return (x) => x
+  }
+
+  const [first, ...rest] = fns
+  return (...args) => rest.reduce((acc, fn) => fn(acc), first(...args))
+}
+
+/**
+ * Creates a throttled function that invokes `fn` immediately on the leading
+ * edge, then suppresses further calls until `delay` milliseconds have
+ * elapsed.
+ *
+ * By default (`hasTrailing: false`), any calls made while suppressed are
+ * dropped entirely — only the leading call's arguments are ever used, and
+ * the very last call of a burst may be lost. Pass `{ hasTrailing: true }` to
+ * additionally invoke `fn` once more, after `delay` has elapsed, with the
+ * arguments from the most recent suppressed call — guaranteeing the final
+ * state of a burst is never silently dropped, at the cost of `fn` running
+ * again asynchronously after the burst settles.
+ *
+ * @param {Function} fn - The function to throttle.
+ * @param {number} [delay=0] - The number of milliseconds to suppress repeated calls.
+ * @param {Object} [options]
+ * @param {boolean} [options.hasTrailing=false] - Whether to invoke `fn` once
+ *   more after `delay`, using the arguments of the last suppressed call.
+ * @returns {Function & { cancel: Function, pending: Function }} The throttled function.
+ */
+export function throttle(
+  fn,
+  delay = DEFAULT_DELAY,
+  { hasTrailing = false } = {},
+) {
+  let timeoutId
+  let result
+  let lastArgs
+  let lastThis
+  let trailingCallPending = false
+
+  function clearPending() {
+    lastArgs = undefined
+    lastThis = undefined
+    trailingCallPending = false
+  }
+
+  function startWindow() {
+    timeoutId = setTimeout(() => {
+      timeoutId = undefined
+
+      // NOTE: this runs asynchronously, after `delay` has elapsed — so this
+      // is the one path where `fn` is not invoked synchronously with the
+      // triggering call. Callers that pass draft/proxy objects through `fn`
+      // (e.g. a mutative entity) must treat this like a debounced call: only
+      // hold onto primitives across the throttle boundary, and re-fetch any
+      // live object when `fn` actually runs here.
+      if (trailingCallPending) {
+        const args = lastArgs
+        const context = lastThis
+        clearPending()
+        result = fn.apply(context, args)
+      }
+    }, delay)
+  }
+
+  function throttled(...args) {
+    lastArgs = args
+    lastThis = this
+
+    if (timeoutId !== undefined) {
+      if (hasTrailing) {
+        trailingCallPending = true
+      }
+      return result
+    }
+
+    result = fn.apply(this, args)
+    lastArgs = undefined
+    lastThis = undefined
+    startWindow()
+    return result
+  }
+
+  throttled.cancel = () => {
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId)
+    }
+
+    timeoutId = undefined
+    clearPending()
+  }
+
+  throttled.pending = () => timeoutId !== undefined || trailingCallPending
+
+  return throttled
+}

package/src/functions/index.js

@@ -1,4 +1 @@
-import * as func from "./function.js"
-import * as funcs from "./functions.js"
-
-export { func, funcs }
+export * from "./function.js"

package/src/math/circle.js

@@ -1,14 +1,12 @@
 /**
- * @typedef {import("../../types/math").Point} Point
- * @typedef {import("../../types/math").Circle} Circle
- * @typedef {import("../../types/math").Rectangle} Rectangle
- * @typedef {import("../../types/math").Platform} Platform
+ * @typedef {import("../../types/math/point").PointInput} PointInput
+ * @typedef {import("../../types/math/circle").Circle} Circle
+ * @typedef {import("../../types/math/rectangle").Rectangle} Rectangle
  */
 
 import { intersectsCircle as pointIntersectsCircle } from "./point.js"
 import { hypothenuse } from "./triangle.js"
-import { clamp } from "./vector.js"
-import { subtract } from "./vectors.js"
+import { clamp, subtract } from "./vector.js"
 
 const HALF = 2
 const SQUARED = 2
@@ -17,7 +15,7 @@ const INITIAL_SUM = 0
 /**
  * Checks if a circle intersects with a point.
  * @param {Circle} circle - The circle to check.
- * @param {Point} point - The point to check.
+ * @param {PointInput} point - The point to check.
  * @returns {boolean} True if the point intersects the circle, false otherwise.
  */
 export function intersectsPoint(circle, point) {

package/src/math/hitmask.js

@@ -1,6 +1,6 @@
 // @see https://jonathanwhiting.com/tutorial/collision/
 
-import { isBetween } from "./numbers.js"
+import { isBetween } from "./number.js"
 import { intersectsRectangle } from "./rectangle.js"
 
 const FIRST = 0

package/src/math/index.js

@@ -2,10 +2,9 @@ import * as circle from "./circle.js"
 import * as hitmask from "./hitmask.js"
 import * as line from "./line.js"
 import * as linearInterpolation from "./linear-interpolation.js"
-import * as numbers from "./numbers.js"
+import * as numbers from "./number.js"
 import * as point from "./point.js"
-import * as quaternion from "./quaternion.js"
-import * as quaternions from "./quaternions.js"
+import * as quaternions from "./quaternion.js"
 import * as rectangle from "./rectangle.js"
 import * as rng from "./rng.js"
 import * as segment from "./segment.js"
@@ -13,7 +12,6 @@ import * as statistics from "./statistics.js"
 import * as triangle from "./triangle.js"
 import * as trigonometry from "./trigonometry.js"
 import * as vector from "./vector.js"
-import * as vectors from "./vectors.js"
 
 export {
   circle,
@@ -22,7 +20,6 @@ export {
   linearInterpolation,
   numbers,
   point,
-  quaternion,
   quaternions,
   rectangle,
   rng,
@@ -31,5 +28,4 @@ export {
   triangle,
   trigonometry,
   vector,
-  vectors,
 }

package/src/math/line.js

@@ -1,10 +1,10 @@
 /**
- * @typedef {import("../../types/math").Line} Line
- * @typedef {import("../../types/math").Point} Point
- * @typedef {import("../../types/math").Circle} Circle
+ * @typedef {import("../../types/math/line").Line} Line
+ * @typedef {import("../../types/math/point").Point} Point
+ * @typedef {import("../../types/math/circle").Circle} Circle
  */
 
-import { abs } from "./numbers.js"
+import { abs } from "./number.js"
 import { hypothenuse } from "./triangle.js"
 
 /**

package/src/math/point.js

@@ -1,15 +1,37 @@
 /**
- * @typedef {import("../../types/math").Point} Point
- * @typedef {import("../../types/math").Line} Line
- * @typedef {import("../../types/math").Circle} Circle
- * @typedef {import("../../types/math").Rectangle} Rectangle
+ * A point in the Inglorious coordinate system: `[x, y, z]`.
+ *
+ * The world is y-up: the origin sits on the floor, and a bigger `y` is always a
+ * higher place in the world. Gravity subtracts from it, a jump adds to it, and an
+ * object resting on the ground has `y = 0`.
+ *
+ * `z` is the depth axis, and it is y-up as well — it is not screen-down, so both
+ * vertical axes grow upwards. Renderers turn them into screen coordinates:
+ * `@inglorious/renderer-2d` projects a point to `canvasY = height - y - z`,
+ * which puts `(0, 0, 0)` at the bottom-left of the canvas and turns both axes
+ * upside down.
+ *
+ * @example Reading a position in a 2D game
+ * ```js
+ * v(0, 0, 0) // the floor
+ * v(0, 100, 0) // a hundred pixels up
+ *
+ * entity.velocity[1] -= GRAVITY * dt // falling loses height
+ * entity.position[1] = 0 // keeping a body on the ground
+ * ```
+ *
+ * @typedef {import("../../types/math/point").Point} Point
+ * @typedef {import("../../types/math/point").PointInput} PointInput
+ * @typedef {import("../../types/math/line").Line} Line
+ * @typedef {import("../../types/math/circle").Circle} Circle
+ * @typedef {import("../../types/math/rectangle").Rectangle} Rectangle
  */
 
 const SQUARED = 2
 const HALF = 2
 
 import { distanceFromPoint } from "./line.js"
-import { isBetween } from "./numbers.js"
+import { isBetween } from "./number.js"
 import { isVector } from "./vector.js"
 
 /**
@@ -24,8 +46,8 @@ export function getDistanceFromLine(point, line) {
 
 /**
  * Checks if two points intersect.
- * @param {Point} point1 - The first point as a 3D coordinate [x, y, z].
- * @param {Point} point2 - The second point as a 3D coordinate [x, y, z].
+ * @param {PointInput} point1 - The first point as a 3D coordinate [x, y, z].
+ * @param {PointInput} point2 - The second point as a 3D coordinate [x, y, z].
  * @returns {boolean} True if the points intersect, false otherwise.
  */
 export function intersectsPoint(point1, point2) {
@@ -36,7 +58,7 @@ export function intersectsPoint(point1, point2) {
 
 /**
  * Checks if a point intersects with a circle.
- * @param {Point} point - The point as a 3D coordinate [x, y, z].
+ * @param {PointInput} point - The point as a 3D coordinate [x, y, z].
  * @param {Circle} circle - The circle with a position and radius.
  * @returns {boolean} True if the point intersects the circle, false otherwise.
  */
@@ -53,7 +75,7 @@ export function intersectsCircle(point, circle) {
 
 /**
  * Checks if a point intersects with a rectangle.
- * @param {Point} point - The point as a 3D coordinate [x, y, z].
+ * @param {PointInput} point - The point as a 3D coordinate [x, y, z].
  * @param {Rectangle} rectangle - The rectangle with a position and size.
  * @returns {boolean} True if the point intersects the rectangle, false otherwise.
  */