@inglorious/utils 2.2.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}

@@ -1,23 +1,24 @@
 /**
+ * @typedef {import('./types').Vector} Vector
  * @typedef {import('./types').Vector2} Vector2
  * @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"
-import { from2D, to2D } from "./2d.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
@@ -30,8 +31,9 @@ const DEFAULT_DECIMALS = 0
 
 /**
  * Returns the absolute value of each component in the vector.
- * @param {Vector3} vector - The input vector.
- * @returns {Vector3} The vector with absolute values.
+ *
+ * @param {Vector} vector - The input vector.
+ * @returns {Vector} The vector with absolute values.
  */
 export function abs(vector) {
   return vector.map(nAbs)
@@ -39,8 +41,9 @@ export function abs(vector) {
 
 /**
  * Calculates the angle of the vector in radians.
- * @param {Vector3} vector - The input vector.
- * @returns {number} The angle in radians.
+ *
+ * @param {Vector} vector - The input vector.
+ * @returns {number} The angle of the vector in the XZ plane (for 3D) or XY plane (for 2D), in radians.
  */
 export function angle(vector) {
   return atan2(vector[vector.length - LAST_COORDINATE], vector[X])
@@ -48,10 +51,11 @@ export function angle(vector) {
 
 /**
  * Clamps the magnitude of the vector between the given min and max values.
- * @param {Vector3} vector - The input vector.
- * @param {number} min - The minimum magnitude.
- * @param {number} max - The maximum magnitude.
- * @returns {Vector3} The clamped vector.
+ *
+ * @param {Vector} vector - The input vector.
+ * @param {number|Vector} min - The minimum magnitude or a vector representing the lower bounds for each component.
+ * @param {number|Vector} max - The maximum magnitude or a vector representing the upper bounds for each component.
+ * @returns {Vector} The clamped vector.
  */
 export function clamp(vector, min, max) {
   const length = magnitude(vector)
@@ -75,18 +79,20 @@ export function clamp(vector, min, max) {
 
 /**
  * Returns the conjugate of the vector.
- * @param {Vector3} vector - The input vector.
- * @returns {Vector3} The conjugated vector.
+ *
+ * @param {Vector} vector - The input vector.
+ * @returns {Vector} The conjugated vector.
  */
 export function conjugate(vector) {
   return vector.map((coordinate, index) => (index ? -coordinate : coordinate))
 }
 
 /**
- * Creates a vector with the given magnitude and angle.
+ * Creates a 3D vector with the given magnitude and angle.
+ *
  * @param {number} magnitude - The magnitude of the vector.
  * @param {number} angle - The angle of the vector in radians.
- * @returns {Vector3} The created vector.
+ * @returns {Vector3} The created 3D vector.
  */
 export function createVector(magnitude, angle) {
   return multiply(fromAngle(angle), magnitude)
@@ -94,16 +100,28 @@ export function createVector(magnitude, angle) {
 
 /**
  * Divides each component of the vector by the given scalar.
- * @param {Vector3} vector - The input vector.
+ *
+ * @param {Vector} vector - The input vector.
  * @param {number} scalar - The scalar value.
- * @returns {Vector3} The resulting vector.
+ * @returns {Vector} The resulting vector.
  */
 export function divide(vector, scalar) {
   return vector.map((coordinate) => coordinate / scalar)
 }
 
 /**
- * Creates a unit vector from the given angle.
+ * 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]
+}
+
+/**
+ * Creates a 3D unit vector from the given angle in the XZ plane.
  * @param {number} angle - The angle in radians.
  * @returns {Vector3} The unit vector.
  */
@@ -111,35 +129,42 @@ 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 of the vector.
- * @param {Vector3} vector - The input vector.
+ * Calculates the magnitude (length) of the vector.
+ * Alias: `length`.
+ *
+ * @param {Vector} vector - The input vector.
  * @returns {number} The magnitude of the vector.
  */
 export function magnitude(vector) {
   return hypothenuse(...vector)
 }
 
+export const length = magnitude
+
 /**
  * Calculates the modulus of each component in the vector with the given divisor.
- * @param {Vector3} vector - The input vector.
+ * Alias: `remainder`.
+ *
+ * @param {Vector} vector - The input vector.
  * @param {number} divisor - The divisor value.
- * @returns {Vector3} The resulting vector.
+ * @returns {Vector} The resulting vector.
  */
 export function mod(vector, divisor) {
   return vector.map((coordinate) => nMod(coordinate, divisor))
@@ -147,18 +172,25 @@ export function mod(vector, divisor) {
 
 /**
  * Multiplies each component of the vector by the given scalar.
- * @param {Vector3} vector - The input vector.
+ * Aliases: `scale`, `times`.
+ *
+ * @param {Vector} vector - The input vector.
  * @param {number} scalar - The scalar value.
- * @returns {Vector3} The resulting vector.
+ * @returns {Vector} The resulting vector.
  */
 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.
- * @param {Vector3} vector - The input vector.
- * @returns {Vector3} The normalized vector.
+ *
+ * @param {Vector} vector - The input vector.
+ * @returns {Vector} The normalized vector.
  */
 export function normalize(vector) {
   const length = magnitude(vector)
@@ -168,10 +200,12 @@ export function normalize(vector) {
 export const remainder = mod
 
 /**
- * Rotates the vector by the given angle.
- * @param {Vector3} vector - The input vector.
+ * Rotates the vector by the given angle. Handles 2D and 3D vectors.
+ * For 3D vectors, rotation is around the Y-axis.
+ *
+ * @param {Vector} vector - The input vector (2D or 3D).
  * @param {number} angle - The angle in radians.
- * @returns {Vector3} The rotated vector.
+ * @returns {Vector} The rotated vector.
  */
 export function rotate(vector, angle) {
   const is2D = vector.length === TWO_COORDINATES
@@ -184,16 +218,9 @@ export function rotate(vector, angle) {
 }
 
 /**
- * Scales the vector by the given scalar. Alias of `multiply`.
- * @param {Vector3} vector - The input vector.
- * @param {number} scalar - The scalar value.
- * @returns {Vector3} The resulting vector.
- */
-export const scale = multiply
-
-/**
- * Sets the angle of the vector while maintaining its magnitude.
- * @param {Vector3} vector - The input vector.
+ * Sets the angle of the vector in the XZ plane while maintaining its magnitude.
+ *
+ * @param {Vector} vector - The input vector.
  * @param {number} angle - The new angle in radians.
  * @returns {Vector3} The vector with the updated angle.
  */
@@ -205,14 +232,17 @@ 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.
- * @param {Vector3} vector - The input vector.
+ * Alias: `setLength`.
+ *
+ * @param {Vector} vector - The input vector.
  * @param {number} length - The new magnitude.
- * @returns {Vector3} The vector with the updated magnitude.
+ * @returns {Vector} The vector with the updated magnitude.
  */
 export function setMagnitude(vector, length) {
   const normalized = normalize(vector)
@@ -221,9 +251,10 @@ export function setMagnitude(vector, length) {
 
 /**
  * Shifts the components of the vector by the given index.
- * @param {Vector3} vector - The input vector.
+ *
+ * @param {Vector} vector - The input vector.
  * @param {number} index - The index to shift by.
- * @returns {Vector3} The shifted vector.
+ * @returns {Vector} The shifted vector.
  */
 export function shift(vector, index) {
   return [...vector.slice(index), ...vector.slice(X, index)]
@@ -231,18 +262,29 @@ export function shift(vector, index) {
 
 /**
  * Snaps each component of the vector to the nearest multiple of the given precision.
- * @param {Vector3} vector - The input vector.
+ *
+ * @param {Vector} vector - The input vector.
  * @param {number} [precision=DEFAULT_PRECISION] - The precision value.
- * @returns {Vector3} The snapped vector.
+ * @returns {Vector} The snapped vector.
  */
 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].
+ *
+ * @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]
+}
 
 /**
- * Converts polar coordinates to Cartesian coordinates.
+ * Converts 2D polar coordinates to 2D Cartesian coordinates.
+ *
  * @param {Vector2} vector - The polar coordinates [magnitude, angle].
  * @returns {Vector2} The Cartesian coordinates [x, y].
  */
@@ -251,9 +293,10 @@ export function toCartesian([magnitude, angle]) {
 }
 
 /**
- * Converts a vector to cylindrical coordinates.
- * @param {Vector2} vector - The input vector.
- * @returns {Vector2} The cylindrical coordinates [radius, theta, z].
+ * Converts a 3D cartesian vector to cylindrical coordinates.
+ *
+ * @param {Vector3} vector - The input vector [x, y, z].
+ * @returns {Vector3} The cylindrical coordinates [radius, theta, z].
  */
 export function toCylindrical(vector) {
   const radius = magnitude(vector)
@@ -262,8 +305,9 @@ export function toCylindrical(vector) {
 }
 
 /**
- * Converts a vector to polar coordinates.
- * @param {Vector2} vector - The input vector.
+ * Converts a 2D cartesian vector to 2D polar coordinates.
+ *
+ * @param {Vector2} vector - The input vector [x, y].
  * @returns {Vector2} The polar coordinates [magnitude, angle].
  */
 export function toPolar(vector) {
@@ -272,7 +316,8 @@ export function toPolar(vector) {
 
 /**
  * Converts a vector to a string representation.
- * @param {Vector3} vector - The input vector.
+ *
+ * @param {Vector} vector - The input vector.
  * @param {number} [decimals=DEFAULT_DECIMALS] - The number of decimal places.
  * @returns {string} The string representation of the vector.
  */
@@ -309,8 +354,9 @@ export function toSpherical(vector) {
 }
 
 /**
- * Creates a unit vector with the given angle.
- * @param {number} angle - The angle in radians.
+ * Creates a 3D unit vector in the XZ plane with the given angle.
+ *
+ * @param {number} [angle=0] - The angle in radians.
  * @returns {Vector3} The unit vector.
  */
 export function unit(angle) {
@@ -322,7 +368,8 @@ export function unit(angle) {
 }
 
 /**
- * Creates a zero vector.
+ * Creates a zero vector of 3 dimensions.
+ *
  * @returns {Vector3} The zero vector.
  */
 export function zero() {
@@ -330,7 +377,8 @@ export function zero() {
 }
 
 /**
- * Rotates the vector using a quaternion.
+ * Rotates a 3D vector around the Y-axis using a quaternion.
+ *
  * @param {Vector3} vector - The input vector.
  * @param {number} angle - The angle in radians.
  * @returns {Vector3} The rotated vector.