@inglorious/utils 2.3.0 → 3.1.0

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
@@ -30,17 +31,15 @@ const DEFAULT_DECIMALS = 0
 
 /**
  * Returns the absolute value of each component in the vector.
- *
  * @param {Vector} vector - The input vector.
  * @returns {Vector} The vector with absolute values.
  */
 export function abs(vector) {
-  return vector.map(nAbs)
+  return v(...vector.map(nAbs))
 }
 
 /**
  * Calculates the angle of the vector 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.
  */
@@ -50,7 +49,6 @@ export function angle(vector) {
 
 /**
  * Clamps the magnitude of the vector between the given min and max values.
- *
  * @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.
@@ -68,8 +66,10 @@ export function clamp(vector, min, max) {
   }
 
   if (typeof min !== "number" && typeof max !== "number") {
-    return vector.map((coordinate, index) =>
-      nClamp(coordinate, min[index], max[index]),
+    return v(
+      ...vector.map((coordinate, index) =>
+        nClamp(coordinate, min[index], max[index]),
+      ),
     )
   }
 
@@ -78,17 +78,17 @@ export function clamp(vector, min, max) {
 
 /**
  * Returns the conjugate of the vector.
- *
  * @param {Vector} vector - The input vector.
  * @returns {Vector} The conjugated vector.
  */
 export function conjugate(vector) {
-  return vector.map((coordinate, index) => (index ? -coordinate : coordinate))
+  return v(
+    ...vector.map((coordinate, index) => (index ? -coordinate : coordinate)),
+  )
 }
 
 /**
  * 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 3D vector.
@@ -99,24 +99,22 @@ export function createVector(magnitude, angle) {
 
 /**
  * Divides each component of the vector by the given scalar.
- *
  * @param {Vector} vector - The input vector.
  * @param {number} scalar - The scalar value.
  * @returns {Vector} The resulting vector.
  */
 export function divide(vector, scalar) {
-  return vector.map((coordinate) => coordinate / scalar)
+  return v(...vector.map((coordinate) => coordinate / scalar))
 }
 
 /**
  * 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]
+  return v(x, NO_Y, z)
 }
 
 /**
@@ -128,24 +126,23 @@ 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.
- *
  * @param {Vector} vector - The input vector.
  * @returns {number} The magnitude of the vector.
  */
@@ -153,45 +150,75 @@ 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 {Vector} vector - The input vector.
  * @param {number} divisor - The divisor value.
  * @returns {Vector} The resulting vector.
  */
 export function mod(vector, divisor) {
-  return vector.map((coordinate) => nMod(coordinate, divisor))
+  return v(...vector.map((coordinate) => nMod(coordinate, divisor)))
 }
 
 /**
  * Multiplies each component of the vector by the given scalar.
- *
  * @param {Vector} vector - The input vector.
  * @param {number} scalar - The scalar value.
  * @returns {Vector} The resulting vector.
  */
 export function multiply(vector, scalar) {
-  return vector.map((coordinate) => coordinate * scalar)
+  return v(...vector.map((coordinate) => coordinate * scalar))
+}
+
+/**
+ * Alias for the power function.
+ * @type {typeof power}
+ */
+export const pow = power
+
+/**
+ * Raises each component of the vector to the given exponent.
+ * @param {Vector} vector - The input vector.
+ * @param {number} exponent - The exponent value.
+ * @returns {Vector} The resulting vector.
+ */
+export function power(vector, exponent) {
+  return v(...vector.map((coordinate) => coordinate ** exponent))
 }
 
+/**
+ * Alias for the multiply function.
+ * @type {typeof multiply}
+ */
+export const scale = multiply
+
+/**
+ * Alias for the multiply function.
+ * @type {typeof multiply}
+ */
+export const times = multiply
+
 /**
  * Normalizes the vector to have a magnitude of 1.
- *
  * @param {Vector} vector - The input vector.
  * @returns {Vector} The normalized vector.
  */
 export function normalize(vector) {
   const length = magnitude(vector)
-  return vector.map((coordinate) => coordinate / length)
+  return v(...vector.map((coordinate) => coordinate / length))
 }
 
+/**
+ * Alias for the mod function.
+ * @type {typeof mod}
+ */
 export const remainder = mod
 
 /**
  * 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 {Vector} The rotated vector.
@@ -206,18 +233,8 @@ 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.
- *
  * @param {Vector} vector - The input vector.
  * @param {number} angle - The new angle in radians.
  * @returns {Vector3} The vector with the updated angle.
@@ -225,17 +242,17 @@ export const scale = multiply
 export function setAngle(vector, angle) {
   const length = magnitude(vector)
   const [x, z] = toCartesian([length, angle])
-  return [x, NO_Y, z]
+  return v(x, NO_Y, z)
 }
 
 /**
- * Sets the length of the vector while maintaining its direction. Alias of `setMagnitude`.
+ * Alias for the setMagnitude function.
+ * @type {typeof setMagnitude}
  */
 export const setLength = setMagnitude
 
 /**
  * Sets the magnitude of the vector while maintaining its direction.
- *
  * @param {Vector} vector - The input vector.
  * @param {number} length - The new magnitude.
  * @returns {Vector} The vector with the updated magnitude.
@@ -247,74 +264,67 @@ export function setMagnitude(vector, length) {
 
 /**
  * Shifts the components of the vector by the given index.
- *
  * @param {Vector} vector - The input vector.
  * @param {number} index - The index to shift by.
  * @returns {Vector} The shifted vector.
  */
 export function shift(vector, index) {
-  return [...vector.slice(index), ...vector.slice(X, index)]
+  return v(...vector.slice(index), ...vector.slice(X, index))
 }
 
 /**
  * Snaps each component of the vector to the nearest multiple of the given precision.
- *
  * @param {Vector} vector - The input vector.
  * @param {number} [precision=DEFAULT_PRECISION] - The precision value.
  * @returns {Vector} The snapped vector.
  */
 export function snap(vector, precision = DEFAULT_PRECISION) {
-  return vector.map((coordinate) => nSnap(coordinate, -precision, precision))
+  return v(
+    ...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]
+  return v(x, z)
 }
 
 /**
  * Converts 2D polar coordinates to 2D Cartesian coordinates.
- *
  * @param {Vector2} vector - The polar coordinates [magnitude, angle].
  * @returns {Vector2} The Cartesian coordinates [x, y].
  */
 export function toCartesian([magnitude, angle]) {
-  return [magnitude * cos(angle), magnitude * sin(angle)]
+  return v(magnitude * cos(angle), magnitude * sin(angle))
 }
 
 /**
  * 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)
   const theta = angle(vector)
-  return [radius * cos(theta), radius * sin(theta), vector[Z]]
+  return v(radius * cos(theta), radius * sin(theta), vector[Z])
 }
 
 /**
  * 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) {
-  return [magnitude(vector), angle(vector)]
+  return v(magnitude(vector), angle(vector))
 }
 
 /**
  * Converts a vector to a string representation.
- *
  * @param {Vector} vector - The input vector.
  * @param {number} [decimals=DEFAULT_DECIMALS] - The number of decimal places.
  * @returns {string} The string representation of the vector.
@@ -325,14 +335,11 @@ export function toString(vector, decimals = DEFAULT_DECIMALS) {
     .join(", ")}]`
 }
 
-// TODO: add toSpherical(vector),
-
 /**
  * Converts a 3D cartesian vector to spherical coordinates [radius, inclination, azimuth].
  * - radius (r): distance from the origin.
  * - inclination (θ): angle from the Y-axis (0 to PI).
  * - azimuth (φ): angle from the X-axis in the XZ-plane (-PI to PI).
- *
  * @param {Vector3} vector The cartesian vector [x, y, z].
  * @returns {Vector3} The spherical coordinates [r, θ, φ].
  */
@@ -348,46 +355,32 @@ export function toSpherical(vector) {
   // Azimuth is the angle in the XZ plane, which `angle()` calculates.
   const azimuth = angle(vector)
 
-  return [r, inclination, azimuth]
+  return v(r, inclination, azimuth)
 }
 
 /**
  * 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) {
   if (!angle) {
-    return [...UNIT_VECTOR]
+    return v(...UNIT_VECTOR)
   }
 
   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.
- *
  * @returns {Vector3} The zero vector.
  */
 export function zero() {
-  return [...ZERO_VECTOR]
+  return v(...ZERO_VECTOR)
 }
 
 /**
  * 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.