@inglorious/utils 1.0.0 → 1.2.0

package/README.md

@@ -1,4 +1,4 @@
-# @inglorious/utils
+# Inglorious Utils
 
 [![NPM version](https://img.shields.io/npm/v/@inglorious/utils.svg)](https://www.npmjs.com/package/@inglorious/utils)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -24,7 +24,7 @@ Here are a few examples of how you can use the utilities in this package.
 Compose functions together in a readable, left-to-right sequence.
 
 ```javascript
-import { pipe } from "@inglorious/utils/function"
+import { pipe } from "@inglorious/utils/functions/functions"
 
 const add = (a) => (b) => a + b
 const multiply = (a) => (b) => a * b
@@ -43,24 +43,23 @@ const result = calculate(10) // 40
 Perform vector operations on plain objects.
 
 ```javascript
-import { add } from "@inglorious/utils/vector"
+import { add } from "@inglorious/utils/math/linear-algebra/vector"
 
-const position = { x: 10, y: 20 }
-const velocity = { x: 2, y: -1 }
+const position = [10, 20]
+const velocity = [2, -1]
 
 const newPosition = add(position, velocity)
-// => { x: 12, y: 19 }
+// => [12, 19]
 ```
 
 ## API
 
 This package is designed to be used with subpath imports, which helps with tree-shaking.
 
-- **`@inglorious/utils/function`**: Utilities for function composition.
-- **`@inglorious/utils/vector`**: Utilities for 2D vector math on plain objects.
-- **`@inglorious/utils/random`**: Utilities for random number and data generation.
-
-_(This is a sample API. Please update it to reflect the actual exported functions.)_
+- **`@inglorious/utils/algorithms`**: Utilities for AI algorithms, like decision trees and A\*.
+- **`@inglorious/utils/functions`**: Utilities for function composition.
+- **`@inglorious/utils/math`**: Utilities for math operations.
+- **`@inglorious/utils/physics`**: Utilities for calculations on friction, acceleration, and gravity.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "1.0.0",
+  "version": "1.2.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)",
   "license": "MIT",
@@ -20,14 +20,14 @@
     "utils"
   ],
   "type": "module",
+  "exports": {
+    "./*": "./src/*"
+  },
   "files": [
     "src",
     "README.md",
     "LICENSE"
   ],
-  "exports": {
-    "./*": "./*"
-  },
   "publishConfig": {
     "access": "public"
   },

package/src/algorithms/decision-tree.js

@@ -0,0 +1,24 @@
+/**
+ * @typedef {import("./types").Conditions} Conditions
+ * @typedef {import("./types").Outcome} Outcome
+ * @typedef {import("./types").DecisionTree} DecisionTree
+ */
+
+/**
+ * Traverses a decision tree recursively based on the provided conditions and returns the resulting node.
+ *
+ * @param {DecisionTree} tree - The decision tree to traverse. Each node contains:
+ *   - `test` {Function}: A function that evaluates the conditions and determines the next branch.
+ *   - Branches keyed by the possible outcomes of the `test` function.
+ * @param {Conditions} conditions - The conditions object passed to the `test` function at each node.
+ * @returns {Outcome | DecisionTree} - The resulting outcome or decision tree itself after traversing the decision tree.
+ */
+export function decide(tree, conditions) {
+  if (!tree.test) {
+    return tree
+  }
+
+  const value = tree.test(conditions)
+
+  return tree[value] && decide(tree[value](conditions), conditions)
+}

package/src/algorithms/decision-tree.test.js

@@ -0,0 +1,153 @@
+import { expect, test } from "vitest"
+
+import { length } from "../math/linear-algebra/vector.js"
+import { subtract } from "../math/linear-algebra/vectors.js"
+import { decide } from "./decision-tree.js"
+
+test("it should make a decision based on a binary decision tree", () => {
+  const entity = { state: "sleeping", position: [0, 0, 0] }
+  const target = { position: [10, 0, 0] }
+  const tree = {
+    test({ entity }) {
+      return entity.state === "idle"
+    },
+    true() {
+      return {
+        test({ entity, target }) {
+          const distance = length(subtract(target.position, entity.position))
+          return distance < 250
+        },
+        true() {
+          return "aware"
+        },
+      }
+    },
+    false() {
+      return {
+        test({ entity }) {
+          return entity.state === "chasing"
+        },
+        true() {
+          return {
+            test({ entity, target }) {
+              const distance = length(
+                subtract(target.position, entity.position),
+              )
+              return distance >= 250
+            },
+            true() {
+              return "idle"
+            },
+            false() {
+              return {
+                test({ entity, target }) {
+                  const distance = length(
+                    subtract(target.position, entity.position),
+                  )
+                  return distance < 10
+                },
+                true() {
+                  return "sleepy"
+                },
+              }
+            },
+          }
+        },
+        false() {
+          return {
+            test({ entity }) {
+              return ["sleepy", "sleeping"].includes(entity.state)
+            },
+            true() {
+              return {
+                test({ entity, target }) {
+                  const distance = length(
+                    subtract(target.position, entity.position),
+                  )
+                  return distance >= 10
+                },
+                true() {
+                  return "aware"
+                },
+              }
+            },
+          }
+        },
+      }
+    },
+  }
+
+  const state = decide(tree, { entity, target })
+
+  expect(state).toBe("aware")
+})
+
+test("it should make a decision on a multi-child tree", () => {
+  const entity = { state: "sleeping", position: [0, 0, 0] }
+  const target = { position: [10, 0, 0] }
+  const wakeUp = () => ({
+    test({ entity, target }) {
+      const distance = length(subtract(target.position, entity.position))
+      return distance >= 10
+    },
+    true() {
+      return "aware"
+    },
+    false({ entity }) {
+      return entity.state
+    },
+  })
+
+  const tree = {
+    test({ entity }) {
+      return entity.state
+    },
+    idle() {
+      return {
+        test({ entity, target }) {
+          const distance = length(subtract(target.position, entity.position))
+          return distance < 250
+        },
+        true() {
+          return "aware"
+        },
+        false({ entity }) {
+          return entity.state
+        },
+      }
+    },
+    chasing() {
+      return {
+        test({ entity, target }) {
+          const distance = length(subtract(target.position, entity.position))
+          return distance >= 250
+        },
+        true() {
+          return "idle"
+        },
+        false() {
+          return {
+            test({ entity, target }) {
+              const distance = length(
+                subtract(target.position, entity.position),
+              )
+              return distance < 10
+            },
+            true() {
+              return "sleepy"
+            },
+            false({ entity }) {
+              return entity.state
+            },
+          }
+        },
+      }
+    },
+    sleepy: wakeUp,
+    sleeping: wakeUp,
+  }
+
+  const state = decide(tree, { entity, target })
+
+  expect(state).toBe("aware")
+})

package/src/algorithms/path-finding.js

@@ -0,0 +1,150 @@
+/**
+ * @typedef {import("./types").Node} Node
+ * @typedef {import("./types").Graph} Graph
+ */
+
+import { contains, push, remove, root } from "../data-structures/heap.js"
+import { abs, magnitude } from "../math/linear-algebra/vector.js"
+import { subtract } from "../math/linear-algebra/vectors.js"
+
+const NO_COST = 0
+
+/**
+ * Calculates the cost of a path using Dijkstra's algorithm.
+ * In this simplified form the cost is simply 0.
+ *
+ * @returns {number} - The cost of the path (which is 0).
+ */
+export const dijkstra = () => NO_COST
+
+/**
+ * Calculates the Euclidean distance between two nodes.
+ *
+ * @param {Node} a - The first node.
+ * @param {Node} b - The second node.
+ * @returns {number} - The Euclidean distance between the two nodes.
+ */
+export const eucledianDistance = (a, b) =>
+  magnitude(subtract(a.position, b.position))
+
+/**
+ * Calculates the Manhattan distance between two nodes.
+ *
+ * @param {Node} a - The first node.
+ * @param {Node} b - The second node.
+ * @returns {number} - The Manhattan distance between the two nodes.
+ */
+export const manhattanDistance = (a, b) => abs(subtract(a.position, b.position))
+
+/**
+ * Compares the cost of two nodes.
+ *
+ * @param {Node} a - The first node.
+ * @param {Node} b - The second node.
+ * @returns {number} - The difference in cost between the two nodes.
+ */
+const compareCost = (a, b) => b.cost - a.cost
+
+/**
+ * Compares the total cost of two nodes.
+ *
+ * @param {Node} a - The first node.
+ * @param {Node} b - The second node.
+ * @returns {number} - The difference in total cost between the two nodes.
+ */
+const compareTotalCost = (a, b) => b.totalCost - a.totalCost
+
+/**
+ * Finds the shortest path in a graph from a start node to an end node using a heuristic.
+ *
+ * @param {Graph} graph - The graph containing nodes and arcs.
+ * @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.
+ */
+export function findPath(graph, start, end, heuristic = eucledianDistance) {
+  const { nodes, arcs } = adaptGraph(graph)
+  const findNode = createFindNode(nodes)
+
+  const startNode = findNode(start)
+  const endNode = findNode(end)
+  let discoveredNodes = [startNode]
+  let evaluatedNodes = []
+  let path = []
+
+  while (discoveredNodes.length) {
+    let current = root(discoveredNodes, compareTotalCost)
+
+    if (current.id === end) {
+      while (current != null) {
+        path = [current.id, ...path]
+        current = current.previous
+      }
+
+      return path
+    }
+
+    discoveredNodes = remove(discoveredNodes, current)
+    evaluatedNodes = push(evaluatedNodes, current)
+
+    const outgoingArcs = arcs.filter(({ from }) => from === current.id)
+    const destinations = outgoingArcs.map(({ to }) => findNode(to))
+
+    for (const destination of destinations) {
+      const totalCost =
+        current.cost +
+        destination.cost +
+        heuristic(current, destination) +
+        outgoingArcs.find(({ to }) => to === destination.id)?.cost
+
+      let isNewPathFound = false
+      if (contains(discoveredNodes, destination)) {
+        if (totalCost < destination.cost) {
+          destination.cost = totalCost
+          isNewPathFound = true
+        }
+      } else {
+        destination.cost = totalCost
+        isNewPathFound = true
+        discoveredNodes = push(discoveredNodes, destination, compareCost)
+      }
+
+      if (isNewPathFound) {
+        destination.totalCost =
+          destination.cost + heuristic(destination, endNode)
+        destination.previous = current
+      }
+    }
+  }
+}
+
+/**
+ * Adapts a graph to ensure all nodes and arcs have a cost property.
+ *
+ * @param {Graph} graph - The graph to adapt.
+ * @returns {Graph} - The adapted graph with cost properties added.
+ */
+function adaptGraph(graph) {
+  return {
+    ...graph,
+    nodes: Array.isArray(graph.nodes)
+      ? graph.nodes.map((node) => ({ ...node, cost: node.cost ?? NO_COST }))
+      : Object.entries(graph.nodes).map(([key, value]) => ({
+          id: key,
+          position: value,
+          cost: 0,
+        })),
+    arcs: graph.arcs.map((arc) => ({ ...arc, cost: arc.cost ?? NO_COST })),
+  }
+}
+
+/**
+ * Creates a function that finds a node by its ID.
+ *
+ * @param {Node[]} nodes - The array of nodes.
+ * @returns {(id: string) => Node} - A function that finds a node by its ID.
+ */
+function createFindNode(nodes) {
+  return (id) => nodes.find((node) => node.id === id)
+}

package/src/algorithms/path-finding.test.js

@@ -0,0 +1,151 @@
+import { expect, test } from "vitest"
+
+import {
+  createBoard,
+  down,
+  downRight,
+  right,
+} from "../data-structures/board.js"
+import { findPath } from "./path-finding.js"
+
+test("it should find the shortest path in a trivial example", () => {
+  const graph = {
+    nodes: {
+      A: [0, 0],
+      B: [2, 0],
+    },
+    arcs: [{ from: "A", to: "B", cost: 2 }],
+  }
+  const start = "A"
+  const end = "B"
+  const expectedResult = ["A", "B"]
+
+  expect(findPath(graph, start, end)).toStrictEqual(expectedResult)
+})
+
+test("it should find the shortest path between two nodes with default heuristic", () => {
+  const graph = {
+    nodes: {
+      A: [0, 0],
+      B: [2, 0],
+      C: [3, 2],
+      D: [4, 4],
+      E: [1, 1],
+      F: [2, 3],
+      G: [0, 4],
+    },
+    arcs: [
+      { from: "A", to: "B" },
+      { from: "B", to: "C" },
+      { from: "C", to: "D" },
+      { from: "A", to: "E" },
+      { from: "E", to: "F" },
+      { from: "F", to: "G" },
+      { from: "G", to: "D" },
+    ],
+  }
+  const start = "A"
+  const end = "D"
+  const expectedResult = ["A", "B", "C", "D"]
+
+  expect(findPath(graph, start, end)).toStrictEqual(expectedResult)
+})
+
+test("it should find the shortest path between two nodes with node costs", () => {
+  const graph = {
+    nodes: [
+      { id: "A", position: [0, 0], cost: 0 },
+      { id: "B", position: [2, 0], cost: 7 },
+      { id: "C", position: [3, 2], cost: 3 },
+      { id: "D", position: [4, 4], cost: 2 },
+      { id: "E", position: [1, 1], cost: 1.5 },
+      { id: "F", position: [2, 3], cost: 2 },
+      { id: "G", position: [0, 4], cost: 3 },
+    ],
+    arcs: [
+      { from: "A", to: "B" },
+      { from: "B", to: "C" },
+      { from: "C", to: "D" },
+      { from: "A", to: "E" },
+      { from: "E", to: "F" },
+      { from: "F", to: "G" },
+      { from: "G", to: "D" },
+    ],
+  }
+  const start = "A"
+  const end = "D"
+  const expectedResult = ["A", "E", "F", "G", "D"]
+
+  expect(findPath(graph, start, end)).toStrictEqual(expectedResult)
+})
+
+test("it should find the shortest path between two nodes with arc costs", () => {
+  const graph = {
+    nodes: {
+      A: [0, 0],
+      B: [2, 0],
+      C: [3, 2],
+      D: [4, 4],
+      E: [1, 1],
+      F: [2, 3],
+      G: [0, 4],
+    },
+    arcs: [
+      { from: "A", to: "B", cost: 7 },
+      { from: "B", to: "C", cost: 3 },
+      { from: "C", to: "D", cost: 2 },
+      { from: "A", to: "E", cost: 1.5 },
+      { from: "E", to: "F", cost: 2 },
+      { from: "F", to: "G", cost: 3 },
+      { from: "G", to: "D", cost: 4 },
+    ],
+  }
+  const start = "A"
+  const end = "D"
+  const expectedResult = ["A", "E", "F", "G", "D"]
+
+  expect(findPath(graph, start, end)).toStrictEqual(expectedResult)
+})
+
+test("it should find the best path in a board graph", () => {
+  const rows = 5
+  const columns = 5
+  const size = [rows, columns]
+  const filler = (i, j) => ({ id: `${i}${j}`, position: [i, j] })
+  const board = createBoard(size, filler)
+
+  const graph = {
+    nodes: board,
+    arcs: [],
+  }
+
+  for (let i = 0; i < rows; i++) {
+    for (let j = 0; j < columns; j++) {
+      const current = `${i}${j}`
+      if (i + 1 < rows) {
+        graph.arcs.push({
+          from: current,
+          to: down([i, j], size).join(""),
+        })
+      }
+      if (j + 1 < columns) {
+        graph.arcs.push({
+          from: current,
+          to: right([i, j], size).join(""),
+        })
+      }
+      if (i + 1 < rows && j + 1 < columns) {
+        graph.arcs.push({
+          from: current,
+          to: downRight([i, j], size).join(""),
+        })
+      }
+    }
+  }
+
+  const start = "00"
+  const end = "44"
+  const expectedResult = ["00", "11", "22", "33", "44"]
+
+  expect(findPath(graph, start, end)).toStrictEqual(expectedResult)
+})

package/src/algorithms/types.d.ts

@@ -0,0 +1,28 @@
+export type Conditions = unknown
+export type Outcome = string | boolean
+
+export interface DecisionTree {
+  test: (conditions: Conditions) => Outcome
+  [outcome: Outcome]: () => Outcome | DecisionTree
+}
+
+interface NodeMap {
+  [id: string]: [number, number] // [x, y]
+}
+
+interface Node {
+  id: string
+  position: [number, number] // [x, y]
+  cost?: number
+}
+
+interface Arc {
+  from: string
+  to: string
+  cost?: number
+}
+
+export interface Graph {
+  nodes: NodeMap | Node[]
+  arcs: Arc[]
+}

package/src/data-structures/array.js

@@ -0,0 +1,93 @@
+/**
+ * A default comparator function that compares two numbers.
+ *
+ * @param {number} a - The first number.
+ * @param {number} b - The second number.
+ * @returns {number} - A positive number if `a` is less than `b`, a negative number if `a` is greater than `b`, or 0 if they are equal.
+ */
+const DEFAULT_COMPARATOR = (a, b) => b - a
+
+// Threshold constants for comparison results
+const LESS_THAN_ZERO = 0
+const GREATER_THAN_ZERO = 0
+
+/**
+ * Checks if an array contains a specific item.
+ *
+ * @param {Array} arr - The array to search.
+ * @param {*} item - The item to check for.
+ * @returns {boolean} - `true` if the item is found, otherwise `false`.
+ */
+export function contains(arr, item) {
+  return arr.includes(item)
+}
+
+/**
+ * Ensures that the given value is an array. If it's not an array, it wraps it in one.
+ *
+ * @param {*} arr - The value to check.
+ * @returns {Array} - The original array or the value wrapped in a new array.
+ */
+export function ensureArray(arr) {
+  return Array.isArray(arr) ? arr : [arr]
+}
+
+/**
+ * Finds the maximum item in an array based on a comparator function.
+ *
+ * @param {Array} arr - The array to search.
+ * @param {Function} [comparator=DEFAULT_COMPARATOR] - The comparator function to determine the maximum item.
+ * @returns {*} - The maximum item in the array.
+ */
+export function max(arr, comparator = DEFAULT_COMPARATOR) {
+  return arr.reduce((acc, item) =>
+    comparator(item, acc) < LESS_THAN_ZERO ? item : acc,
+  )
+}
+
+/**
+ * Finds the minimum item in an array based on a comparator function.
+ *
+ * @param {Array} arr - The array to search.
+ * @param {Function} [comparator=DEFAULT_COMPARATOR] - The comparator function to determine the minimum item.
+ * @returns {*} - The minimum item in the array.
+ */
+export function min(arr, comparator = DEFAULT_COMPARATOR) {
+  return arr.reduce((acc, item) =>
+    comparator(item, acc) > GREATER_THAN_ZERO ? item : acc,
+  )
+}
+
+/**
+ * Removes the smallest item from an array, based on a comparator function.
+ *
+ * @param {Array} arr - The array to remove the item from.
+ * @param {Function} [comparator=DEFAULT_COMPARATOR] - The comparator function to determine the smallest item.
+ * @returns {*} - A new array with the item removed.
+ */
+export function pop(arr, comparator = DEFAULT_COMPARATOR) {
+  const item = min(arr, comparator)
+  return remove(arr, item)
+}
+
+/**
+ * Adds an item to an array in an immutable way.
+ *
+ * @param {Array} arr - The array to add the item to.
+ * @param {*} item - The item to add.
+ * @returns {Array} - A new array with the item added.
+ */
+export function push(arr, item) {
+  return [...arr, item]
+}
+
+/**
+ * Removes a specific item from an array in an immutable way.
+ *
+ * @param {Array} arr - The array to remove the item from.
+ * @param {*} item - The item to remove.
+ * @returns {Array} - A new array with the item removed.
+ */
+export function remove(arr, item) {
+  return arr.filter((el) => el !== item)
+}