@inglorious/engine 0.1.1 → 0.2.0

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

@@ -1,102 +1,138 @@
-const INITIAL_LEVEL = 0
-const NEXT_LEVEL = 2
-
-/**
- * Creates a deep clone of the given object.
- * @param {Object} obj - The object to clone.
- * @returns {Object} A deep clone of the input object.
- */
-export function clone(obj) {
-  return JSON.parse(JSON.stringify(obj))
-}
-
-/**
- * Filters the properties of an object based on a callback function.
- * @param {Object} obj - The object to filter.
- * @param {Function} callback - A function that determines whether a property should be included.
- *                              Receives (key, value, obj) as arguments.
- * @returns {Object} A new object with the filtered properties.
- */
-export function filter(obj, callback) {
-  return Object.fromEntries(
-    Object.entries(obj).filter(([key, value], obj) =>
-      callback(key, value, obj),
-    ),
-  )
-}
-
-/**
- * Finds the first property in an object that satisfies the callback function.
- * @param {Object} obj - The object to search.
- * @param {Function} callback - A function that determines whether a property matches.
- *                              Receives (key, value, obj) as arguments.
- * @returns {Object} An object containing the first matching property, or an empty object if none match.
- */
-export function find(obj, callback) {
-  return Object.fromEntries([
-    Object.entries(obj).find(([key, value], obj) => callback(key, value, obj)),
-  ])
-}
-
-/**
- * Checks if a value is a plain object.
- * @param {*} obj - The value to check.
- * @returns {boolean} True if the value is a plain object, false otherwise.
- */
-export function isObject(obj) {
-  return obj != null && obj.constructor === Object
-}
-
-/**
- * Maps the properties of an object using a callback function.
- * @param {Object} obj - The object to map.
- * @param {Function} callback - A function that transforms each property.
- *                              Receives (key, value, obj) as arguments.
- * @returns {Object} A new object with the mapped properties.
- */
-export function map(obj, callback) {
-  return Object.entries(obj).reduce((acc, [key, value]) => {
-    acc[key] = callback(key, value, obj)
-    return acc
-  }, {})
-}
-
-/**
- * Converts an object or array to a formatted string representation.
- * @param {*} obj - The object or array to convert.
- * @param {number} [indentationLevel=INITIAL_LEVEL] - The current indentation level (used for nested structures).
- * @returns {string} A string representation of the input object or array.
- */
-export function toString(obj, indentationLevel = INITIAL_LEVEL) {
-  if (Array.isArray(obj)) {
-    return `[
-${obj
-  .map(
-    (item) =>
-      " ".repeat(indentationLevel + NEXT_LEVEL) +
-      toString(item, indentationLevel + NEXT_LEVEL),
-  )
-  .join(",\n")}
-${" ".repeat(indentationLevel)}]`
-  }
-
-  if (typeof obj === "object" && obj != null) {
-    return `{
-${Object.entries(obj)
-  .map(
-    ([key, value]) =>
-      `${" ".repeat(indentationLevel + NEXT_LEVEL)}${key}: ${toString(
-        value,
-        indentationLevel + NEXT_LEVEL,
-      )}`,
-  )
-  .join(",\n")}
-${" ".repeat(indentationLevel)}}`
-  }
-
-  if (typeof obj === "string") {
-    return `"${obj}"`
-  }
-
-  return obj
-}
+const INITIAL_LEVEL = 0
+const NEXT_LEVEL = 2
+
+/**
+ * Creates a deep clone of the given object.
+ * @param {Object} obj - The object to clone.
+ * @returns {Object} A deep clone of the input object.
+ */
+export function clone(obj) {
+  return JSON.parse(JSON.stringify(obj))
+}
+
+/**
+ * Filters the properties of an object based on a callback function.
+ * @param {Object} obj - The object to filter.
+ * @param {Function} callback - A function that determines whether a property should be included.
+ *                              Receives (key, value, obj) as arguments.
+ * @returns {Object} A new object with the filtered properties.
+ */
+export function filter(obj, callback) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([key, value], obj) =>
+      callback(key, value, obj),
+    ),
+  )
+}
+
+/**
+ * Finds the first property in an object that satisfies the callback function.
+ * @param {Object} obj - The object to search.
+ * @param {Function} callback - A function that determines whether a property matches.
+ *                              Receives (key, value, obj) as arguments.
+ * @returns {Object} An object containing the first matching property, or an empty object if none match.
+ */
+export function find(obj, callback) {
+  return Object.fromEntries([
+    Object.entries(obj).find(([key, value], obj) => callback(key, value, obj)),
+  ])
+}
+
+/**
+ * Checks if a value is a plain object.
+ * @param {*} obj - The value to check.
+ * @returns {boolean} True if the value is a plain object, false otherwise.
+ */
+export function isObject(obj) {
+  return obj != null && obj.constructor === Object
+}
+
+/**
+ * Maps the properties of an object using a callback function.
+ * @param {Object} obj - The object to map.
+ * @param {Function} callback - A function that transforms each property.
+ *                              Receives (key, value, obj) as arguments.
+ * @returns {Object} A new object with the mapped properties.
+ */
+export function map(obj, callback) {
+  return Object.entries(obj).reduce((acc, [key, value]) => {
+    acc[key] = callback(key, value, obj)
+    return acc
+  }, {})
+}
+
+/**
+ * A utility function inspired by Immer's `produce` API. It provides a convenient
+ * way to work with immutable data structures by allowing "mutations" on a
+ * temporary draft.
+ *
+ * **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
+ * inefficient for large or complex states. It is intended for simple use cases
+ * where the convenience of the API outweighs the performance cost.
+ *
+ * The recipe function receives a draft copy of the state. It can either
+ * mutate the draft and return nothing (`undefined`), or it can return a
+ * completely new value, which will become the next state.
+ *
+ * Can be called in two ways:
+ * - **Standard:** `produce(baseState, recipe, ...args)`
+ * - **Curried:** `produce(recipe)` returns a new function `(baseState, ...args) => newState`
+ *
+ * @template T
+ * @param {T|function(T, ...*): (T|void)} baseState The initial state, or a recipe for currying.
+ * @param {function(T, ...*): (T|void)} [recipe] The recipe function.
+ * @param {...*} args Additional arguments to pass to the recipe.
+ * @returns {T | function(T, ...*): T} A new state, or a producer function if curried.
+ */
+export function produce(baseState, recipe, ...args) {
+  if (typeof baseState === "function" && recipe === undefined) {
+    const recipeFn = baseState
+    return (state, ...recipeArgs) => produce(state, recipeFn, ...recipeArgs)
+  }
+
+  const draft = clone(baseState)
+  const result = recipe(draft, ...args)
+  return result === undefined ? draft : result
+}
+
+/**
+ * Converts an object or array to a formatted string representation.
+ * @param {*} obj - The object or array to convert.
+ * @param {number} [indentationLevel=INITIAL_LEVEL] - The current indentation level (used for nested structures).
+ * @returns {string} A string representation of the input object or array.
+ */
+export function toString(obj, indentationLevel = INITIAL_LEVEL) {
+  if (Array.isArray(obj)) {
+    return `[
+${obj
+  .map(
+    (item) =>
+      " ".repeat(indentationLevel + NEXT_LEVEL) +
+      toString(item, indentationLevel + NEXT_LEVEL),
+  )
+  .join(",\n")}
+${" ".repeat(indentationLevel)}]`
+  }
+
+  if (typeof obj === "object" && obj != null) {
+    return `{
+${Object.entries(obj)
+  .map(
+    ([key, value]) =>
+      `${" ".repeat(indentationLevel + NEXT_LEVEL)}${key}: ${toString(
+        value,
+        indentationLevel + NEXT_LEVEL,
+      )}`,
+  )
+  .join(",\n")}
+${" ".repeat(indentationLevel)}}`
+  }
+
+  if (typeof obj === "string") {
+    return `"${obj}"`
+  }
+
+  return obj
+}

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

@@ -1,121 +1,218 @@
-import { expect, test } from "vitest"
-
-import { clone, filter, find, isObject, map, toString } from "./object.js"
-
-test("it should deep clone an object", () => {
-  const obj = {
-    primitive: 1,
-    array: [2, 3],
-    object: { a: 1, b: 2 },
-  }
-  const expectedResult = {
-    primitive: 1,
-    array: [2, 3],
-    object: { a: 1, b: 2 },
-  }
-
-  const result = clone(obj)
-
-  expect(result).toStrictEqual(expectedResult)
-  expect(result).not.toBe(expectedResult)
-  expect(result.primitive).toBe(expectedResult.primitive)
-  expect(result.array).not.toBe(expectedResult.array)
-  expect(result.object).not.toBe(expectedResult.object)
-})
-
-test("it should behave like Array.prototype.filter, but on an object", () => {
-  const obj = {
-    key1: "value1",
-    key2: "value2",
-    key3: "value3",
-  }
-  const callback = (key) => ["key2", "key3"].includes(key)
-  const expectedResult = {
-    key2: "value2",
-    key3: "value3",
-  }
-
-  expect(filter(obj, callback)).toStrictEqual(expectedResult)
-})
-
-test("it should behave like Array.prototype.find, but on an object", () => {
-  const obj = {
-    key1: "value1",
-    key2: "value2",
-    key3: "value3",
-  }
-  const callback = (key) => ["key2", "key3"].includes(key)
-  const expectedResult = {
-    key2: "value2",
-  }
-
-  expect(find(obj, callback)).toStrictEqual(expectedResult)
-})
-
-test("it correctly should check if a value is an object", () => {
-  expect(isObject(1)).toBe(false)
-  expect(isObject("a")).toBe(false)
-  expect(isObject([])).toBe(false)
-  expect(isObject(null)).toBe(false)
-  expect(isObject(new Date())).toBe(false)
-  expect(isObject({})).toBe(true)
-})
-
-test("it should behave like Array.prototype.map, but on an object", () => {
-  const obj = {
-    key1: "value1",
-    key2: "value2",
-    key3: "value3",
-  }
-  const callback = (key, value) => value.toUpperCase()
-  const expectedResult = {
-    key1: "VALUE1",
-    key2: "VALUE2",
-    key3: "VALUE3",
-  }
-
-  expect(map(obj, callback)).toStrictEqual(expectedResult)
-})
-
-test("it should return a string representation of a shallow object", () => {
-  const obj = {
-    key1: "value1",
-    key2: "value2",
-    key3: "value3",
-  }
-
-  expect(toString(obj)).toBe(`{
-  key1: "value1",
-  key2: "value2",
-  key3: "value3"
-}`)
-})
-
-test("it should return a string representation of a nested object", () => {
-  const obj = {
-    a: 1,
-    b: [7, 3],
-    c: { d: 4, h: 8 },
-    e: [{ f: 5, i: 9 }],
-    g: 6,
-  }
-
-  expect(toString(obj)).toBe(`{
-  a: 1,
-  b: [
-    7,
-    3
-  ],
-  c: {
-    d: 4,
-    h: 8
-  },
-  e: [
-    {
-      f: 5,
-      i: 9
-    }
-  ],
-  g: 6
-}`)
-})
+import { expect, test } from "vitest"
+
+import {
+  clone,
+  filter,
+  find,
+  isObject,
+  map,
+  produce,
+  toString,
+} from "./object.js"
+
+test("it should deep clone an object", () => {
+  const obj = {
+    primitive: 1,
+    array: [2, 3],
+    object: { a: 1, b: 2 },
+  }
+  const expectedResult = {
+    primitive: 1,
+    array: [2, 3],
+    object: { a: 1, b: 2 },
+  }
+
+  const result = clone(obj)
+
+  expect(result).toStrictEqual(expectedResult)
+  expect(result).not.toBe(expectedResult)
+  expect(result.primitive).toBe(expectedResult.primitive)
+  expect(result.array).not.toBe(expectedResult.array)
+  expect(result.object).not.toBe(expectedResult.object)
+})
+
+test("it should behave like Array.prototype.filter, but on an object", () => {
+  const obj = {
+    key1: "value1",
+    key2: "value2",
+    key3: "value3",
+  }
+  const callback = (key) => ["key2", "key3"].includes(key)
+  const expectedResult = {
+    key2: "value2",
+    key3: "value3",
+  }
+
+  expect(filter(obj, callback)).toStrictEqual(expectedResult)
+})
+
+test("it should behave like Array.prototype.find, but on an object", () => {
+  const obj = {
+    key1: "value1",
+    key2: "value2",
+    key3: "value3",
+  }
+  const callback = (key) => ["key2", "key3"].includes(key)
+  const expectedResult = {
+    key2: "value2",
+  }
+
+  expect(find(obj, callback)).toStrictEqual(expectedResult)
+})
+
+test("it correctly should check if a value is an object", () => {
+  expect(isObject(1)).toBe(false)
+  expect(isObject("a")).toBe(false)
+  expect(isObject([])).toBe(false)
+  expect(isObject(null)).toBe(false)
+  expect(isObject(new Date())).toBe(false)
+  expect(isObject({})).toBe(true)
+})
+
+test("it should behave like Array.prototype.map, but on an object", () => {
+  const obj = {
+    key1: "value1",
+    key2: "value2",
+    key3: "value3",
+  }
+  const callback = (key, value) => value.toUpperCase()
+  const expectedResult = {
+    key1: "VALUE1",
+    key2: "VALUE2",
+    key3: "VALUE3",
+  }
+
+  expect(map(obj, callback)).toStrictEqual(expectedResult)
+})
+
+test("it should produce a new state without mutating the original", () => {
+  const baseState = {
+    a: 1,
+    b: {
+      c: [2, 3],
+      d: { e: 4 },
+    },
+    f: 5,
+  }
+
+  const recipe = (draft) => {
+    draft.a = 10
+    draft.b.c.push(4)
+    draft.b.d.e = 40
+    draft.g = 6
+  }
+
+  const expectedState = {
+    a: 10,
+    b: {
+      c: [2, 3, 4],
+      d: { e: 40 },
+    },
+    f: 5,
+    g: 6,
+  }
+
+  const originalBaseState = JSON.parse(JSON.stringify(baseState))
+
+  const nextState = produce(baseState, recipe)
+
+  expect(nextState).toStrictEqual(expectedState)
+  expect(nextState).not.toBe(baseState)
+  expect(baseState).toStrictEqual(originalBaseState)
+})
+
+test("it should support currying to produce a new state", () => {
+  const baseState = {
+    a: 1,
+    b: {
+      c: [2, 3],
+      d: { e: 4 },
+    },
+    f: 5,
+  }
+  const originalStateCopy = clone(baseState)
+
+  const recipe = (draft) => {
+    draft.a = 10
+    draft.b.c.push(4)
+    draft.g = 6
+  }
+
+  const expectedState = {
+    a: 10,
+    b: {
+      c: [2, 3, 4],
+      d: { e: 4 },
+    },
+    f: 5,
+    g: 6,
+  }
+
+  const producer = produce(recipe)
+  const nextState = producer(baseState)
+
+  expect(nextState).toStrictEqual(expectedState)
+  expect(nextState).not.toBe(baseState)
+  expect(baseState).toStrictEqual(originalStateCopy)
+})
+
+test("it should pass extra arguments to the recipe", () => {
+  const baseState = { value: 1 }
+  const recipe = (draft, increment, multiplier) => {
+    draft.value = (draft.value + increment) * multiplier
+  }
+
+  // Test non-curried version
+  const nextStateUncurried = produce(baseState, recipe, 2, 3) // (1 + 2) * 3 = 9
+  expect(nextStateUncurried.value).toBe(9)
+
+  // Test curried version
+  const producer = produce(recipe)
+  const nextStateCurried = producer(baseState, 4, 5) // (1 + 4) * 5 = 25
+  expect(nextStateCurried.value).toBe(25)
+
+  expect(baseState.value).toBe(1)
+})
+
+test("it should return a string representation of a shallow object", () => {
+  const obj = {
+    key1: "value1",
+    key2: "value2",
+    key3: "value3",
+  }
+
+  expect(toString(obj)).toBe(`{
+  key1: "value1",
+  key2: "value2",
+  key3: "value3"
+}`)
+})
+
+test("it should return a string representation of a nested object", () => {
+  const obj = {
+    a: 1,
+    b: [7, 3],
+    c: { d: 4, h: 8 },
+    e: [{ f: 5, i: 9 }],
+    g: 6,
+  }
+
+  expect(toString(obj)).toBe(`{
+  a: 1,
+  b: [
+    7,
+    3
+  ],
+  c: {
+    d: 4,
+    h: 8
+  },
+  e: [
+    {
+      f: 5,
+      i: 9
+    }
+  ],
+  g: 6
+}`)
+})