@inglorious/engine 0.2.0 → 0.3.0

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

@@ -1,138 +0,0 @@
-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,218 +0,0 @@
-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
-}`)
-})

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

@@ -1,66 +0,0 @@
-import { isObject } from "./object.js"
-
-/**
- * Extends a target object by merging it with one or more source objects.
- * Performs a deep merge for nested objects and arrays.
- *
- * @param {Object} target - The target object to extend.
- * @param {...Object} sources - The source objects to merge into the target object.
- * @returns {Object} - The extended target object.
- */
-export function extend(target, ...sources) {
-  return merge({}, target, ...sources)
-}
-
-/**
- * Merges multiple source objects into a target object.
- * Performs a deep merge for nested objects and arrays.
- *
- * @param {Object} target - The target object to merge into.
- * @param {...Object} sources - The source objects to merge from.
- * @returns {Object} - The merged target object.
- */
-export function merge(target, ...sources) {
-  return sources
-    .filter((source) => source != null)
-    .reduce((acc, source) => deepMerge(acc, source), target)
-}
-
-/**
- * Recursively merges the properties of the source object into the target object.
- *
- * @param {Object} target - The target object to merge into.
- * @param {Object} source - The source object to merge from.
- * @returns {Object} - The merged target object.
- */
-function deepMerge(target, source) {
-  for (const [key, value] of Object.entries(source)) {
-    if (Array.isArray(value) || isObject(value)) {
-      if (target[key] === undefined) {
-        target[key] = new value.__proto__.constructor()
-      }
-      target[key] = deepMerge(target[key], value)
-    } else {
-      target[key] = value
-    }
-  }
-  return target
-}
-
-/**
- * Assigns default properties to a target object from a source object.
- * For each key in `defaultProps`, if `target[key]` is `null` or `undefined`,
- * it is set to `defaultProps[key]`.
- *
- * This function modifies the target object in place.
- *
- * @param {Object} target The object to apply defaults to.
- * @param {Object} defaultProps The object containing the default properties.
- * @returns {Object} The modified target object.
- */
-export function defaults(target, defaultProps) {
-  for (const key in defaultProps) {
-    target[key] ??= defaultProps[key]
-  }
-  return target
-}

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

@@ -1,99 +0,0 @@
-import { expect, test } from "vitest"
-
-import { extend, merge } from "./objects.js"
-
-test("it should extend an object with another, producing a new object as a result", () => {
-  const obj1 = {
-    primitiveKept: 1,
-    primitiveMerged: 2,
-    primitiveArrayKept: [1, 2],
-    primitiveArrayMerged: [3, 4],
-    primitiveObjectKept: { a: 1 },
-    primitiveObjectMerged: { b: 2, c: 3 },
-    nestedArrayKept: [{ a: 1 }],
-    nestedArrayMerged: [{ b: 2, c: 3 }],
-    nestedObjectKept: { a: { b: 2 } },
-    nestedObjectMerged: { c: { d: 4 } },
-  }
-  const obj2 = {
-    primitiveMerged: 3,
-    primitiveAdded: 4,
-    primitiveArrayMerged: [5],
-    primitiveArrayAdded: [6, 7],
-    primitiveObjectMerged: { c: 4 },
-    primitiveObjectAdded: { d: 4 },
-    nestedArrayMerged: [{ d: 4 }],
-    nestedArrayAdded: [{ e: 5 }],
-    nestedObjectMerged: { c: { e: 5 } },
-    nestedObjectAdded: { f: { g: 7 } },
-  }
-  const expectedResult = {
-    primitiveKept: 1,
-    primitiveMerged: 3,
-    primitiveAdded: 4,
-    primitiveArrayKept: [1, 2],
-    primitiveArrayMerged: [5, 4],
-    primitiveArrayAdded: [6, 7],
-    primitiveObjectKept: { a: 1 },
-    primitiveObjectMerged: { b: 2, c: 4 },
-    primitiveObjectAdded: { d: 4 },
-    nestedArrayKept: [{ a: 1 }],
-    nestedArrayMerged: [{ b: 2, c: 3, d: 4 }],
-    nestedArrayAdded: [{ e: 5 }],
-    nestedObjectKept: { a: { b: 2 } },
-    nestedObjectMerged: { c: { d: 4, e: 5 } },
-    nestedObjectAdded: { f: { g: 7 } },
-  }
-
-  const result = extend(obj1, obj2)
-  expect(result).toStrictEqual(expectedResult)
-  expect(result).not.toBe(obj1)
-})
-
-test("it should deep merge an two objects, changing the first object in place", () => {
-  const obj1 = {
-    primitiveKept: 1,
-    primitiveMerged: 2,
-    primitiveArrayKept: [1, 2],
-    primitiveArrayMerged: [3, 4],
-    primitiveObjectKept: { a: 1 },
-    primitiveObjectMerged: { b: 2, c: 3 },
-    nestedArrayKept: [{ a: 1 }],
-    nestedArrayMerged: [{ b: 2, c: 3 }],
-    nestedObjectKept: { a: { b: 2 } },
-    nestedObjectMerged: { c: { d: 4 } },
-  }
-  const obj2 = {
-    primitiveMerged: 3,
-    primitiveAdded: 4,
-    primitiveArrayMerged: [5],
-    primitiveArrayAdded: [6, 7],
-    primitiveObjectMerged: { c: 4 },
-    primitiveObjectAdded: { d: 4 },
-    nestedArrayMerged: [{ d: 4 }],
-    nestedArrayAdded: [{ e: 5 }],
-    nestedObjectMerged: { c: { e: 5 } },
-    nestedObjectAdded: { f: { g: 7 } },
-  }
-  const expectedResult = {
-    primitiveKept: 1,
-    primitiveMerged: 3,
-    primitiveAdded: 4,
-    primitiveArrayKept: [1, 2],
-    primitiveArrayMerged: [5, 4],
-    primitiveArrayAdded: [6, 7],
-    primitiveObjectKept: { a: 1 },
-    primitiveObjectMerged: { b: 2, c: 4 },
-    primitiveObjectAdded: { d: 4 },
-    nestedArrayKept: [{ a: 1 }],
-    nestedArrayMerged: [{ b: 2, c: 3, d: 4 }],
-    nestedArrayAdded: [{ e: 5 }],
-    nestedObjectKept: { a: { b: 2 } },
-    nestedObjectMerged: { c: { d: 4, e: 5 } },
-    nestedObjectAdded: { f: { g: 7 } },
-  }
-
-  const result = merge(obj1, obj2)
-  expect(result).toStrictEqual(expectedResult)
-  expect(result).toBe(obj1)
-})

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

@@ -1,36 +0,0 @@
-/** @typedef {import('./types').Tree} Tree */
-
-/**
- * Performs a breadth-first search (BFS) traversal on a tree structure.
- * @param {Tree} tree - The root node of the tree.
- * @returns {Array} An array of values in BFS order.
- */
-export function bfs(tree) {
-  const result = []
-  const queue = [tree]
-
-  while (queue.length) {
-    const node = queue.shift()
-    result.push(node.value)
-    if (node.children) {
-      queue.push(...node.children)
-    }
-  }
-
-  return result
-}
-
-/**
- * Performs a depth-first search (DFS) traversal on a tree structure.
- * @param {Tree} tree - The root node of the tree.
- * @returns {Array} An array of values in DFS order.
- */
-export function dfs(tree) {
-  const result = [tree.value]
-
-  if (tree.children) {
-    result.push(...tree.children.flatMap(dfs))
-  }
-
-  return result
-}

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

@@ -1,33 +0,0 @@
-import { expect, test } from "vitest"
-
-import { bfs, dfs } from "./tree.js"
-
-test("it should perform Breadth-First Search on a tree", () => {
-  const tree = {
-    value: 1,
-    children: [
-      { value: 2, children: [{ value: 4 }, { value: 5 }] },
-      { value: 3, children: [{ value: 6 }, { value: 7 }] },
-    ],
-  }
-  const expectedResult = [1, 2, 3, 4, 5, 6, 7]
-
-  const result = bfs(tree)
-
-  expect(result).toStrictEqual(expectedResult)
-})
-
-test("it should perform Depth-First Search on a tree", () => {
-  const tree = {
-    value: 1,
-    children: [
-      { value: 2, children: [{ value: 3 }, { value: 4 }] },
-      { value: 5, children: [{ value: 6 }, { value: 7 }] },
-    ],
-  }
-  const expectedResult = [1, 2, 3, 4, 5, 6, 7]
-
-  const result = dfs(tree)
-
-  expect(result).toStrictEqual(expectedResult)
-})

package/src/utils/data-structures/types.d.ts

@@ -1,4 +0,0 @@
-export interface Tree {
-  value: any
-  children: Tree[]
-}

package/src/utils/functions/functions.js

@@ -1,19 +0,0 @@
-/**
- * Composes multiple functions from right to left, as if every function wraps the next one.
- *
- * @param {...Function} fns - Functions to compose.
- * @returns {Function} A function that takes an initial value and applies the composed functions.
- */
-export function compose(...fns) {
-  return (x) => fns.reduceRight((acc, fn) => fn(acc), x)
-}
-
-/**
- * Pipes multiple functions from left to right, as if the functions are applied one by one.
- *
- * @param {...Function} fns - Functions to pipe.
- * @returns {Function} A function that takes an initial value and applies the piped functions.
- */
-export function pipe(...fns) {
-  return (x) => fns.reduce((acc, fn) => fn(acc), x)
-}

package/src/utils/functions/functions.test.js

@@ -1,23 +0,0 @@
-import { expect, test } from "vitest"
-
-import { compose, pipe } from "./functions.js"
-
-test("it should compose functions", () => {
-  const shout = (x) => x.toUpperCase()
-  const punctuate = (mark) => (x) => `${x}${mark}`
-  const html = (tag) => (x) => `<${tag}>${x}</${tag}>`
-
-  const fn = compose(html("p"), punctuate("!"), shout)
-
-  expect(fn("Hello world")).toBe("<p>HELLO WORLD!</p>")
-})
-
-test("it should pipe functions", () => {
-  const shout = (x) => x.toUpperCase()
-  const punctuate = (mark) => (x) => `${x}${mark}`
-  const html = (tag) => (x) => `<${tag}>${x}</${tag}>`
-
-  const fn = pipe(shout, punctuate("!"), html("p"))
-
-  expect(fn("Hello world")).toBe("<p>HELLO WORLD!</p>")
-})