@inglorious/utils 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "2.2.0",
+  "version": "2.3.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/math/linear-algebra/types.d.ts

@@ -1,3 +1,4 @@
+export type Vector = number[]
 export type Vector2 = [number, number]
 export type Vector3 = [number, number, number]
 export type Quaternion = [number, number, number, number]

package/src/math/linear-algebra/vector.js

@@ -1,4 +1,5 @@
 /**
+ * @typedef {import('./types').Vector} Vector
  * @typedef {import('./types').Vector2} Vector2
  * @typedef {import('./types').Vector3} Vector3
  */
@@ -12,7 +13,6 @@ import {
   snap as nSnap,
 } from "../numbers.js"
 import { atan2, cos, sin } from "../trigonometry.js"
-import { from2D, to2D } from "./2d.js"
 import { quaternion } from "./quaternion.js"
 import { cross, sum } from "./vectors.js"
 
@@ -30,8 +30,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 +40,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 +50,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 +78,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 +99,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.
  */
@@ -127,8 +144,9 @@ export function isVector(value) {
 }
 
 /**
- * Calculates the magnitude of the vector.
- * @param {Vector3} vector - The input vector.
+ * Calculates the magnitude (length) of the vector.
+ *
+ * @param {Vector} vector - The input vector.
  * @returns {number} The magnitude of the vector.
  */
 export function magnitude(vector) {
@@ -137,9 +155,10 @@ export function magnitude(vector) {
 
 /**
  * Calculates the modulus of each component in the vector with the given divisor.
- * @param {Vector3} vector - The input vector.
+ *
+ * @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,9 +166,10 @@ export function mod(vector, divisor) {
 
 /**
  * Multiplies 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 multiply(vector, scalar) {
   return vector.map((coordinate) => coordinate * scalar)
@@ -157,8 +177,9 @@ export function multiply(vector, scalar) {
 
 /**
  * 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 +189,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
@@ -185,15 +208,17 @@ export function rotate(vector, angle) {
 
 /**
  * Scales the vector by the given scalar. Alias of `multiply`.
- * @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 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.
  */
@@ -210,9 +235,10 @@ export const setLength = setMagnitude
 
 /**
  * Sets the magnitude of the vector while maintaining its direction.
- * @param {Vector3} vector - The input vector.
+ *
+ * @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 +247,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,9 +258,10 @@ 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))
@@ -242,7 +270,19 @@ export function snap(vector, precision = DEFAULT_PRECISION) {
 export const times = multiply
 
 /**
- * Converts polar coordinates to Cartesian coordinates.
+ * 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 2D polar coordinates to 2D Cartesian coordinates.
+ *
  * @param {Vector2} vector - The polar coordinates [magnitude, angle].
  * @returns {Vector2} The Cartesian coordinates [x, y].
  */
@@ -251,9 +291,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 +303,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 +314,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 +352,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 +366,19 @@ export function unit(angle) {
 }
 
 /**
- * Creates a zero vector.
+ * 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() {
@@ -330,7 +386,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.

package/src/math/linear-algebra/vector.test.js

@@ -9,7 +9,9 @@ import {
   conjugate,
   createVector,
   divide,
+  from2D,
   fromAngle,
+  isVector,
   magnitude,
   mod,
   multiply,
@@ -19,12 +21,15 @@ import {
   setMagnitude,
   shift,
   snap,
+  to2D,
   toCartesian,
   toCylindrical,
   toPolar,
   toSpherical,
   toString,
   unit,
+  v,
+  zero,
 } from "./vector.js"
 
 test("it should compute the absolute value of a vector's coordinates", () => {
@@ -98,6 +103,13 @@ test("it should divide a vector by a scalar", () => {
   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]
+
+  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)]
@@ -112,6 +124,19 @@ test("it should compute the magnitude of a vector (aka length)", () => {
   expect(magnitude(vector)).toBe(expectedResult)
 })
 
+test("it should check if a value is a vector", () => {
+  expect(isVector([1, 2, 3])).toBe(true)
+  expect(isVector([])).toBe(true)
+})
+
+test("it should check if a value is not a vector", () => {
+  expect(isVector([1, "a", 3])).toBe(false)
+  expect(isVector({ x: 1, y: 2 })).toBe(false)
+  expect(isVector(null)).toBe(false)
+  expect(isVector("vector")).toBe(false)
+  expect(isVector(123)).toBe(false)
+})
+
 test("it should apply the mod operator (aka remainder) on a vector", () => {
   const vector = [10, 12, -18]
   const divisor = 12
@@ -213,6 +238,13 @@ test("it should snap a floating vector to a certain precision", () => {
   expect(snap(vector, precision)).toStrictEqual(expectedResult)
 })
 
+test("it should build a 2D vector from a 3D one", () => {
+  const vector = [3, 0, 4]
+  const expectedResult = [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]
@@ -263,3 +295,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 [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()).toStrictEqual([])
+  expect(v(0, -5.5)).toStrictEqual([0, -5.5])
+})
+
+test("it should create a 3D zero vector", () => {
+  const expectedResult = [0, 0, 0]
+
+  expect(zero()).toStrictEqual(expectedResult)
+})

package/src/math/linear-algebra/2d.js

@@ -1,28 +0,0 @@
-/**
- * @typedef {import('../../../types').Vector2} Vector2
- * @typedef {import('../../../types').Vector3} Vector3
- */
-
-const NO_Y = 0 // Default Y-coordinate value for 3D vectors derived from 2D vectors.
-
-/**
- * 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]
-}
-
-/**
- * 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]
-}

package/src/math/linear-algebra/2d.test.js

@@ -1,17 +0,0 @@
-import { expect, test } from "vitest"
-
-import { from2D, to2D } from "./2d.js"
-
-test("build a 3D vector from a 2D one", () => {
-  const vector = [3, 4]
-  const expectedResult = [3, 0, 4]
-
-  expect(from2D(vector)).toStrictEqual(expectedResult)
-})
-
-test("build a 2D vector from a 3D one", () => {
-  const vector = [3, 0, 4]
-  const expectedResult = [3, 4]
-
-  expect(to2D(vector)).toStrictEqual(expectedResult)
-})