@inglorious/utils 1.0.0 → 1.2.0

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

@@ -0,0 +1,185 @@
+import { expect, test } from "vitest"
+
+import { contains, ensureArray, max, min, pop, push, remove } from "./array.js"
+
+test("it should check if an array contains a value", () => {
+  const arr = [3, 2, 6, 1, 7, 4, 5]
+  const item = 1
+  const expectedResult = true
+
+  expect(contains(arr, item)).toBe(expectedResult)
+})
+
+test("it should check if an array contains an object", () => {
+  const arr = [
+    { value: 3 },
+    { value: 2 },
+    { value: 6 },
+    { value: 1 },
+    { value: 7 },
+    { value: 4 },
+    { value: 5 },
+  ]
+  const item = arr[3]
+  const expectedResult = true
+
+  expect(contains(arr, item)).toBe(expectedResult)
+})
+
+test("it should return the same array if the value is already an array", () => {
+  const arr = [1, "two", { three: 3 }]
+
+  expect(ensureArray(arr)).toBe(arr)
+})
+
+test("it should wrap the value in an array if it is not an array", () => {
+  const str = "hello"
+
+  expect(ensureArray(str)).toStrictEqual([str])
+})
+
+test("it should find the maximum value of an array", () => {
+  const arr = [3, 2, 6, 1, 7, 4, 5]
+  const expectedResult = 7
+
+  expect(max(arr)).toBe(expectedResult)
+})
+
+test("it should find the maximum value in an array of objects", () => {
+  const arr = [
+    { value: 3 },
+    { value: 2 },
+    { value: 6 },
+    { value: 1 },
+    { value: 7 },
+    { value: 4 },
+    { value: 5 },
+  ]
+  const comparator = (a, b) => b.value - a.value
+  const expectedResult = { value: 7 }
+
+  expect(max(arr, comparator)).toStrictEqual(expectedResult)
+})
+
+test("it should find the minimum value of an array", () => {
+  const arr = [3, 2, 6, 1, 7, 4, 5]
+  const expectedResult = 1
+
+  expect(min(arr)).toBe(expectedResult)
+})
+
+test("it should find the minimum value in an array of objects", () => {
+  const arr = [
+    { value: 3 },
+    { value: 2 },
+    { value: 6 },
+    { value: 1 },
+    { value: 7 },
+    { value: 4 },
+    { value: 5 },
+  ]
+  const comparator = (a, b) => b.value - a.value
+  const expectedResult = { value: 1 }
+
+  expect(min(arr, comparator)).toStrictEqual(expectedResult)
+})
+
+test("it should remove the minimum value from an array", () => {
+  const arr = [3, 2, 6, 1, 7, 4, 5]
+  const expectedResult = [3, 2, 6, 7, 4, 5]
+
+  expect(pop(arr)).toStrictEqual(expectedResult)
+})
+
+test("it should remove the minimum object from an array", () => {
+  const arr = [
+    { value: 3 },
+    { value: 2 },
+    { value: 6 },
+    { value: 1 },
+    { value: 7 },
+    { value: 4 },
+    { value: 5 },
+  ]
+  const comparator = (a, b) => b.value - a.value
+  const expectedResult = [
+    { value: 3 },
+    { value: 2 },
+    { value: 6 },
+    { value: 7 },
+    { value: 4 },
+    { value: 5 },
+  ]
+
+  expect(pop(arr, comparator)).toStrictEqual(expectedResult)
+})
+
+test("it should remove the maximum value from an array", () => {
+  const arr = [3, 2, 6, 1, 7, 4, 5]
+  const comparator = (a, b) => a - b
+  const expectedResult = [3, 2, 6, 1, 4, 5]
+
+  expect(pop(arr, comparator)).toStrictEqual(expectedResult)
+})
+
+test("it should remove the maximum object from an array", () => {
+  const arr = [
+    { value: 3 },
+    { value: 2 },
+    { value: 6 },
+    { value: 1 },
+    { value: 7 },
+    { value: 4 },
+    { value: 5 },
+  ]
+  const comparator = (a, b) => a.value - b.value
+  const expectedResult = [
+    { value: 3 },
+    { value: 2 },
+    { value: 6 },
+    { value: 1 },
+    { value: 4 },
+    { value: 5 },
+  ]
+
+  expect(pop(arr, comparator)).toStrictEqual(expectedResult)
+})
+
+test("it should add a value at the end of the array", () => {
+  const arr = [3, 2, 6, 1, 7, 4]
+  const item = 5
+  const expectedResult = [3, 2, 6, 1, 7, 4, 5]
+
+  expect(push(arr, item)).toStrictEqual(expectedResult)
+})
+
+test("it should remove a primitive value from an array", () => {
+  const arr = [3, 2, 6, 1, 7, 4, 5]
+  const item = 1
+  const expectedResult = [3, 2, 6, 7, 4, 5]
+
+  expect(remove(arr, item)).toStrictEqual(expectedResult)
+})
+
+test("it should remove an object from an array", () => {
+  const arr = [
+    { value: 3 },
+    { value: 2 },
+    { value: 6 },
+    { value: 1 },
+    { value: 7 },
+    { value: 4 },
+    { value: 5 },
+  ]
+  const item = arr[3]
+  const expectedResult = [
+    { value: 3 },
+    { value: 2 },
+    { value: 6 },
+    { value: 7 },
+    { value: 4 },
+    { value: 5 },
+  ]
+
+  expect(remove(arr, item)).toStrictEqual(expectedResult)
+})

package/src/data-structures/board.js

@@ -0,0 +1,159 @@
+/**
+ * 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/data-structures/board.test.js

@@ -0,0 +1,242 @@
+import { expect, test } from "vitest"
+
+import { mod } from "../math/numbers.js"
+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/data-structures/boolean.js

@@ -0,0 +1,9 @@
+/**
+ * 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"
+}