@inglorious/utils 3.8.0 → 5.0.0

package/src/math/quaternion.js

@@ -1,16 +1,33 @@
 /**
- * @typedef {import("../../types/math").Vector3} Vector3
- * @typedef {import("../../types/math").Quaternion} Quaternion
+ * @typedef {import("../../types/math/vector").Vector3} Vector3
+ * @typedef {import("../../types/math/quaternion").Quaternion} Quaternion
  */
 
 import { v } from "../v.js"
 import { cos, sin } from "./trigonometry.js"
+import { cross, dot, multiply, sum } from "./vector.js"
 
 const DEFAULT_ANGLE = 0
 const HALF = 2 // Constant representing the divisor for halving an angle.
 // eslint-disable-next-line no-magic-numbers
 const Y_AXIS = v(0, 1, 0) // Default axis of rotation (Y-axis).
 
+/**
+ * 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(multiply(v2, s1), multiply(v1, s2), cross(v1, v2)),
+  )
+}
+
 /**
  * Computes a quaternion representing a rotation around a given axis.
  * @param {number} [angle=0] - The angle of rotation in radians. Defaults to 0.

package/src/math/rectangle.js

@@ -1,7 +1,14 @@
 /**
- * @typedef {import("../../types/math").Circle} Circle
- * @typedef {import("../../types/math").Rectangle} Rectangle
- * @typedef {import("../../types/math").Platform} Platform
+ * `height` and `depth` are independent axes, not halves of one screen
+ * dimension, so a body on the `xy` plane is sized `v(w, h, 0)` and one on the
+ * `xz` plane `v(w, 0, h)`. `@inglorious/renderer-2d` flattens both onto the
+ * screen and draws a rectangle `height + depth` tall, while
+ * {@link intersectsRectangle} tests the two axes separately.
+ *
+ * @typedef {import("../../types/math/rectangle").Size} Size
+ * @typedef {import("../../types/math/circle").Circle} Circle
+ * @typedef {import("../../types/math/point").PointInput} PointInput
+ * @typedef {import("../../types/math/rectangle").Rectangle} Rectangle
  */
 
 import { intersectsRectangle as circleIntersectsRectangle } from "./circle.js"
@@ -11,8 +18,13 @@ const HALF = 2
 
 /**
  * Checks if a rectangle intersects with a point.
+ *
+ * The rectangle's `position` is its center, and `size` extends around it. An
+ * anchored shape is the exception: its `anchor` picks which point sits on the
+ * position, so the two only line up when the anchor matches, such as
+ * `[0.5, 0.5]` for a centred one.
  * @param {Rectangle} rectangle - The rectangle 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(rectangle, point) {

package/src/math/rng.js

@@ -31,10 +31,13 @@ export function random(...args) {
     return Math.random()
   }
 
+  // A range with a fractional bound cannot be stepped through as integers, so it
+  // is read as a continuous range. Requiring both bounds to be floats used to
+  // send `random(0.5, 1)` down the integer path, where it could only ever answer
+  // 0 or 1.
   if (
     args.length > 1 &&
-    !Number.isInteger(args[0]) &&
-    !Number.isInteger(args[1])
+    (!Number.isInteger(args[0]) || !Number.isInteger(args[1]))
   ) {
     const [from, to] = args
     return Math.random() * (to - from) + from

package/src/math/segment.js

@@ -1,11 +1,17 @@
 /**
- * @typedef {import("../../types/math").Segment} Segment
- * @typedef {import("../../types/math").Point} Point
- * @typedef {import("../../types/math").Circle} Circle
+ * @typedef {import("../../types/math/segment").Segment} Segment
+ * @typedef {import("../../types/math/point").Point} Point
+ * @typedef {import("../../types/math/circle").Circle} Circle
  */
 
-import { magnitude, setMagnitude } from "./vector.js"
-import { distance, dot, subtract, sum } from "./vectors.js"
+import {
+  distance,
+  dot,
+  magnitude,
+  setMagnitude,
+  subtract,
+  sum,
+} from "./vector.js"
 
 const BEFORE_SEGMENT = 0
 

package/src/math/trigonometry.js

@@ -1,4 +1,4 @@
-import { mod } from "./numbers.js"
+import { mod } from "./number.js"
 
 const HALF_CIRCLE_IN_DEGRESS = 180 // Half-circle in degrees (180°)
 const FULL_CIRCLE = 2 // Full circle multiplier for radians (2π)

package/src/math/vector.js

@@ -1,7 +1,8 @@
 /**
- * @typedef {import("../../types/math").Vector} Vector
- * @typedef {import("../../types/math").Vector2} Vector2
- * @typedef {import("../../types/math").Vector3} Vector3
+ * @typedef {import("../../types/math/vector").Vector} Vector
+ * @typedef {import("../../types/math/vector").Vector2} Vector2
+ * @typedef {import("../../types/math/vector").Vector3} Vector3
+ * @typedef {import("../../types/math/vector").Vector7} Vector7
  */
 
 import { v } from "../v.js"
@@ -10,14 +11,32 @@ import {
   clamp as nClamp,
   mod as nMod,
   snap as nSnap,
-} from "./numbers.js"
+} from "./number.js"
 import { quaternion } from "./quaternion.js"
+import { random } from "./rng.js"
 import { hypothenuse } from "./triangle.js"
 import { atan2, cos, sin } from "./trigonometry.js"
-import { cross, sum } from "./vectors.js"
 
-const ZERO_VECTOR = v(0, 0, 0) // eslint-disable-line no-magic-numbers
-const UNIT_VECTOR = v(1, 0, 0) // eslint-disable-line no-magic-numbers
+/**
+ * The vector with every component at zero. Useful for naming the components you
+ * care about, and for building a vector up from scratch:
+ *
+ *     const [, NO_RISE, NO_DEPTH] = ZERO_VECTOR
+ *     const position = v(10, 20, NO_DEPTH)
+ *
+ * Vectors are mutable arrays, so copy it rather than storing it where something
+ * writes to one, such as an entity position. Copy it with `v(...ZERO_VECTOR)`,
+ * since a plain spread drops the tag `isVector` looks for.
+ */
+export const ZERO_VECTOR = v(0, 0, 0) // eslint-disable-line no-magic-numbers
+
+/**
+ * The vector one unit long along the x axis. Useful for facing a direction, as
+ * in `rotate(UNIT_VECTOR, angle)`.
+ *
+ * As with `ZERO_VECTOR`, copy it with `v(...UNIT_VECTOR)` before storing it.
+ */
+export const UNIT_VECTOR = v(1, 0, 0) // eslint-disable-line no-magic-numbers
 
 const X = 0
 const Y = 1
@@ -25,6 +44,7 @@ const Z = 2
 const LAST_COORDINATE = 1
 const TWO_COORDINATES = 2
 const NO_Y = 0
+const NO_COMPONENT = 0
 const DEFAULT_PRECISION = 1
 const DEFAULT_DECIMALS = 0
 
@@ -37,6 +57,12 @@ export function abs(vector) {
   return v(...vector.map(nAbs))
 }
 
+/**
+ * Alias for the sum function.
+ * @type {typeof sum}
+ */
+export const add = sum
+
 /**
  * Calculates the angle of the vector in radians.
  * @param {Vector} vector - The input vector.
@@ -96,6 +122,34 @@ export function createVector(magnitude, angle) {
   return scale(fromAngle(angle), magnitude)
 }
 
+/**
+ * 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 vectors. A scalar operand is applied
+ * to every component.
+ * @param {...(Vector2 | Vector3 | number)} operands - The vectors to divide, or a scalar to divide each component by.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+export function divide(...operands) {
+  return v(...operands.reduce(divideCoordinates))
+}
+
 /**
  * Divides a scalar by each component of the vector.
  * @param {number} scalar - The dividend.
@@ -107,13 +161,14 @@ export function divideBy(scalar, vector) {
 }
 
 /**
- * Divides each component of the vector by the given scalar.
- * @param {Vector} vector - The input vector.
- * @param {number} scalar - The scalar value.
- * @returns {Vector} The resulting vector.
+ * 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 divide(vector, scalar) {
-  return v(...vector.map((coordinate) => coordinate / scalar))
+export function dot(...vectors) {
+  return vectors
+    .reduce(dotMultiplyCoordinates)
+    .reduce((coord1, coord2) => coord1 + coord2)
 }
 
 /**
@@ -135,6 +190,12 @@ export function fromAngle(angle) {
   return rotate(UNIT_VECTOR, angle)
 }
 
+/**
+ * Alias for the multiply function.
+ * @type {typeof multiply}
+ */
+export const hadamard = multiply
+
 /**
  * Checks if a value is a vector.
  * This is determined by checking for the `__isVector__` property, which is
@@ -158,13 +219,13 @@ export function magnitude(vector) {
 export const length = magnitude
 
 /**
- * Calculates the modulus of each component in the vector with the given divisor.
- * @param {Vector} vector - The input vector.
- * @param {number} divisor - The divisor value.
- * @returns {Vector} The resulting vector.
+ * Computes the component-wise modulus of vectors. A scalar operand is applied
+ * to every component.
+ * @param {...(Vector2 | Vector3 | number)} operands - The vectors to compute the modulus for, or a scalar divisor for each component.
+ * @returns {Vector2 | Vector3} The resulting vector after the modulus.
  */
-export function mod(vector, divisor) {
-  return v(...vector.map((coordinate) => nMod(coordinate, divisor)))
+export function mod(...operands) {
+  return v(...operands.reduce(modCoordinates))
 }
 
 /**
@@ -178,13 +239,33 @@ export function modOf(scalar, vector) {
 }
 
 /**
- * Multiplies each component of the vector by the given scalar.
+ * Computes the component-wise multiplication of vectors. A scalar operand is
+ * applied to every component.
+ * @param {...(Vector2 | Vector3 | number)} operands - The vectors to multiply, or a scalar to multiply each component by.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+export function multiply(...operands) {
+  return v(...operands.reduce(multiplyCoordinates))
+}
+
+/**
+ * Flips the direction of every component, so that adding the result to a vector
+ * gives back the point mirrored through it.
  * @param {Vector} vector - The input vector.
- * @param {number} scalar - The scalar value.
- * @returns {Vector} The resulting vector.
+ * @returns {Vector} The negated vector.
  */
-export function multiply(vector, scalar) {
-  return v(...vector.map((coordinate) => coordinate * scalar))
+export function negate(vector) {
+  return v(...vector.map((coordinate) => -coordinate))
+}
+
+/**
+ * Normalizes the vector to have a magnitude of 1.
+ * @param {Vector} vector - The input vector.
+ * @returns {Vector} The normalized vector.
+ */
+export function normalize(vector) {
+  const length = magnitude(vector)
+  return v(...vector.map((coordinate) => coordinate / length))
 }
 
 /**
@@ -194,13 +275,13 @@ export function multiply(vector, scalar) {
 export const pow = power
 
 /**
- * Raises each component of the vector to the given exponent.
- * @param {Vector} vector - The input vector.
- * @param {number} exponent - The exponent value.
- * @returns {Vector} The resulting vector.
+ * Computes the component-wise power of vectors. A scalar operand is applied
+ * to every component.
+ * @param {...(Vector2 | Vector3 | number)} operands - The vectors to compute the power for, or a scalar exponent for each component.
+ * @returns {Vector2 | Vector3} The resulting vector after the power.
  */
-export function power(vector, exponent) {
-  return v(...vector.map((coordinate) => coordinate ** exponent))
+export function power(...operands) {
+  return v(...operands.reduce(powerCoordinates))
 }
 
 /**
@@ -214,13 +295,32 @@ export function powerOf(scalar, vector) {
 }
 
 /**
- * Normalizes the vector to have a magnitude of 1.
- * @param {Vector} vector - The input vector.
- * @returns {Vector} The normalized vector.
- */
-export function normalize(vector) {
-  const length = magnitude(vector)
-  return v(...vector.map((coordinate) => coordinate / length))
+ * Draws a random vector, taking each component from its own range: the low end is
+ * where that axis starts, the high end where it can reach. This is `random`
+ * applied per axis, so it suits ranges that differ by axis, where a single pair of
+ * bounds would have to be square.
+ *
+ * A component whose bounds are the same always comes out equal to them, and either
+ * bound may be left out to fall back to zero on that axis.
+ *
+ * @param {Vector} [low] - Where each axis starts.
+ * @param {Vector} [high] - Where each axis can reach.
+ * @returns {Vector} The random vector.
+ * @example
+ * ```js
+ * // Debris thrown to the left or right, never up or down.
+ * randomVector(v(-15, 0, 0), v(15, 0, 0))
+ * ```
+ */
+export function randomVector(low, high) {
+  const [lowX, lowY, lowZ] = low ?? []
+  const [highX, highY, highZ] = high ?? []
+
+  return v(
+    random(lowX ?? NO_COMPONENT, highX ?? NO_COMPONENT),
+    random(lowY ?? NO_COMPONENT, highY ?? NO_COMPONENT),
+    random(lowZ ?? NO_COMPONENT, highZ ?? NO_COMPONENT),
+  )
 }
 
 /**
@@ -246,6 +346,12 @@ export function rotate(vector, angle) {
   return is2D ? to2D(result) : result
 }
 
+/**
+ * Alias for the dot product function.
+ * @type {typeof dot}
+ */
+export const scalarProduct = dot
+
 /**
  * Alias for the multiply function.
  * @type {typeof multiply}
@@ -303,6 +409,24 @@ export function snap(vector, precision = DEFAULT_PRECISION) {
   )
 }
 
+/**
+ * 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 multiply function.
  * @type {typeof multiply}
@@ -396,6 +520,12 @@ export function unit(angle) {
   return setAngle(UNIT_VECTOR, angle)
 }
 
+/**
+ * Alias for the cross product function.
+ * @type {typeof cross}
+ */
+export const vectorProduct = cross
+
 /**
  * Creates a zero vector of 3 dimensions.
  * @returns {Vector3} The zero vector.
@@ -404,6 +534,127 @@ export function zero() {
   return v(...ZERO_VECTOR)
 }
 
+/**
+ * Reads the value at the given index of a vector operand, broadcasting a
+ * scalar operand to every index.
+ * @param {number | Vector2 | Vector3 | Vector7} operand - A vector or a scalar.
+ * @param {number} index - The index of the coordinate to read.
+ * @returns {number} The coordinate value.
+ */
+function broadcast(operand, index) {
+  return typeof operand === "number" ? operand : operand[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]
+      )
+    }),
+  )
+}
+
+/**
+ * Divides the coordinates of two vectors component-wise. Scalars are broadcast.
+ * @param {Vector2 | Vector3} vector1 - The dividend vector.
+ * @param {number | Vector2 | Vector3} vector2 - The divisor vector or scalar.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+function divideCoordinates(vector1, vector2) {
+  return v(
+    ...vector1.map(
+      (coordinate, index) => coordinate / broadcast(vector2, index),
+    ),
+  )
+}
+
+/**
+ * Multiplies the coordinates of two vectors component-wise. Scalars are broadcast.
+ * @param {Vector2 | Vector3} vector1 - The first vector.
+ * @param {number | Vector2 | Vector3} vector2 - The second vector or scalar.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+function dotMultiplyCoordinates(vector1, vector2) {
+  return v(...vector1.map((coordinate, index) => coordinate * vector2[index]))
+}
+
+/**
+ * Computes the component-wise modulus of two vectors. Scalars are broadcast.
+ * @param {Vector2 | Vector3} vector1 - The first vector.
+ * @param {number | Vector2 | Vector3} vector2 - The second vector or scalar.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+function modCoordinates(vector1, vector2) {
+  return v(
+    ...vector1.map((coordinate, index) =>
+      nMod(coordinate, broadcast(vector2, index)),
+    ),
+  )
+}
+
+/**
+ * Multiplies the coordinates of two vectors component-wise. Scalars are broadcast.
+ * @param {Vector2 | Vector3} vector1 - The first vector.
+ * @param {number | Vector2 | Vector3} vector2 - The second vector or scalar.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+function multiplyCoordinates(vector1, vector2) {
+  return v(
+    ...vector1.map(
+      (coordinate, index) => coordinate * broadcast(vector2, index),
+    ),
+  )
+}
+
+/**
+ * Raises the coordinates of the first vector to the power of the second vector's coordinates. Scalars are broadcast.
+ * @param {Vector2 | Vector3} vector1 - The base vector.
+ * @param {number | Vector2 | Vector3} vector2 - The exponent vector or scalar.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+function powerCoordinates(vector1, vector2) {
+  return v(
+    ...vector1.map(
+      (coordinate, index) => coordinate ** broadcast(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]))
+}
+
+/**
+ * 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]))
+}
+
 /**
  * Rotates a 3D vector around the Y-axis using a quaternion.
  * @param {Vector3} vector - The input vector.

package/src/physics/acceleration.js

@@ -1,9 +1,8 @@
 /**
- * @typedef {import("../../types/math").Vector3} Vector3
+ * @typedef {import("../../types/math/vector").Vector3} Vector3
  */
 
-import { clamp, multiply, zero } from "../math/vector.js"
-import { sum } from "../math/vectors.js"
+import { clamp, multiply, sum, zero } from "../math/vector.js"
 import { applyFriction } from "./friction.js"
 
 const DEFAULT_DT = 1 // Default time delta for the applyAcceleration function.

package/src/physics/friction.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import("../../types/math").Vector3} Vector3
+ * @typedef {import("../../types/math/vector").Vector3} Vector3
  */
 
 import { magnitude, setMagnitude, zero } from "../math/vector.js"

package/src/physics/gravity.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import("../../types/math").Vector3} Vector3
+ * @typedef {import("../../types/math/vector").Vector3} Vector3
  */
 
 /* eslint-disable no-magic-numbers */

package/src/physics/jump.js

@@ -1,7 +1,3 @@
-/**
- * @typedef {import("../../types/math").Vector3} Vector3
- */
-
 /* eslint-disable no-magic-numbers */
 
 const DEFAULT_MAX_JUMP = 0 // Default maximum jump height.

package/src/physics/velocity.js

@@ -1,9 +1,8 @@
 /**
- * @typedef {import("../../types/math").Vector3} Vector3
+ * @typedef {import("../../types/math/vector").Vector3} Vector3
  */
 
-import { clamp, multiply, zero } from "../math/vector.js"
-import { sum } from "../math/vectors.js"
+import { clamp, multiply, sum, zero } from "../math/vector.js"
 
 const DEFAULT_DT = 1 // Default time delta for the applyVelocity function.
 const DEFAULT_MAX_SPEED = 0 // Default maximum speed for velocity clamping.

package/src/v.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import("../types/math").Vector} Vector
+ * @typedef {import("../types/math/vector").Vector} Vector
  */
 
 import { isArray } from "./data-structures/array.js"

package/types/algorithms/decision-tree.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Represents the input conditions evaluated by a decision tree.
+ */
+export type Conditions = unknown
+
+/**
+ * Represents the value returned by a decision tree node's test function.
+ */
+export type Outcome = string | boolean
+
+/**
+ * Represents a node in a decision tree.
+ */
+export interface DecisionTree<C = Conditions> {
+  /** Evaluates conditions and returns the key of the branch to follow. */
+  test?: (conditions: C) => Outcome
+  /** Resolves the branch associated with a test outcome. */
+  [outcome: string]: ((conditions: C) => Outcome | DecisionTree<C>) | undefined
+}
+
+/**
+ * Traverses a decision tree based on the provided conditions.
+ */
+export function decide<C>(
+  tree: DecisionTree<C>,
+  conditions: NoInfer<C>,
+): Outcome | DecisionTree<C> | undefined

package/types/algorithms/index.d.ts

@@ -0,0 +1,2 @@
+export * as decisionTree from "./decision-tree"
+export * as pathfinding from "./path-finding"