@inglorious/utils 4.0.0 → 5.0.0

package/README.md

@@ -92,7 +92,7 @@ const throttledSave = throttle(() => {
 Perform vector operations on plain objects.
 
 ```javascript
-import { add } from "@inglorious/utils/vectors"
+import { add } from "@inglorious/utils/vector.js"
 
 const position = [10, 20]
 const velocity = [2, -1]
@@ -101,6 +101,23 @@ const newPosition = add(position, velocity)
 // => [12, 19]
 ```
 
+Two vectors are worth knowing by name: `ZERO_VECTOR`, with every component at zero, and
+`UNIT_VECTOR`, one unit long along the x axis. The zero one is handy for naming the components
+you care about, or for building a vector up from scratch:
+
+```javascript
+import { ZERO_VECTOR } from "@inglorious/utils/math/vector.js"
+import { v } from "@inglorious/utils/v.js"
+
+const [, NO_RISE, NO_DEPTH] = ZERO_VECTOR
+
+const position = v(10, 20, NO_DEPTH)
+```
+
+Vectors are mutable arrays, so copy a shared vector rather than storing it where something writes
+to one, such as an entity position. Copy it with `v(...ZERO_VECTOR)`: a plain spread
+(`[...ZERO_VECTOR]`) gives you a new array but drops the tag that `isVector` looks for.
+
 ---
 
 ## API
@@ -111,7 +128,6 @@ Most modules are grouped by category:
 
 - **`@inglorious/utils/algorithms`**: Utilities for AI algorithms, like decision trees and A\*.
 - **`@inglorious/utils/data-structures`**: Utilities for arrays, boards, heaps, objects, sets, strings, and trees.
-- **`@inglorious/utils/functions`**: Utilities for function composition and timing.
 - **`@inglorious/utils/math`**: Utilities for math operations.
 - **`@inglorious/utils/physics`**: Utilities for calculations on friction, acceleration, and gravity.
 
@@ -119,15 +135,15 @@ The four largest modules are also available as top-level subpaths, so you don't
 know whether a helper lives under `data-structures` or `math`:
 
 - **`@inglorious/utils/functions`**: `compose`, `debounce`, `isFunction`, `pipe`, `throttle`.
-- **`@inglorious/utils/objects`**: Single-object helpers (`clone`, `get`, `set`, `produce`, ...) alongside multi-object helpers (`merge`, `extend`, `defaults`, ...).
-- **`@inglorious/utils/quaternions`**: `quaternion` and `combine`.
-- **`@inglorious/utils/vectors`**: Single-vector helpers (`magnitude`, `normalize`, `rotate`, ...) alongside multi-vector helpers (`cross`, `dot`, `sum`, ...).
+- **`@inglorious/utils/object`**: Single-object helpers (`clone`, `get`, `set`, `produce`, ...) alongside multi-object helpers (`merge`, `extend`, `defaults`, ...).
+- **`@inglorious/utils/quaternion`**: `quaternion` and `combine`.
+- **`@inglorious/utils/vector`**: Single-vector helpers (`magnitude`, `normalize`, `rotate`, ...) alongside multi-vector helpers (`cross`, `dot`, `sum`, ...).
 
 `divide`, `mod`, `multiply` and `power` accept either a scalar or one or more vectors:
 a scalar is applied to every component, while vectors are combined component-wise.
 
 ```javascript
-import { multiply } from "@inglorious/utils/vectors"
+import { multiply } from "@inglorious/utils/vector.js"
 
 multiply([1, 2, 3], 2) // => [2, 4, 6]
 multiply([1, 2, 3], [4, 5, 6]) // => [4, 10, 18]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "A set of general-purpose utility functions designed with functional programming principles in mind.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -26,6 +26,14 @@
       "types": "./types/index.d.ts",
       "import": "./src/index.js"
     },
+    "./array.js": {
+      "types": "./types/data-structures/array.d.ts",
+      "import": "./src/data-structures/array.js"
+    },
+    "./array": {
+      "types": "./types/data-structures/array.d.ts",
+      "import": "./src/data-structures/array.js"
+    },
     "./algorithms": {
       "types": "./types/algorithms/index.d.ts",
       "import": "./src/algorithms/index.js"
@@ -50,6 +58,14 @@
       "types": "./types/data-structures/*.d.ts",
       "import": "./src/data-structures/*.js"
     },
+    "./function.js": {
+      "types": "./types/functions/function.d.ts",
+      "import": "./src/functions/function.js"
+    },
+    "./function": {
+      "types": "./types/functions/function.d.ts",
+      "import": "./src/functions/function.js"
+    },
     "./functions": {
       "types": "./types/functions/index.d.ts",
       "import": "./src/functions/index.js"
@@ -78,29 +94,29 @@
       "types": "./types/physics/*.d.ts",
       "import": "./src/physics/*.js"
     },
-    "./objects.js": {
-      "types": "./types/data-structures/objects.d.ts",
-      "import": "./src/data-structures/objects.js"
+    "./object.js": {
+      "types": "./types/data-structures/object.d.ts",
+      "import": "./src/data-structures/object.js"
     },
-    "./objects": {
-      "types": "./types/data-structures/objects.d.ts",
-      "import": "./src/data-structures/objects.js"
+    "./object": {
+      "types": "./types/data-structures/object.d.ts",
+      "import": "./src/data-structures/object.js"
     },
-    "./quaternions.js": {
-      "types": "./types/math/quaternions.d.ts",
-      "import": "./src/math/quaternions.js"
+    "./quaternion.js": {
+      "types": "./types/math/quaternion.d.ts",
+      "import": "./src/math/quaternion.js"
     },
-    "./quaternions": {
-      "types": "./types/math/quaternions.d.ts",
-      "import": "./src/math/quaternions.js"
+    "./quaternion": {
+      "types": "./types/math/quaternion.d.ts",
+      "import": "./src/math/quaternion.js"
     },
-    "./vectors.js": {
-      "types": "./types/math/vectors.d.ts",
-      "import": "./src/math/vectors.js"
+    "./vector.js": {
+      "types": "./types/math/vector.d.ts",
+      "import": "./src/math/vector.js"
     },
-    "./vectors": {
-      "types": "./types/math/vectors.d.ts",
-      "import": "./src/math/vectors.js"
+    "./vector": {
+      "types": "./types/math/vector.d.ts",
+      "import": "./src/math/vector.js"
     },
     "./v.js": {
       "types": "./types/v.d.ts",

package/src/algorithms/path-finding.js

@@ -1,11 +1,11 @@
 /**
  * @typedef {import("../../types/algorithms/path-finding").Node} Node
  * @typedef {import("../../types/algorithms/path-finding").Graph} Graph
- * @typedef {import("../../types/math/vectors").Vector2} Vector2
+ * @typedef {import("../../types/math/vector").Vector2} Vector2
  */
 
 import { contains, push, remove, root } from "../data-structures/heap.js"
-import { abs, magnitude, subtract } from "../math/vectors.js"
+import { abs, magnitude, subtract } from "../math/vector.js"
 
 const NO_COST = 0
 

package/src/data-structures/array.js

@@ -22,6 +22,18 @@ export function contains(arr, item) {
   return arr.includes(item)
 }
 
+/**
+ * The index `step` places along a list of `length`, wrapping round at either end.
+ *
+ * @param {number} index - Where to start from.
+ * @param {number} length - How long the list is.
+ * @param {number} step - How far to move. Negative steps move backwards.
+ * @returns {number} - The index landed on, always within the list.
+ */
+export function cycleIndex(index, length, step) {
+  return (((index + step) % length) + length) % length
+}
+
 /**
  * Ensures that the given value is an array. If it's not an array, it wraps it in one.
  *

package/src/data-structures/index.js

@@ -2,9 +2,9 @@ import * as array from "./array.js"
 import * as board from "./board.js"
 import * as boolean from "./boolean.js"
 import * as heap from "./heap.js"
-import * as objects from "./objects.js"
+import * as object from "./object.js"
 import * as set from "./set.js"
 import * as string from "./string.js"
 import * as tree from "./tree.js"
 
-export { array, board, boolean, heap, objects, set, string, tree }
+export { array, board, boolean, heap, object, set, string, tree }

package/src/data-structures/{objects.js → object.js}

@@ -1,4 +1,4 @@
-import { isFunction } from "../functions/functions.js"
+import { isFunction } from "../functions/function.js"
 import { v } from "../v.js"
 import { isArray } from "./array.js"
 
@@ -28,6 +28,39 @@ 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`,
@@ -186,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
 }
@@ -286,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",
@@ -360,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) {
@@ -396,36 +480,3 @@ ${" ".repeat(indentationLevel)}}`
 
   return 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
-}

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

@@ -1 +1 @@
-export * from "./functions.js"
+export * from "./function.js"

package/src/math/circle.js

@@ -6,7 +6,7 @@
 
 import { intersectsCircle as pointIntersectsCircle } from "./point.js"
 import { hypothenuse } from "./triangle.js"
-import { clamp, subtract } from "./vectors.js"
+import { clamp, subtract } from "./vector.js"
 
 const HALF = 2
 const SQUARED = 2

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,16 +2,16 @@ 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 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"
 import * as statistics from "./statistics.js"
 import * as triangle from "./triangle.js"
 import * as trigonometry from "./trigonometry.js"
-import * as vectors from "./vectors.js"
+import * as vector from "./vector.js"
 
 export {
   circle,
@@ -27,5 +27,5 @@ export {
   statistics,
   triangle,
   trigonometry,
-  vectors,
+  vector,
 }

package/src/math/line.js

@@ -4,7 +4,7 @@
  * @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,4 +1,25 @@
 /**
+ * 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
@@ -10,8 +31,8 @@ const SQUARED = 2
 const HALF = 2
 
 import { distanceFromPoint } from "./line.js"
-import { isBetween } from "./numbers.js"
-import { isVector } from "./vectors.js"
+import { isBetween } from "./number.js"
+import { isVector } from "./vector.js"
 
 /**
  * Calculates the distance from a point to a line.

package/src/math/{quaternions.js → quaternion.js}

@@ -1,11 +1,11 @@
 /**
- * @typedef {import("../../types/math/vectors").Vector3} Vector3
- * @typedef {import("../../types/math/quaternions").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 "./vectors.js"
+import { cross, dot, multiply, sum } from "./vector.js"
 
 const DEFAULT_ANGLE = 0
 const HALF = 2 // Constant representing the divisor for halving an angle.

package/src/math/rectangle.js

@@ -1,4 +1,11 @@
 /**
+ * `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
@@ -11,6 +18,11 @@ 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 {PointInput} point - The point to check.
  * @returns {boolean} True if the point intersects the circle, false otherwise.

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

@@ -11,7 +11,7 @@ import {
   setMagnitude,
   subtract,
   sum,
-} from "./vectors.js"
+} 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/{vectors.js → vector.js}

@@ -1,8 +1,8 @@
 /**
- * @typedef {import("../../types/math/vectors").Vector} Vector
- * @typedef {import("../../types/math/vectors").Vector2} Vector2
- * @typedef {import("../../types/math/vectors").Vector3} Vector3
- * @typedef {import("../../types/math/vectors").Vector7} Vector7
+ * @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"
@@ -11,13 +11,32 @@ import {
   clamp as nClamp,
   mod as nMod,
   snap as nSnap,
-} from "./numbers.js"
-import { quaternion } from "./quaternions.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"
 
-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
 
@@ -228,6 +248,16 @@ 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.
+ * @returns {Vector} The negated vector.
+ */
+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.
@@ -264,6 +294,35 @@ export function powerOf(scalar, vector) {
   return v(...vector.map((coordinate) => scalar ** coordinate))
 }
 
+/**
+ * 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),
+  )
+}
+
 /**
  * Alias for the mod function.
  * @type {typeof mod}

package/src/physics/acceleration.js

@@ -1,8 +1,8 @@
 /**
- * @typedef {import("../../types/math/vectors").Vector3} Vector3
+ * @typedef {import("../../types/math/vector").Vector3} Vector3
  */
 
-import { clamp, multiply, sum, zero } 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,8 +1,8 @@
 /**
- * @typedef {import("../../types/math/vectors").Vector3} Vector3
+ * @typedef {import("../../types/math/vector").Vector3} Vector3
  */
 
-import { magnitude, setMagnitude, zero } from "../math/vectors.js"
+import { magnitude, setMagnitude, zero } from "../math/vector.js"
 
 const DEFAULT_DT = 1 // Default time delta for the applyFriction function.
 const NO_FRICTION = 0 // No friction constant.

package/src/physics/gravity.js

@@ -1,10 +1,10 @@
 /**
- * @typedef {import("../../types/math/vectors").Vector3} Vector3
+ * @typedef {import("../../types/math/vector").Vector3} Vector3
  */
 
 /* eslint-disable no-magic-numbers */
 
-import { zero } from "../math/vectors.js"
+import { zero } from "../math/vector.js"
 
 const DEFAULT_DT = 1 // Default delta time for the applyGravity function.
 const DEFAULT_JUMP = 0 // Default maximum jump height.

package/src/physics/velocity.js

@@ -1,8 +1,8 @@
 /**
- * @typedef {import("../../types/math/vectors").Vector3} Vector3
+ * @typedef {import("../../types/math/vector").Vector3} Vector3
  */
 
-import { clamp, multiply, sum, zero } 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/vectors").Vector} Vector
+ * @typedef {import("../types/math/vector").Vector} Vector
  */
 
 import { isArray } from "./data-structures/array.js"

package/types/algorithms/path-finding.d.ts

@@ -1,4 +1,4 @@
-import type { Vector2 } from "../math/vectors"
+import type { Vector2 } from "../math/vector"
 
 /**
  * A map where keys are node identifiers and values are their [x, y] coordinates.

package/types/data-structures/array.d.ts

@@ -5,6 +5,11 @@ export type Comparator<T> = (left: T, right: T) => number
  */
 export function contains<T>(arr: readonly T[], item: T): boolean
 
+/**
+ * The index `step` places along a list of `length`, wrapping round at either end.
+ */
+export function cycleIndex(index: number, length: number, step: number): number
+
 /**
  * Ensures that a value is an array.
  */

package/types/data-structures/index.d.ts

@@ -2,7 +2,7 @@ export * as array from "./array"
 export * as board from "./board"
 export * as boolean from "./boolean"
 export * as heap from "./heap"
-export * as objects from "./objects"
+export * as object from "./object"
 export * as set from "./set"
 export * as string from "./string"
 export * as tree from "./tree"

package/types/data-structures/{objects.d.ts → object.d.ts}

@@ -1,4 +1,4 @@
-import type { Vector } from "../math/vectors"
+import type { Vector } from "../math/vector"
 
 export type ObjectValue<T> = T extends object ? T[keyof T] : never
 

package/types/math/index.d.ts

@@ -2,13 +2,13 @@ export * as circle from "./circle"
 export * as hitmask from "./hitmask"
 export * as line from "./line"
 export * as linearInterpolation from "./linear-interpolation"
-export * as numbers from "./numbers"
+export * as number from "./number"
 export * as point from "./point"
-export * as quaternions from "./quaternions"
+export * as quaternion from "./quaternion"
 export * as rectangle from "./rectangle"
 export * as rng from "./rng"
 export * as segment from "./segment"
 export * as statistics from "./statistics"
 export * as triangle from "./triangle"
 export * as trigonometry from "./trigonometry"
-export * as vectors from "./vectors"
+export * as vector from "./vector"

package/types/math/point.d.ts

@@ -3,7 +3,32 @@ import type { Circle } from "./circle"
 import type { Line } from "./line"
 import type { Rectangle } from "./rectangle"
 
-/** Represents a point in 3D space. */
+/**
+ * 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 are what turn them into screen
+ * coordinates: `@inglorious/renderer-2d` projects a point to
+ * `canvasY = viewportHeight - y - z`, which puts `(0, 0, 0)` at the bottom-left
+ * corner of the canvas and turns both axes upside down.
+ *
+ * @example Reading a position in a 2D game
+ * ```js
+ * // Ground level, and a hundred pixels above it.
+ * v(0, 0, 0) // the floor
+ * v(0, 100, 0) // a hundred pixels up
+ *
+ * // Falling means losing height, in 2D as well as in 3D.
+ * entity.velocity[1] -= GRAVITY * dt
+ *
+ * // Keep a body on the ground.
+ * entity.position[1] = 0
+ * ```
+ */
 export type Point = readonly [x: number, y: number, z: number]
 
 /** Accepts a 3D point, branded vector, or object with a point position. */

package/types/math/{quaternions.d.ts → quaternion.d.ts}

@@ -1,4 +1,4 @@
-import type { Vector, Vector3 } from "./vectors"
+import type { Vector, Vector3 } from "./vector"
 
 /** A quaternion represented as a four-dimensional vector. */
 export type Quaternion = Vector<readonly [number, number, number, number]>

package/types/math/rectangle.d.ts

@@ -1,10 +1,31 @@
 import type { Circle } from "./circle"
 import type { Point, PointInput } from "./point"
 
-/** Represents the dimensions of a 3D object. */
+/**
+ * The dimensions of a 3D object, as `[width, height, depth]`.
+ *
+ * `width` is the extent along `x`, `height` the extent along `y` and `depth` the
+ * extent along `z`. `height` and `depth` are **independent axes**, not halves of
+ * one screen dimension, so in a 2D game that plays on the `xy` plane a size reads
+ * as `v(w, h, 0)` — and an entity whose body is placed on the `xz` plane instead
+ * reads as `v(w, 0, h)`.
+ *
+ * When a renderer has to flatten both vertical axes onto the screen, it adds
+ * them: `@inglorious/renderer-2d` draws a rectangle `height + depth` tall. A
+ * collision shape never does — `intersectsRectangle` tests the two axes
+ * separately, which is why a body cannot collide with something that is merely
+ * "near it" on the other axis.
+ */
 export type Size = readonly [width: number, height: number, depth: number]
 
-/** Represents an axis-aligned rectangle. */
+/**
+ * Represents an axis-aligned rectangle.
+ *
+ * `position` is the point the box hangs off and `size` is its extent, so with
+ * the default centred anchor the position is the middle of the box. Set an
+ * `anchor` to describe the box by a different point, such as `[0, 0]` for its
+ * bottom-left corner, so that the box stands on its position.
+ */
 export interface Rectangle {
   /** The center of the rectangle. */
   position: Point

package/types/math/{vectors.d.ts → vector.d.ts}

@@ -18,6 +18,22 @@ export type Vector7 = Vector<
   readonly [number, number, number, number, number, number, number]
 >
 
+/**
+ * The vector with every component at zero.
+ *
+ * Vectors are mutable, so copy it with `v(...ZERO_VECTOR)` before storing it
+ * where something writes to one.
+ */
+export const ZERO_VECTOR: Vector3
+
+/**
+ * The vector one unit long along the x axis.
+ *
+ * Vectors are mutable, so copy it with `v(...UNIT_VECTOR)` before storing it
+ * where something writes to one.
+ */
+export const UNIT_VECTOR: Vector3
+
 /** Returns the absolute value of each vector component. */
 export function abs<T extends Vector>(vector: T): T
 
@@ -107,6 +123,11 @@ export function multiply<T extends Vector2 | Vector3>(
 ): T
 
 /** Normalizes a vector to unit magnitude. */
+/**
+ * Flips the direction of every component.
+ */
+export function negate<T extends Vector>(vector: T): T
+
 export function normalize<T extends Vector>(vector: T): T
 
 /** Alias for `power`. */
@@ -124,6 +145,14 @@ export function power<T extends Vector2 | Vector3>(
 /** Raises a scalar to each vector component. */
 export function powerOf<T extends Vector>(scalar: number, vector: T): T
 
+/**
+ * Draws a random vector, taking each component from its own range.
+ */
+export function randomVector(
+  low?: readonly number[],
+  high?: readonly number[],
+): Vector3
+
 /** Alias for `mod`. */
 export const remainder: typeof mod
 

package/types/physics/acceleration.d.ts

@@ -1,4 +1,4 @@
-import type { Vector3 } from "../math/vectors"
+import type { Vector3 } from "../math/vector"
 
 export interface AccelerationParams {
   acceleration?: Vector3

package/types/physics/friction.d.ts

@@ -1,4 +1,4 @@
-import type { Vector3 } from "../math/vectors"
+import type { Vector3 } from "../math/vector"
 
 export interface FrictionParams {
   friction: number

package/types/physics/gravity.d.ts

@@ -1,4 +1,4 @@
-import type { Vector3 } from "../math/vectors"
+import type { Vector3 } from "../math/vector"
 
 export interface GravityParams {
   maxJump?: number

package/types/physics/velocity.d.ts

@@ -1,4 +1,4 @@
-import type { Vector3 } from "../math/vectors"
+import type { Vector3 } from "../math/vector"
 
 export interface VelocityParams {
   maxSpeed?: number

package/types/v.d.ts

@@ -1,4 +1,4 @@
-import type { Vector } from "./math/vectors"
+import type { Vector } from "./math/vector"
 
 /**
  * Ensures that a given value is a vector.