@inglorious/utils 3.8.0 → 5.0.0

package/src/data-structures/objects.js

@@ -1,113 +0,0 @@
-import { isFunction } from "../functions/function.js"
-import { isArray } from "./array.js"
-import { isObject } from "./object.js"
-
-/**
- * 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)
-}
-
-/**
- * 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)
-}
-
-/**
- * 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.
- *
- * @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)
-}
-
-/**
- * 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
-}

package/src/functions/functions.js

@@ -1,31 +0,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))
-}
-
-/**
- * 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))
-}

package/src/math/quaternions.js

@@ -1,23 +0,0 @@
-/**
- * @typedef {import("../../types/math").Quaternion} Quaternion
- */
-
-import { v } from "../v.js"
-import { times } from "./vector.js"
-import { cross, dot, sum } from "./vectors.js"
-
-/**
- * Combines two quaternions using the Hamilton product.
- * @param {Quaternion} q1 - The first quaternion.
- * @param {Quaternion} q2 - The second quaternion.
- * @returns {Quaternion} - The resulting quaternion after combining q1 and q2.
- */
-export function combine(q1, q2) {
-  const [s1, ...v1] = q1
-  const [s2, ...v2] = q2
-
-  return v(
-    s1 * s2 - dot(v1, v2),
-    ...sum(times(v2, s1), times(v1, s2), cross(v1, v2)),
-  )
-}

package/src/math/vectors.js

@@ -1,212 +0,0 @@
-/**
- * @typedef {import("../../types/math").Vector2} Vector2
- * @typedef {import("../../types/math").Vector3} Vector3
- * @typedef {import("../../types/math").Vector7} Vector7
- */
-
-import { v } from "../v.js"
-import { mod as nMod } from "./numbers.js"
-import { magnitude, shift } from "./vector.js"
-
-/**
- * Alias for the sum function.
- * @type {typeof sum}
- */
-export const add = sum
-
-/**
- * Computes the cross product of multiple vectors.
- * @param {...Vector3 | Vector7} vectors - The vectors to compute the cross product for.
- * @returns {Vector3 | Vector7} The resulting vector after the cross product.
- */
-export function cross(...vectors) {
-  return v(...vectors.reduce(crossMultiplyCoordinates))
-}
-
-/**
- * Computes the distance between multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to compute the distance between.
- * @returns {number} The distance between the vectors.
- */
-export function distance(...vectors) {
-  return magnitude(subtract(...vectors))
-}
-
-/**
- * Computes the component-wise division of multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to divide.
- * @returns {Vector2 | Vector3} The resulting vector.
- */
-export function divide(...vectors) {
-  return v(...vectors.reduce(divideCoordinates))
-}
-
-/**
- * Computes the dot product of multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to compute the dot product for.
- * @returns {number} The resulting scalar value of the dot product.
- */
-export function dot(...vectors) {
-  return vectors
-    .reduce(dotMultiplyCoordinates)
-    .reduce((coord1, coord2) => coord1 + coord2)
-}
-
-/**
- * Alias for the multiply function.
- * @type {typeof multiply}
- */
-export const hadamard = multiply
-
-/**
- * Computes the component-wise modulus of multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to compute the modulus for.
- * @returns {Vector2 | Vector3} The resulting vector after the modulus.
- */
-export function mod(...vectors) {
-  return v(...vectors.reduce(modCoordinates))
-}
-
-/**
- * Computes the component-wise multiplication of multiple vectors (Hadamard product).
- * @param {...Vector2 | Vector3} vectors - The vectors to multiply.
- * @returns {Vector2 | Vector3} The resulting vector.
- */
-export function multiply(...vectors) {
-  return v(...vectors.reduce(multiplyCoordinates))
-}
-
-/**
- * Computes the component-wise power of multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to compute the power for.
- * @returns {Vector2 | Vector3} The resulting vector after the power.
- */
-export function power(...vectors) {
-  return v(...vectors.reduce(powerCoordinates))
-}
-
-/**
- * Alias for the dot product function.
- * @type {typeof dot}
- */
-export const scalarProduct = dot
-
-/**
- * Subtracts multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to subtract.
- * @returns {Vector2 | Vector3} The resulting vector after subtraction.
- */
-export function subtract(...vectors) {
-  return v(...vectors.reduce(subtractCoordinates))
-}
-
-/**
- * Sums multiple vectors.
- * @param {...Vector2 | Vector3} vectors - The vectors to sum.
- * @returns {Vector2 | Vector3} The resulting vector after summation.
- */
-export function sum(...vectors) {
-  return v(...vectors.reduce(sumCoordinates))
-}
-
-/**
- * Alias for the cross product function.
- * @type {typeof cross}
- */
-export const vectorProduct = cross
-
-/**
- * Adds the coordinates of two vectors.
- * @param {Vector2 | Vector3} vector1 - The first vector.
- * @param {Vector2 | Vector3} vector2 - The second vector.
- * @returns {Vector2 | Vector3} The resulting vector after addition.
- */
-function sumCoordinates(vector1, vector2) {
-  return v(...vector1.map((coordinate, index) => coordinate + vector2[index]))
-}
-
-/**
- * Subtracts the coordinates of two vectors.
- * @param {Vector2 | Vector3} vector1 - The first vector.
- * @param {Vector2 | Vector3} vector2 - The second vector.
- * @returns {Vector2 | Vector3} The resulting vector after subtraction.
- */
-function subtractCoordinates(vector1, vector2) {
-  return v(...vector1.map((coordinate, index) => coordinate - vector2[index]))
-}
-
-/**
- * Divides the coordinates of two vectors component-wise.
- * @param {Vector2 | Vector3} vector1 - The dividend vector.
- * @param {Vector2 | Vector3} vector2 - The divisor vector.
- * @returns {Vector2 | Vector3} The resulting vector.
- */
-function divideCoordinates(vector1, vector2) {
-  return v(...vector1.map((coordinate, index) => coordinate / vector2[index]))
-}
-
-/**
- * Computes the component-wise modulus of two vectors.
- * @param {Vector2 | Vector3} vector1 - The first vector.
- * @param {Vector2 | Vector3} vector2 - The second vector.
- * @returns {Vector2 | Vector3} The resulting vector after the modulus.
- */
-function modCoordinates(vector1, vector2) {
-  return v(
-    ...vector1.map((coordinate, index) => nMod(coordinate, vector2[index])),
-  )
-}
-
-/**
- * Multiplies the coordinates of two vectors component-wise.
- * @param {Vector2 | Vector3} vector1 - The first vector.
- * @param {Vector2 | Vector3} vector2 - The second vector.
- * @returns {Vector2 | Vector3} The resulting vector.
- */
-function multiplyCoordinates(vector1, vector2) {
-  return v(...vector1.map((coordinate, index) => coordinate * vector2[index]))
-}
-
-/**
- * Raises the coordinates of the first vector to the power of the second vector's coordinates.
- * @param {Vector2 | Vector3} vector1 - The base vector.
- * @param {Vector2 | Vector3} vector2 - The exponent vector.
- * @returns {Vector2 | Vector3} The resulting vector.
- */
-function powerCoordinates(vector1, vector2) {
-  return v(...vector1.map((coordinate, index) => coordinate ** vector2[index]))
-}
-
-/**
- * Computes the cross product of two vectors' coordinates.
- * @param {Vector3} vector1 - The first vector.
- * @param {Vector3} vector2 - The second vector.
- * @returns {Vector3} The resulting vector after the cross product.
- */
-function crossMultiplyCoordinates(vector1, vector2) {
-  const indexes = Array(vector1.length)
-    .fill(null)
-    .map((_, index) => index)
-
-  return v(
-    ...indexes.map((_, index) => {
-      const [index1, index2] = shift(
-        indexes.filter((_, i) => i !== index),
-        index,
-      )
-      return (
-        vector1[index1] * vector2[index2] - vector1[index2] * vector2[index1]
-      )
-    }),
-  )
-}
-
-/**
- * Multiplies the coordinates of two vectors.
- * @param {Vector2 | Vector3} vector1 - The first vector.
- * @param {Vector2 | Vector3} vector2 - The second vector.
- * @returns {Vector2 | Vector3} The resulting vector containing multiplied coordinates.
- */
-function dotMultiplyCoordinates(vector1, vector2) {
-  return v(...vector1.map((coordinate, index) => coordinate * vector2[index]))
-}

package/types/algorithms.d.ts

@@ -1,26 +0,0 @@
-/**
- * Represents the input conditions to be evaluated by a decision tree node.
- * The `unknown` type is used to allow for flexible condition structures.
- */
-export type Conditions = unknown
-
-/**
- * Represents the result of a decision tree's `test` function, which is used
- * as a key to determine the next branch.
- */
-export type Outcome = string
-
-/**
- * Represents a node in a decision tree. It consists of:
- * - A `test` function that evaluates conditions and returns an outcome.
- * - A map of outcomes to subsequent actions, which can be either a final outcome
- *   or another `DecisionTree` node.
- */
-export type DecisionTree = {
-  /**
-   * A function that takes a set of conditions and returns an outcome string.
-   * @param conditions - The conditions to evaluate.
-   * @returns The outcome of the test.
-   */
-  test: (conditions: Conditions) => Outcome
-} & Record<Outcome, () => Outcome | DecisionTree>

package/types/data-structures.d.ts

@@ -1,53 +0,0 @@
-/**
- * Represents a generic tree data structure.
- * Each node in the tree has a value and an array of child nodes.
- * @template T - The type of the value stored in the tree nodes. Defaults to `any`.
- */
-export interface Tree<T = any> {
-  /** The value of the current node. */
-  value: T
-  /** An array of child `Tree` nodes. */
-  children: Tree<T>[]
-}
-
-/**
- * A map where keys are node identifiers and values are their [x, y] coordinates.
- * Used for efficient node lookups by ID.
- */
-export interface NodeMap {
-  [id: string]: [number, number] // [x, y]
-}
-
-/**
- * Represents a node in a graph.
- */
-export interface Node {
-  /** A unique identifier for the node. */
-  id: string
-  /** The [x, y] coordinates of the node. */
-  position: [number, number] // [x, y]
-  /** An optional cost associated with traversing to this node. */
-  cost?: number
-}
-
-/**
- * Represents a directed edge (or arc) between two nodes in a graph.
- */
-export interface Arc {
-  /** The ID of the starting node. */
-  from: string
-  /** The ID of the ending node. */
-  to: string
-  /** An optional cost associated with traversing this arc. */
-  cost?: number
-}
-
-/**
- * Represents a graph structure consisting of nodes and arcs.
- */
-export interface Graph {
-  /** The nodes of the graph, as either an array or a map for efficient lookups. */
-  nodes: NodeMap | Node[]
-  /** An array of arcs connecting the nodes. */
-  arcs: Arc[]
-}

package/types/math.d.ts

@@ -1,90 +0,0 @@
-// geometry
-
-/**
- * Represents a point in 3D space using a readonly tuple of numbers.
- * @public
- */
-export type Point = readonly [number, number, number] // [x, y, z]
-
-/**
- * Represents the dimensions of an object in 3D space.
- * @public
- */
-export type Size = readonly [number, number, number] // [width, height, depth]
-
-/**
- * Represents a line in 2D space in the form `ax + by + c = 0`.
- * @public
- */
-export type Line = readonly [number, number, number] // [a, b, c]
-
-/**
- * Represents a circle with a position and radius.
- * @public
- */
-export interface Circle {
-  /** The center point of the circle. */
-  position: Point
-  /** The radius of the circle. */
-  radius: number
-}
-
-/**
- * Represents a rectangle with a position and size.
- * @public
- */
-export interface Rectangle {
-  /** The top-left corner point of the rectangle. */
-  position: Point
-  /** The dimensions of the rectangle. */
-  size: Size
-}
-
-/**
- * Represents a platform, typically for physics or collision detection.
- * @public
- */
-export interface Platform {
-  /** The position of the platform. */
-  position: Point
-  /** The dimensions of the platform. */
-  size: Size
-}
-
-/**
- * Represents a line segment defined by two points.
- * @public
- */
-export interface Segment {
-  /** The starting point of the segment. */
-  from: Point
-  /** The ending point of the segment. */
-  to: Point
-}
-
-// linear algebra
-
-/**
- * A nominal type brand to identify vector types.
- * This prevents accidental assignment of a plain number array to a vector.
- * @internal
- */
-type IsVector = {
-  readonly __isVector__: true
-}
-
-/** A generic, dynamically-sized vector. */
-export type Vector = IsVector & readonly number[]
-
-/** A 2-dimensional vector. */
-export type Vector2 = IsVector & readonly [number, number]
-
-/** A 3-dimensional vector. */
-export type Vector3 = IsVector & readonly [number, number, number]
-
-/** A 4-dimensional vector, often used for quaternions. */
-export type Quaternion = IsVector & readonly [number, number, number, number]
-
-/** A 7-dimensional vector. */
-export type Vector7 = IsVector &
-  readonly [number, number, number, number, number, number, number]