@inglorious/utils 2.3.0 → 3.0.0

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/types.d.ts

@@ -1,5 +0,0 @@
-export type Vector = number[]
-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]