@inglorious/utils 1.0.0 → 1.2.0

package/src/math/linear-algebra/vectors.js

@@ -0,0 +1,122 @@
+/**
+ * @typedef {import('./types').Vector2} Vector2
+ * @typedef {import('./types').Vector3} Vector3
+ * @typedef {import('./types').Vector7} Vector7
+ */
+
+import { magnitude, shift } from "./vector.js"
+
+/**
+ * Alias for the sum function.
+ * @type {typeof sum}
+ */
+export const add = sum
+
+/**
+ * Computes the cross product of multiple vectors.
+ * @param {...Vector3 | Vector7} vectors - The vectors to compute the cross product for.
+ * @returns {Vector3 | Vector7} The resulting vector after the cross product.
+ */
+export function cross(...vectors) {
+  return vectors.reduce(crossMultiplyCoordinates)
+}
+
+/**
+ * Computes the distance between multiple vectors.
+ * @param {...Vector2 | Vector3} vectors - The vectors to compute the distance between.
+ * @returns {number} The distance between the vectors.
+ */
+export function distance(...vectors) {
+  return magnitude(subtract(...vectors))
+}
+
+/**
+ * Computes the dot product of multiple vectors.
+ * @param {...Vector2 | Vector3} vectors - The vectors to compute the dot product for.
+ * @returns {number} The resulting scalar value of the dot product.
+ */
+export function dot(...vectors) {
+  return vectors
+    .reduce(dotMultiplyCoordinates)
+    .reduce((coord1, coord2) => coord1 + coord2)
+}
+
+/**
+ * Alias for the dot product function.
+ * @type {typeof dot}
+ */
+export const scalarProduct = dot
+
+/**
+ * Subtracts multiple vectors.
+ * @param {...Vector2 | Vector3} vectors - The vectors to subtract.
+ * @returns {Vector2 | Vector3} The resulting vector after subtraction.
+ */
+export function subtract(...vectors) {
+  return vectors.reduce(subtractCoordinates)
+}
+
+/**
+ * Sums multiple vectors.
+ * @param {...Vector2 | Vector3} vectors - The vectors to sum.
+ * @returns {Vector2 | Vector3} The resulting vector after summation.
+ */
+export function sum(...vectors) {
+  return vectors.reduce(sumCoordinates)
+}
+
+/**
+ * Alias for the cross product function.
+ * @type {typeof cross}
+ */
+export const vectorProduct = cross
+
+/**
+ * Adds the coordinates of two vectors.
+ * @param {Vector2 | Vector3} vector1 - The first vector.
+ * @param {Vector2 | Vector3} vector2 - The second vector.
+ * @returns {Vector2 | Vector3} The resulting vector after addition.
+ */
+function sumCoordinates(vector1, vector2) {
+  return vector1.map((coordinate, index) => coordinate + vector2[index])
+}
+
+/**
+ * Subtracts the coordinates of two vectors.
+ * @param {Vector2 | Vector3} vector1 - The first vector.
+ * @param {Vector2 | Vector3} vector2 - The second vector.
+ * @returns {Vector2 | Vector3} The resulting vector after subtraction.
+ */
+function subtractCoordinates(vector1, vector2) {
+  return vector1.map((coordinate, index) => coordinate - vector2[index])
+}
+
+/**
+ * Computes the cross product of two vectors' coordinates.
+ * @param {Vector3} vector1 - The first vector.
+ * @param {Vector3} vector2 - The second vector.
+ * @returns {Vector3} The resulting vector after the cross product.
+ */
+function crossMultiplyCoordinates(vector1, vector2) {
+  const indexes = Array(vector1.length)
+    .fill(null)
+    .map((_, index) => index)
+
+  return indexes.map((_, index) => {
+    const [index1, index2] = shift(
+      indexes.filter((_, i) => i !== index),
+      index,
+    )
+    return vector1[index1] * vector2[index2] - vector1[index2] * vector2[index1]
+  })
+}
+
+/**
+ * Multiplies the coordinates of two vectors.
+ * @param {Vector2 | Vector3} vector1 - The first vector.
+ * @param {Vector2 | Vector3} vector2 - The second vector.
+ * @returns {Vector2 | Vector3} The resulting vector containing multiplied coordinates.
+ */
+function dotMultiplyCoordinates(vector1, vector2) {
+  return vector1.map((coordinate, index) => coordinate * vector2[index])
+}

package/src/math/linear-algebra/vectors.test.js

@@ -0,0 +1,65 @@
+import { expect, test } from "vitest"
+
+import { cross, distance, dot, subtract, sum } from "./vectors.js"
+
+test("it should compute the cross product between two vectors (aka vectorProduct)", () => {
+  const vector1 = [1, 2, 3]
+  const vector2 = [4, 5, 6]
+  const expectedResult = [-3, 6, -3]
+
+  expect(cross(vector1, vector2)).toStrictEqual(expectedResult)
+})
+
+test("it should compute the cross product of multiple vectors (aka vectorProduct)", () => {
+  const vectors = [
+    [1, 2, 3],
+    [4, 5, 6],
+    [7, 8, 9],
+  ]
+  const expectedResult = [78, 6, -66]
+
+  expect(cross(...vectors)).toStrictEqual(expectedResult)
+})
+
+test("it should compute the distance between multiple vectors", () => {
+  const vectors = [
+    [0, 0, 0],
+    [4, 0, 3],
+  ]
+  const expectedResult = 5
+
+  expect(distance(...vectors)).toStrictEqual(expectedResult)
+})
+
+test("it should compute the dot product of multiple vectors (aka scalarProduct)", () => {
+  const vectors = [
+    [1, 2, 3],
+    [4, 5, 6],
+    [7, 8, 9],
+  ]
+  const expectedResult = 270
+
+  expect(dot(...vectors)).toStrictEqual(expectedResult)
+})
+
+test("it should subtract multiple vectors", () => {
+  const vectors = [
+    [1, 2, 3],
+    [4, 5, 6],
+    [7, 8, 9],
+  ]
+  const expectedResult = [-10, -11, -12]
+
+  expect(subtract(...vectors)).toStrictEqual(expectedResult)
+})
+
+test("it should sum multiple vectors (aka add)", () => {
+  const vectors = [
+    [1, 2, 3],
+    [4, 5, 6],
+    [7, 8, 9],
+  ]
+  const expectedResult = [12, 15, 18]
+
+  expect(sum(...vectors)).toStrictEqual(expectedResult)
+})

package/src/math/linear-interpolation.js

@@ -0,0 +1,9 @@
+/**
+ * Performs linear interpolation between two numbers.
+ *
+ * @param {number} a - The start value.
+ * @param {number} b - The end value.
+ * @param {number} t - The interpolation factor, typically in the range [0, 1].
+ * @returns {number} The interpolated value.
+ */
+export const lerp = (a, b, t) => a + (b - a) * t

package/src/math/numbers.js

@@ -0,0 +1,90 @@
+const DEFAULT_PRECISION = 1 // Default precision used for snapping numbers.
+const DEFAULT_TOLERANCE = 0.1 // Default tolerance used for comparing numbers.
+const SQUARE_ROOT = 0.5 // Exponent used for calculating square roots.
+
+/**
+ * Returns the absolute value of a number.
+ * @param {number} num - The number to get the absolute value of.
+ * @returns {number} The absolute value of the input number.
+ */
+export function abs(num) {
+  return Math.abs(num)
+}
+
+/**
+ * Clamps a number within the inclusive range specified by min and max.
+ * @param {number} num - The number to clamp.
+ * @param {number} min - The minimum value.
+ * @param {number} max - The maximum value.
+ * @returns {number} The clamped value.
+ */
+export function clamp(num, min, max) {
+  if (num < min) {
+    return min
+  }
+
+  if (num > max) {
+    return max
+  }
+
+  return num
+}
+
+/**
+ * Checks if two numbers are close to each other within a given tolerance.
+ * @param {number} num1 - The first number.
+ * @param {number} num2 - The second number.
+ * @param {number} [tolerance=DEFAULT_TOLERANCE] - The tolerance for comparison.
+ * @returns {boolean} True if the numbers are close, false otherwise.
+ */
+export function isClose(num1, num2, tolerance = DEFAULT_TOLERANCE) {
+  return abs(num1 - num2) <= tolerance
+}
+
+/**
+ * Computes the modulus of two numbers, ensuring a positive result.
+ * @param {number} dividend - The number to be divided.
+ * @param {number} divisor - The number to divide by.
+ * @returns {number} The modulus result.
+ */
+export function mod(dividend, divisor) {
+  return ((dividend % divisor) + divisor) % divisor
+}
+
+/**
+ * Snaps a number to the nearest multiple of a given precision.
+ * @param {number} num - The number to snap.
+ * @param {number} [precision=DEFAULT_PRECISION] - The precision to snap to.
+ * @returns {number} The snapped value.
+ */
+export function snap(num, precision = DEFAULT_PRECISION) {
+  return Math.round(num / precision) * precision
+}
+
+/**
+ * Alias for the `mod` function.
+ * @type {typeof mod}
+ */
+export const remainder = mod
+
+/**
+ * Returns the sign of a number: 1 for positive, -1 for negative, and 0 for zero.
+ * @param {number} num - The number to get the sign of.
+ * @returns {number} The sign of the number.
+ */
+export function sign(num) {
+  if (!num) {
+    return num
+  }
+
+  return num / abs(num)
+}
+
+/**
+ * Computes the square root of a number.
+ * @param {number} num - The number to compute the square root of.
+ * @returns {number} The square root of the number.
+ */
+export function sqrt(num) {
+  return num ** SQUARE_ROOT
+}

package/src/math/numbers.test.js

@@ -0,0 +1,137 @@
+import { expect, test } from "vitest"
+
+import { abs, clamp, isClose, mod, sign, snap, sqrt } from "./numbers.js"
+
+test("it should return the same number if already positive", () => {
+  const num = 42
+  const expectedResult = 42
+
+  expect(abs(num)).toBe(expectedResult)
+})
+
+test("it should return the absolute value of a number", () => {
+  const num = -42
+  const expectedResult = 42
+
+  expect(abs(num)).toBe(expectedResult)
+})
+
+test("it should not clamp a number in the range", () => {
+  const num = 42
+  const min = 0
+  const max = 100
+  const expectedResult = 42
+
+  expect(clamp(num, min, max)).toBe(expectedResult)
+})
+
+test("it should clamp a number too small", () => {
+  const num = -42
+  const min = 0
+  const max = 100
+  const expectedResult = 0
+
+  expect(clamp(num, min, max)).toBe(expectedResult)
+})
+
+test("it should clamp a number too big", () => {
+  const num = 142
+  const min = 0
+  const max = 100
+  const expectedResult = 100
+
+  expect(clamp(num, min, max)).toBe(expectedResult)
+})
+
+test("it should check if two numbers are close given some tolerance", () => {
+  const num1 = 42
+  const num2 = 42.1
+  const tolerance = 0.2
+  const expectedResult = true
+
+  expect(isClose(num1, num2, tolerance)).toBe(expectedResult)
+})
+
+test("it should return zero if dividend equals divisor", () => {
+  const num = 2
+  const divisor = 2
+  const expectedResult = 0
+
+  expect(mod(num, divisor)).toBe(expectedResult)
+})
+
+test("it should return one if number is odd", () => {
+  const num = 3
+  const divisor = 2
+  const expectedResult = 1
+
+  expect(mod(num, divisor)).toBe(expectedResult)
+})
+
+test("it should return one if negative number turns to positive one", () => {
+  const num = -3
+  const divisor = 2
+  const expectedResult = 1
+
+  expect(mod(num, divisor)).toBe(expectedResult)
+})
+
+test("it should convert a float number greater than 1 to a range between -1 and 1", () => {
+  const num = 5 / 4
+  const divisor = 1
+  const expectedResult = 1 / 4
+
+  expect(mod(num, divisor)).toBe(expectedResult)
+})
+
+test("it should convert a float number greater than 2 to a range between -1 and 1", () => {
+  const num = 13 / 4
+  const divisor = 1
+  const expectedResult = 1 / 4
+
+  expect(mod(num, divisor)).toBe(expectedResult)
+})
+
+test("it should convert a negative float number to a range between -1 and 1", () => {
+  const num = -5 / 4
+  const divisor = 1
+  const expectedResult = 3 / 4
+
+  expect(mod(num, divisor)).toBe(expectedResult)
+})
+
+test("it should return one if number is positive", () => {
+  const num = 42
+  const expectedResult = 1
+
+  expect(sign(num)).toBe(expectedResult)
+})
+
+test("it should return minus one if number is negative", () => {
+  const num = -42
+  const expectedResult = -1
+
+  expect(sign(num)).toBe(expectedResult)
+})
+
+test("it should return the number itself if the sign is zero", () => {
+  const num = 0
+  const expectedResult = 0
+
+  expect(sign(num)).toBe(expectedResult)
+})
+
+test("it should snap the number to the given precision", () => {
+  const num = 42
+  const precision = 10
+  const expectedResult = 40
+
+  expect(snap(num, precision)).toBe(expectedResult)
+})
+
+test("it should compute the square root of the number", () => {
+  const num = 9
+  const expectedResult = 3
+
+  expect(sqrt(num)).toBe(expectedResult)
+})

package/src/math/rng.js

@@ -0,0 +1,44 @@
+/* eslint-disable no-magic-numbers */
+
+/**
+ * Generates a random number.
+ * - If no arguments are provided, returns a random float between 0 (inclusive) and 1 (exclusive).
+ * - If one argument is provided, returns a random integer between 0 and the given number (inclusive).
+ * - If two or more arguments are provided, returns a random integer within the specified range and step.
+ *
+ * @param {number} [to] - The upper bound (inclusive) if one argument is provided.
+ * @param {number} [from] - The lower bound (inclusive) if two arguments are provided.
+ * @param {number} [step=1] - The step size if two or more arguments are provided.
+ * @returns {number} A random number based on the provided arguments.
+ */
+export function random(...args) {
+  let step, from, to
+
+  if (!args.length) {
+    return Math.random()
+  }
+
+  if (args.length === 1) {
+    step = 1
+    from = 0
+    to = args[0] + 1
+  }
+
+  if (args.length > 1) {
+    step = args[2] ?? 1
+    from = args[0] / step
+    to = (args[1] + 1) / step
+  }
+
+  return Math.floor(Math.random() * (to - from) + from) * step
+}
+
+/**
+ * Generates a random binomial value.
+ * The result is the difference between two random numbers.
+ *
+ * @returns {number} A random binomial value.
+ */
+export function randomBinomial() {
+  return random() - random()
+}

package/src/math/rng.test.js

@@ -0,0 +1,39 @@
+import { expect, test } from "vitest"
+
+import { random, randomBinomial } from "./rng.js"
+
+test("it should create a random number in the range [0, 1)", () => {
+  const randomNumber = random()
+
+  expect(randomNumber).toBeGreaterThanOrEqual(0)
+  expect(randomNumber).toBeLessThan(1)
+})
+
+test("it should create a random integer in the range [0, 6]", () => {
+  const randomNumber = random(6)
+
+  expect(randomNumber).toBeGreaterThanOrEqual(0)
+  expect(randomNumber).toBeLessThanOrEqual(6)
+})
+
+test("it should create a random integer in the range [1, 6]", () => {
+  const randomNumber = random(1, 6)
+
+  expect(randomNumber).toBeGreaterThanOrEqual(1)
+  expect(randomNumber).toBeLessThanOrEqual(6)
+})
+
+test("it should create a random even number in the range [2, 6]", () => {
+  const randomNumber = random(2, 6, 2)
+
+  expect(randomNumber).toBeGreaterThanOrEqual(1)
+  expect(randomNumber).toBeLessThanOrEqual(6)
+  expect(randomNumber % 2).toBe(0)
+})
+
+test("it should create a random number in the range (-1, 1)", () => {
+  const randomNumber = randomBinomial()
+
+  expect(randomNumber).toBeGreaterThan(-1)
+  expect(randomNumber).toBeLessThan(1)
+})

package/src/math/statistics.js

@@ -0,0 +1,43 @@
+const HALF = 2
+const AROUND_INDEX = 1
+const NO_OCCURRENCES = 0
+
+export const average = mean
+
+export function mean(...numbers) {
+  return numbers.reduce((acc, num) => acc + num) / numbers.length
+}
+
+export function median(...numbers) {
+  const sortedNumbers = numbers.toSorted()
+  const middleIndex = numbers.length / HALF
+
+  if (Number.isInteger(middleIndex)) {
+    return mean(
+      ...sortedNumbers.slice(
+        middleIndex - AROUND_INDEX,
+        middleIndex + AROUND_INDEX,
+      ),
+    )
+  }
+
+  return sortedNumbers[Math.floor(middleIndex)]
+}
+
+export function mode(...values) {
+  const occurrences = values.reduce((acc, value) => {
+    acc[value] = acc[value] ?? NO_OCCURRENCES
+    acc[value]++
+    return acc
+  }, {})
+
+  return Object.entries(occurrences).reduce(
+    (acc, [value, occurrences]) => {
+      if (occurrences > acc.occurrences) {
+        acc = { value, occurrences }
+      }
+      return acc
+    },
+    { occurrences: 0 },
+  ).value
+}

package/src/math/statistics.test.js

@@ -0,0 +1,47 @@
+import { expect, test } from "vitest"
+
+import { mean, median, mode } from "./statistics.js"
+
+test("it should return the average of the given numbers", () => {
+  const numbers = [1, 3, 2]
+  const expectedResult = 2
+
+  expect(mean(...numbers)).toBeCloseTo(expectedResult)
+})
+
+test("it should return the median value from an odd list of numbers", () => {
+  const numbers = [1, 3, 2]
+  const expectedResult = 2
+
+  expect(median(...numbers)).toBe(expectedResult)
+})
+
+test("it should return the median value from an even list of numbers", () => {
+  const numbers = [1, 3, 2, 4]
+  const expectedResult = 2.5
+
+  expect(median(...numbers)).toBe(expectedResult)
+})
+
+test("it should find the mode of a list of values", () => {
+  const values = [
+    "rarely",
+    "seldom",
+    "seldom",
+    "sometimes",
+    "sometimes",
+    "sometimes",
+    "often",
+    "often",
+    "often",
+    "often",
+    "always",
+    "always",
+    "always",
+    "always",
+    "always",
+  ]
+  const expectedResult = "always"
+
+  expect(mode(...values)).toBe(expectedResult)
+})

package/src/math/trigonometry.js

@@ -0,0 +1,89 @@
+import { mod } from "./numbers.js"
+
+const HALF_CIRCLE_IN_DEGRESS = 180 // Half-circle in degrees (180°)
+const FULL_CIRCLE = 2 // Full circle multiplier for radians (2π)
+
+/**
+ * Calculates the arctangent of the quotient of its arguments.
+ * @param {number} y - The y-coordinate.
+ * @param {number} x - The x-coordinate.
+ * @returns {number} The angle in radians.
+ */
+export function atan2(y, x) {
+  return Math.atan2(y, x)
+}
+
+/**
+ * Calculates the cosine of an angle.
+ * @param {number} angle - The angle in radians.
+ * @returns {number} The cosine of the angle.
+ */
+export function cos(angle) {
+  return Math.cos(angle)
+}
+
+/**
+ * Alias for the `cos` function.
+ * @type {typeof cos}.
+ */
+export const cosine = cos
+
+/**
+ * Returns the value of π (pi).
+ * @returns {number} The value of π.
+ */
+export function pi() {
+  return Math.PI
+}
+
+/**
+ * Calculates the sine of an angle.
+ * @param {number} angle - The angle in radians.
+ * @returns {number} The sine of the angle.
+ */
+export function sin(angle) {
+  return Math.sin(angle)
+}
+
+/**
+ * Alias for the `sin` function.
+ * @type {typeof sin}.
+ */
+export const sine = sin
+
+/**
+ * Converts an angle from radians to degrees.
+ * @param {number} radians - The angle in radians.
+ * @returns {number} The angle in degrees.
+ */
+export function toDegrees(radians) {
+  return (radians * HALF_CIRCLE_IN_DEGRESS) / pi()
+}
+
+/**
+ * Converts an angle from degrees to radians.
+ * @param {number} degrees - The angle in degrees.
+ * @returns {number} The angle in radians.
+ */
+export function toRadians(degrees) {
+  return (degrees * pi()) / HALF_CIRCLE_IN_DEGRESS
+}
+
+/**
+ * Normalizes an angle to the range [-π, π].
+ * @param {number} angle - The angle in radians.
+ * @returns {number} The normalized angle in radians.
+ */
+export function toRange(angle) {
+  if (angle > -pi() && angle < pi()) {
+    return angle
+  }
+
+  angle = mod(angle, FULL_CIRCLE * pi())
+
+  if (angle > pi()) {
+    angle -= FULL_CIRCLE * pi()
+  }
+
+  return angle
+}