@inglorious/utils 3.6.3 → 3.7.1

package/README.md

@@ -3,7 +3,7 @@
 [![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)
 
-A set of general-purpose utility functions designed with functional programming principles in mind. This package is part of the [Inglorious Engine](https://github.com/IngloriousCoderz/inglorious-engine) monorepo.
+A set of general-purpose utility functions designed with functional programming principles in mind. This package is part of the [Inglorious Forge](https://github.com/IngloriousCoderz/inglorious-forge) monorepo.
 
 ---
 

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@inglorious/utils",
-  "version": "3.6.3",
+  "version": "3.7.1",
   "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",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/IngloriousCoderz/inglorious-engine.git",
+    "url": "git+https://github.com/IngloriousCoderz/inglorious-forge.git",
     "directory": "packages/utils"
   },
   "homepage": "https://inglorious-engine.vercel.app/",
   "bugs": {
-    "url": "https://github.com/IngloriousCoderz/inglorious-engine/issues"
+    "url": "https://github.com/IngloriousCoderz/inglorious-forge/issues"
   },
   "keywords": [
     "functional-programming",
@@ -33,6 +33,7 @@
   },
   "files": [
     "src",
+    "!src/**/*.test.js",
     "types"
   ],
   "publishConfig": {
@@ -42,7 +43,7 @@
     "prettier": "^3.6.2",
     "vite": "^7.1.3",
     "vitest": "^1.6.1",
-    "@inglorious/eslint-config": "1.0.1"
+    "@inglorious/eslint-config": "1.1.1"
   },
   "engines": {
     "node": ">= 22"

package/src/data-structures/object.js

@@ -2,13 +2,26 @@ import { v } from "../v.js"
 import { isArray } from "./array.js"
 
 const INITIAL_LEVEL = 0
+const LAST_KEY_OFFSET = 1
+const NEXT_KEY_OFFSET = 1
 const NEXT_LEVEL = 2
 
 /**
- * Creates a deep clone of the given object.
+ * Creates a deep clone of a given value using the structured clone algorithm.
+ * This is a modern and efficient way to deep-clone objects.
  *
- * @param {Object} obj - The object to clone.
- * @returns {Object} A deep clone of the input object.
+ * Note: `structuredClone` has some limitations. It cannot clone functions,
+ * DOM nodes, property descriptors, getters, setters, or certain other
+ * non-serializable objects. It will throw a `DataCloneError` in such cases.
+ *
+ * For more details, see:
+ * https://developer.mozilla.org/en-US/docs/Web/API/structuredClone
+ *
+ * This is similar to Lodash's `_.cloneDeep`.
+ *
+ * @template T
+ * @param {T} obj - The value to clone.
+ * @returns {T} A deep clone of the input value.
  */
 export function clone(obj) {
   return deserialize(serialize(obj))
@@ -83,6 +96,42 @@ export function find(obj, callback) {
   ])
 }
 
+/**
+ * Gets the value at a specified path of an object. If the resolved value is
+ * `undefined`, the `defaultValue` is returned in its place. This function
+ * supports dot-notation for nested properties and numbers for array indices.
+ *
+ * This is similar to Lodash's `_.get`.
+ *
+ * @example
+ * const object = { 'a': [{ 'b': { 'c': 3 } }] };
+ * get(object, 'a.0.b.c');
+ * // => 3
+ *
+ * get(object, 'a.0.d', 'default');
+ * // => 'default'
+ *
+ * @param {Object} obj - The object to query.
+ * @param {string} path - The path of the property to retrieve.
+ * @param {*} [defaultValue=undefined] - The value returned for `undefined` resolved values.
+ * @returns {*} Returns the resolved value, else the `defaultValue`.
+ */
+export function get(obj, path, defaultValue = undefined) {
+  if (!path) return defaultValue
+
+  const keys = path.split(".")
+  let result = obj
+
+  for (const key of keys) {
+    if (result == null || typeof result !== "object") {
+      return defaultValue
+    }
+    result = result[key]
+  }
+
+  return result !== undefined ? result : defaultValue
+}
+
 /**
  * Checks if a value is a plain object.
  *
@@ -185,6 +234,50 @@ export function serialize(obj) {
   return JSON.stringify(obj, replacer)
 }
 
+/**
+ * Sets the value at a specified path of an object. If a portion of the path
+ * doesn't exist, it's created. Arrays are created for missing index properties
+ * while objects are created for all other missing properties. This function
+ * mutates the object.
+ *
+ * This is similar to Lodash's `_.set`.
+ *
+ * @example
+ * const object = { 'a': [{ 'b': { 'c': 3 } }] };
+ * set(object, 'a.0.b.d', 4);
+ * // object is now { 'a': [{ 'b': { 'c': 3, 'd': 4 } }] }
+ *
+ * set(object, 'x.0.y', 5);
+ * // object is now { 'a': [...], 'x': [{ 'y': 5 }] }
+ *
+ * @param {Object} obj - The object to modify.
+ * @param {string} path - The path of the property to set.
+ * @param {*} value - The value to set.
+ * @returns {Object} Returns the modified object.
+ */
+export function set(obj, path, value) {
+  if (!path) return obj
+
+  const keys = path.split(".")
+  let current = obj
+
+  for (let i = 0; i < keys.length - LAST_KEY_OFFSET; i++) {
+    const key = keys[i]
+    const nextKey = keys[i + NEXT_KEY_OFFSET]
+
+    // Create missing intermediate objects
+    if (!(key in current) || typeof current[key] !== "object") {
+      // Create array if next key is a number, object otherwise
+      current[key] = /^\d+$/.test(nextKey) ? [] : {}
+    }
+
+    current = current[key]
+  }
+
+  current[keys[keys.length - LAST_KEY_OFFSET]] = value
+  return obj
+}
+
 /**
  * Converts an object or array to a formatted string representation.
  *

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

@@ -1,154 +0,0 @@
-import { expect, test } from "vitest"
-
-import { length } from "../math/vector.js"
-import { subtract } from "../math/vectors.js"
-import { v } from "../v.js"
-import { decide } from "./decision-tree.js"
-
-test("it should make a decision based on a binary decision tree", () => {
-  const entity = { state: "sleeping", position: v(0, 0, 0) }
-  const target = { position: v(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: v(0, 0, 0) }
-  const target = { position: v(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.test.js

@@ -1,151 +0,0 @@
-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/data-structures/array.test.js

@@ -1,206 +0,0 @@
-import { expect, test } from "vitest"
-
-import {
-  contains,
-  ensureArray,
-  isArray,
-  max,
-  min,
-  pop,
-  push,
-  remove,
-} from "./array.js"
-
-test("it should check if an array contains a value", () => {
-  const arr = [3, 2, 6, 1, 7, 4, 5]
-  const item = 1
-  const expectedResult = true
-
-  expect(contains(arr, item)).toBe(expectedResult)
-})
-
-test("it should check if an array contains an object", () => {
-  const arr = [
-    { value: 3 },
-    { value: 2 },
-    { value: 6 },
-    { value: 1 },
-    { value: 7 },
-    { value: 4 },
-    { value: 5 },
-  ]
-  const item = arr[3]
-  const expectedResult = true
-
-  expect(contains(arr, item)).toBe(expectedResult)
-})
-
-test("it should return the same array if the value is already an array", () => {
-  const arr = [1, "two", { three: 3 }]
-
-  expect(ensureArray(arr)).toBe(arr)
-})
-
-test("it should wrap the value in an array if it is not an array", () => {
-  const str = "hello"
-
-  expect(ensureArray(str)).toStrictEqual([str])
-})
-
-test("it should correctly identify an array", () => {
-  const arr = [1, "two", { three: 3 }]
-
-  expect(isArray(arr)).toBe(true)
-})
-
-test("it should correctly identify a non-array", () => {
-  const str = "hello"
-
-  expect(isArray(str)).toBe(false)
-})
-
-test("it should find the maximum value of an array", () => {
-  const arr = [3, 2, 6, 1, 7, 4, 5]
-  const expectedResult = 7
-
-  expect(max(arr)).toBe(expectedResult)
-})
-
-test("it should find the maximum value in an array of objects", () => {
-  const arr = [
-    { value: 3 },
-    { value: 2 },
-    { value: 6 },
-    { value: 1 },
-    { value: 7 },
-    { value: 4 },
-    { value: 5 },
-  ]
-  const comparator = (a, b) => b.value - a.value
-  const expectedResult = { value: 7 }
-
-  expect(max(arr, comparator)).toStrictEqual(expectedResult)
-})
-
-test("it should find the minimum value of an array", () => {
-  const arr = [3, 2, 6, 1, 7, 4, 5]
-  const expectedResult = 1
-
-  expect(min(arr)).toBe(expectedResult)
-})
-
-test("it should find the minimum value in an array of objects", () => {
-  const arr = [
-    { value: 3 },
-    { value: 2 },
-    { value: 6 },
-    { value: 1 },
-    { value: 7 },
-    { value: 4 },
-    { value: 5 },
-  ]
-  const comparator = (a, b) => b.value - a.value
-  const expectedResult = { value: 1 }
-
-  expect(min(arr, comparator)).toStrictEqual(expectedResult)
-})
-
-test("it should remove the minimum value from an array", () => {
-  const arr = [3, 2, 6, 1, 7, 4, 5]
-  const expectedResult = [3, 2, 6, 7, 4, 5]
-
-  expect(pop(arr)).toStrictEqual(expectedResult)
-})
-
-test("it should remove the minimum object from an array", () => {
-  const arr = [
-    { value: 3 },
-    { value: 2 },
-    { value: 6 },
-    { value: 1 },
-    { value: 7 },
-    { value: 4 },
-    { value: 5 },
-  ]
-  const comparator = (a, b) => b.value - a.value
-  const expectedResult = [
-    { value: 3 },
-    { value: 2 },
-    { value: 6 },
-    { value: 7 },
-    { value: 4 },
-    { value: 5 },
-  ]
-
-  expect(pop(arr, comparator)).toStrictEqual(expectedResult)
-})
-
-test("it should remove the maximum value from an array", () => {
-  const arr = [3, 2, 6, 1, 7, 4, 5]
-  const comparator = (a, b) => a - b
-  const expectedResult = [3, 2, 6, 1, 4, 5]
-
-  expect(pop(arr, comparator)).toStrictEqual(expectedResult)
-})
-
-test("it should remove the maximum object from an array", () => {
-  const arr = [
-    { value: 3 },
-    { value: 2 },
-    { value: 6 },
-    { value: 1 },
-    { value: 7 },
-    { value: 4 },
-    { value: 5 },
-  ]
-  const comparator = (a, b) => a.value - b.value
-  const expectedResult = [
-    { value: 3 },
-    { value: 2 },
-    { value: 6 },
-    { value: 1 },
-    { value: 4 },
-    { value: 5 },
-  ]
-
-  expect(pop(arr, comparator)).toStrictEqual(expectedResult)
-})
-
-test("it should add a value at the end of the array", () => {
-  const arr = [3, 2, 6, 1, 7, 4]
-  const item = 5
-  const expectedResult = [3, 2, 6, 1, 7, 4, 5]
-
-  expect(push(arr, item)).toStrictEqual(expectedResult)
-})
-
-test("it should remove a primitive value from an array", () => {
-  const arr = [3, 2, 6, 1, 7, 4, 5]
-  const item = 1
-  const expectedResult = [3, 2, 6, 7, 4, 5]
-
-  expect(remove(arr, item)).toStrictEqual(expectedResult)
-})
-
-test("it should remove an object from an array", () => {
-  const arr = [
-    { value: 3 },
-    { value: 2 },
-    { value: 6 },
-    { value: 1 },
-    { value: 7 },
-    { value: 4 },
-    { value: 5 },
-  ]
-  const item = arr[3]
-  const expectedResult = [
-    { value: 3 },
-    { value: 2 },
-    { value: 6 },
-    { value: 7 },
-    { value: 4 },
-    { value: 5 },
-  ]
-
-  expect(remove(arr, item)).toStrictEqual(expectedResult)
-})