@inglorious/utils 2.3.0 → 3.0.0

package/src/math/{geometry/rectangle.test.js → rectangle.test.js}

@@ -1,15 +1,16 @@
 import { expect, test } from "vitest"
 
+import { v } from "../v.js"
 import { intersectsRectangle } from "./rectangle.js"
 
 test("it should prove that a rectangle crossing another one intersects with it", () => {
   const rectangle1 = {
-    position: [0, 0, 0],
-    size: [2, 2, 2],
+    position: v(0, 0, 0),
+    size: v(2, 2, 2),
   }
   const rectangle2 = {
-    position: [1, 1, 1],
-    size: [2, 2, 2],
+    position: v(1, 1, 1),
+    size: v(2, 2, 2),
   }
 
   expect(intersectsRectangle(rectangle1, rectangle2)).toBe(true)
@@ -17,12 +18,12 @@ test("it should prove that a rectangle crossing another one intersects with it",
 
 test("it should prove that a rectangle right on top of another intersects with it", () => {
   const rectangle1 = {
-    position: [0, 0, 0],
-    size: [2, 2, 2],
+    position: v(0, 0, 0),
+    size: v(2, 2, 2),
   }
   const rectangle2 = {
-    position: [0, 0, 0],
-    size: [2, 0, 2],
+    position: v(0, 0, 0),
+    size: v(2, 0, 2),
   }
 
   expect(intersectsRectangle(rectangle1, rectangle2)).toBe(true)
@@ -30,12 +31,12 @@ test("it should prove that a rectangle right on top of another intersects with i
 
 test("it should prove that a rectangle not crossing another one does not intersect with it", () => {
   const rectangle1 = {
-    position: [0, 0, 0],
-    size: [2, 2, 2],
+    position: v(0, 0, 0),
+    size: v(2, 2, 2),
   }
   const rectangle2 = {
-    position: [3, 3, 3],
-    size: [2, 2, 2],
+    position: v(3, 3, 3),
+    size: v(2, 2, 2),
   }
 
   expect(intersectsRectangle(rectangle1, rectangle2)).toBe(false)

package/src/math/{geometry/segment.js → segment.js}

@@ -1,11 +1,11 @@
 /**
- * @typedef {import("./types").Segment} Segment
- * @typedef {import("./types").Point} Point
- * @typedef {import("./types").Circle} Circle
+ * @typedef {import("./geometry/types.js").Segment} Segment
+ * @typedef {import("./geometry/types.js").Point} Point
+ * @typedef {import("./geometry/types.js").Circle} Circle
  */
 
-import { magnitude, setMagnitude } from "../linear-algebra/vector.js"
-import { distance, dot, subtract, sum } from "../linear-algebra/vectors.js"
+import { magnitude, setMagnitude } from "./vector.js"
+import { distance, dot, subtract, sum } from "./vectors.js"
 
 const BEFORE_SEGMENT = 0
 

package/src/math/{geometry/segment.test.js → segment.test.js}

@@ -1,6 +1,7 @@
 import { expect, test } from "vitest"
 
-import { isClose } from "../numbers.js"
+import { v } from "../v.js"
+import { isClose } from "./numbers.js"
 import {
   closestPoint,
   coefficients,
@@ -21,64 +22,64 @@ expect.extend({
 
 test("it should retrieve values of *a*, *b*, and *c* from a segment, so it looks like a line in the form *ax + by + c = 0*", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [1, 0, 2],
+    from: v(0, 0, 0),
+    to: v(1, 0, 2),
   }
-  const expectedResult = [-2, 1, 0]
+  const expectedResult = v(-2, 1, 0)
 
   expect(coefficients(segment)).toStrictEqual(expectedResult)
 })
 
 test("it should find the closest point in a segment to a point projectable on it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [2, 0, 2],
+    from: v(0, 0, 0),
+    to: v(2, 0, 2),
   }
-  const point = [2, 0, 0]
-  const expectedResult = [1, 0, 1]
+  const point = v(2, 0, 0)
+  const expectedResult = v(1, 0, 1)
 
   expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it should find the closest point as the point itself when resting on the segment", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [2, 0, 2],
+    from: v(0, 0, 0),
+    to: v(2, 0, 2),
   }
-  const point = [1, 0, 1]
-  const expectedResult = [1, 0, 1]
+  const point = v(1, 0, 1)
+  const expectedResult = v(1, 0, 1)
 
   expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it return the start of a segment when the point is close to its start", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [3, 0, 4],
+    from: v(0, 0, 0),
+    to: v(3, 0, 4),
   }
-  const point = [-2, 0, 0]
-  const expectedResult = [0, 0, 0]
+  const point = v(-2, 0, 0)
+  const expectedResult = v(0, 0, 0)
 
   expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it should return the end of a segment when the point is close to its end", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [3, 0, 4],
+    from: v(0, 0, 0),
+    to: v(3, 0, 4),
   }
-  const point = [5, 0, 4]
-  const expectedResult = [3, 0, 4]
+  const point = v(5, 0, 4)
+  const expectedResult = v(3, 0, 4)
 
   expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it should compute the distance between a segment and a point projectable on it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [3, 0, 4],
+    from: v(0, 0, 0),
+    to: v(3, 0, 4),
   }
-  const point = [5, 0, 0]
+  const point = v(5, 0, 0)
   const expectedResult = 4
 
   expect(distanceFromPoint(segment, point)).toBe(expectedResult)
@@ -86,10 +87,10 @@ test("it should compute the distance between a segment and a point projectable o
 
 test("it should compute the distance between a segment and a point resting on it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [2, 0, 2],
+    from: v(0, 0, 0),
+    to: v(2, 0, 2),
   }
-  const point = [1, 0, 1]
+  const point = v(1, 0, 1)
   const expectedResult = 0
 
   expect(distanceFromPoint(segment, point)).toBeCloseTo(expectedResult)
@@ -97,10 +98,10 @@ test("it should compute the distance between a segment and a point resting on it
 
 test("it should compute the distance between a segment and a point close to the start", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [3, 0, 4],
+    from: v(0, 0, 0),
+    to: v(3, 0, 4),
   }
-  const point = [-2, 0, 0]
+  const point = v(-2, 0, 0)
   const expectedResult = 2
 
   expect(distanceFromPoint(segment, point)).toBe(expectedResult)
@@ -108,10 +109,10 @@ test("it should compute the distance between a segment and a point close to the
 
 test("it should compute the distance between a segment and a point close to the end", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [3, 0, 4],
+    from: v(0, 0, 0),
+    to: v(3, 0, 4),
   }
-  const point = [5, 0, 4]
+  const point = v(5, 0, 4)
   const expectedResult = 2
 
   expect(distanceFromPoint(segment, point)).toBeCloseTo(expectedResult)
@@ -119,11 +120,11 @@ test("it should compute the distance between a segment and a point close to the
 
 test("it should prove that a segment that crosses a circle intersects with it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [2, 0, 2],
+    from: v(0, 0, 0),
+    to: v(2, 0, 2),
   }
   const circle = {
-    position: [1, 0, 1],
+    position: v(1, 0, 1),
     radius: 1,
   }
 
@@ -132,11 +133,11 @@ test("it should prove that a segment that crosses a circle intersects with it",
 
 test("it should prove that a segment tangent to a circle intersects with it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [0, 0, 2],
+    from: v(0, 0, 0),
+    to: v(0, 0, 2),
   }
   const circle = {
-    position: [1, 0, 1],
+    position: v(1, 0, 1),
     radius: 1,
   }
 
@@ -145,11 +146,11 @@ test("it should prove that a segment tangent to a circle intersects with it", ()
 
 test("it should prove that a segment inside of a circle intersects with it", () => {
   const segment = {
-    from: [0.5, 0, 0.5],
-    to: [1.5, 0, 1.5],
+    from: v(0.5, 0, 0.5),
+    to: v(1.5, 0, 1.5),
   }
   const circle = {
-    position: [1, 0, 1],
+    position: v(1, 0, 1),
     radius: 1,
   }
 
@@ -158,11 +159,11 @@ test("it should prove that a segment inside of a circle intersects with it", ()
 
 test("it should prove that a segment that does not cross a circle does not intersect with it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [-2, 0, 2],
+    from: v(0, 0, 0),
+    to: v(-2, 0, 2),
   }
   const circle = {
-    position: [1, 0, 1],
+    position: v(1, 0, 1),
     radius: 1,
   }
 
@@ -171,11 +172,11 @@ test("it should prove that a segment that does not cross a circle does not inter
 
 test("it should prove that a segment that reaches outside of a circle does not intersect with it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [-1, 0, -2],
+    from: v(0, 0, 0),
+    to: v(-1, 0, -2),
   }
   const circle = {
-    position: [1, 0, 1],
+    position: v(1, 0, 1),
     radius: 1,
   }
 

package/src/math/{geometry/types.d.ts → types.d.ts}

@@ -1,3 +1,5 @@
+// geometry
+
 export type Point = [number, number, number] // [x, y, z]
 export type Size = [number, number, number] // [width, height, depth]
 export type Line = [number, number, number] // [a, b, c]
@@ -21,3 +23,11 @@ export interface Segment {
   from: Point
   to: Point
 }
+
+// linear algebra
+
+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]

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

@@ -4,20 +4,21 @@
  * @typedef {import('./types').Vector3} Vector3
  */
 
-import { isArray } from "../../data-structures/array.js"
-import { hypothenuse } from "../geometry/triangle.js"
+import { isArray } from "../data-structures/array.js"
+import { v } from "../v.js"
 import {
   abs as nAbs,
   clamp as nClamp,
   mod as nMod,
   snap as nSnap,
-} from "../numbers.js"
-import { atan2, cos, sin } from "../trigonometry.js"
+} from "./numbers.js"
 import { quaternion } from "./quaternion.js"
+import { hypothenuse } from "./triangle.js"
+import { atan2, cos, sin } from "./trigonometry.js"
 import { cross, sum } from "./vectors.js"
 
-const ZERO_VECTOR = [0, 0, 0] // eslint-disable-line no-magic-numbers
-const UNIT_VECTOR = [1, 0, 0] // eslint-disable-line no-magic-numbers
+const ZERO_VECTOR = v(0, 0, 0) // eslint-disable-line no-magic-numbers
+const UNIT_VECTOR = v(1, 0, 0) // eslint-disable-line no-magic-numbers
 
 const X = 0
 const Y = 1
@@ -128,23 +129,25 @@ export function fromAngle(angle) {
   return rotate(UNIT_VECTOR, angle)
 }
 
-export const length = magnitude
-
 /**
  * Checks if a value is a vector.
+ * A vector is an array of numbers. For performance, vectors created with `v()`
+ * are tagged and can be identified more quickly.
  *
  * @param {*} value - The value to check.
  * @returns {boolean} True if the value is a vector, false otherwise.
  */
 export function isVector(value) {
   return (
-    isArray(value) &&
-    value.every((coordinate) => typeof coordinate === "number")
+    value?.__isVector__ ||
+    (isArray(value) &&
+      value.every((coordinate) => typeof coordinate === "number"))
   )
 }
 
 /**
  * Calculates the magnitude (length) of the vector.
+ * Alias: `length`.
  *
  * @param {Vector} vector - The input vector.
  * @returns {number} The magnitude of the vector.
@@ -153,8 +156,11 @@ export function magnitude(vector) {
   return hypothenuse(...vector)
 }
 
+export const length = magnitude
+
 /**
  * Calculates the modulus of each component in the vector with the given divisor.
+ * Alias: `remainder`.
  *
  * @param {Vector} vector - The input vector.
  * @param {number} divisor - The divisor value.
@@ -166,6 +172,7 @@ export function mod(vector, divisor) {
 
 /**
  * Multiplies each component of the vector by the given scalar.
+ * Aliases: `scale`, `times`.
  *
  * @param {Vector} vector - The input vector.
  * @param {number} scalar - The scalar value.
@@ -175,6 +182,10 @@ export function multiply(vector, scalar) {
   return vector.map((coordinate) => coordinate * scalar)
 }
 
+export const scale = multiply
+
+export const times = multiply
+
 /**
  * Normalizes the vector to have a magnitude of 1.
  *
@@ -206,15 +217,6 @@ export function rotate(vector, angle) {
   return is2D ? to2D(result) : result
 }
 
-/**
- * Scales the vector by the given scalar. Alias of `multiply`.
- *
- * @param {Vector} vector - The input vector.
- * @param {number} scalar - The scalar value.
- * @returns {Vector} The resulting vector.
- */
-export const scale = multiply
-
 /**
  * Sets the angle of the vector in the XZ plane while maintaining its magnitude.
  *
@@ -230,11 +232,13 @@ export function setAngle(vector, angle) {
 
 /**
  * Sets the length of the vector while maintaining its direction. Alias of `setMagnitude`.
+ * Alias: `setLength`.
  */
 export const setLength = setMagnitude
 
 /**
  * Sets the magnitude of the vector while maintaining its direction.
+ * Alias: `setLength`.
  *
  * @param {Vector} vector - The input vector.
  * @param {number} length - The new magnitude.
@@ -267,8 +271,6 @@ export function snap(vector, precision = DEFAULT_PRECISION) {
   return vector.map((coordinate) => nSnap(coordinate, -precision, precision))
 }
 
-export const times = multiply
-
 /**
  * Converts a 3D vector [x, y, z] into a 2D vector [x, z].
  *
@@ -365,17 +367,6 @@ export function unit(angle) {
   return setAngle(UNIT_VECTOR, angle)
 }
 
-/**
- * A utility function to create a vector from a list of coordinates.
- * This is a shorthand for `[x, y, z, ...]`.
- *
- * @param {...number} coords - The coordinates of the vector.
- * @returns {Vector} The created vector.
- */
-export function v(...coords) {
-  return coords
-}
-
 /**
  * Creates a zero vector of 3 dimensions.
  *

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,
@@ -28,13 +29,12 @@ 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)
 })
@@ -47,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)
@@ -81,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)
 })
@@ -90,29 +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 = [3, 0, 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)
 })
@@ -125,8 +125,9 @@ 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(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", () => {
@@ -138,17 +139,17 @@ 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)
 })
@@ -176,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)
 })
@@ -231,15 +232,15 @@ 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 = [3, 0, 4]
+  const vector = v(3, 0, 4)
   const expectedResult = [3, 4]
 
   expect(to2D(vector)).toStrictEqual(expectedResult)
@@ -253,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)
 })
@@ -267,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)
@@ -289,21 +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([1, 2, 3])
+  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 = [0, 0, 0]
+  const expectedResult = v(0, 0, 0)
 
   expect(zero()).toStrictEqual(expectedResult)
 })