@inglorious/utils 3.0.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "A set of general-purpose utility functions designed with functional programming principles in mind.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",

package/src/data-structures/object.js

@@ -1,3 +1,6 @@
+import { v } from "../v.js"
+import { isArray } from "./array.js"
+
 const INITIAL_LEVEL = 0
 const NEXT_LEVEL = 2
 
@@ -8,7 +11,46 @@ const NEXT_LEVEL = 2
  * @returns {Object} A deep clone of the input object.
  */
 export function clone(obj) {
-  return JSON.parse(JSON.stringify(obj))
+  return deserialize(serialize(obj))
+}
+
+/**
+ * Deserializes an object, converting plain object representations back into
+ * their original types, such as vector-like objects. This is the inverse
+ * operation of `serialize`.
+ *
+ * - Recursively deserializes nested objects.
+ * - Converts objects with a `_type: "vector"` property and `coords` array
+ *   back into a vector-like object using the `v` factory function.
+ * - Copies all other property values as-is.
+ *
+ * @param {string} str - The JSON string to deserialize.
+ * @returns {Object} The deserialized object.
+ */
+export function deserialize(str) {
+  const data = JSON.parse(str)
+
+  return revive(data)
+
+  function revive(value) {
+    if (isArray(value)) {
+      return value.map(revive)
+    }
+    if (isObject(value)) {
+      if (value._type === "vector" && value.coords) {
+        return v(...value.coords)
+      }
+
+      const deserialized = {}
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          deserialized[key] = revive(value[key])
+        }
+      }
+      return deserialized
+    }
+    return value
+  }
 }
 
 /**
@@ -73,7 +115,7 @@ export function map(obj, callback) {
  *
  * **Important:** Unlike Immer, which uses structural sharing via proxies for
  * high performance, this implementation performs a full deep clone of the base
- * state on every call using `JSON.parse(JSON.stringify())`. This can be
+ * state on every call using `deserialize(serialize())`. This can be
  * inefficient for large or complex states. It is intended for simple use cases
  * where the convenience of the API outweighs the performance cost.
  *
@@ -102,6 +144,47 @@ export function produce(baseState, recipe, ...args) {
   return result === undefined ? draft : result
 }
 
+/**
+ * Serializes an object, converting special types like vectors into a plain
+ * object representation. This is useful for processes like saving state to a
+ * file or sending it over a network.
+ *
+ * - Recursively serializes nested objects.
+ * - Converts objects with a `__isVector__` property into a serializable
+ *   format: `{ _type: "vector", coords: [...] }`.
+ * - Copies all other property values as-is.
+ *
+ * @param {Object} obj - The object to serialize.
+ * @returns {string} The serialized JSON string.
+ */
+export function serialize(obj) {
+  function replacer(key, value) {
+    // Handle top-level vector
+    if (value?.__isVector__) {
+      return {
+        _type: "vector",
+        coords: Array.from(value),
+      }
+    }
+
+    if (isObject(value)) {
+      const serialized = {}
+
+      for (const k in value) {
+        if (Object.prototype.hasOwnProperty.call(value, k)) {
+          serialized[k] = replacer(undefined, value[k])
+        }
+      }
+
+      return serialized
+    }
+
+    return value
+  }
+
+  return JSON.stringify(obj, replacer)
+}
+
 /**
  * Converts an object or array to a formatted string representation.
  *

package/src/data-structures/object.test.js

@@ -1,12 +1,15 @@
 import { expect, test } from "vitest"
 
+import { v } from "../v.js"
 import {
   clone,
+  deserialize,
   filter,
   find,
   isObject,
   map,
   produce,
+  serialize,
   toString,
 } from "./object.js"
 
@@ -112,7 +115,7 @@ test("it should produce a new state without mutating the original", () => {
     g: 6,
   }
 
-  const originalBaseState = JSON.parse(JSON.stringify(baseState))
+  const originalBaseState = deserialize(serialize(baseState))
 
   const nextState = produce(baseState, recipe)
 
@@ -216,3 +219,117 @@ test("it should return a string representation of a nested object", () => {
   g: 6
 }`)
 })
+
+test("it should serialize a basic object with primitive values", () => {
+  const obj = { a: 1, b: "hello", c: true }
+  const expected = `{"a":1,"b":"hello","c":true}`
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should serialize an object with nested objects", () => {
+  const obj = { a: 1, b: { c: "nested", d: { e: false } } }
+  const expected = `{"a":1,"b":{"c":"nested","d":{"e":false}}}`
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should serialize an object containing a vector-like object", () => {
+  const obj = { position: v(1, 2, 3) }
+  const expected = `{"position":{"_type":"vector","coords":[1,2,3]}}`
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should serialize an object with nested vector-like objects", () => {
+  const obj = {
+    entity: {
+      id: "player",
+      pos: v(10, 20),
+      vel: v(1, 0),
+      stats: { health: 100 },
+    },
+  }
+  const expected = `{"entity":{"id":"player","pos":{"_type":"vector","coords":[10,20]},"vel":{"_type":"vector","coords":[1,0]},"stats":{"health":100}}}`
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should serialize an empty object", () => {
+  const obj = {}
+  const expected = `{}`
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should serialize an object with null and undefined values (undefined should be omitted)", () => {
+  const obj = { a: null, b: undefined, c: 1 }
+  const expected = `{"a":null,"c":1}` // JSON.stringify omits undefined properties
+
+  expect(serialize(obj)).toBe(expected)
+})
+
+test("it should deserialize a basic object with primitive values", () => {
+  const serialized = `{"a":1,"b":"hello","c":true}`
+  const expected = { a: 1, b: "hello", c: true }
+
+  expect(deserialize(serialized)).toStrictEqual(expected)
+})
+
+test("it should deserialize an object with nested objects", () => {
+  const serialized = `{"a":1,"b":{"c":"nested","d":{"e":false}}}`
+  const expected = { a: 1, b: { c: "nested", d: { e: false } } }
+
+  expect(deserialize(serialized)).toStrictEqual(expected)
+})
+
+test("it should deserialize an object containing a vector representation", () => {
+  const serialized = `{"position":{"_type":"vector","coords":[1,2,3]}}`
+  const expected = { position: v(1, 2, 3) }
+
+  const result = deserialize(serialized)
+
+  expect(result).toStrictEqual(expected)
+  expect(result.position.__isVector__).toBe(true)
+})
+
+test("it should deserialize an object with nested vector representations", () => {
+  const serialized = `{"entity":{"id":"player","pos":{"_type":"vector","coords":[10,20]},"vel":{"_type":"vector","coords":[1,0]},"stats":{"health":100}}}`
+  const expected = {
+    entity: {
+      id: "player",
+      pos: v(10, 20),
+      vel: v(1, 0),
+      stats: { health: 100 },
+    },
+  }
+  const result = deserialize(serialized)
+
+  expect(result).toStrictEqual(expected)
+  expect(result.entity.pos.__isVector__).toBe(true)
+  expect(result.entity.vel.__isVector__).toBe(true)
+})
+
+test("it should deserialize an empty object", () => {
+  const serialized = `{}`
+  const expected = {}
+
+  expect(deserialize(serialized)).toStrictEqual(expected)
+})
+
+test("it should correctly round-trip a complex object through serialize and deserialize", () => {
+  const original = {
+    id: "game1",
+    player: { name: "Alice", score: 100, position: v(10, 20) },
+    enemies: [{ type: "goblin", pos: v(5, 5) }],
+    settings: { volume: 0.8, mute: false },
+  }
+  const jsonString = serialize(original)
+  const deserialized = deserialize(jsonString)
+
+  expect(deserialized).toStrictEqual(original)
+  expect(deserialized.player.position.__isVector__).toBe(true)
+  expect(deserialized.enemies[0].pos.__isVector__).toBe(true)
+  // Ensure that non-vector objects are still distinct references if they were originally
+  expect(deserialized.player).not.toBe(original.player)
+})

package/src/math/line.js

@@ -9,7 +9,6 @@ import { hypothenuse } from "./triangle.js"
 
 /**
  * Calculates the shortest distance from a point to a line in 2D space.
- *
  * @param {Line} line - The line represented by the equation ax + bz + c = 0, where `line` is [a, b, c].
  * @param {Point} point - The point in 3D space represented as [x, y, z].
  * @returns {number} The shortest distance from the point to the line.
@@ -24,7 +23,6 @@ export function distanceFromPoint(line, point) {
 // @see https://math.stackexchange.com/questions/275529/check-if-line-intersects-with-circles-perimeter
 /**
  * Determines whether a line intersects with the perimeter of a circle.
- *
  * @param {Line} line - The line represented by the equation ax + bz + c = 0, where `line` is [a, b, c].
  * @param {Circle} circle - The circle defined by its position (center) and radius.
  * @returns {boolean} `true` if the line intersects the circle's perimeter, otherwise `false`.

package/src/math/linear-interpolation.js

@@ -1,6 +1,5 @@
 /**
  * Performs linear interpolation between two numbers.
- *
  * @param {number} a - The start value.
  * @param {number} b - The end value.
  * @param {number} t - The interpolation factor, typically in the range [0, 1].

package/src/math/quaternion.js

@@ -13,11 +13,10 @@ const Y_AXIS = v(0, 1, 0) // Default axis of rotation (Y-axis).
 
 /**
  * Computes a quaternion representing a rotation around a given axis.
- *
  * @param {number} [angle=0] - The angle of rotation in radians. Defaults to 0.
  * @param {Vector3} [axis=Y_AXIS] - The axis of rotation as a 3D vector Defaults to the Y-axis.
  * @returns {Quaternion} The quaternion as an array [w, x, y, z].
  */
 export function quaternion(angle = DEFAULT_ANGLE, axis = Y_AXIS) {
-  return [cos(angle / HALF), ...axis.map((coord) => coord * sin(angle / HALF))]
+  return v(cos(angle / HALF), ...axis.map((coord) => coord * sin(angle / HALF)))
 }

package/src/math/quaternions.js

@@ -2,19 +2,22 @@
  * @typedef {import('./types').Quaternion} Quaternion
  */
 
+import { v } from "../v.js"
 import { times } from "./vector.js"
 import { cross, dot, sum } from "./vectors.js"
 
 /**
  * Combines two quaternions using the Hamilton product.
- *
  * @param {Quaternion} q1 - The first quaternion.
  * @param {Quaternion} q2 - The second quaternion.
  * @returns {Quaternion} - The resulting quaternion after combining q1 and q2.
  */
 export function combine(q1, q2) {
-  const [s, ...v] = q1
-  const [t, ...w] = q2
+  const [s1, ...v1] = q1
+  const [s2, ...v2] = q2
 
-  return [s * t - dot(v, w), ...sum(times(w, s), times(v, t), cross(v, w))]
+  return v(
+    s1 * s2 - dot(v1, v2),
+    ...sum(times(v2, s1), times(v1, s2), cross(v1, v2)),
+  )
 }

package/src/math/rectangle.js

@@ -21,7 +21,6 @@ export function intersectsPoint(rectangle, point) {
 
 /**
  * Checks if a rectangle intersects with a circle.
- *
  * @param {Rectangle} rectangle - The rectangle to check.
  * @param {Circle} circle - The circle to check.
  * @returns {boolean} True if the rectangle intersects the circle, false otherwise.
@@ -32,7 +31,6 @@ export function intersectsCircle(rectangle, circle) {
 
 /**
  * Determines whether a rectangle intersects another in 3D space.
- *
  * @param {Rectangle} rectangle1 - The first rectangle, defined by its position (x, y, z) and size (width, height, depth).
  * @param {Rectangle} rectangle2 - The second rectangle, defined by its position (x, y, z) and size (width, height, depth).
  * @returns {boolean} True if the two rectangles intersect, false otherwise.

package/src/math/rng.js

@@ -5,7 +5,6 @@
  * - If no arguments are provided, returns a random float between 0 (inclusive) and 1 (exclusive).
  * - If one argument is provided, returns a random integer between 0 and the given number (inclusive).
  * - If two or more arguments are provided, returns a random integer within the specified range and step.
- *
  * @param {number} [to] - The upper bound (inclusive) if one argument is provided.
  * @param {number} [from] - The lower bound (inclusive) if two arguments are provided.
  * @param {number} [step=1] - The step size if two or more arguments are provided.
@@ -36,7 +35,6 @@ export function random(...args) {
 /**
  * Generates a random binomial value.
  * The result is the difference between two random numbers.
- *
  * @returns {number} A random binomial value.
  */
 export function randomBinomial() {

package/src/math/segment.js

@@ -12,7 +12,6 @@ const BEFORE_SEGMENT = 0
 /**
  * Calculates the coefficients [a, b, c] of the line equation ax + bz + c = 0
  * for a given segment in 2D space.
- *
  * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
  * @returns {[number, number, number]} An array [a, b, c] representing the line equation.
  */
@@ -24,7 +23,6 @@ export function coefficients(segment) {
 
 /**
  * Finds the closest point on a segment to a given point in 3D space.
- *
  * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
  * @param {Point} point - The point in 3D space represented as [x, y, z].
  * @returns {Point} The closest point on the segment to the given point.
@@ -50,7 +48,6 @@ export function closestPoint(segment, point) {
 
 /**
  * Calculates the shortest distance from a point to a segment in 3D space.
- *
  * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
  * @param {Point} point - The point in 3D space represented as [x, y, z].
  * @returns {number} The shortest distance from the point to the segment.
@@ -62,7 +59,6 @@ export function distanceFromPoint(segment, point) {
 
 /**
  * Determines whether a segment intersects with the perimeter of a circle.
- *
  * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
  * @param {Circle} circle - The circle defined by its position (center) and radius.
  * @returns {boolean} `true` if the segment intersects the circle's perimeter, otherwise `false`.

package/src/math/triangle.js

@@ -1,7 +1,6 @@
 /**
  * Calculates the length of the hypothenuse (or magnitude) for a given set of numbers
  * using the Pythagorean theorem.
- *
  * @param {number[]} nums - A list of numbers representing the sides of a right triangle.
  * @returns {number} The length of the hypothenuse.
  */
@@ -11,5 +10,6 @@ export function hypothenuse(...nums) {
 
 /**
  * Alias for the `hypothenuse` function.
+ *  @type {typeof hypothenuse}
  */
 export const pythagoras = hypothenuse

package/src/math/vector.js

@@ -31,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.
  */
@@ -51,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.
@@ -69,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]),
+      ),
     )
   }
 
@@ -79,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.
@@ -100,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)
 }
 
 /**
@@ -133,7 +130,6 @@ export function fromAngle(angle) {
  * 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.
  */
@@ -147,8 +143,6 @@ export function isVector(value) {
 
 /**
  * Calculates the magnitude (length) of the vector.
- * Alias: `length`.
- *
  * @param {Vector} vector - The input vector.
  * @returns {number} The magnitude of the vector.
  */
@@ -160,49 +154,71 @@ 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.
  * @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.
- * Aliases: `scale`, `times`.
- *
  * @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.
@@ -219,7 +235,6 @@ export function rotate(vector, angle) {
 
 /**
  * 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.
@@ -227,19 +242,17 @@ export function rotate(vector, angle) {
 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: `setLength`.
+ * Alias for the setMagnitude function.
+ * @type {typeof setMagnitude}
  */
 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.
  * @returns {Vector} The vector with the updated magnitude.
@@ -251,72 +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)),
+  )
 }
 
 /**
  * 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.
@@ -327,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, θ, φ].
  */
@@ -350,18 +355,17 @@ 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)
@@ -369,16 +373,14 @@ export function unit(angle) {
 
 /**
  * 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.

package/src/math/vector.test.js

@@ -17,6 +17,7 @@ import {
   mod,
   multiply,
   normalize,
+  power,
   rotate,
   setAngle,
   setMagnitude,
@@ -40,7 +41,7 @@ test("it should compute the absolute value of a vector's coordinates", () => {
 })
 
 test("it should compute the angle of a 2D vector", () => {
-  const vector = [1, 1]
+  const vector = v(1, 1)
   const expectedResult = pi() / 4
 
   expect(angle(vector)).toBe(expectedResult)
@@ -54,28 +55,28 @@ test("it should compute the angle of a 3D vector", () => {
 })
 
 test("it should clamp the magnitude of a vector to a certain length if too long", () => {
-  const vector = [6, 8]
+  const vector = v(6, 8)
   const min = 0
   const max = 5
-  const expectedResult = [3, 4]
+  const expectedResult = v(3, 4)
 
   expect(clamp(vector, min, max)).toStrictEqual(expectedResult)
 })
 
 test("it should not clamp the magnitude of a vector to a certain length if not too long", () => {
-  const vector = [3, 4]
+  const vector = v(3, 4)
   const min = 0
   const max = 6
-  const expectedResult = [3, 4]
+  const expectedResult = v(3, 4)
 
   expect(clamp(vector, min, max)).toStrictEqual(expectedResult)
 })
 
 test("it should clamp the magnitude of a vector to the values of other vector bounds", () => {
-  const vector = [6, 8]
+  const vector = v(6, 8)
   const lowerBound = [0, 0]
   const upperBound = [3, 4]
-  const expectedResult = [3, 4]
+  const expectedResult = v(3, 4)
 
   expect(clamp(vector, lowerBound, upperBound)).toStrictEqual(expectedResult)
 })
@@ -104,7 +105,7 @@ test("it should divide a vector by a scalar", () => {
 })
 
 test("it should build a 3D vector from a 2D one", () => {
-  const vector = [3, 4]
+  const vector = v(3, 4)
   const expectedResult = v(3, 0, 4)
 
   expect(from2D(vector)).toStrictEqual(expectedResult)
@@ -118,14 +119,14 @@ test("it should create a 3D unit vector from an angle", () => {
 })
 
 test("it should compute the magnitude of a vector (aka length)", () => {
-  const vector = [3, 4]
+  const vector = v(3, 4)
   const expectedResult = 5
 
   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([1, 2, 3])).toBe(true)
   expect(isVector([])).toBe(true)
   expect(isVector(v(1, 2, 3))).toBe(true)
 })
@@ -155,23 +156,31 @@ test("it should multiply a vector with a scalar (aka times)", () => {
 })
 
 test("it should normalize a vector so it has unit length", () => {
-  const vector = [3, 4]
-  const expectedResult = [0.6, 0.8]
+  const vector = v(3, 4)
+  const expectedResult = v(0.6, 0.8)
 
   expect(normalize(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should normalize a negative vector", () => {
-  const vector = [-3, -4]
-  const expectedResult = [-0.6, -0.8]
+  const vector = v(-3, -4)
+  const expectedResult = v(-0.6, -0.8)
 
   expect(normalize(vector)).toStrictEqual(expectedResult)
 })
 
+test("it should raise each component of a vector to the given exponent (aka pow)", () => {
+  const vector = v(1, 2, 3)
+  const exponent = 2
+  const expectedResult = v(1, 4, 9)
+
+  expect(power(vector, exponent)).toStrictEqual(expectedResult)
+})
+
 test("it should rotate a 2D vector by a certain angle", () => {
-  const vector = [1, 0]
+  const vector = v(1, 0)
   const angle = pi() / 4
-  const expectedResult = [0.7071067811865475, 0.7071067811865476] // close to [cos(pi/4), sin(pi/4)]
+  const expectedResult = v(0.7071067811865475, 0.7071067811865476) // close to [cos(pi/4), sin(pi/4)]
 
   expect(rotate(vector, angle)).toStrictEqual(expectedResult)
 })
@@ -201,32 +210,32 @@ test("it should rotate a vector that faces left by a certain angle", () => {
 })
 
 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 v(0, 0, 1)
+  const vector = v(cos(pi() / 4), 0, sin(pi() / 4))
+  const expectedResult = v(6.123233995736766e-17, 0, 1) // close to v(0, 0, 1)
 
   expect(setAngle(vector, 1.5707963267948966)).toStrictEqual(expectedResult)
 })
 
 test("it should change magnitude of a vector (aka setLength)", () => {
-  const vector = [3, 4]
+  const vector = v(3, 4)
   const magnitude = 10
-  const expectedResult = [6, 8]
+  const expectedResult = v(6, 8)
 
   expect(setMagnitude(vector, magnitude)).toStrictEqual(expectedResult)
 })
 
 test("it should change magnitude of a negative vector", () => {
-  const vector = [-3, -4]
+  const vector = v(-3, -4)
   const magnitude = 10
-  const expectedResult = [-6, -8]
+  const expectedResult = v(-6, -8)
 
   expect(setMagnitude(vector, magnitude)).toStrictEqual(expectedResult)
 })
 
 test("it should shift a vector at a certain index", () => {
-  const vector = [1, 2, 3, 4, 5]
+  const vector = v(1, 2, 3, 4, 5)
   const index = 2
-  const expectedResult = [3, 4, 5, 1, 2]
+  const expectedResult = v(3, 4, 5, 1, 2)
 
   expect(shift(vector, index)).toStrictEqual(expectedResult)
 })
@@ -241,14 +250,14 @@ test("it should snap a floating vector to a certain precision", () => {
 
 test("it should build a 2D vector from a 3D one", () => {
   const vector = v(3, 0, 4)
-  const expectedResult = [3, 4]
+  const expectedResult = v(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]
+  const vector = v(sqrt(2), pi() / 4)
+  const expectedResult = v(1.0000000000000002, 1)
 
   expect(toCartesian(vector)).toStrictEqual(expectedResult)
 })
@@ -261,28 +270,28 @@ test("it should convert a 3D cartesian vector to cylindrical coordinates", () =>
 })
 
 test("it should convert a 2D cartesian vector to polar coordinates", () => {
-  const vector = [1, 1]
-  const expectedResult = [sqrt(2), pi() / 4]
+  const vector = v(1, 1)
+  const expectedResult = v(sqrt(2), pi() / 4)
 
   expect(toPolar(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should convert a 3D cartesian vector to spherical coordinates", () => {
   const vector = v(1, 1, 1)
-  const expectedResult = [sqrt(3), Math.acos(1 / sqrt(3)), pi() / 4]
+  const expectedResult = v(sqrt(3), Math.acos(1 / sqrt(3)), pi() / 4)
 
   expect(toSpherical(vector)).toStrictEqual(expectedResult)
 })
 
 test("it should create a string representation of an integer vector", () => {
-  const vector = [3, 4]
+  const vector = v(3, 4)
   const expectedResult = "[3, 4]"
 
   expect(toString(vector)).toBe(expectedResult)
 })
 
 test("it should create a string representation of a float vector", () => {
-  const vector = [pi() / 4, pi() / 4]
+  const vector = v(pi() / 4, pi() / 4)
   const decimals = 2
   const expectedResult = "[0.79, 0.79]"
 
@@ -294,21 +303,15 @@ test("it should create a unit vector oriented on the X-axis", () => {
 })
 
 test("it should create a unit vector oriented on the Z-axis", () => {
-  expect(unit(pi() / 2)).toStrictEqual([6.123233995736766e-17, 0, 1]) // close to v(0, 0, 1)
+  expect(unit(pi() / 2)).toStrictEqual(v(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(1, 2, 3)).toStrictEqual([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)
 

package/src/math/vectors.js

@@ -4,6 +4,7 @@
  * @typedef {import('./types').Vector7} Vector7
  */
 
+import { v } from "../v.js"
 import { magnitude, shift } from "./vector.js"
 
 /**
@@ -18,7 +19,7 @@ export const add = sum
  * @returns {Vector3 | Vector7} The resulting vector after the cross product.
  */
 export function cross(...vectors) {
-  return vectors.reduce(crossMultiplyCoordinates)
+  return v(...vectors.reduce(crossMultiplyCoordinates))
 }
 
 /**
@@ -53,7 +54,7 @@ export const scalarProduct = dot
  * @returns {Vector2 | Vector3} The resulting vector after subtraction.
  */
 export function subtract(...vectors) {
-  return vectors.reduce(subtractCoordinates)
+  return v(...vectors.reduce(subtractCoordinates))
 }
 
 /**
@@ -62,7 +63,7 @@ export function subtract(...vectors) {
  * @returns {Vector2 | Vector3} The resulting vector after summation.
  */
 export function sum(...vectors) {
-  return vectors.reduce(sumCoordinates)
+  return v(...vectors.reduce(sumCoordinates))
 }
 
 /**
@@ -78,7 +79,7 @@ export const vectorProduct = cross
  * @returns {Vector2 | Vector3} The resulting vector after addition.
  */
 function sumCoordinates(vector1, vector2) {
-  return vector1.map((coordinate, index) => coordinate + vector2[index])
+  return v(...vector1.map((coordinate, index) => coordinate + vector2[index]))
 }
 
 /**
@@ -88,7 +89,7 @@ function sumCoordinates(vector1, vector2) {
  * @returns {Vector2 | Vector3} The resulting vector after subtraction.
  */
 function subtractCoordinates(vector1, vector2) {
-  return vector1.map((coordinate, index) => coordinate - vector2[index])
+  return v(...vector1.map((coordinate, index) => coordinate - vector2[index]))
 }
 
 /**
@@ -102,13 +103,17 @@ function crossMultiplyCoordinates(vector1, vector2) {
     .fill(null)
     .map((_, index) => index)
 
-  return indexes.map((_, index) => {
-    const [index1, index2] = shift(
-      indexes.filter((_, i) => i !== index),
-      index,
-    )
-    return vector1[index1] * vector2[index2] - vector1[index2] * vector2[index1]
-  })
+  return v(
+    ...indexes.map((_, index) => {
+      const [index1, index2] = shift(
+        indexes.filter((_, i) => i !== index),
+        index,
+      )
+      return (
+        vector1[index1] * vector2[index2] - vector1[index2] * vector2[index1]
+      )
+    }),
+  )
 }
 
 /**
@@ -118,5 +123,5 @@ function crossMultiplyCoordinates(vector1, vector2) {
  * @returns {Vector2 | Vector3} The resulting vector containing multiplied coordinates.
  */
 function dotMultiplyCoordinates(vector1, vector2) {
-  return vector1.map((coordinate, index) => coordinate * vector2[index])
+  return v(...vector1.map((coordinate, index) => coordinate * vector2[index]))
 }

package/src/physics/acceleration.js

@@ -14,8 +14,8 @@ const HALF_ACCELERATION = 0.5 // Half of the acceleration factor used in positio
  * Applies acceleration to an object using Euler's integration method.
  *
  * Euler's Integration:
- * v += a * dt
- * p += v * dt + 1/2 * a * dt * dt
+ * 1. v += a * dt
+ * 2. p += v * dt + 1/2 * a * dt * dt
  *
  * @param {Object} params - The parameters for the function.
  * @param {number} params.maxAcceleration - The maximum allowed acceleration.

package/src/physics/friction.js

@@ -9,7 +9,6 @@ const NO_FRICTION = 0 // No friction constant.
 
 /**
  * Applies friction to a given velocity vector.
- *
  * @param {Object} params - The parameters for the function.
  * @param {Vector3} params.velocity - The velocity vector. Defaults to a zero vector.
  * @param {number} params.friction - The friction coefficient. Defaults to 0.

package/src/physics/jump.js

@@ -11,7 +11,6 @@ const DEFAULT_MAX_SPEED = 0 // Default maximum speed.
 /**
  * Calculates the vertical velocity (vy) of a jump
  * based on the provided parameters.
- *
  * @param {Object} params - Parameters for the jump calculation.
  * @param {number} params.maxJump - Maximum jump height. Defaults to 0.
  * @param {number} params.maxLeap - Maximum leap distance. Defaults to 0.

package/src/physics/velocity.js

@@ -10,7 +10,6 @@ const DEFAULT_MAX_SPEED = 0 // Default maximum speed for velocity clamping.
 
 /**
  * Applies velocity to a position based on the given parameters and options.
- *
  * @param {Object} params - The parameters for velocity application.
  * @param {number} [params.maxSpeed] - The maximum speed for clamping the velocity. Defaults to 0.
  * @param {Vector3} [params.velocity] - The current velocity vector. Defaults to a zero vector.

package/src/v.js

@@ -3,7 +3,6 @@
  * 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.
  */

package/src/v.test.js

@@ -0,0 +1,13 @@
+import { expect, test } from "vitest"
+
+import { v } from "./v"
+
+test("a vector created with the v() function is just a number array", () => {
+  const vector = v(1, 2, 3)
+  expect(vector).toStrictEqual([1, 2, 3])
+})
+
+test("a vector created with the v() function has a __isVector__ property", () => {
+  const vector = v(1, 2, 3)
+  expect(vector.__isVector__).toBe(true)
+})