@inglorious/utils 1.0.0 → 1.2.0

package/src/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/data-structures/set.js

@@ -0,0 +1,9 @@
+/**
+ * Ensures that the given value is a Set. If it's not a Set, it creates one from the value.
+ *
+ * @param {*} value - The value to check.
+ * @returns {Set} - The original Set or a new Set created from the value.
+ */
+export function ensureSet(value) {
+  return value instanceof Set ? value : new Set(value)
+}

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

@@ -0,0 +1,15 @@
+import { expect, test } from "vitest"
+
+import { ensureSet } from "./set.js"
+
+test("it should return the same array if the value is already an array", () => {
+  const set = new Set([1, "two", { three: 3 }])
+
+  expect(ensureSet(set)).toBe(set)
+})
+
+test("it should wrap the value in an array if it is not an array", () => {
+  const str = "hello"
+
+  expect(ensureSet(str)).toStrictEqual(new Set(["h", "e", "l", "o"]))
+})

package/src/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/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)
+})

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

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

package/src/functions/functions.js

@@ -0,0 +1,19 @@
+/**
+ * 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/functions/functions.test.js

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

package/src/math/geometry/circle.js

@@ -0,0 +1,69 @@
+/**
+ * @typedef {import("./types").Point} Point
+ * @typedef {import("./types").Circle} Circle
+ * @typedef {import("./types").Rectangle} Rectangle
+ * @typedef {import("./types").Platform} Platform
+ */
+
+import { clamp } from "../linear-algebra/vector.js"
+import { subtract } from "../linear-algebra/vectors.js"
+import { intersectsCircle as pointIntersectsCircle } from "./point.js"
+import { hypothenuse } from "./triangle.js"
+
+const HALF = 2
+const SQUARED = 2
+const INITIAL_SUM = 0
+
+/**
+ * Checks if a circle intersects with a point.
+ * @param {Circle} circle - The circle to check.
+ * @param {Point} point - The point to check.
+ * @returns {boolean} True if the point intersects the circle, false otherwise.
+ */
+export function intersectsPoint(circle, point) {
+  return pointIntersectsCircle(point, circle)
+}
+
+/**
+ * Checks if two circles intersect.
+ * @param {Circle} circle1 - The first circle.
+ * @param {Circle} circle2 - The second circle.
+ * @returns {boolean} True if the circles intersect, false otherwise.
+ */
+export function intersectsCircle(circle1, circle2) {
+  return (
+    hypothenuse(...subtract(circle1.position, circle2.position)) <=
+    circle1.radius + circle2.radius
+  )
+}
+
+/**
+ * Checks if a circle intersects with a rectangle.
+ * @param {Circle} circle - The circle to check.
+ * @param {Rectangle} rectangle - The rectangle to check.
+ * @returns {boolean} True if the circle intersects the rectangle, false otherwise.
+ */
+export function intersectsRectangle(circle, rectangle) {
+  const [rectX, rectY, rectZ] = rectangle.position
+  const [width, height, depth] = rectangle.size
+
+  const left = rectX - width / HALF
+  const right = rectX + width / HALF
+  const bottom = rectY - height / HALF
+  const top = rectY + height / HALF
+  const back = rectZ - depth / HALF
+  const front = rectZ + depth / HALF
+
+  const closestPoint = clamp(
+    circle.position,
+    [left, bottom, back],
+    [right, top, front],
+  )
+
+  const distanceSquared = subtract(circle.position, closestPoint).reduce(
+    (sum, value) => sum + value ** SQUARED,
+    INITIAL_SUM,
+  )
+
+  return distanceSquared <= circle.radius ** SQUARED
+}

package/src/math/geometry/circle.test.js

@@ -0,0 +1,97 @@
+import { expect, test } from "vitest"
+
+import {
+  intersectsCircle,
+  intersectsPoint,
+  intersectsRectangle,
+} from "./circle.js"
+
+test("it should prove that a circle around a point intersects with it", () => {
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+  const point = [1.5, 1.5, 0]
+
+  expect(intersectsPoint(circle, point)).toBe(true)
+})
+
+test("it should prove that two equal circles intersect", () => {
+  const circle1 = { position: [1, 1, 0], radius: 1 }
+  const circle2 = { position: [1, 1, 0], radius: 1 }
+
+  expect(intersectsCircle(circle1, circle2)).toBe(true)
+})
+
+test("it should prove that two circles shifted by a small x intersect", () => {
+  const circle1 = { position: [1, 1, 0], radius: 1 }
+  const circle2 = { position: [2, 1, 0], radius: 1 }
+
+  expect(intersectsCircle(circle1, circle2)).toBe(true)
+})
+
+test("it should prove that two touching circles intersect", () => {
+  const circle1 = { position: [1, 1, 0], radius: 1 }
+  const circle2 = { position: [3, 1, 0], radius: 1 }
+
+  expect(intersectsCircle(circle1, circle2)).toBe(true)
+})
+
+test("it should prove that two non-touching circles do not intersect", () => {
+  const circle1 = { position: [1, 1, 0], radius: 1 }
+  const circle2 = { position: [4, 1, 0], radius: 1 }
+
+  expect(intersectsCircle(circle1, circle2)).toBe(false)
+})
+
+test("it should prove that a circle inside of a rectangle intersects with it", () => {
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+  const rectangle = {
+    position: [-1, -1, 0],
+    size: [4, 4, 0],
+  }
+
+  expect(intersectsRectangle(circle, rectangle)).toBe(true)
+})
+
+test("it should prove that a circle touching the border of a rectangle intersects with it", () => {
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+  const rectangle = {
+    position: [-1, 1, 0], // Rectangle's right edge is at x=0, touching the circle's left edge.
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(circle, rectangle)).toBe(true)
+})
+
+test("it should prove that a circle crossing a rectangle intersects with it", () => {
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+  const rectangle = {
+    position: [0, 0, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(circle, rectangle)).toBe(true)
+})
+
+test("it should prove that a circle outside of a rectangle does not intersect with it", () => {
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+  const rectangle = {
+    position: [-3, 0, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(circle, rectangle)).toBe(false)
+})

package/src/math/geometry/hitmask.js

@@ -0,0 +1,70 @@
+// @see https://jonathanwhiting.com/tutorial/collision/
+
+import { intersectsRectangle } from "./rectangle.js"
+
+const FIRST_TILE = 0
+const HALF = 2
+const LAST_ROW = 1
+
+export function findCollisions(hitmask, target) {
+  const [tilemapX, tilemapY, tilemapZ] = hitmask.position
+  const [tileWidth, tileDepth] = hitmask.tileSize
+  const halfTileWidth = tileWidth / HALF
+  const halfTileDepth = tileDepth / HALF
+
+  const dRows = Math.ceil(hitmask.heights.length / hitmask.columns)
+  const tilemapWidth = hitmask.columns * tileWidth
+  const tilemapDepth = dRows * tileDepth
+
+  const tilemapLeft = tilemapX - tilemapWidth / HALF
+  const tilemapBack = tilemapZ - tilemapDepth / HALF
+
+  const [targetX, , targetZ] = target.position
+  const [targetWidth, , targetDepth] = target.size
+  const targetHalfWidth = targetWidth / HALF
+  const targetHalfDepth = targetDepth / HALF
+
+  const targetLeft = targetX - targetHalfWidth
+  const targetRight = targetX + targetHalfWidth
+  const targetBack = targetZ - targetHalfDepth
+  const targetFront = targetZ + targetHalfDepth
+
+  const minTileX = Math.floor((targetLeft - tilemapLeft) / tileWidth)
+  const maxTileX = Math.floor((targetRight - tilemapLeft) / tileWidth)
+  const minTileZ = Math.floor((targetBack - tilemapBack) / tileDepth)
+  const maxTileZ = Math.floor((targetFront - tilemapBack) / tileDepth)
+
+  for (let i = minTileX; i <= maxTileX; i++) {
+    for (let j = minTileZ; j <= maxTileZ; j++) {
+      if (
+        i < FIRST_TILE ||
+        i >= hitmask.columns ||
+        j < FIRST_TILE ||
+        j >= dRows
+      ) {
+        continue
+      }
+
+      const invertedRow = dRows - LAST_ROW - j
+      const tileIndex = invertedRow * hitmask.columns + i
+      const tileHeightValue = hitmask.heights[tileIndex]
+
+      if (tileHeightValue) {
+        const tileRectangle = {
+          position: [
+            tilemapLeft + i * tileWidth + halfTileWidth,
+            tilemapY,
+            tilemapBack + j * tileDepth + halfTileDepth,
+          ],
+          size: [tileWidth, tileHeightValue, tileDepth],
+        }
+
+        if (intersectsRectangle(target, tileRectangle)) {
+          return true
+        }
+      }
+    }
+  }
+
+  return false
+}

package/src/math/geometry/hitmask.test.js

@@ -0,0 +1,155 @@
+import { expect, test } from "vitest"
+
+import { findCollisions } from "./hitmask"
+
+/**
+ * Given a rectangle located at (x=1.5, y=0, z=2.5) with a size of (1, 1, 1),
+ * which is touching a wall tile, this test proves a collision is detected.
+ *
+ * Tilemap layout:
+ * ⬛️🟩🟩⬛️
+ * ⬛️⬛️⬛️⬛️
+ * ⬛️⬛️⬛️⬛️
+ *
+ * Rectangle position (X,Z): R at (1.5, 2.5)
+ *
+ * Expected outcome: true
+ */
+test("it should prove that a rectangle touching a wall intersects with it", () => {
+  const hitmask = {
+    position: [2, 0, 1.5],
+    tileSize: [1, 1],
+    columns: 4,
+    // The top row (indices 0, 1, 2, 3) now has the walls.
+    heights: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [1.5, 0, 2.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(true)
+})
+
+/**
+ * Given the same scenario as the previous test, but all coordinates
+ * are shifted by a constant value, this test proves the outcome remains
+ * unchanged, ensuring the collision detection is relative.
+ *
+ * Tilemap layout:
+ * ⬛️🟩🟩⬛️
+ * ⬛️⬛️⬛️⬛️
+ * ⬛️⬛️⬛️⬛️
+ *
+ * Rectangle position (X,Z): R at (11.5, 12.5)
+ *
+ * Expected outcome: true
+ */
+test("it should prove that shifting operands does not change the outcome", () => {
+  const SHIFT = 10
+  const hitmask = {
+    position: [2 + SHIFT, 0, 1.5 + SHIFT],
+    tileSize: [1, 1],
+    columns: 4,
+    // The top row (indices 0, 1, 2, 3) now has the walls.
+    heights: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [11.5, 0, 12.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(true)
+})
+
+/**
+ * Given a rectangle located at (x=0.5, y=0, z=0.5) with a size of (1, 1, 1),
+ * which is not touching any walls, this test proves no collision is detected.
+ *
+ * Tilemap layout:
+ * ⬛️🟩🟩⬛️
+ * ⬛️⬛️⬛️⬛️
+ * ⬛️⬛️⬛️⬛️
+ *
+ * Rectangle position (X,Z): R at (0.5, 0.5)
+ *
+ * Expected outcome: false
+ */
+test("it should prove that a rectangle not touching a wall does not intersect with it", () => {
+  const hitmask = {
+    position: [2, 0, 1.5],
+    tileSize: [1, 1],
+    columns: 4,
+    // The top row (indices 0, 1, 2, 3) now has the walls.
+    heights: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [0.5, 0, 0.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(false)
+})
+
+/**
+ * Given a rectangle located above the tile, this test proves no
+ * collision is detected even when the X and Z positions overlap.
+ *
+ * Tilemap layout:
+ * ⬛️🟩🟩⬛️
+ * ⬛️⬛️⬛️⬛️
+ * ⬛️⬛️⬛️⬛️
+ *
+ * Rectangle position: R at (x=1.5, y=1.6, z=2.5)
+ *
+ * Expected outcome: false
+ */
+test("it should prove that a rectangle above the tile of a hitmask does not intersect with it", () => {
+  const hitmask = {
+    position: [2, 0, 1.5],
+    tileSize: [1, 1],
+    columns: 4,
+    // The top row (indices 0, 1, 2, 3) now has the walls.
+    heights: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [1.5, 1.6, 2.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(false)
+})
+
+/**
+ * Given a rectangle located outside of the tilemap, this test proves
+ * no collision is detected.
+ *
+ * Tilemap layout:
+ * ⬛️🟩🟩⬛️
+ * ⬛️⬛️⬛️⬛️
+ * ⬛️⬛️⬛️⬛️
+ *
+ * Rectangle position: R at (x=5.5, y=0.5, z=1.5)
+ *
+ * Expected outcome: false
+ */
+test("it should prove that a rectangle outside of a hitmask does not intersect with it", () => {
+  const hitmask = {
+    position: [2, 0, 1.5],
+    tileSize: [1, 1],
+    columns: 4,
+    // The top row (indices 0, 1, 2, 3) now has the walls.
+    heights: [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+  }
+  const rectangle = {
+    shape: "rectangle",
+    position: [5.5, 0.5, 1.5],
+    size: [1, 1, 1],
+  }
+
+  expect(findCollisions(hitmask, rectangle)).toBe(false)
+})

package/src/math/geometry/line.js

@@ -0,0 +1,34 @@
+/**
+ * @typedef {import("./types").Line} Line
+ * @typedef {import("./types").Point} Point
+ * @typedef {import("./types").Circle} Circle
+ */
+
+import { abs } from "../numbers.js"
+import { hypothenuse } from "./triangle.js"
+
+/**
+ * Calculates the shortest distance from a point to a line in 2D space.
+ *
+ * @param {Line} line - The line represented by the equation ax + bz + c = 0, where `line` is [a, b, c].
+ * @param {Point} point - The point in 3D space represented as [x, y, z].
+ * @returns {number} The shortest distance from the point to the line.
+ */
+export function distanceFromPoint(line, point) {
+  const [a, b, c] = line
+  const [x, , z] = point
+
+  return abs(a * x + b * z + c) / hypothenuse(a, b)
+}
+
+// @see https://math.stackexchange.com/questions/275529/check-if-line-intersects-with-circles-perimeter
+/**
+ * Determines whether a line intersects with the perimeter of a circle.
+ *
+ * @param {Line} line - The line represented by the equation ax + bz + c = 0, where `line` is [a, b, c].
+ * @param {Circle} circle - The circle defined by its position (center) and radius.
+ * @returns {boolean} `true` if the line intersects the circle's perimeter, otherwise `false`.
+ */
+export function intersectsCircle(line, circle) {
+  return distanceFromPoint(line, circle.position) <= circle.radius
+}