@inglorious/engine 0.1.1 → 0.3.0

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

@@ -1,159 +0,0 @@
-/**
- * Default filler function for board cells.
- * @returns {null} Default value for a cell.
- */
-const DEFAULT_FILLER = () => null
-
-/**
- * Default function to convert a cell to a string.
- * @param {*} cell - The cell value.
- * @returns {string} String representation of the cell.
- */
-const DEFAULT_CELL_TO_STRING = (cell) => `${cell}`
-
-const FIRST_ROW = 0
-const FIRST_COLUMN = 0
-const LAST_ROW_OFFSET = 1
-const LAST_COLUMN_OFFSET = 1
-const MOVE_DOWN = 1
-const MOVE_LEFT = -1
-const MOVE_RIGHT = 1
-const MOVE_UP = -1
-
-/**
- * Calculates the index in a one-dimensional array for given row and column.
- * @param {number} row - The row index.
- * @param {number} column - The column index.
- * @param {number} columns - The total number of columns.
- * @returns {number} The calculated index.
- */
-function getIndex(row, column, columns) {
-  return row * columns + column
-}
-
-/**
- * Creates a 1D board with the specified dimensions and fills it using the provided filler function.
- * @param {[number, number]} dimensions - Array containing the number of rows and columns.
- * @param {Function} [filler=DEFAULT_FILLER] - Function to fill each cell of the board.
- * @returns {any[]} The created board.
- */
-export function createBoard([rows, columns], filler = DEFAULT_FILLER) {
-  return new Array(rows * columns).fill(null).map((_, index) => {
-    const row = Math.floor(index / columns)
-    const column = index % columns
-    return filler(row, column)
-  })
-}
-
-/**
- * Moves the given coordinates one step down.
- * @param {[number, number]} coords - The current coordinates [row, column].
- * @param {[number]} size - Array containing the number of rows.
- * @returns {[number, number]} The new coordinates after moving down.
- * @throws {Error} If the movement goes out of bounds.
- */
-export function down([i, j], [rows]) {
-  if (i === rows - LAST_ROW_OFFSET) {
-    throw new Error()
-  }
-  return [i + MOVE_DOWN, j]
-}
-
-/**
- * Moves the given coordinates one step down and one step left.
- * @param {[number, number]} coords - The current coordinates [row, column].
- * @param {[number, number]} size - Array containing the number of rows and columns.
- * @returns {[number, number]} The new coordinates after moving down-left.
- */
-export function downLeft(coords, size) {
-  return down(left(coords, size), size)
-}
-
-/**
- * Moves the given coordinates one step down and one step right.
- * @param {[number, number]} coords - The current coordinates [row, column].
- * @param {[number, number]} size - Array containing the number of rows and columns.
- * @returns {[number, number]} The new coordinates after moving down-right.
- */
-export function downRight(coords, size) {
-  return down(right(coords, size), size)
-}
-
-/**
- * Moves the given coordinates one step left.
- * @param {[number, number]} coords - The current coordinates [row, column].
- * @returns {[number, number]} The new coordinates after moving left.
- * @throws {Error} If the movement goes out of bounds.
- */
-export function left([i, j]) {
-  if (j === FIRST_COLUMN) {
-    throw new Error()
-  }
-  return [i, j + MOVE_LEFT]
-}
-
-/**
- * Moves the given coordinates one step right.
- * @param {[number, number]} coords - The current coordinates [row, column].
- * @param {[number, number]} size - Array containing the number of rows and columns.
- * @returns {[number, number]} The new coordinates after moving right.
- * @throws {Error} If the movement goes out of bounds.
- */
-export function right([i, j], [, columns]) {
-  if (j === columns - LAST_COLUMN_OFFSET) {
-    throw new Error()
-  }
-  return [i, j + MOVE_RIGHT]
-}
-
-/**
- * Converts the board to a string representation.
- * @param {any[]} board - The 1D board to convert.
- * @param {[number, number]} dimensions - Array containing the number of rows and columns.
- * @param {Function} [cellToString=DEFAULT_CELL_TO_STRING] - Function to convert each cell to a string.
- * @returns {string} The string representation of the board.
- */
-export function toString(
-  board,
-  [rows, columns],
-  cellToString = DEFAULT_CELL_TO_STRING,
-) {
-  return Array.from({ length: rows }, (_, i) =>
-    Array.from({ length: columns }, (_, j) =>
-      cellToString(board[getIndex(i, j, columns)], i, j),
-    ).join(" "),
-  ).join("\n")
-}
-
-/**
- * Moves the given coordinates one step up.
- * @param {[number, number]} coords - The current coordinates [row, column].
- * @returns {[number, number]} The new coordinates after moving up.
- * @throws {Error} If the movement goes out of bounds.
- */
-export function up([i, j]) {
-  if (i === FIRST_ROW) {
-    throw new Error()
-  }
-  return [i + MOVE_UP, j]
-}
-
-/**
- * Moves the given coordinates one step up and one step left.
- * @param {[number, number]} coords - The current coordinates [row, column].
- * @param {[number, number]} size - Array containing the number of rows and columns.
- * @returns {[number, number]} The new coordinates after moving up-left.
- */
-export function upLeft(coords, size) {
-  return up(left(coords, size), size)
-}
-
-/**
- * Moves the given coordinates one step up and one step right.
- * @param {[number, number]} coords - The current coordinates [row, column].
- * @param {[number, number]} size - Array containing the number of rows and columns.
- * @returns {[number, number]} The new coordinates after moving up-right.
- */
-export function upRight(coords, size) {
-  return up(right(coords, size), size)
-}

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

@@ -1,242 +0,0 @@
-import { mod } from "@inglorious/utils/math/numbers.js"
-import { expect, test } from "vitest"
-
-import {
-  createBoard,
-  down,
-  downLeft,
-  downRight,
-  left,
-  right,
-  toString,
-  up,
-  upLeft,
-  upRight,
-} from "./board.js"
-
-test("it should create an empty board", () => {
-  const size = [4, 4]
-  const expectedResult = [
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-    null,
-  ]
-
-  expect(createBoard(size)).toStrictEqual(expectedResult)
-})
-
-test("it should create a checkerboard", () => {
-  const size = [4, 4]
-  const filler = (i, j) => (!mod(i + j, 2) ? 1 : 0)
-  const expectedResult = [1, 0, 1, 0, 0, 1, 0, 1, 1, 0, 1, 0, 0, 1, 0, 1]
-
-  expect(createBoard(size, filler)).toStrictEqual(expectedResult)
-})
-
-test("it should return the coordinates of the cell downward", () => {
-  const size = [8, 8]
-  const coordinates = [3, 4]
-  const expectedResult = [4, 4]
-
-  expect(down(coordinates, size)).toStrictEqual(expectedResult)
-})
-
-test("it should throw going down if cell is downmost", () => {
-  const size = [8, 8]
-  const coordinates = [7, 4]
-
-  expect(() => down(coordinates, size)).toThrow()
-})
-
-test("it should return the coordinates of the cell down left", () => {
-  const size = [8, 8]
-  const coordinates = [3, 4]
-  const expectedResult = [4, 3]
-
-  expect(downLeft(coordinates, size)).toStrictEqual(expectedResult)
-})
-
-test("it should throw going down left if cell is downmost", () => {
-  const size = [8, 8]
-  const coordinates = [7, 4]
-
-  expect(() => downLeft(coordinates, size)).toThrow()
-})
-
-test("it should throw going down left if cell is downmost", () => {
-  const size = [8, 8]
-  const coordinates = [3, 0]
-
-  expect(() => downLeft(coordinates, size)).toThrow()
-})
-
-test("it should throw going down left if cell is on the angle", () => {
-  const size = [8, 8]
-  const coordinates = [7, 0]
-
-  expect(() => downLeft(coordinates, size)).toThrow()
-})
-
-test("it should return the coordinates of the cell down right", () => {
-  const size = [8, 8]
-  const coordinates = [3, 4]
-  const expectedResult = [4, 5]
-
-  expect(downRight(coordinates, size)).toStrictEqual(expectedResult)
-})
-
-test("it should throw going down right if cell is downmost", () => {
-  const size = [8, 8]
-  const coordinates = [7, 4]
-
-  expect(() => downRight(coordinates, size)).toThrow()
-})
-
-test("it should throw going down right if cell is downmost", () => {
-  const size = [8, 8]
-  const coordinates = [3, 7]
-
-  expect(() => downRight(coordinates, size)).toThrow()
-})
-
-test("it should throw going down right if cell is on the angle", () => {
-  const size = [8, 8]
-  const coordinates = [7, 7]
-
-  expect(() => downRight(coordinates, size)).toThrow()
-})
-
-test("it should return the coordinates of the cell to the left", () => {
-  const size = [8, 8]
-  const coordinates = [3, 4]
-  const expectedResult = [3, 3]
-
-  expect(left(coordinates, size)).toStrictEqual(expectedResult)
-})
-
-test("it should not return coordinates to the left if cell is leftmost", () => {
-  const size = [8, 8]
-  const coordinates = [3, 0]
-
-  expect(() => left(coordinates, size)).toThrow()
-})
-
-test("it should return the coordinates of the cell to the right", () => {
-  const size = [8, 8]
-  const coordinates = [3, 4]
-  const expectedResult = [3, 5]
-
-  expect(right(coordinates, size)).toStrictEqual(expectedResult)
-})
-
-test("it should not return coordinates to the right if cell is rightmost", () => {
-  const size = [8, 8]
-  const coordinates = [3, 7]
-
-  expect(() => right(coordinates, size)).toThrow()
-})
-
-test("it should return a string representation of the given board", () => {
-  const board = [1, 0, 1, 0, 0, 1, 0, 1, 1, 0, 1, 0, 0, 1, 0, 1]
-
-  expect(toString(board, [4, 4])).toBe(`1 0 1 0
-0 1 0 1
-1 0 1 0
-0 1 0 1`)
-})
-
-test("it should return a custom string representation of the given board", () => {
-  const board = [1, 0, 1, 0, 0, 1, 0, 1, 1, 0, 1, 0, 0, 1, 0, 1]
-  const cellToString = (cell) => cell.toFixed(1)
-
-  expect(toString(board, [4, 4], cellToString)).toBe(`1.0 0.0 1.0 0.0
-0.0 1.0 0.0 1.0
-1.0 0.0 1.0 0.0
-0.0 1.0 0.0 1.0`)
-})
-
-test("it should return the coordinates of the cell upward", () => {
-  const size = [8, 8]
-  const coordinates = [3, 4]
-  const expectedResult = [2, 4]
-
-  expect(up(coordinates, size)).toStrictEqual(expectedResult)
-})
-
-test("it should throw going upward if cell is topmost", () => {
-  const size = [8, 8]
-  const coordinates = [0, 4]
-
-  expect(() => up(coordinates, size)).toThrow()
-})
-
-test("it should return the coordinates of the cell up left", () => {
-  const size = [8, 8]
-  const coordinates = [3, 4]
-  const expectedResult = [2, 3]
-
-  expect(upLeft(coordinates, size)).toStrictEqual(expectedResult)
-})
-
-test("it should throw going up left if cell is upmost", () => {
-  const size = [8, 8]
-  const coordinates = [0, 4]
-
-  expect(() => upLeft(coordinates, size)).toThrow()
-})
-
-test("it should throw going up left if cell is leftmost", () => {
-  const size = [8, 8]
-  const coordinates = [3, 0]
-
-  expect(() => upLeft(coordinates, size)).toThrow()
-})
-
-test("it should throw going up left if cell is on the angle", () => {
-  const size = [8, 8]
-  const coordinates = [0, 0]
-
-  expect(() => upLeft(coordinates, size)).toThrow()
-})
-
-test("it should return the coordinates of the cell up right", () => {
-  const size = [8, 8]
-  const coordinates = [3, 4]
-  const expectedResult = [2, 5]
-
-  expect(upRight(coordinates, size)).toStrictEqual(expectedResult)
-})
-
-test("it should throw going up right if cell is upmost", () => {
-  const size = [8, 8]
-  const coordinates = [0, 4]
-
-  expect(() => upRight(coordinates, size)).toThrow()
-})
-
-test("it should throw going down right if cell is rightmost", () => {
-  const size = [8, 8]
-  const coordinates = [3, 7]
-
-  expect(() => upRight(coordinates, size)).toThrow()
-})
-
-test("it should throw going down right if cell is on the angle", () => {
-  const size = [8, 8]
-  const coordinates = [0, 7]
-
-  expect(() => upRight(coordinates, size)).toThrow()
-})

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

@@ -1,9 +0,0 @@
-/**
- * Converts a boolean value to its string representation.
- *
- * @param {boolean} bool - The boolean value to convert.
- * @returns {string} The string "true" if the input is true, otherwise "false".
- */
-export function toString(bool) {
-  return bool ? "true" : "false"
-}

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

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

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