@inglorious/utils 3.8.0 → 5.0.0

package/README.md

@@ -25,12 +25,43 @@ npm install @inglorious/utils
 
 Here are a few examples of how you can use the utilities in this package.
 
+### `compose`
+
+Compose functions together from right to left.
+
+```javascript
+import { compose } from "@inglorious/utils/functions"
+
+const add = (a) => (b) => a + b
+const multiply = (a) => (b) => a * b
+
+const calculate = compose(
+  add(10), // 30 + 10 = 40
+  multiply(2), // 15 * 2 = 30
+  add(5), // 10 + 5 = 15
+)
+
+const result = calculate(10) // 40
+```
+
+### `debounce`
+
+Delay a function until calls stop for a given amount of time.
+
+```javascript
+import { debounce } from "@inglorious/utils/functions"
+
+const debouncedSave = debounce(() => {
+  save()
+}, 300)
+```
+
 ### `pipe`
 
 Compose functions together in a readable, left-to-right sequence.
 
 ```javascript
-import { pipe } from "@inglorious/utils/functions/functions"
+import { pipe } from "@inglorious/utils/functions"
 
 const add = (a) => (b) => a + b
 const multiply = (a) => (b) => a * b
@@ -44,12 +75,24 @@ const calculate = pipe(
 const result = calculate(10) // 40
 ```
 
+### `throttle`
+
+Run a function immediately, then suppress repeated calls until the wait time has elapsed.
+
+```javascript
+import { throttle } from "@inglorious/utils/functions"
+
+const throttledSave = throttle(() => {
+  save()
+}, 300)
+```
+
 ### Vector Math
 
 Perform vector operations on plain objects.
 
 ```javascript
-import { add } from "@inglorious/utils/math/vector.js"
+import { add } from "@inglorious/utils/vector.js"
 
 const position = [10, 20]
 const velocity = [2, -1]
@@ -58,17 +101,54 @@ 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
 
 This package is designed to be used with subpath imports, which helps with tree-shaking.
 
+Most modules are grouped by category:
+
 - **`@inglorious/utils/algorithms`**: Utilities for AI algorithms, like decision trees and A\*.
-- **`@inglorious/utils/functions`**: Utilities for function composition.
+- **`@inglorious/utils/data-structures`**: Utilities for arrays, boards, heaps, objects, sets, strings, and trees.
 - **`@inglorious/utils/math`**: Utilities for math operations.
 - **`@inglorious/utils/physics`**: Utilities for calculations on friction, acceleration, and gravity.
 
+The four largest modules are also available as top-level subpaths, so you don't need to
+know whether a helper lives under `data-structures` or `math`:
+
+- **`@inglorious/utils/functions`**: `compose`, `debounce`, `isFunction`, `pipe`, `throttle`.
+- **`@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/vector.js"
+
+multiply([1, 2, 3], 2) // => [2, 4, 6]
+multiply([1, 2, 3], [4, 5, 6]) // => [4, 10, 18]
+```
+
 ---
 
 ## License

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@inglorious/utils",
-  "version": "3.8.0",
+  "version": "5.0.0",
   "description": "A set of general-purpose utility functions designed with functional programming principles in mind.",
-  "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
+  "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,13 +26,105 @@
       "types": "./types/index.d.ts",
       "import": "./src/index.js"
     },
-    "./data-structures/string.js": {
-      "types": "./types/data-structures/string.d.ts",
-      "import": "./src/data-structures/string.js"
+    "./array.js": {
+      "types": "./types/data-structures/array.d.ts",
+      "import": "./src/data-structures/array.js"
     },
-    "./*": {
-      "types": "./types/*.d.ts",
-      "import": "./src/*"
+    "./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"
+    },
+    "./algorithms/*.js": {
+      "types": "./types/algorithms/*.d.ts",
+      "import": "./src/algorithms/*.js"
+    },
+    "./algorithms/*": {
+      "types": "./types/algorithms/*.d.ts",
+      "import": "./src/algorithms/*.js"
+    },
+    "./data-structures": {
+      "types": "./types/data-structures/index.d.ts",
+      "import": "./src/data-structures/index.js"
+    },
+    "./data-structures/*.js": {
+      "types": "./types/data-structures/*.d.ts",
+      "import": "./src/data-structures/*.js"
+    },
+    "./data-structures/*": {
+      "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"
+    },
+    "./math": {
+      "types": "./types/math/index.d.ts",
+      "import": "./src/math/index.js"
+    },
+    "./math/*.js": {
+      "types": "./types/math/*.d.ts",
+      "import": "./src/math/*.js"
+    },
+    "./math/*": {
+      "types": "./types/math/*.d.ts",
+      "import": "./src/math/*.js"
+    },
+    "./physics": {
+      "types": "./types/physics/index.d.ts",
+      "import": "./src/physics/index.js"
+    },
+    "./physics/*.js": {
+      "types": "./types/physics/*.d.ts",
+      "import": "./src/physics/*.js"
+    },
+    "./physics/*": {
+      "types": "./types/physics/*.d.ts",
+      "import": "./src/physics/*.js"
+    },
+    "./object.js": {
+      "types": "./types/data-structures/object.d.ts",
+      "import": "./src/data-structures/object.js"
+    },
+    "./object": {
+      "types": "./types/data-structures/object.d.ts",
+      "import": "./src/data-structures/object.js"
+    },
+    "./quaternion.js": {
+      "types": "./types/math/quaternion.d.ts",
+      "import": "./src/math/quaternion.js"
+    },
+    "./quaternion": {
+      "types": "./types/math/quaternion.d.ts",
+      "import": "./src/math/quaternion.js"
+    },
+    "./vector.js": {
+      "types": "./types/math/vector.d.ts",
+      "import": "./src/math/vector.js"
+    },
+    "./vector": {
+      "types": "./types/math/vector.d.ts",
+      "import": "./src/math/vector.js"
+    },
+    "./v.js": {
+      "types": "./types/v.d.ts",
+      "import": "./src/v.js"
+    },
+    "./v": {
+      "types": "./types/v.d.ts",
+      "import": "./src/v.js"
     }
   },
   "files": [
@@ -45,10 +137,10 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "prettier": "^3.6.2",
-    "vite": "^7.1.3",
-    "vitest": "^1.6.1",
-    "@inglorious/eslint-config": "1.1.2"
+    "@inglorious/eslint-config": "1.1.2",
+    "prettier": "^3.9.6",
+    "vite": "^8.2.2",
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">= 22"

package/src/algorithms/decision-tree.js

@@ -1,7 +1,7 @@
 /**
- * @typedef {import("../../types/algorithms").Conditions} Conditions
- * @typedef {import("../../types/algorithms").Outcome} Outcome
- * @typedef {import("../../types/algorithms").DecisionTree} DecisionTree
+ * @typedef {import("../../types/algorithms/decision-tree").Conditions} Conditions
+ * @typedef {import("../../types/algorithms/decision-tree").Outcome} Outcome
+ * @typedef {import("../../types/algorithms/decision-tree").DecisionTree} DecisionTree
  */
 
 /**

package/src/algorithms/path-finding.js

@@ -1,11 +1,11 @@
 /**
- * @typedef {import("../../types/data-structures").Node} Node
- * @typedef {import("../../types/data-structures").Graph} Graph
+ * @typedef {import("../../types/algorithms/path-finding").Node} Node
+ * @typedef {import("../../types/algorithms/path-finding").Graph} Graph
+ * @typedef {import("../../types/math/vector").Vector2} Vector2
  */
 
 import { contains, push, remove, root } from "../data-structures/heap.js"
-import { abs, magnitude } from "../math/vector.js"
-import { subtract } from "../math/vectors.js"
+import { abs, magnitude, subtract } from "../math/vector.js"
 
 const NO_COST = 0
 
@@ -32,7 +32,7 @@ export const eucledianDistance = (a, b) =>
  *
  * @param {Node} a - The first node.
  * @param {Node} b - The second node.
- * @returns {number} - The Manhattan distance between the two nodes.
+ * @returns {Vector2} The component-wise Manhattan distance between the two nodes.
  */
 export const manhattanDistance = (a, b) => abs(subtract(a.position, b.position))
 
@@ -61,7 +61,7 @@ const compareTotalCost = (a, b) => b.totalCost - a.totalCost
  * @param {string} start - The ID of the start node.
  * @param {string} end - The ID of the end node.
  * @param {(a: Node, b: Node) => number} [heuristic=eucledianDistance] - The heuristic function to estimate the cost.
- * @returns {string[]} - An array of node IDs representing the shortest path.
+ * @returns {string[]|undefined} - The node IDs representing the shortest path, or `undefined` if no path exists.
  */
 export function findPath(graph, start, end, heuristic = eucledianDistance) {
   const { nodes, arcs } = adaptGraph(graph)

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

@@ -11,24 +11,55 @@ const DEFAULT_FILLER = () => null
  */
 const DEFAULT_CELL_TO_STRING = (cell) => `${cell}`
 
+/**
+ * Default predicate that matches every neighboring cell.
+ * @returns {boolean} Always true.
+ */
+const DEFAULT_NEIGHBOR_PREDICATE = () => true
+
 const FIRST_ROW = 0
 const FIRST_COLUMN = 0
 const LAST_ROW_OFFSET = 1
 const LAST_COLUMN_OFFSET = 1
-const MOVE_DOWN = 1
-const MOVE_LEFT = -1
-const MOVE_RIGHT = 1
-const MOVE_UP = -1
+const DOWN = 1
+const LEFT = -1
+const RIGHT = 1
+const UP = -1
+const CENTER = 0
+
+const BOTH = "both"
+const HORIZONTAL = "horizontal"
+const NO_WRAP = undefined
+const VERTICAL = "vertical"
+
+const NEIGHBOR_OFFSETS = [
+  [UP, LEFT],
+  [UP, CENTER],
+  [UP, RIGHT],
+  [CENTER, LEFT],
+  [CENTER, RIGHT],
+  [DOWN, LEFT],
+  [DOWN, CENTER],
+  [DOWN, RIGHT],
+]
 
 /**
- * Calculates the index in a one-dimensional array for given row and column.
- * @param {number} row - The row index.
- * @param {number} column - The column index.
- * @param {number} columns - The total number of columns.
- * @returns {number} The calculated index.
+ * Counts the neighboring cells that satisfy a predicate.
+ * @param {Array} cells - The board cells.
+ * @param {[number, number]} coords - The coordinates [row, column].
+ * @param {[number, number]} size - Array containing the number of rows and columns.
+ * @param {Object} [options] - Neighbor options.
+ * @param {Function} [options.predicate=DEFAULT_NEIGHBOR_PREDICATE] - The predicate applied to each neighboring cell.
+ * @param {"horizontal" | "vertical" | "both"} [options.wrap=undefined] - The axes that wrap around board edges.
+ * @returns {number} The number of matching neighboring cells.
  */
-function getIndex(row, column, columns) {
-  return row * columns + column
+export function countNeighbors(cells, coords, size, options = {}) {
+  const { predicate = DEFAULT_NEIGHBOR_PREDICATE, wrap = NO_WRAP } = options
+  const [, columns] = size
+
+  return neighbors(coords, size, { wrap }).filter(([row, column]) =>
+    predicate(cells[getIndex(row, column, columns)]),
+  ).length
 }
 
 /**
@@ -56,7 +87,7 @@ export function down([i, j], [rows]) {
   if (i === rows - LAST_ROW_OFFSET) {
     throw new Error()
   }
-  return [i + MOVE_DOWN, j]
+  return [i + DOWN, j]
 }
 
 /**
@@ -79,6 +110,17 @@ export function downRight(coords, size) {
   return down(right(coords, size), size)
 }
 
+/**
+ * Calculates the index in a one-dimensional array for given row and column.
+ * @param {number} row - The row index.
+ * @param {number} column - The column index.
+ * @param {number} columns - The total number of columns.
+ * @returns {number} The calculated index.
+ */
+export function getIndex(row, column, columns) {
+  return row * columns + column
+}
+
 /**
  * Moves the given coordinates one step left.
  * @param {[number, number]} coords - The current coordinates [row, column].
@@ -89,7 +131,36 @@ export function left([i, j]) {
   if (j === FIRST_COLUMN) {
     throw new Error()
   }
-  return [i, j + MOVE_LEFT]
+  return [i, j + LEFT]
+}
+
+/**
+ * Returns the coordinates neighboring the given coordinates that fall within the board.
+ * @param {[number, number]} coords - The coordinates [row, column].
+ * @param {[number, number]} size - Array containing the number of rows and columns.
+ * @param {Object} [options] - Neighbor options.
+ * @param {"horizontal" | "vertical" | "both"} [options.wrap=undefined] - The axes that wrap around board edges. "horizontal" wraps the column axis, "vertical" wraps the row axis, and "both" wraps each axis independently.
+ * @returns {[number, number][]} The neighboring coordinates within the board.
+ */
+export function neighbors([i, j], [rows, columns], options = {}) {
+  const { wrap = NO_WRAP } = options
+  const shouldWrapRows = wrap === BOTH || wrap === VERTICAL
+  const shouldWrapColumns = wrap === BOTH || wrap === HORIZONTAL
+
+  return NEIGHBOR_OFFSETS.map(([rowOffset, columnOffset]) => {
+    const row = shouldWrapRows ? wrapIndex(i + rowOffset, rows) : i + rowOffset
+    const column = shouldWrapColumns
+      ? wrapIndex(j + columnOffset, columns)
+      : j + columnOffset
+
+    return [row, column]
+  }).filter(
+    ([row, column]) =>
+      row >= FIRST_ROW &&
+      row < rows &&
+      column >= FIRST_COLUMN &&
+      column < columns,
+  )
 }
 
 /**
@@ -103,7 +174,7 @@ export function right([i, j], [, columns]) {
   if (j === columns - LAST_COLUMN_OFFSET) {
     throw new Error()
   }
-  return [i, j + MOVE_RIGHT]
+  return [i, j + RIGHT]
 }
 
 /**
@@ -135,7 +206,7 @@ export function up([i, j]) {
   if (i === FIRST_ROW) {
     throw new Error()
   }
-  return [i + MOVE_UP, j]
+  return [i + UP, j]
 }
 
 /**
@@ -157,3 +228,14 @@ export function upLeft(coords, size) {
 export function upRight(coords, size) {
   return up(right(coords, size), size)
 }
+
+/**
+ * Normalizes an index into a wrapping range.
+ * @param {number} index - The index to normalize.
+ * @param {number} length - The range length.
+ * @returns {number} The normalized index.
+ */
+function wrapIndex(index, length) {
+  const remainder = index % length
+  return remainder < FIRST_ROW ? remainder + length : remainder
+}

package/src/data-structures/index.js

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