@inglorious/utils 2.2.0 → 3.0.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,
@@ -9,7 +10,9 @@ import {
   conjugate,
   createVector,
   divide,
+  from2D,
   fromAngle,
+  isVector,
   magnitude,
   mod,
   multiply,
@@ -19,17 +22,19 @@ import {
   setMagnitude,
   shift,
   snap,
+  to2D,
   toCartesian,
   toCylindrical,
   toPolar,
   toSpherical,
   toString,
   unit,
+  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)
 })
@@ -42,7 +47,7 @@ test("it should compute the angle of a 2D vector", () => {
 })
 
 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)
@@ -76,8 +81,8 @@ test("it should clamp the magnitude of a vector to the values of other vector bo
 })
 
 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)
 })
@@ -85,22 +90,29 @@ 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 = 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)
 })
@@ -112,18 +124,32 @@ test("it should compute the magnitude of a vector (aka length)", () => {
   expect(magnitude(vector)).toBe(expectedResult)
 })
 
+test("it should check if a value is a vector", () => {
+  expect(isVector(v(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", () => {
+  expect(isVector([1, "a", 3])).toBe(false)
+  expect(isVector({ x: 1, y: 2 })).toBe(false)
+  expect(isVector(null)).toBe(false)
+  expect(isVector("vector")).toBe(false)
+  expect(isVector(123)).toBe(false)
+})
+
 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)
 })
@@ -151,32 +177,32 @@ test("it should rotate a 2D vector by a certain angle", () => {
 })
 
 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 expectedResult = [6.123233995736766e-17, 0, 1] // close to v(0, 0, 1)
 
   expect(setAngle(vector, 1.5707963267948966)).toStrictEqual(expectedResult)
 })
@@ -206,13 +232,20 @@ test("it should shift a vector at a certain index", () => {
 })
 
 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 = v(3, 0, 4)
+  const expectedResult = [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]
@@ -221,8 +254,8 @@ test("it should convert a 2D polar vector to cartesian coordinates", () => {
 })
 
 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)
 })
@@ -235,7 +268,7 @@ test("it should convert a 2D cartesian vector to polar coordinates", () => {
 })
 
 test("it should convert a 3D cartesian vector to spherical coordinates", () => {
-  const vector = [1, 1, 1]
+  const vector = v(1, 1, 1)
   const expectedResult = [sqrt(3), Math.acos(1 / sqrt(3)), pi() / 4]
 
   expect(toSpherical(vector)).toStrictEqual(expectedResult)
@@ -257,9 +290,27 @@ 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([6.123233995736766e-17, 0, 1]) // close to v(0, 0, 1)
+})
+
+test("it should create a vector from a list of coordinates", () => {
+  expect(v(1, 2, 3)).toStrictEqual(v(1, 2, 3))
+  expect(v()).toStrictEqual([])
+  expect(v(0, -5.5)).toStrictEqual([0, -5.5])
+})
+
+test("it should create a vector with a __isVector__ property", () => {
+  const vector = v(1, 2, 3)
+  expect(vector).toStrictEqual(v(1, 2, 3))
+  expect(vector.__isVector__).toBe(true)
+})
+
+test("it should create a 3D zero vector", () => {
+  const expectedResult = v(0, 0, 0)
+
+  expect(zero()).toStrictEqual(expectedResult)
 })

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.

package/src/physics/friction.js

@@ -1,8 +1,8 @@
 /**
- * @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.

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.

package/src/physics/gravity.test.js

@@ -1,5 +1,6 @@
 import { expect, test } from "vitest"
 
+import { v } from "../v.js"
 import { applyGravity } from "./gravity.js"
 
 test("it should apply gravity based on input parameters", () => {
@@ -8,13 +9,13 @@ test("it should apply gravity based on input parameters", () => {
     maxLeap: 10,
     maxSpeed: 10,
     vy: 10,
-    position: [0, 10, 0],
+    position: v(0, 10, 0),
   }
 
   expect(applyGravity(params)).toStrictEqual({
     ay: -20,
     vy: -10,
-    position: [0, -10, 0],
+    position: v(0, -10, 0),
   })
 })
 
@@ -23,13 +24,13 @@ test("it should compute no gravity when max jump height is not set", () => {
     maxLeap: 10,
     maxSpeed: 10,
     vy: 10,
-    position: [0, 10, 0],
+    position: v(0, 10, 0),
   }
 
   expect(applyGravity(params)).toStrictEqual({
     ay: -0,
     vy: 10,
-    position: [0, 20, 0],
+    position: v(0, 20, 0),
   })
 })
 
@@ -38,13 +39,13 @@ test("it should compute no gravity when max movement speed is not set", () => {
     maxJump: 10,
     maxLeap: 10,
     vy: 10,
-    position: [0, 10, 0],
+    position: v(0, 10, 0),
   }
 
   expect(applyGravity(params)).toStrictEqual({
     ay: -0,
     vy: 10,
-    position: [0, 20, 0],
+    position: v(0, 20, 0),
   })
 })
 
@@ -54,14 +55,14 @@ test("it should apply no gravity when no time has passed", () => {
     maxLeap: 10,
     maxSpeed: 10,
     vy: 10,
-    position: [0, 10, 0],
+    position: v(0, 10, 0),
   }
   const dt = 0
 
   expect(applyGravity(params, dt)).toStrictEqual({
     ay: -20,
     vy: 10,
-    position: [0, 10, 0],
+    position: v(0, 10, 0),
   })
 })
 
@@ -70,7 +71,7 @@ test("it should throw an error when max leap distance is not set", () => {
     maxJump: 10,
     maxSpeed: 10,
     vy: 10,
-    position: [0, 10, 0],
+    position: v(0, 10, 0),
   }
 
   expect(() => applyGravity(params)).toThrow()

package/src/physics/index.js

@@ -0,0 +1,7 @@
+import * as acceleration from "./acceleration.js"
+import * as friction from "./friction.js"
+import * as gravity from "./gravity.js"
+import * as jump from "./jump.js"
+import * as velocity from "./velocity.js"
+
+export { acceleration, friction, gravity, jump, velocity }

package/src/physics/jump.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('../math/linear-algebra/types').Vector3} Vector3
+ * @typedef {import('../math/types').Vector3} Vector3
  */
 
 /* eslint-disable no-magic-numbers */

package/src/physics/velocity.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"
 
 const DEFAULT_DT = 1 // Default time delta for the applyVelocity function.
 const DEFAULT_MAX_SPEED = 0 // Default maximum speed for velocity clamping.

package/src/v.js

@@ -0,0 +1,18 @@
+/**
+ * A utility function to create a vector from a list of coordinates.
+ * This is a shorthand for `[x, y, z, ...]`.
+ * It also tags the array with a non-enumerable `__isVector__` property for
+ * efficient type checking.
+ *
+ * @param {...number} coords - The coordinates of the vector.
+ * @returns {Vector} The created vector.
+ */
+export function v(...coords) {
+  Object.defineProperty(coords, "__isVector__", {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  })
+  return coords
+}

package/src/math/linear-algebra/2d.js

@@ -1,28 +0,0 @@
-/**
- * @typedef {import('../../../types').Vector2} Vector2
- * @typedef {import('../../../types').Vector3} Vector3
- */
-
-const NO_Y = 0 // Default Y-coordinate value for 3D vectors derived from 2D vectors.
-
-/**
- * Converts a 2D vector [x, z] into a 3D vector [x, 0, z].
- *
- * @param {Vector2} vector - A 2D vector represented as [x, z].
- * @returns {Vector3} A 3D vector represented as [x, 0, z].
- */
-export function from2D(vector) {
-  const [x, z] = vector
-  return [x, NO_Y, z]
-}
-
-/**
- * Converts a 3D vector [x, y, z] into a 2D vector [x, z].
- *
- * @param {Vector3} vector - A 3D vector represented as [x, y, z].
- * @returns {Vector2} A 2D vector represented as [x, z].
- */
-export function to2D(vector) {
-  const [x, , z] = vector
-  return [x, z]
-}

package/src/math/linear-algebra/2d.test.js

@@ -1,17 +0,0 @@
-import { expect, test } from "vitest"
-
-import { from2D, to2D } from "./2d.js"
-
-test("build a 3D vector from a 2D one", () => {
-  const vector = [3, 4]
-  const expectedResult = [3, 0, 4]
-
-  expect(from2D(vector)).toStrictEqual(expectedResult)
-})
-
-test("build a 2D vector from a 3D one", () => {
-  const vector = [3, 0, 4]
-  const expectedResult = [3, 4]
-
-  expect(to2D(vector)).toStrictEqual(expectedResult)
-})

package/src/math/linear-algebra/types.d.ts

@@ -1,4 +0,0 @@
-export type Vector2 = [number, number]
-export type Vector3 = [number, number, number]
-export type Quaternion = [number, number, number, number]
-export type Vector7 = [number, number, number, number, number, number, number]