@inglorious/utils 5.0.0 → 5.2.0

package/README.md

@@ -16,7 +16,7 @@ This package provides a collection of pure, composable helper functions to strea
 ## Installation
 
 ```bash
-npm install @inglorious/utils
+pnpm add @inglorious/utils
 ```
 
 ---
@@ -118,6 +118,21 @@ Vectors are mutable arrays, so copy a shared vector rather than storing it where
 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.
 
+### Saving and loading JSON
+
+Keep a value in `localStorage` between visits, such as a game's high scores or an app's
+saved state. Neither function throws: absent or blocked storage, and a value that cannot be
+parsed, read as the fallback, and a write that did not happen answers `false`.
+
+```javascript
+import { readJSON, writeJSON } from "@inglorious/utils/storage.js"
+
+const scores = readJSON("high-scores", [])
+writeJSON("high-scores", [...scores, 1200]) // => true
+```
+
+Pass another `Storage` as the last argument, such as `sessionStorage` or a fake in tests.
+
 ---
 
 ## API
@@ -139,6 +154,10 @@ know whether a helper lives under `data-structures` or `math`:
 - **`@inglorious/utils/quaternion`**: `quaternion` and `combine`.
 - **`@inglorious/utils/vector`**: Single-vector helpers (`magnitude`, `normalize`, `rotate`, ...) alongside multi-vector helpers (`cross`, `dot`, `sum`, ...).
 
+One module stands on its own:
+
+- **`@inglorious/utils/storage`**: `readJSON` and `writeJSON`, for keeping JSON in `localStorage`.
+
 `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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "5.0.0",
+  "version": "5.2.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",
@@ -118,6 +118,14 @@
       "types": "./types/math/vector.d.ts",
       "import": "./src/math/vector.js"
     },
+    "./storage.js": {
+      "types": "./types/storage.d.ts",
+      "import": "./src/storage.js"
+    },
+    "./storage": {
+      "types": "./types/storage.d.ts",
+      "import": "./src/storage.js"
+    },
     "./v.js": {
       "types": "./types/v.d.ts",
       "import": "./src/v.js"
@@ -137,13 +145,13 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@inglorious/eslint-config": "1.1.2",
+    "@inglorious/eslint-config": "1.2.0",
     "prettier": "^3.9.6",
     "vite": "^8.2.2",
     "vitest": "^5.0.0"
   },
   "engines": {
-    "node": ">= 22"
+    "node": ">= 26"
   },
   "scripts": {
     "format": "prettier --write .",

package/src/algorithms/path-finding.js

@@ -36,24 +36,6 @@ export const eucledianDistance = (a, b) =>
  */
 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.
  *
@@ -148,3 +130,25 @@ function adaptGraph(graph) {
 function createFindNode(nodes) {
   return (id) => nodes.find((node) => node.id === id)
 }
+
+/**
+ * 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.
+ */
+function compareCost(a, b) {
+  return 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.
+ */
+function compareTotalCost(a, b) {
+  return b.totalCost - a.totalCost
+}

package/src/data-structures/array.js

@@ -7,7 +7,6 @@
  */
 const DEFAULT_COMPARATOR = (a, b) => b - a
 
-// Threshold constants for comparison results
 const LESS_THAN_ZERO = 0
 const GREATER_THAN_ZERO = 0
 

package/src/data-structures/heap.js

@@ -1,5 +1,3 @@
-// @see https://stackfull.dev/heaps-in-javascript
-
 /**
  * Default comparator for a max-heap.
  * @param {*} a - First element.
@@ -8,17 +6,16 @@
  */
 const DEFAULT_COMPARATOR = (a, b) => b - a
 
-// Constants for heap operations
-const ROOT_INDEX = 0 // Index of the root element in the heap.
-const SINGLE_ELEMENT = 1 // Heap size when it contains a single element.
-const LEFT_CHILD_MULTIPLIER = 2 // Multiplier to calculate the left child index.
-const RIGHT_CHILD_MULTIPLIER = 2 // Multiplier to calculate the right child index.
-const PARENT_DIVISOR = 2 // Divisor to calculate the parent index.
-const LEFT_CHILD_OFFSET = 1 // Offset to calculate the left child index.
-const RIGHT_CHILD_OFFSET = 2 // Offset to calculate the right child index.
-const LAST_ELEMENT_OFFSET = 1 // Offset to get the last element in the heap.
-const INDEX_ADJUSTMENT = 1 // Adjustment for zero-based indexing.
-const COMPARATOR_THRESHOLD = 0 // Threshold for comparator results.
+const ROOT_INDEX = 0
+const SINGLE_ELEMENT = 1
+const LEFT_CHILD_MULTIPLIER = 2
+const RIGHT_CHILD_MULTIPLIER = 2
+const PARENT_DIVISOR = 2
+const LEFT_CHILD_OFFSET = 1
+const RIGHT_CHILD_OFFSET = 2
+const LAST_ELEMENT_OFFSET = 1
+const INDEX_ADJUSTMENT = 1
+const COMPARATOR_THRESHOLD = 0
 
 /**
  * Checks if a heap contains a specific item.

package/src/data-structures/object.js

@@ -8,57 +8,57 @@ const NEXT_KEY_OFFSET = 1
 const NEXT_LEVEL = 2
 
 /**
- * Creates a deep clone of a given value using the structured clone algorithm.
- * This is a modern and efficient way to deep-clone objects.
+ * Creates a deep clone of a given value.
  *
- * 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.
+ * Plain objects, arrays and primitives -- what state is nearly always made of -- are
+ * copied by hand, because a general algorithm pays for being one: across thousands of
+ * small objects, `structuredClone` takes about twice as long and a JSON round trip
+ * longer still. Vectors stay vectors, which neither of those keeps: the tag that marks
+ * one is not enumerable, so anything that copies only what it can see drops it.
  *
- * For more details, see:
- * https://developer.mozilla.org/en-US/docs/Web/API/structuredClone
+ * Anything else is handed to `structuredClone`, so a `Date` or a `Map` is still copied
+ * properly, and DOM nodes or class instances with non-cloneable internals still throw a
+ * `DataCloneError`. Functions are kept as they are rather than copied, since there is
+ * nothing in one to copy.
  *
  * This is similar to Lodash's `_.cloneDeep`.
  *
  * @template T
- * @param {T} obj - The value to clone.
+ * @param {T} value - The value to clone.
  * @returns {T} A deep clone of the input value.
  */
-export function clone(obj) {
-  return deserialize(serialize(obj))
-}
+export function clone(value) {
+  if (value?.__isVector__) {
+    return v(...value)
+  }
 
-/**
- * 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)) {
+    const copy = new Array(value.length)
 
-    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
+    for (let index = 0; index < value.length; index++) {
+      copy[index] = clone(value[index])
     }
+
+    return copy
   }
-  return target
+
+  if (value === null || typeof value !== "object") {
+    return value
+  }
+
+  const prototype = Object.getPrototypeOf(value)
+
+  if (prototype !== Object.prototype && prototype !== null) {
+    return structuredClone(value)
+  }
+
+  const copy = {}
+
+  for (const key in value) {
+    copy[key] = clone(value[key])
+  }
+
+  return copy
 }
 
 /**
@@ -242,9 +242,6 @@ export function get(obj, path, defaultValue = undefined) {
 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
 
@@ -326,7 +323,7 @@ export function mergeWith(merger, target, ...sources) {
  *
  * **Important:** Unlike Immer, which uses structural sharing via proxies for
  * high performance, this implementation performs a full deep clone of the base
- * state on every call using `deserialize(serialize())`. This can be
+ * state on every call using `clone`. This can be
  * inefficient for large or complex states. It is intended for simple use cases
  * where the convenience of the API outweighs the performance cost.
  *
@@ -370,7 +367,6 @@ export function produce(baseState, recipe, ...args) {
  */
 export function serialize(obj) {
   function replacer(key, value) {
-    // Handle top-stage vector
     if (value?.__isVector__) {
       return {
         _type: "vector",
@@ -427,9 +423,7 @@ export function set(obj, path, value) {
     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) ? [] : {}
     }
 
@@ -480,3 +474,36 @@ ${" ".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

@@ -12,8 +12,6 @@ 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
@@ -56,9 +54,6 @@ export function editDistance(a, b) {
   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
 
 /**

package/src/math/hitmask.js

@@ -1,5 +1,3 @@
-// @see https://jonathanwhiting.com/tutorial/collision/
-
 import { isBetween } from "./number.js"
 import { intersectsRectangle } from "./rectangle.js"
 

package/src/math/line.js

@@ -20,7 +20,6 @@ export function distanceFromPoint(line, point) {
   return abs(a * x + b * z + c) / hypothenuse(a, b)
 }
 
-// @see https://math.stackexchange.com/questions/275529/check-if-line-intersects-with-circles-perimeter
 /**
  * Determines whether a line intersects with the perimeter of a circle.
  * @param {Line} line - The line represented by the equation ax + bz + c = 0, where `line` is [a, b, c].

package/src/math/number.js

@@ -1,6 +1,6 @@
-const DEFAULT_PRECISION = 1 // Default precision used for snapping numbers.
-const DEFAULT_TOLERANCE = 0.1 // Default tolerance used for comparing numbers.
-const SQUARE_ROOT = 0.5 // Exponent used for calculating square roots.
+const DEFAULT_PRECISION = 1
+const DEFAULT_TOLERANCE = 0.1
+const SQUARE_ROOT = 0.5
 
 /**
  * Returns the absolute value of a number.

package/src/math/quaternion.js

@@ -8,9 +8,9 @@ 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.
+const HALF = 2
 // eslint-disable-next-line no-magic-numbers
-const Y_AXIS = v(0, 1, 0) // Default axis of rotation (Y-axis).
+const Y_AXIS = v(0, 1, 0)
 
 /**
  * Combines two quaternions using the Hamilton product.

package/src/math/rectangle.js

@@ -74,7 +74,6 @@ export function intersectsRectangle(rectangle1, rectangle2) {
   const back2 = z2 - halfD2
   const front2 = z2 + halfD2
 
-  // AABB intersection test
   return (
     left1 <= right2 &&
     right1 >= left2 &&

package/src/math/rng.js

@@ -31,10 +31,6 @@ 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]))

package/src/math/trigonometry.js

@@ -1,7 +1,7 @@
 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π)
+const HALF_CIRCLE_IN_DEGRESS = 180
+const FULL_CIRCLE = 2
 
 /**
  * Calculates the arctangent of the quotient of its arguments.

package/src/math/vector.js

@@ -499,9 +499,7 @@ export function toSpherical(vector) {
     return zero()
   }
 
-  // In a Y-up system, inclination is the angle with the Y axis.
   const inclination = Math.acos(vector[Y] / r)
-  // Azimuth is the angle in the XZ plane, which `angle()` calculates.
   const azimuth = angle(vector)
 
   return v(r, inclination, azimuth)
@@ -666,7 +664,6 @@ function rotateWithQuaternion(vector, angle) {
     return vector
   }
 
-  // @see https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Performance_comparisons
   const [w, ...r] = quaternion(angle)
   const result = sum(
     vector,

package/src/physics/acceleration.js

@@ -5,9 +5,9 @@
 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.
-const NO_FRICTION = 0 // No friction constant.
-const HALF_ACCELERATION = 0.5 // Half of the acceleration factor used in position calculation.
+const DEFAULT_DT = 1
+const NO_FRICTION = 0
+const HALF_ACCELERATION = 0.5
 
 /**
  * Applies acceleration to an object using Euler's integration method.
@@ -36,15 +36,12 @@ export function applyAcceleration(params, dt = DEFAULT_DT) {
     friction = NO_FRICTION,
   } = params
 
-  // Clamp acceleration to the maximum allowed range
   acceleration = clamp(acceleration, -maxAcceleration, maxAcceleration)
 
-  // Update velocity with acceleration and clamp to the maximum allowed speed
   velocity = sum(velocity, multiply(acceleration, dt))
   velocity = clamp(velocity, -maxSpeed, maxSpeed)
   velocity = applyFriction({ velocity, friction }, dt)
 
-  // Update position with velocity and acceleration
   position = sum(
     position,
     multiply(velocity, dt),

package/src/physics/friction.js

@@ -4,8 +4,8 @@
 
 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.
+const DEFAULT_DT = 1
+const NO_FRICTION = 0
 
 /**
  * Applies friction to a given velocity vector.

package/src/physics/gravity.js

@@ -6,11 +6,11 @@
 
 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.
-const DEFAULT_LEAP = 0 // Default maximum leap distance.
-const DEFAULT_SPEED = 0 // Default maximum speed.
-const NO_VELOCITY = 0 // No initial velocity.
+const DEFAULT_DT = 1
+const DEFAULT_JUMP = 0
+const DEFAULT_LEAP = 0
+const DEFAULT_SPEED = 0
+const NO_VELOCITY = 0
 
 /**
  * Applies gravity to an object based on its current velocity and position.

package/src/physics/jump.js

@@ -1,8 +1,8 @@
 /* eslint-disable no-magic-numbers */
 
-const DEFAULT_MAX_JUMP = 0 // Default maximum jump height.
-const DEFAULT_MAX_LEAP = 0 // Default maximum leap distance.
-const DEFAULT_MAX_SPEED = 0 // Default maximum speed.
+const DEFAULT_MAX_JUMP = 0
+const DEFAULT_MAX_LEAP = 0
+const DEFAULT_MAX_SPEED = 0
 
 /**
  * Calculates the vertical velocity (vy) of a jump

package/src/physics/velocity.js

@@ -4,8 +4,8 @@
 
 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.
+const DEFAULT_DT = 1
+const DEFAULT_MAX_SPEED = 0
 
 /**
  * Applies velocity to a position based on the given parameters and options.

package/src/storage.js

@@ -0,0 +1,52 @@
+const DEFAULT_STORAGE = () => globalThis.localStorage
+
+/**
+ * Reads a value back as JSON.
+ *
+ * Storage that is absent -- a server render, a private window, a test -- reads as the
+ * fallback rather than throwing, so a caller does not have to know whether it is running
+ * somewhere that has any. A value that cannot be parsed is treated the same way: what is
+ * stored is not this function's to defend, and refusing to start over it would be worse
+ * than starting again.
+ *
+ * @param {string} key - Where the value is kept.
+ * @param {*} fallback - What to answer when there is nothing usable to read.
+ * @param {Storage} [storage] - Where to read from. Defaults to the browser's own.
+ * @returns {*} The stored value, or the fallback.
+ */
+export function readJSON(key, fallback, storage) {
+  try {
+    const raw = store(storage)?.getItem(key)
+    if (raw === null || raw === undefined) return fallback
+    return JSON.parse(raw)
+  } catch {
+    return fallback
+  }
+}
+
+/**
+ * Writes a value down as JSON, and answers whether it took.
+ *
+ * Storage can be full, absent, or refusing writes for its own reasons, and none of those
+ * is worth throwing over: a game that cannot remember a score can still be played. The
+ * answer is returned so that a caller which does care -- a test, mostly -- can say so.
+ *
+ * @param {string} key - Where to keep the value.
+ * @param {*} value - The value to keep.
+ * @param {Storage} [storage] - Where to write to. Defaults to the browser's own.
+ * @returns {boolean} `true` if the value was written.
+ */
+export function writeJSON(key, value, storage) {
+  try {
+    const target = store(storage)
+    if (!target) return false
+    target.setItem(key, JSON.stringify(value))
+    return true
+  } catch {
+    return false
+  }
+}
+
+function store(storage) {
+  return storage ?? DEFAULT_STORAGE()
+}

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

@@ -71,9 +71,10 @@ export type DefaultsResult<T extends object, D extends object> = Omit<
 }
 
 /**
- * Creates a deep clone of a value.
+ * Creates a deep clone of a value. Plain data is copied by hand and vectors stay
+ * vectors; anything else goes through `structuredClone`.
  */
-export function clone<T>(obj: T): T
+export function clone<T>(value: T): T
 
 /**
  * Assigns default properties to a target in place.

package/types/storage.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Reads a value back as JSON. Absent storage, a missing key or a value that
+ * cannot be parsed all read as the fallback, rather than throwing.
+ *
+ * @param key - Where the value is kept.
+ * @param fallback - What to answer when there is nothing usable to read.
+ * @param storage - Where to read from. Defaults to the browser's own.
+ * @returns The stored value, or the fallback.
+ */
+export function readJSON<T>(
+  key: string,
+  fallback: T,
+  storage?: Storage | null,
+): T
+
+/**
+ * Writes a value down as JSON, and answers whether it took. Absent, full or
+ * refusing storage answers `false` rather than throwing.
+ *
+ * @param key - Where to keep the value.
+ * @param value - The value to keep.
+ * @param storage - Where to write to. Defaults to the browser's own.
+ * @returns `true` if the value was written.
+ */
+export function writeJSON(
+  key: string,
+  value: unknown,
+  storage?: Storage | null,
+): boolean