@inglorious/utils 3.1.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "3.1.0",
+  "version": "3.3.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",

package/src/data-structures/object.js

@@ -1,3 +1,6 @@
+import { v } from "../v.js"
+import { isArray } from "./array.js"
+
 const INITIAL_LEVEL = 0
 const NEXT_LEVEL = 2
 
@@ -8,7 +11,46 @@ const NEXT_LEVEL = 2
  * @returns {Object} A deep clone of the input object.
  */
 export function clone(obj) {
-  return JSON.parse(JSON.stringify(obj))
+  return deserialize(serialize(obj))
+}
+
+/**
+ * Deserializes an object, converting plain object representations back into
+ * their original types, such as vector-like objects. This is the inverse
+ * operation of `serialize`.
+ *
+ * - Recursively deserializes nested objects.
+ * - Converts objects with a `_type: "vector"` property and `coords` array
+ *   back into a vector-like object using the `v` factory function.
+ * - Copies all other property values as-is.
+ *
+ * @param {string} str - The JSON string to deserialize.
+ * @returns {Object} The deserialized object.
+ */
+export function deserialize(str) {
+  const data = JSON.parse(str)
+
+  return revive(data)
+
+  function revive(value) {
+    if (isArray(value)) {
+      return value.map(revive)
+    }
+    if (isObject(value)) {
+      if (value._type === "vector" && value.coords) {
+        return v(...value.coords)
+      }
+
+      const deserialized = {}
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          deserialized[key] = revive(value[key])
+        }
+      }
+      return deserialized
+    }
+    return value
+  }
 }
 
 /**
@@ -73,7 +115,7 @@ export function map(obj, callback) {
  *
  * **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 `JSON.parse(JSON.stringify())`. This can be
+ * state on every call using `deserialize(serialize())`. 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.
  *
@@ -102,6 +144,47 @@ export function produce(baseState, recipe, ...args) {
   return result === undefined ? draft : result
 }
 
+/**
+ * Serializes an object, converting special types like vectors into a plain
+ * object representation. This is useful for processes like saving state to a
+ * file or sending it over a network.
+ *
+ * - Recursively serializes nested objects.
+ * - Converts objects with a `__isVector__` property into a serializable
+ *   format: `{ _type: "vector", coords: [...] }`.
+ * - Copies all other property values as-is.
+ *
+ * @param {Object} obj - The object to serialize.
+ * @returns {string} The serialized JSON string.
+ */
+export function serialize(obj) {
+  function replacer(key, value) {
+    // Handle top-level vector
+    if (value?.__isVector__) {
+      return {
+        _type: "vector",
+        coords: Array.from(value),
+      }
+    }
+
+    if (isObject(value)) {
+      const serialized = {}
+
+      for (const k in value) {
+        if (Object.prototype.hasOwnProperty.call(value, k)) {
+          serialized[k] = replacer(undefined, value[k])
+        }
+      }
+
+      return serialized
+    }
+
+    return value
+  }
+
+  return JSON.stringify(obj, replacer)
+}
+
 /**
  * Converts an object or array to a formatted string representation.
  *

package/src/data-structures/object.test.js

@@ -1,12 +1,15 @@
 import { expect, test } from "vitest"
 
+import { v } from "../v.js"
 import {
   clone,
+  deserialize,
   filter,
   find,
   isObject,
   map,
   produce,
+  serialize,
   toString,
 } from "./object.js"
 
@@ -112,7 +115,7 @@ test("it should produce a new state without mutating the original", () => {
     g: 6,
   }
 
-  const originalBaseState = JSON.parse(JSON.stringify(baseState))
+  const originalBaseState = deserialize(serialize(baseState))
 
   const nextState = produce(baseState, recipe)
 
@@ -216,3 +219,117 @@ test("it should return a string representation of a nested object", () => {
   g: 6
 }`)
 })
+
+test("it should serialize a basic object with primitive values", () => {
+  const obj = { a: 1, b: "hello", c: true }
+  const expected = `{"a":1,"b":"hello","c":true}`
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should serialize an object with nested objects", () => {
+  const obj = { a: 1, b: { c: "nested", d: { e: false } } }
+  const expected = `{"a":1,"b":{"c":"nested","d":{"e":false}}}`
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should serialize an object containing a vector-like object", () => {
+  const obj = { position: v(1, 2, 3) }
+  const expected = `{"position":{"_type":"vector","coords":[1,2,3]}}`
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should serialize an object with nested vector-like objects", () => {
+  const obj = {
+    entity: {
+      id: "player",
+      pos: v(10, 20),
+      vel: v(1, 0),
+      stats: { health: 100 },
+    },
+  }
+  const expected = `{"entity":{"id":"player","pos":{"_type":"vector","coords":[10,20]},"vel":{"_type":"vector","coords":[1,0]},"stats":{"health":100}}}`
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should serialize an empty object", () => {
+  const obj = {}
+  const expected = `{}`
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should serialize an object with null and undefined values (undefined should be omitted)", () => {
+  const obj = { a: null, b: undefined, c: 1 }
+  const expected = `{"a":null,"c":1}` // JSON.stringify omits undefined properties
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should deserialize a basic object with primitive values", () => {
+  const serialized = `{"a":1,"b":"hello","c":true}`
+  const expected = { a: 1, b: "hello", c: true }
+
+  expect(deserialize(serialized)).toStrictEqual(expected)
+})
+
+test("it should deserialize an object with nested objects", () => {
+  const serialized = `{"a":1,"b":{"c":"nested","d":{"e":false}}}`
+  const expected = { a: 1, b: { c: "nested", d: { e: false } } }
+
+  expect(deserialize(serialized)).toStrictEqual(expected)
+})
+
+test("it should deserialize an object containing a vector representation", () => {
+  const serialized = `{"position":{"_type":"vector","coords":[1,2,3]}}`
+  const expected = { position: v(1, 2, 3) }
+
+  const result = deserialize(serialized)
+
+  expect(result).toStrictEqual(expected)
+  expect(result.position.__isVector__).toBe(true)
+})
+
+test("it should deserialize an object with nested vector representations", () => {
+  const serialized = `{"entity":{"id":"player","pos":{"_type":"vector","coords":[10,20]},"vel":{"_type":"vector","coords":[1,0]},"stats":{"health":100}}}`
+  const expected = {
+    entity: {
+      id: "player",
+      pos: v(10, 20),
+      vel: v(1, 0),
+      stats: { health: 100 },
+    },
+  }
+  const result = deserialize(serialized)
+
+  expect(result).toStrictEqual(expected)
+  expect(result.entity.pos.__isVector__).toBe(true)
+  expect(result.entity.vel.__isVector__).toBe(true)
+})
+
+test("it should deserialize an empty object", () => {
+  const serialized = `{}`
+  const expected = {}
+
+  expect(deserialize(serialized)).toStrictEqual(expected)
+})
+
+test("it should correctly round-trip a complex object through serialize and deserialize", () => {
+  const original = {
+    id: "game1",
+    player: { name: "Alice", score: 100, position: v(10, 20) },
+    enemies: [{ type: "goblin", pos: v(5, 5) }],
+    settings: { volume: 0.8, mute: false },
+  }
+  const jsonString = serialize(original)
+  const deserialized = deserialize(jsonString)
+
+  expect(deserialized).toStrictEqual(original)
+  expect(deserialized.player.position.__isVector__).toBe(true)
+  expect(deserialized.enemies[0].pos.__isVector__).toBe(true)
+  // Ensure that non-vector objects are still distinct references if they were originally
+  expect(deserialized.player).not.toBe(original.player)
+})

package/src/math/vector.js

@@ -4,7 +4,6 @@
  * @typedef {import('./types').Vector3} Vector3
  */
 
-import { isArray } from "../data-structures/array.js"
 import { v } from "../v.js"
 import {
   abs as nAbs,
@@ -128,17 +127,13 @@ export function fromAngle(angle) {
 
 /**
  * Checks if a value is a vector.
- * A vector is an array of numbers. For performance, vectors created with `v()`
- * are tagged and can be identified more quickly.
+ * This is determined by checking for the `__isVector__` property, which is
+ * added by the `v()` factory function for efficient type checking.
  * @param {*} value - The value to check.
  * @returns {boolean} True if the value is a vector, false otherwise.
  */
 export function isVector(value) {
-  return (
-    value?.__isVector__ ||
-    (isArray(value) &&
-      value.every((coordinate) => typeof coordinate === "number"))
-  )
+  return !!value?.__isVector__
 }
 
 /**

package/src/math/vector.test.js

@@ -126,8 +126,7 @@ test("it should compute the magnitude of a vector (aka length)", () => {
 })
 
 test("it should check if a value is a vector", () => {
-  expect(isVector([1, 2, 3])).toBe(true)
-  expect(isVector([])).toBe(true)
+  expect(isVector([1, 2, 3])).toBe(false)
   expect(isVector(v(1, 2, 3))).toBe(true)
 })