@inglorious/utils 2.3.0 → 3.1.0

package/src/math/{linear-algebra/vector.test.js → vector.test.js}

@@ -1,7 +1,8 @@
 import { expect, test } from "vitest"
 
-import { sqrt } from "../numbers.js"
-import { cos, pi, sin } from "../trigonometry.js"
+import { v } from "../v.js"
+import { sqrt } from "./numbers.js"
+import { cos, pi, sin } from "./trigonometry.js"
 import {
   abs,
   angle,
@@ -16,6 +17,7 @@ import {
   mod,
   multiply,
   normalize,
+  power,
   rotate,
   setAngle,
   setMagnitude,
@@ -28,61 +30,60 @@ import {
   toSpherical,
   toString,
   unit,
-  v,
   zero,
 } from "./vector.js"
 
 test("it should compute the absolute value of a vector's coordinates", () => {
-  const vector = [-2, 0, 3]
-  const expectedResult = [2, 0, 3]
+  const vector = v(-2, 0, 3)
+  const expectedResult = v(2, 0, 3)
 
   expect(abs(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should compute the angle of a 2D vector", () => {
-  const vector = [1, 1]
+  const vector = v(1, 1)
   const expectedResult = pi() / 4
 
   expect(angle(vector)).toBe(expectedResult)
 })
 
 test("it should compute the angle of a 3D vector", () => {
-  const vector = [1, 0, 1]
+  const vector = v(1, 0, 1)
   const expectedResult = pi() / 4
 
   expect(angle(vector)).toBe(expectedResult)
 })
 
 test("it should clamp the magnitude of a vector to a certain length if too long", () => {
-  const vector = [6, 8]
+  const vector = v(6, 8)
   const min = 0
   const max = 5
-  const expectedResult = [3, 4]
+  const expectedResult = v(3, 4)
 
   expect(clamp(vector, min, max)).toStrictEqual(expectedResult)
 })
 
 test("it should not clamp the magnitude of a vector to a certain length if not too long", () => {
-  const vector = [3, 4]
+  const vector = v(3, 4)
   const min = 0
   const max = 6
-  const expectedResult = [3, 4]
+  const expectedResult = v(3, 4)
 
   expect(clamp(vector, min, max)).toStrictEqual(expectedResult)
 })
 
 test("it should clamp the magnitude of a vector to the values of other vector bounds", () => {
-  const vector = [6, 8]
+  const vector = v(6, 8)
   const lowerBound = [0, 0]
   const upperBound = [3, 4]
-  const expectedResult = [3, 4]
+  const expectedResult = v(3, 4)
 
   expect(clamp(vector, lowerBound, upperBound)).toStrictEqual(expectedResult)
 })
 
 test("it should conjugate a vector", () => {
-  const vector = [1, 2, 3]
-  const expectedResult = [1, -2, -3]
+  const vector = v(1, 2, 3)
+  const expectedResult = v(1, -2, -3)
 
   expect(conjugate(vector)).toStrictEqual(expectedResult)
 })
@@ -90,35 +91,35 @@ test("it should conjugate a vector", () => {
 test("it should create a 3D vector given its magnitude and angle", () => {
   const magnitude = sqrt(2)
   const angle = pi() / 4
-  const expectedResult = [1, -0, 1.0000000000000002] // close to [1, 0, 1]
+  const expectedResult = v(1, -0, 1.0000000000000002) // close to v(1, 0, 1)
 
   expect(createVector(magnitude, angle)).toStrictEqual(expectedResult)
 })
 
 test("it should divide a vector by a scalar", () => {
-  const vector = [4, 8, 12]
+  const vector = v(4, 8, 12)
   const scalar = 4
-  const expectedResult = [1, 2, 3]
+  const expectedResult = v(1, 2, 3)
 
   expect(divide(vector, scalar)).toStrictEqual(expectedResult)
 })
 
 test("it should build a 3D vector from a 2D one", () => {
-  const vector = [3, 4]
-  const expectedResult = [3, 0, 4]
+  const vector = v(3, 4)
+  const expectedResult = v(3, 0, 4)
 
   expect(from2D(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should create a 3D unit vector from an angle", () => {
   const angle = pi() / 4
-  const expectedResult = [0.7071067811865475, -0, 0.7071067811865476] // close to [cos(angle), 0, sin(angle)]
+  const expectedResult = v(0.7071067811865475, -0, 0.7071067811865476) // close to [cos(angle), 0, sin(angle)]
 
   expect(fromAngle(angle)).toStrictEqual(expectedResult)
 })
 
 test("it should compute the magnitude of a vector (aka length)", () => {
-  const vector = [3, 4]
+  const vector = v(3, 4)
   const expectedResult = 5
 
   expect(magnitude(vector)).toBe(expectedResult)
@@ -127,6 +128,7 @@ test("it should compute the magnitude of a vector (aka length)", () => {
 test("it should check if a value is a vector", () => {
   expect(isVector([1, 2, 3])).toBe(true)
   expect(isVector([])).toBe(true)
+  expect(isVector(v(1, 2, 3))).toBe(true)
 })
 
 test("it should check if a value is not a vector", () => {
@@ -138,150 +140,158 @@ test("it should check if a value is not a vector", () => {
 })
 
 test("it should apply the mod operator (aka remainder) on a vector", () => {
-  const vector = [10, 12, -18]
+  const vector = v(10, 12, -18)
   const divisor = 12
-  const expectedResult = [10, 0, 6]
+  const expectedResult = v(10, 0, 6)
 
   expect(mod(vector, divisor)).toStrictEqual(expectedResult)
 })
 
 test("it should multiply a vector with a scalar (aka times)", () => {
-  const vector = [1, 2, 3]
+  const vector = v(1, 2, 3)
   const scalar = 4
-  const expectedResult = [4, 8, 12]
+  const expectedResult = v(4, 8, 12)
 
   expect(multiply(vector, scalar)).toStrictEqual(expectedResult)
 })
 
 test("it should normalize a vector so it has unit length", () => {
-  const vector = [3, 4]
-  const expectedResult = [0.6, 0.8]
+  const vector = v(3, 4)
+  const expectedResult = v(0.6, 0.8)
 
   expect(normalize(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should normalize a negative vector", () => {
-  const vector = [-3, -4]
-  const expectedResult = [-0.6, -0.8]
+  const vector = v(-3, -4)
+  const expectedResult = v(-0.6, -0.8)
 
   expect(normalize(vector)).toStrictEqual(expectedResult)
 })
 
+test("it should raise each component of a vector to the given exponent (aka pow)", () => {
+  const vector = v(1, 2, 3)
+  const exponent = 2
+  const expectedResult = v(1, 4, 9)
+
+  expect(power(vector, exponent)).toStrictEqual(expectedResult)
+})
+
 test("it should rotate a 2D vector by a certain angle", () => {
-  const vector = [1, 0]
+  const vector = v(1, 0)
   const angle = pi() / 4
-  const expectedResult = [0.7071067811865475, 0.7071067811865476] // close to [cos(pi/4), sin(pi/4)]
+  const expectedResult = v(0.7071067811865475, 0.7071067811865476) // close to [cos(pi/4), sin(pi/4)]
 
   expect(rotate(vector, angle)).toStrictEqual(expectedResult)
 })
 
 test("it should not rotate a vector when the angle is zero", () => {
-  const vector = [1, 0, 0]
+  const vector = v(1, 0, 0)
   const angle = 0
-  const expectedResult = [1, 0, 0]
+  const expectedResult = v(1, 0, 0)
 
   expect(rotate(vector, angle)).toStrictEqual(expectedResult)
 })
 
 test("it should rotate a vector by a certain angle", () => {
-  const vector = [1, 0, 0]
+  const vector = v(1, 0, 0)
   const angle = pi() / 4
-  const expectedResult = [0.7071067811865475, -0, 0.7071067811865476] // close to [cos(pi/4), 0, sin(pi/4)]
+  const expectedResult = v(0.7071067811865475, -0, 0.7071067811865476) // close to [cos(pi/4), 0, sin(pi/4)]
 
   expect(rotate(vector, angle)).toStrictEqual(expectedResult)
 })
 
 test("it should rotate a vector that faces left by a certain angle", () => {
-  const vector = [-1, 0, 0]
+  const vector = v(-1, 0, 0)
   const angle = pi() / 4
-  const expectedResult = [-0.7071067811865475, -0, -0.7071067811865476] // close to [cos(-3/4pi), 0, sin(-3/4pi)]
+  const expectedResult = v(-0.7071067811865475, -0, -0.7071067811865476) // close to [cos(-3/4pi), 0, sin(-3/4pi)]
 
   expect(rotate(vector, angle)).toStrictEqual(expectedResult)
 })
 
 test("it should change the angle of a vector", () => {
-  const vector = [cos(pi() / 4), 0, sin(pi() / 4)]
-  const expectedResult = [6.123233995736766e-17, 0, 1] // close to [0, 0, 1]
+  const vector = v(cos(pi() / 4), 0, sin(pi() / 4))
+  const expectedResult = v(6.123233995736766e-17, 0, 1) // close to v(0, 0, 1)
 
   expect(setAngle(vector, 1.5707963267948966)).toStrictEqual(expectedResult)
 })
 
 test("it should change magnitude of a vector (aka setLength)", () => {
-  const vector = [3, 4]
+  const vector = v(3, 4)
   const magnitude = 10
-  const expectedResult = [6, 8]
+  const expectedResult = v(6, 8)
 
   expect(setMagnitude(vector, magnitude)).toStrictEqual(expectedResult)
 })
 
 test("it should change magnitude of a negative vector", () => {
-  const vector = [-3, -4]
+  const vector = v(-3, -4)
   const magnitude = 10
-  const expectedResult = [-6, -8]
+  const expectedResult = v(-6, -8)
 
   expect(setMagnitude(vector, magnitude)).toStrictEqual(expectedResult)
 })
 
 test("it should shift a vector at a certain index", () => {
-  const vector = [1, 2, 3, 4, 5]
+  const vector = v(1, 2, 3, 4, 5)
   const index = 2
-  const expectedResult = [3, 4, 5, 1, 2]
+  const expectedResult = v(3, 4, 5, 1, 2)
 
   expect(shift(vector, index)).toStrictEqual(expectedResult)
 })
 
 test("it should snap a floating vector to a certain precision", () => {
-  const vector = [1, 1.5, 1.7]
+  const vector = v(1, 1.5, 1.7)
   const precision = 1
-  const expectedResult = [1, 1, 2]
+  const expectedResult = v(1, 1, 2)
 
   expect(snap(vector, precision)).toStrictEqual(expectedResult)
 })
 
 test("it should build a 2D vector from a 3D one", () => {
-  const vector = [3, 0, 4]
-  const expectedResult = [3, 4]
+  const vector = v(3, 0, 4)
+  const expectedResult = v(3, 4)
 
   expect(to2D(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should convert a 2D polar vector to cartesian coordinates", () => {
-  const vector = [sqrt(2), pi() / 4]
-  const expectedResult = [1.0000000000000002, 1]
+  const vector = v(sqrt(2), pi() / 4)
+  const expectedResult = v(1.0000000000000002, 1)
 
   expect(toCartesian(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should convert a 3D cartesian vector to cylindrical coordinates", () => {
-  const vector = [1, 1, 1]
-  const expectedResult = [1.2247448713915892, 1.224744871391589, 1]
+  const vector = v(1, 1, 1)
+  const expectedResult = v(1.2247448713915892, 1.224744871391589, 1)
 
   expect(toCylindrical(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should convert a 2D cartesian vector to polar coordinates", () => {
-  const vector = [1, 1]
-  const expectedResult = [sqrt(2), pi() / 4]
+  const vector = v(1, 1)
+  const expectedResult = v(sqrt(2), pi() / 4)
 
   expect(toPolar(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should convert a 3D cartesian vector to spherical coordinates", () => {
-  const vector = [1, 1, 1]
-  const expectedResult = [sqrt(3), Math.acos(1 / sqrt(3)), pi() / 4]
+  const vector = v(1, 1, 1)
+  const expectedResult = v(sqrt(3), Math.acos(1 / sqrt(3)), pi() / 4)
 
   expect(toSpherical(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should create a string representation of an integer vector", () => {
-  const vector = [3, 4]
+  const vector = v(3, 4)
   const expectedResult = "[3, 4]"
 
   expect(toString(vector)).toBe(expectedResult)
 })
 
 test("it should create a string representation of a float vector", () => {
-  const vector = [pi() / 4, pi() / 4]
+  const vector = v(pi() / 4, pi() / 4)
   const decimals = 2
   const expectedResult = "[0.79, 0.79]"
 
@@ -289,11 +299,11 @@ test("it should create a string representation of a float vector", () => {
 })
 
 test("it should create a unit vector oriented on the X-axis", () => {
-  expect(unit()).toStrictEqual([1, 0, 0])
+  expect(unit()).toStrictEqual(v(1, 0, 0))
 })
 
 test("it should create a unit vector oriented on the Z-axis", () => {
-  expect(unit(pi() / 2)).toStrictEqual([6.123233995736766e-17, 0, 1]) // close to [0, 0, 1]
+  expect(unit(pi() / 2)).toStrictEqual(v(6.123233995736766e-17, 0, 1)) // close to v(0, 0, 1)
 })
 
 test("it should create a vector from a list of coordinates", () => {
@@ -303,7 +313,7 @@ test("it should create a vector from a list of coordinates", () => {
 })
 
 test("it should create a 3D zero vector", () => {
-  const expectedResult = [0, 0, 0]
+  const expectedResult = v(0, 0, 0)
 
   expect(zero()).toStrictEqual(expectedResult)
 })

package/src/math/{linear-algebra/vectors.js → vectors.js}

@@ -4,6 +4,7 @@
  * @typedef {import('./types').Vector7} Vector7
  */
 
+import { v } from "../v.js"
 import { magnitude, shift } from "./vector.js"
 
 /**
@@ -18,7 +19,7 @@ export const add = sum
  * @returns {Vector3 | Vector7} The resulting vector after the cross product.
  */
 export function cross(...vectors) {
-  return vectors.reduce(crossMultiplyCoordinates)
+  return v(...vectors.reduce(crossMultiplyCoordinates))
 }
 
 /**
@@ -53,7 +54,7 @@ export const scalarProduct = dot
  * @returns {Vector2 | Vector3} The resulting vector after subtraction.
  */
 export function subtract(...vectors) {
-  return vectors.reduce(subtractCoordinates)
+  return v(...vectors.reduce(subtractCoordinates))
 }
 
 /**
@@ -62,7 +63,7 @@ export function subtract(...vectors) {
  * @returns {Vector2 | Vector3} The resulting vector after summation.
  */
 export function sum(...vectors) {
-  return vectors.reduce(sumCoordinates)
+  return v(...vectors.reduce(sumCoordinates))
 }
 
 /**
@@ -78,7 +79,7 @@ export const vectorProduct = cross
  * @returns {Vector2 | Vector3} The resulting vector after addition.
  */
 function sumCoordinates(vector1, vector2) {
-  return vector1.map((coordinate, index) => coordinate + vector2[index])
+  return v(...vector1.map((coordinate, index) => coordinate + vector2[index]))
 }
 
 /**
@@ -88,7 +89,7 @@ function sumCoordinates(vector1, vector2) {
  * @returns {Vector2 | Vector3} The resulting vector after subtraction.
  */
 function subtractCoordinates(vector1, vector2) {
-  return vector1.map((coordinate, index) => coordinate - vector2[index])
+  return v(...vector1.map((coordinate, index) => coordinate - vector2[index]))
 }
 
 /**
@@ -102,13 +103,17 @@ function crossMultiplyCoordinates(vector1, vector2) {
     .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]
-  })
+  return v(
+    ...indexes.map((_, index) => {
+      const [index1, index2] = shift(
+        indexes.filter((_, i) => i !== index),
+        index,
+      )
+      return (
+        vector1[index1] * vector2[index2] - vector1[index2] * vector2[index1]
+      )
+    }),
+  )
 }
 
 /**
@@ -118,5 +123,5 @@ function crossMultiplyCoordinates(vector1, vector2) {
  * @returns {Vector2 | Vector3} The resulting vector containing multiplied coordinates.
  */
 function dotMultiplyCoordinates(vector1, vector2) {
-  return vector1.map((coordinate, index) => coordinate * vector2[index])
+  return v(...vector1.map((coordinate, index) => coordinate * vector2[index]))
 }

package/src/math/{linear-algebra/vectors.test.js → vectors.test.js}

@@ -1,65 +1,47 @@
 import { expect, test } from "vitest"
 
+import { v } from "../v.js"
 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]
+  const vector1 = v(1, 2, 3)
+  const vector2 = v(4, 5, 6)
+  const expectedResult = v(-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]
+  const vectors = [v(1, 2, 3), v(4, 5, 6), v(7, 8, 9)]
+  const expectedResult = v(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 vectors = [v(0, 0, 0), v(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 vectors = [v(1, 2, 3), v(4, 5, 6), v(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]
+  const vectors = [v(1, 2, 3), v(4, 5, 6), v(7, 8, 9)]
+  const expectedResult = v(-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]
+  const vectors = [v(1, 2, 3), v(4, 5, 6), v(7, 8, 9)]
+  const expectedResult = v(12, 15, 18)
 
   expect(sum(...vectors)).toStrictEqual(expectedResult)
 })

package/src/physics/acceleration.js

@@ -1,9 +1,9 @@
 /**
- * @typedef {import('../math/linear-algebra/types').Vector3} Vector3
+ * @typedef {import('../math/types.js').Vector3} Vector3
  */
 
-import { clamp, multiply, zero } from "../math/linear-algebra/vector.js"
-import { sum } from "../math/linear-algebra/vectors.js"
+import { clamp, multiply, zero } from "../math/vector.js"
+import { sum } from "../math/vectors.js"
 import { applyFriction } from "./friction.js"
 
 const DEFAULT_DT = 1 // Default time delta for the applyAcceleration function.
@@ -14,8 +14,8 @@ const HALF_ACCELERATION = 0.5 // Half of the acceleration factor used in positio
  * Applies acceleration to an object using Euler's integration method.
  *
  * Euler's Integration:
- * v += a * dt
- * p += v * dt + 1/2 * a * dt * dt
+ * 1. v += a * dt
+ * 2. p += v * dt + 1/2 * a * dt * dt
  *
  * @param {Object} params - The parameters for the function.
  * @param {number} params.maxAcceleration - The maximum allowed acceleration.

package/src/physics/friction.js

@@ -1,15 +1,14 @@
 /**
- * @typedef {import('../math/linear-algebra/types').Vector3} Vector3
+ * @typedef {import('../math/types.js').Vector3} Vector3
  */
 
-import { magnitude, setMagnitude, zero } from "../math/linear-algebra/vector.js"
+import { magnitude, setMagnitude, zero } from "../math/vector.js"
 
 const DEFAULT_DT = 1 // Default time delta for the applyFriction function.
 const NO_FRICTION = 0 // No friction constant.
 
 /**
  * Applies friction to a given velocity vector.
- *
  * @param {Object} params - The parameters for the function.
  * @param {Vector3} params.velocity - The velocity vector. Defaults to a zero vector.
  * @param {number} params.friction - The friction coefficient. Defaults to 0.

package/src/physics/friction.test.js

@@ -1,18 +1,19 @@
 import { expect, test } from "vitest"
 
-import { zero } from "../math/linear-algebra/vector.js"
+import { zero } from "../math/vector.js"
+import { v } from "../v.js"
 import { applyFriction } from "./friction.js"
 
 test("it should apply friction to some velocity", () => {
-  const velocity = [8, 0, 6]
+  const velocity = v(8, 0, 6)
   const friction = 5
-  const expectedResult = [4, 0, 3]
+  const expectedResult = v(4, 0, 3)
 
   expect(applyFriction({ velocity, friction })).toStrictEqual(expectedResult)
 })
 
 test("it should stop movement when friction is equal to velocity", () => {
-  const velocity = [8, 0, 6]
+  const velocity = v(8, 0, 6)
   const friction = 5
   const dt = 2
 
@@ -27,14 +28,14 @@ test("it should apply no friction on no velocity", () => {
 })
 
 test("it should apply no friction if no friction is passed", () => {
-  const velocity = [8, 0, 6]
+  const velocity = v(8, 0, 6)
   const friction = 0
 
   expect(applyFriction({ velocity, friction })).toStrictEqual(velocity)
 })
 
 test("it should apply no friction if no time passed", () => {
-  const velocity = [8, 0, 6]
+  const velocity = v(8, 0, 6)
   const friction = 5
   const dt = 0
 

package/src/physics/gravity.js

@@ -1,10 +1,10 @@
 /**
- * @typedef {import('../math/linear-algebra/types').Vector3} Vector3
+ * @typedef {import('../math/types.js').Vector3} Vector3
  */
 
 /* eslint-disable no-magic-numbers */
 
-import { zero } from "../math/linear-algebra/vector.js"
+import { zero } from "../math/vector.js"
 
 const DEFAULT_DT = 1 // Default delta time for the applyGravity function.
 const DEFAULT_JUMP = 0 // Default maximum jump height.