@inglorious/utils 3.8.0 → 4.0.0

package/src/data-structures/objects.js

@@ -1,6 +1,89 @@
-import { isFunction } from "../functions/function.js"
+import { isFunction } from "../functions/functions.js"
+import { v } from "../v.js"
 import { isArray } from "./array.js"
-import { isObject } from "./object.js"
+
+const INITIAL_LEVEL = 0
+const LAST_KEY_OFFSET = 1
+const NEXT_KEY_OFFSET = 1
+const NEXT_LEVEL = 2
+
+/**
+ * Creates a deep clone of a given value using the structured clone algorithm.
+ * This is a modern and efficient way to deep-clone objects.
+ *
+ * Note: `structuredClone` has some limitations. It cannot clone functions,
+ * DOM nodes, property descriptors, getters, setters, or certain other
+ * non-serializable objects. It will throw a `DataCloneError` in such cases.
+ *
+ * For more details, see:
+ * https://developer.mozilla.org/en-US/docs/Web/API/structuredClone
+ *
+ * This is similar to Lodash's `_.cloneDeep`.
+ *
+ * @template T
+ * @param {T} obj - The value to clone.
+ * @returns {T} A deep clone of the input value.
+ */
+export function clone(obj) {
+  return deserialize(serialize(obj))
+}
+
+/**
+ * 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
+ * operation of `serialize`.
+ *
+ * - Recursively deserializes nested objects.
+ * - Converts objects with a `_type: "vector"` property and `coords` array
+ *   back into a vector-like object using the `v` factory function.
+ * - Copies all other property values as-is.
+ *
+ * @param {string} str - The JSON string to deserialize.
+ * @returns {Object} The deserialized object.
+ */
+export function deserialize(str) {
+  const data = JSON.parse(str)
+
+  return revive(data)
+
+  function revive(value) {
+    if (isArray(value)) {
+      return value.map(revive)
+    }
+    if (isObject(value)) {
+      if (value._type === "vector" && value.coords) {
+        return v(...value.coords)
+      }
+
+      const deserialized = {}
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          deserialized[key] = revive(value[key])
+        }
+      }
+      return deserialized
+    }
+    return value
+  }
+}
 
 /**
  * Creates a new object by deeply merging a target object with one or more source objects.
@@ -17,6 +100,111 @@ 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.
+ *
+ * @param {Object} obj - The object to filter.
+ * @param {Function} callback - A function that determines whether a property should be included.
+ *                              Receives (key, value, obj) as arguments.
+ * @returns {Object} A new object with the filtered properties.
+ */
+export function filter(obj, callback) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([key, value], obj) =>
+      callback(key, value, obj),
+    ),
+  )
+}
+
+/**
+ * Finds the first property in an object that satisfies the callback function.
+ *
+ * @param {Object} obj - The object to search.
+ * @param {Function} callback - A function that determines whether a property matches.
+ *                              Receives (key, value, obj) as arguments.
+ * @returns {Object} An object containing the first matching property, or an empty object if none match.
+ */
+export function find(obj, callback) {
+  return Object.fromEntries([
+    Object.entries(obj).find(([key, value], obj) => callback(key, value, obj)),
+  ])
+}
+
+/**
+ * Gets the value at a specified path of an object. If the resolved value is
+ * `undefined`, the `defaultValue` is returned in its place. This function
+ * supports dot-notation for nested properties and numbers for array indices.
+ *
+ * This is similar to Lodash's `_.get`.
+ *
+ * @example
+ * const object = { 'a': [{ 'b': { 'c': 3 } }] };
+ * get(object, 'a.0.b.c');
+ * // => 3
+ *
+ * get(object, 'a.0.d', 'default');
+ * // => 'default'
+ *
+ * @param {Object} obj - The object to query.
+ * @param {string} path - The path of the property to retrieve.
+ * @param {*} [defaultValue=undefined] - The value returned for `undefined` resolved values.
+ * @returns {*} Returns the resolved value, else the `defaultValue`.
+ */
+export function get(obj, path, defaultValue = undefined) {
+  if (!path) return defaultValue
+
+  const keys = path.split(".")
+  let result = obj
+
+  for (const key of keys) {
+    if (result == null || typeof result !== "object") {
+      return defaultValue
+    }
+    result = result[key]
+  }
+
+  return result !== undefined ? result : defaultValue
+}
+
+/**
+ * Checks if a value is a plain object.
+ *
+ * @param {*} value - The value to check.
+ * @returns {boolean} True if the value is a plain object, false otherwise.
+ */
+export function isObject(value) {
+  return value != null && value.constructor === Object
+}
+
+/**
+ * Maps the properties of an object using a callback function.
+ *
+ * @param {Object} obj - The object to map.
+ * @param {Function} callback - A function that transforms each property.
+ *                              Receives (key, value, obj) as arguments.
+ * @returns {Object} A new object with the mapped properties.
+ */
+export function map(obj, callback) {
+  return Object.entries(obj).reduce((acc, [key, value]) => {
+    acc[key] = callback(key, value, obj)
+    return acc
+  }, {})
+}
+
 /**
  * Merges multiple source objects into a target object.
  * This function is mutable; it modifies the `target` object in place.
@@ -32,20 +220,6 @@ export function merge(target, ...sources) {
   return mergeWith(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)
-}
-
 /**
  * Merges multiple source objects into a target object, using a custom merger function.
  * This function is mutable; it modifies the `target` object in place.
@@ -61,6 +235,168 @@ export function mergeWith(merger, target, ...sources) {
     .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
+ * temporary draft.
+ *
+ * **Important:** Unlike Immer, which uses structural sharing via proxies for
+ * high performance, this implementation performs a full deep clone of the base
+ * state on every call using `deserialize(serialize())`. This can be
+ * inefficient for large or complex states. It is intended for simple use cases
+ * where the convenience of the API outweighs the performance cost.
+ *
+ * The recipe function receives a draft copy of the state. It can either
+ * mutate the draft and return nothing (`undefined`), or it can return a
+ * completely new value, which will become the next state.
+ *
+ * Can be called in two ways:
+ * - **Standard:** `produce(baseState, recipe, ...args)`
+ * - **Curried:** `produce(recipe)` returns a new function `(baseState, ...args) => newState`
+ *
+ * @template T
+ * @param {T|function(T, ...*): (T|void)} baseState The initial state, or a recipe for currying.
+ * @param {function(T, ...*): (T|void)} [recipe] The recipe function.
+ * @param {...*} args Additional arguments to pass to the recipe.
+ * @returns {T | function(T, ...*): T} A new state, or a producer function if curried.
+ */
+export function produce(baseState, recipe, ...args) {
+  if (typeof baseState === "function" && recipe === undefined) {
+    const recipeFn = baseState
+    return (state, ...recipeArgs) => produce(state, recipeFn, ...recipeArgs)
+  }
+
+  const draft = clone(baseState)
+  const result = recipe(draft, ...args)
+  return result === undefined ? draft : result
+}
+
+/**
+ * Serializes an object, converting special types like vectors into a plain
+ * object representation. This is useful for processes like saving state to a
+ * file or sending it over a network.
+ *
+ * - Recursively serializes nested objects.
+ * - Converts objects with a `__isVector__` property into a serializable
+ *   format: `{ _type: "vector", coords: [...] }`.
+ * - Copies all other property values as-is.
+ *
+ * @param {Object} obj - The object to serialize.
+ * @returns {string} The serialized JSON string.
+ */
+export function serialize(obj) {
+  function replacer(key, value) {
+    // Handle top-level vector
+    if (value?.__isVector__) {
+      return {
+        _type: "vector",
+        coords: Array.from(value),
+      }
+    }
+
+    if (isObject(value)) {
+      const serialized = {}
+
+      for (const k in value) {
+        if (Object.prototype.hasOwnProperty.call(value, k)) {
+          serialized[k] = replacer(undefined, value[k])
+        }
+      }
+
+      return serialized
+    }
+
+    return value
+  }
+
+  return JSON.stringify(obj, replacer)
+}
+
+/**
+ * Sets the value at a specified path of an object. If a portion of the path
+ * doesn't exist, it's created. Arrays are created for missing index properties
+ * while objects are created for all other missing properties. This function
+ * mutates the object.
+ *
+ * This is similar to Lodash's `_.set`.
+ *
+ * @example
+ * const object = { 'a': [{ 'b': { 'c': 3 } }] };
+ * set(object, 'a.0.b.d', 4);
+ * // object is now { 'a': [{ 'b': { 'c': 3, 'd': 4 } }] }
+ *
+ * set(object, 'x.0.y', 5);
+ * // object is now { 'a': [...], 'x': [{ 'y': 5 }] }
+ *
+ * @param {Object} obj - The object to modify.
+ * @param {string} path - The path of the property to set.
+ * @param {*} value - The value to set.
+ * @returns {Object} Returns the modified object.
+ */
+export function set(obj, path, value) {
+  if (!path) return obj
+
+  const keys = path.split(".")
+  let current = obj
+
+  for (let i = 0; i < keys.length - LAST_KEY_OFFSET; i++) {
+    const key = keys[i]
+    const nextKey = keys[i + NEXT_KEY_OFFSET]
+
+    // Create missing intermediate objects
+    if (!(key in current) || typeof current[key] !== "object") {
+      // Create array if next key is a number, object otherwise
+      current[key] = /^\d+$/.test(nextKey) ? [] : {}
+    }
+
+    current = current[key]
+  }
+
+  current[keys[keys.length - LAST_KEY_OFFSET]] = value
+  return obj
+}
+
+/**
+ * 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).
+ * @returns {string} A string representation of the input object or array.
+ */
+export function toString(obj, indentationLevel = INITIAL_LEVEL) {
+  if (Array.isArray(obj)) {
+    return `[
+${obj
+  .map(
+    (item) =>
+      " ".repeat(indentationLevel + NEXT_LEVEL) +
+      toString(item, indentationLevel + NEXT_LEVEL),
+  )
+  .join(",\n")}
+${" ".repeat(indentationLevel)}]`
+  }
+
+  if (typeof obj === "object" && obj != null) {
+    return `{
+${Object.entries(obj)
+  .map(
+    ([key, value]) =>
+      `${" ".repeat(indentationLevel + NEXT_LEVEL)}${key}: ${toString(
+        value,
+        indentationLevel + NEXT_LEVEL,
+      )}`,
+  )
+  .join(",\n")}
+${" ".repeat(indentationLevel)}}`
+  }
+
+  if (typeof obj === "string") {
+    return `"${obj}"`
+  }
+
+  return obj
+}
+
 /**
  * Recursively merges properties from a source object into a target object.
  * This is a helper function for `merge` and `extend`.
@@ -93,21 +429,3 @@ function deepMerge(target, source, merger) {
   }
   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
-}

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/functions.js

@@ -1,3 +1,5 @@
+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.
@@ -14,6 +16,84 @@ export function compose(...fns) {
   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.
+ *
+ * @param {*} func - The value to check.
+ * @returns {boolean} True if the value is a function, false otherwise.
+ */
+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.
@@ -29,3 +109,91 @@ export function pipe(...fns) {
   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 "./functions.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 "./vectors.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/index.js

@@ -4,7 +4,6 @@ import * as line from "./line.js"
 import * as linearInterpolation from "./linear-interpolation.js"
 import * as numbers from "./numbers.js"
 import * as point from "./point.js"
-import * as quaternion from "./quaternion.js"
 import * as quaternions from "./quaternions.js"
 import * as rectangle from "./rectangle.js"
 import * as rng from "./rng.js"
@@ -12,7 +11,6 @@ import * as segment from "./segment.js"
 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 {
@@ -22,7 +20,6 @@ export {
   linearInterpolation,
   numbers,
   point,
-  quaternion,
   quaternions,
   rectangle,
   rng,
@@ -30,6 +27,5 @@ export {
   statistics,
   triangle,
   trigonometry,
-  vector,
   vectors,
 }

package/src/math/line.js

@@ -1,7 +1,7 @@
 /**
- * @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"