@inglorious/engine 0.1.0

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

@@ -0,0 +1,164 @@
+// @see https://stackfull.dev/heaps-in-javascript
+
+/**
+ * Default comparator for a max-heap.
+ * @param {*} a - First element.
+ * @param {*} b - Second element.
+ * @returns {number} Positive if `a` should come before `b`, negative otherwise.
+ */
+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.
+
+/**
+ * Checks if a heap contains a specific item.
+ * @param {Array} heap - The heap array.
+ * @param {*} item - The item to check for.
+ * @returns {boolean} True if the item exists in the heap, false otherwise.
+ */
+export function contains(heap, item) {
+  return heap.includes(item)
+}
+
+/**
+ * Converts an array into a heap.
+ * @param {Array} arr - The input array.
+ * @param {Function} [comparator=DEFAULT_COMPARATOR] - Comparator function to define heap order.
+ * @returns {Array} The heapified array.
+ */
+export function heapify(arr, comparator = DEFAULT_COMPARATOR) {
+  let heap = []
+  for (const item of arr) {
+    heap = push(heap, item, comparator)
+  }
+  return heap
+}
+
+/**
+ * Adds an item to the heap and maintains the heap property.
+ * @param {Array} heap - The heap array.
+ * @param {*} item - The item to add.
+ * @param {Function} [comparator=DEFAULT_COMPARATOR] - Comparator function to define heap order.
+ * @returns {Array} The updated heap array.
+ */
+export function push(heap, item, comparator = DEFAULT_COMPARATOR) {
+  const h = [...heap, item]
+
+  if (h.length === SINGLE_ELEMENT) {
+    return h
+  }
+
+  let index = h.length - LAST_ELEMENT_OFFSET
+  let parentIndex = parent(index)
+
+  while (
+    index > ROOT_INDEX &&
+    comparator(h[index], h[parentIndex]) > COMPARATOR_THRESHOLD
+  ) {
+    ;[h[index], h[parentIndex]] = [h[parentIndex], h[index]]
+
+    index = parentIndex
+    parentIndex = parent(index)
+  }
+
+  return h
+}
+
+/**
+ * Calculates the index of the left child of a given node.
+ * @param {number} index - The index of the parent node.
+ * @returns {number} The index of the left child.
+ */
+export function left(index) {
+  return LEFT_CHILD_MULTIPLIER * index + LEFT_CHILD_OFFSET
+}
+
+/**
+ * Calculates the index of the parent of a given node.
+ * @param {number} index - The index of the child node.
+ * @returns {number} The index of the parent node.
+ */
+export function parent(index) {
+  return Math.floor((index - INDEX_ADJUSTMENT) / PARENT_DIVISOR)
+}
+
+/**
+ * Removes and returns the root element of the heap.
+ * @param {Array} heap - The heap array.
+ * @param {Function} [comparator=DEFAULT_COMPARATOR] - Comparator function to define heap order.
+ * @returns {Array} The updated heap array after removing the root.
+ */
+export function pop(heap, comparator = DEFAULT_COMPARATOR) {
+  const h = [...heap]
+  ;[h[ROOT_INDEX], h[h.length - LAST_ELEMENT_OFFSET]] = [
+    h[h.length - LAST_ELEMENT_OFFSET],
+    h[ROOT_INDEX],
+  ]
+
+  h.pop()
+
+  let index = ROOT_INDEX
+  let leftIndex = left(index)
+  let rightIndex = right(index)
+  let newMinFound = false
+
+  while (leftIndex < h.length && !newMinFound) {
+    const minIndex =
+      rightIndex < h.length &&
+      comparator(h[rightIndex], h[leftIndex]) > COMPARATOR_THRESHOLD
+        ? rightIndex
+        : leftIndex
+    newMinFound = comparator(h[minIndex], h[index]) > COMPARATOR_THRESHOLD
+
+    if (newMinFound) {
+      ;[h[minIndex], h[index]] = [h[index], h[minIndex]]
+
+      index = minIndex
+      leftIndex = left(index)
+      rightIndex = right(index)
+    }
+  }
+
+  return h
+}
+
+/**
+ * Removes the root element and reorders the heap.
+ * @param {Array} heap - The heap array.
+ * @returns {Array} The updated heap array.
+ */
+export function remove(heap) {
+  const [, ...rest] = heap
+  return heapify([
+    ...rest.slice(-LAST_ELEMENT_OFFSET),
+    ...rest.slice(ROOT_INDEX, -LAST_ELEMENT_OFFSET),
+  ])
+}
+
+/**
+ * Calculates the index of the right child of a given node.
+ * @param {number} index - The index of the parent node.
+ * @returns {number} The index of the right child.
+ */
+export function right(index) {
+  return RIGHT_CHILD_MULTIPLIER * index + RIGHT_CHILD_OFFSET
+}
+
+/**
+ * Retrieves the root element of the heap.
+ * @param {Array} heap - The heap array.
+ * @returns {*} The root element of the heap.
+ */
+export function root(heap) {
+  return heap[ROOT_INDEX]
+}

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

@@ -0,0 +1,103 @@
+import { expect, test } from "vitest"
+
+import { contains, heapify, pop, push, remove, root } from "./heap.js"
+
+test("it should check if a heap contains a value", () => {
+  const heap = [3, 2, 6, 1, 7, 4, 5]
+  const item = 1
+  const expectedResult = true
+
+  expect(contains(heap, item)).toBe(expectedResult)
+})
+
+test("it should check if a heap contains an object", () => {
+  const heap = [
+    { value: 3 },
+    { value: 2 },
+    { value: 6 },
+    { value: 1 },
+    { value: 7 },
+    { value: 4 },
+    { value: 5 },
+  ]
+  const item = heap[3]
+  const expectedResult = true
+
+  expect(contains(heap, item)).toBe(expectedResult)
+})
+
+test("it should not convert an array in existing heap form into a heap", () => {
+  const arr = [1, 2, 3, 4, 5, 6, 7]
+  const expectedResult = [1, 2, 3, 4, 5, 6, 7]
+
+  expect(heapify(arr)).toStrictEqual(expectedResult)
+})
+
+test("it should convert an array into a heap", () => {
+  const arr = [7, 6, 5, 4, 3, 2, 1]
+  const expectedResult = [1, 4, 2, 7, 5, 6, 3]
+
+  expect(heapify(arr)).toStrictEqual(expectedResult)
+})
+
+test("it should convert an array into a maxheap", () => {
+  const arr = [1, 2, 3, 4, 5, 6, 7]
+  const comparator = (a, b) => a - b
+  const expectedResult = [7, 4, 6, 1, 3, 2, 5]
+
+  expect(heapify(arr, comparator)).toStrictEqual(expectedResult)
+})
+
+test("it should find the minimum value in a min heap", () => {
+  const heap = [1, 4, 2, 7, 5, 6, 3]
+  const expectedResult = 1
+
+  expect(root(heap)).toBe(expectedResult)
+})
+
+test("it should push the first element of the heap", () => {
+  const heap = []
+  const value = 7
+  const expectedResult = [7]
+
+  expect(push(heap, value)).toStrictEqual(expectedResult)
+})
+
+test("it should push the biggest value at the end of the heap", () => {
+  const heap = [3, 13, 19, 33, 42, 23, 21]
+  const value = 50
+  const expectedResult = [3, 13, 19, 33, 42, 23, 21, 50]
+
+  expect(push(heap, value)).toStrictEqual(expectedResult)
+})
+
+test("it should push a value in the right spot of a heap", () => {
+  const heap = [3, 13, 19, 33, 42, 23, 21]
+  const value = 7
+  const expectedResult = [3, 7, 19, 13, 42, 23, 21, 33]
+
+  expect(push(heap, value)).toStrictEqual(expectedResult)
+})
+
+test("it should pop the lowest value from the end of the heap", () => {
+  const heap = [3, 13, 19, 33, 42, 23, 21]
+  const expectedResult = [13, 21, 19, 33, 42, 23]
+
+  expect(pop(heap)).toStrictEqual(expectedResult)
+})
+
+test("it should push the biggest value at the beginning of a maxheap", () => {
+  const heap = [3, 13, 19, 33, 42, 23, 21]
+  const comparator = (a, b) => a - b
+  const value = 50
+  const expectedResult = [50, 3, 19, 13, 42, 23, 21, 33]
+
+  expect(push(heap, value, comparator)).toStrictEqual(expectedResult)
+})
+
+test("it should remove the heap's root element", () => {
+  const heap = [3, 13, 19, 33, 42, 23, 21]
+  const expectedResult = [13, 21, 19, 33, 42, 23]
+
+  expect(remove(heap)).toStrictEqual(expectedResult)
+})

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

@@ -0,0 +1,102 @@
+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
+}

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

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

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

@@ -0,0 +1,48 @@
+import { isObject } from "./object.js"
+
+/**
+ * Extends a destination object by merging it with one or more source objects.
+ * Performs a deep merge for nested objects and arrays.
+ *
+ * @param {Object} dest - The destination object to extend.
+ * @param {...Object} sources - The source objects to merge into the destination object.
+ * @returns {Object} - The extended destination object.
+ */
+export function extend(dest, ...sources) {
+  return merge({}, dest, ...sources)
+}
+
+/**
+ * Merges multiple source objects into a destination object.
+ * Performs a deep merge for nested objects and arrays.
+ *
+ * @param {Object} dest - The destination object to merge into.
+ * @param {...Object} sources - The source objects to merge from.
+ * @returns {Object} - The merged destination object.
+ */
+export function merge(dest, ...sources) {
+  return sources
+    .filter((source) => source != null)
+    .reduce((acc, source) => deepMerge(acc, source), dest)
+}
+
+/**
+ * Recursively merges the properties of the source object into the destination object.
+ *
+ * @param {Object} dest - The destination object to merge into.
+ * @param {Object} source - The source object to merge from.
+ * @returns {Object} - The merged destination object.
+ */
+function deepMerge(dest, source) {
+  for (const [key, value] of Object.entries(source)) {
+    if (Array.isArray(value) || isObject(value)) {
+      if (dest[key] === undefined) {
+        dest[key] = new value.__proto__.constructor()
+      }
+      dest[key] = deepMerge(dest[key], value)
+    } else {
+      dest[key] = value
+    }
+  }
+  return dest
+}

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

@@ -0,0 +1,99 @@
+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

@@ -0,0 +1,36 @@
+/** @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

@@ -0,0 +1,33 @@
+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)
+})