@inglorious/utils 3.5.3 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "3.5.3",
+  "version": "3.6.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",
@@ -41,7 +41,7 @@
     "prettier": "^3.6.2",
     "vite": "^7.1.3",
     "vitest": "^1.6.1",
-    "@inglorious/eslint-config": "1.0.0"
+    "@inglorious/eslint-config": "1.0.1"
   },
   "engines": {
     "node": ">= 22"

package/src/functions/functions.js

@@ -1,19 +1,31 @@
 /**
  * Composes multiple functions from right to left, as if every function wraps the next one.
+ * The first function (rightmost) can take multiple arguments; the remaining functions must be unary.
  *
  * @param {...Function} fns - Functions to compose.
- * @returns {Function} A function that takes an initial value and applies the composed functions.
+ * @returns {Function} A function that takes the initial arguments and applies the composed functions.
  */
 export function compose(...fns) {
-  return (x) => fns.reduceRight((acc, fn) => fn(acc), x)
+  if (!fns.length) {
+    return (x) => x
+  }
+
+  const [last, ...rest] = fns.reverse()
+  return (...args) => rest.reduce((acc, fn) => fn(acc), last(...args))
 }
 
 /**
  * Pipes multiple functions from left to right, as if the functions are applied one by one.
+ * The first function (leftmost) can take multiple arguments; the remaining functions must be unary.
  *
  * @param {...Function} fns - Functions to pipe.
- * @returns {Function} A function that takes an initial value and applies the piped functions.
+ * @returns {Function} A function that takes the initial arguments and applies the piped functions.
  */
 export function pipe(...fns) {
-  return (x) => fns.reduce((acc, fn) => fn(acc), x)
+  if (!fns.length) {
+    return (x) => x
+  }
+
+  const [first, ...rest] = fns
+  return (...args) => rest.reduce((acc, fn) => fn(acc), first(...args))
 }

package/src/functions/functions.test.js

@@ -2,22 +2,50 @@ import { expect, test } from "vitest"
 
 import { compose, pipe } from "./functions.js"
 
-test("it should compose functions", () => {
+test("it should compose unary functions", () => {
   const shout = (x) => x.toUpperCase()
   const punctuate = (mark) => (x) => `${x}${mark}`
   const html = (tag) => (x) => `<${tag}>${x}</${tag}>`
 
   const fn = compose(html("p"), punctuate("!"), shout)
-
   expect(fn("Hello world")).toBe("<p>HELLO WORLD!</p>")
 })
 
-test("it should pipe functions", () => {
+test("it should compose functions with multiple initial arguments", () => {
+  const add = (a, b) => a + b
+  const square = (x) => x * x
+  const half = (x) => x / 2
+
+  const fn = compose(half, square, add) // half(square(add(2, 3)))
+  expect(fn(2, 3)).toBe(12.5)
+})
+
+test("it should return an identity-like function if compose is called with no arguments", () => {
+  const fn = compose()
+  expect(fn(42)).toBe(42)
+  expect(fn({ a: 1 })).toStrictEqual({ a: 1 })
+})
+
+test("it should pipe unary functions", () => {
   const shout = (x) => x.toUpperCase()
   const punctuate = (mark) => (x) => `${x}${mark}`
   const html = (tag) => (x) => `<${tag}>${x}</${tag}>`
 
   const fn = pipe(shout, punctuate("!"), html("p"))
-
   expect(fn("Hello world")).toBe("<p>HELLO WORLD!</p>")
 })
+
+test("it should pipe functions with multiple initial arguments", () => {
+  const add = (a, b) => a + b
+  const square = (x) => x * x
+  const half = (x) => x / 2
+
+  const fn = pipe(add, square, half) // half(square(add(2, 3)))
+  expect(fn(2, 3)).toBe(12.5)
+})
+
+test("it should return an identity-like function if pipe is called with no arguments", () => {
+  const fn = pipe()
+  expect(fn(42)).toBe(42)
+  expect(fn({ a: 1 })).toStrictEqual({ a: 1 })
+})

package/src/math/numbers.js

@@ -54,11 +54,15 @@ export function isClose(num1, num2, tolerance = DEFAULT_TOLERANCE) {
 
 /**
  * Computes the modulus of two numbers, ensuring a positive result.
+ * If the divisor is zero, it returns the dividend to avoid `NaN`.
  * @param {number} dividend - The number to be divided.
  * @param {number} divisor - The number to divide by.
  * @returns {number} The modulus result.
  */
 export function mod(dividend, divisor) {
+  if (!divisor) {
+    return dividend
+  }
   return ((dividend % divisor) + divisor) % divisor
 }
 

package/src/math/numbers.test.js

@@ -154,6 +154,13 @@ test("it should convert a negative float number to a range between -1 and 1", ()
   expect(mod(num, divisor)).toBe(expectedResult)
 })
 
+test("it should return the dividend if the divisor is zero", () => {
+  const num = 42
+  const divisor = 0
+
+  expect(mod(num, divisor)).toBe(num)
+})
+
 test("it should return one if number is positive", () => {
   const num = 42
   const expectedResult = 1

package/src/math/vector.js

@@ -96,6 +96,16 @@ export function createVector(magnitude, angle) {
   return scale(fromAngle(angle), magnitude)
 }
 
+/**
+ * Divides a scalar by each component of the vector.
+ * @param {number} scalar - The dividend.
+ * @param {Vector} vector - The divisor vector.
+ * @returns {Vector} The resulting vector.
+ */
+export function divideBy(scalar, vector) {
+  return v(...vector.map((coordinate) => scalar / coordinate))
+}
+
 /**
  * Divides each component of the vector by the given scalar.
  * @param {Vector} vector - The input vector.
@@ -157,6 +167,16 @@ export function mod(vector, divisor) {
   return v(...vector.map((coordinate) => nMod(coordinate, divisor)))
 }
 
+/**
+ * Calculates the modulus of a scalar with each component of the vector.
+ * @param {number} scalar - The dividend.
+ * @param {Vector} vector - The divisor vector.
+ * @returns {Vector} The resulting vector.
+ */
+export function modOf(scalar, vector) {
+  return v(...vector.map((coordinate) => nMod(scalar, coordinate)))
+}
+
 /**
  * Multiplies each component of the vector by the given scalar.
  * @param {Vector} vector - The input vector.
@@ -184,16 +204,14 @@ export function power(vector, exponent) {
 }
 
 /**
- * Alias for the multiply function.
- * @type {typeof multiply}
- */
-export const scale = multiply
-
-/**
- * Alias for the multiply function.
- * @type {typeof multiply}
+ * Raises a scalar to the power of each component of the vector.
+ * @param {number} scalar - The base value.
+ * @param {Vector} vector - The exponent vector.
+ * @returns {Vector} The resulting vector.
  */
-export const times = multiply
+export function powerOf(scalar, vector) {
+  return v(...vector.map((coordinate) => scalar ** coordinate))
+}
 
 /**
  * Normalizes the vector to have a magnitude of 1.
@@ -228,6 +246,12 @@ export function rotate(vector, angle) {
   return is2D ? to2D(result) : result
 }
 
+/**
+ * Alias for the multiply function.
+ * @type {typeof multiply}
+ */
+export const scale = multiply
+
 /**
  * Sets the angle of the vector in the XZ plane while maintaining its magnitude.
  * @param {Vector} vector - The input vector.
@@ -279,6 +303,12 @@ export function snap(vector, precision = DEFAULT_PRECISION) {
   )
 }
 
+/**
+ * Alias for the multiply function.
+ * @type {typeof multiply}
+ */
+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].

package/src/math/vector.test.js

@@ -10,14 +10,17 @@ import {
   conjugate,
   createVector,
   divide,
+  divideBy,
   from2D,
   fromAngle,
   isVector,
   magnitude,
   mod,
+  modOf,
   multiply,
   normalize,
   power,
+  powerOf,
   rotate,
   setAngle,
   setMagnitude,
@@ -104,6 +107,14 @@ test("it should divide a vector by a scalar", () => {
   expect(divide(vector, scalar)).toStrictEqual(expectedResult)
 })
 
+test("it should divide a scalar by a vector", () => {
+  const scalar = 12
+  const vector = v(4, 8, 12)
+  const expectedResult = v(3, 1.5, 1)
+
+  expect(divideBy(scalar, vector)).toStrictEqual(expectedResult)
+})
+
 test("it should build a 3D vector from a 2D one", () => {
   const vector = v(3, 4)
   const expectedResult = v(3, 0, 4)
@@ -146,6 +157,14 @@ test("it should apply the mod operator (aka remainder) on a vector", () => {
   expect(mod(vector, divisor)).toStrictEqual(expectedResult)
 })
 
+test("it should apply the mod operator of a scalar with a vector", () => {
+  const scalar = 18
+  const vector = v(10, 12, -18)
+  const expectedResult = v(8, 6, -0)
+
+  expect(modOf(scalar, vector)).toStrictEqual(expectedResult)
+})
+
 test("it should multiply a vector with a scalar (aka times)", () => {
   const vector = v(1, 2, 3)
   const scalar = 4
@@ -176,6 +195,14 @@ test("it should raise each component of a vector to the given exponent (aka pow)
   expect(power(vector, exponent)).toStrictEqual(expectedResult)
 })
 
+test("it should raise a scalar to the power of each component of a vector", () => {
+  const scalar = 2
+  const vector = v(1, 2, 3)
+  const expectedResult = v(2, 4, 8)
+
+  expect(powerOf(scalar, vector)).toStrictEqual(expectedResult)
+})
+
 test("it should rotate a 2D vector by a certain angle", () => {
   const vector = v(1, 0)
   const angle = pi() / 4

package/src/math/vectors.js

@@ -5,6 +5,7 @@
  */
 
 import { v } from "../v.js"
+import { mod as nMod } from "./numbers.js"
 import { magnitude, shift } from "./vector.js"
 
 /**
@@ -31,6 +32,15 @@ export function distance(...vectors) {
   return magnitude(subtract(...vectors))
 }
 
+/**
+ * Computes the component-wise division of multiple vectors.
+ * @param {...Vector2 | Vector3} vectors - The vectors to divide.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+export function divide(...vectors) {
+  return v(...vectors.reduce(divideCoordinates))
+}
+
 /**
  * Computes the dot product of multiple vectors.
  * @param {...Vector2 | Vector3} vectors - The vectors to compute the dot product for.
@@ -42,6 +52,39 @@ export function dot(...vectors) {
     .reduce((coord1, coord2) => coord1 + coord2)
 }
 
+/**
+ * Alias for the multiply function.
+ * @type {typeof multiply}
+ */
+export const hadamard = multiply
+
+/**
+ * Computes the component-wise modulus of multiple vectors.
+ * @param {...Vector2 | Vector3} vectors - The vectors to compute the modulus for.
+ * @returns {Vector2 | Vector3} The resulting vector after the modulus.
+ */
+export function mod(...vectors) {
+  return v(...vectors.reduce(modCoordinates))
+}
+
+/**
+ * Computes the component-wise multiplication of multiple vectors (Hadamard product).
+ * @param {...Vector2 | Vector3} vectors - The vectors to multiply.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+export function multiply(...vectors) {
+  return v(...vectors.reduce(multiplyCoordinates))
+}
+
+/**
+ * Computes the component-wise power of multiple vectors.
+ * @param {...Vector2 | Vector3} vectors - The vectors to compute the power for.
+ * @returns {Vector2 | Vector3} The resulting vector after the power.
+ */
+export function power(...vectors) {
+  return v(...vectors.reduce(powerCoordinates))
+}
+
 /**
  * Alias for the dot product function.
  * @type {typeof dot}
@@ -92,6 +135,48 @@ function subtractCoordinates(vector1, vector2) {
   return v(...vector1.map((coordinate, index) => coordinate - vector2[index]))
 }
 
+/**
+ * Divides the coordinates of two vectors component-wise.
+ * @param {Vector2 | Vector3} vector1 - The dividend vector.
+ * @param {Vector2 | Vector3} vector2 - The divisor vector.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+function divideCoordinates(vector1, vector2) {
+  return v(...vector1.map((coordinate, index) => coordinate / vector2[index]))
+}
+
+/**
+ * Computes the component-wise modulus of two vectors.
+ * @param {Vector2 | Vector3} vector1 - The first vector.
+ * @param {Vector2 | Vector3} vector2 - The second vector.
+ * @returns {Vector2 | Vector3} The resulting vector after the modulus.
+ */
+function modCoordinates(vector1, vector2) {
+  return v(
+    ...vector1.map((coordinate, index) => nMod(coordinate, vector2[index])),
+  )
+}
+
+/**
+ * Multiplies the coordinates of two vectors component-wise.
+ * @param {Vector2 | Vector3} vector1 - The first vector.
+ * @param {Vector2 | Vector3} vector2 - The second vector.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+function multiplyCoordinates(vector1, vector2) {
+  return v(...vector1.map((coordinate, index) => coordinate * vector2[index]))
+}
+
+/**
+ * Raises the coordinates of the first vector to the power of the second vector's coordinates.
+ * @param {Vector2 | Vector3} vector1 - The base vector.
+ * @param {Vector2 | Vector3} vector2 - The exponent vector.
+ * @returns {Vector2 | Vector3} The resulting vector.
+ */
+function powerCoordinates(vector1, vector2) {
+  return v(...vector1.map((coordinate, index) => coordinate ** vector2[index]))
+}
+
 /**
  * Computes the cross product of two vectors' coordinates.
  * @param {Vector3} vector1 - The first vector.

package/src/math/vectors.test.js

@@ -1,7 +1,16 @@
 import { expect, test } from "vitest"
 
 import { v } from "../v.js"
-import { cross, distance, dot, subtract, sum } from "./vectors.js"
+import {
+  cross,
+  distance,
+  divide,
+  dot,
+  multiply,
+  power,
+  subtract,
+  sum,
+} from "./vectors.js"
 
 test("it should compute the cross product between two vectors (aka vectorProduct)", () => {
   const vector1 = v(1, 2, 3)
@@ -25,6 +34,13 @@ test("it should compute the distance between multiple vectors", () => {
   expect(distance(...vectors)).toStrictEqual(expectedResult)
 })
 
+test("it should divide multiple vectors component-wise", () => {
+  const vectors = [v(80, 40, 20), v(2, 4, 5), v(2, 2, 2)]
+  const expectedResult = v(20, 5, 2)
+
+  expect(divide(...vectors)).toStrictEqual(expectedResult)
+})
+
 test("it should compute the dot product of multiple vectors (aka scalarProduct)", () => {
   const vectors = [v(1, 2, 3), v(4, 5, 6), v(7, 8, 9)]
   const expectedResult = 270
@@ -32,6 +48,20 @@ test("it should compute the dot product of multiple vectors (aka scalarProduct)"
   expect(dot(...vectors)).toStrictEqual(expectedResult)
 })
 
+test("it should multiply multiple vectors component-wise (Hadamard product)", () => {
+  const vectors = [v(1, 2, 3), v(4, 5, 6), v(2, 2, 2)]
+  const expectedResult = v(8, 20, 36)
+
+  expect(multiply(...vectors)).toStrictEqual(expectedResult)
+})
+
+test("it should raise a vector to the power of another vector", () => {
+  const vectors = [v(2, 3, 4), v(4, 3, 2)]
+  const expectedResult = v(16, 27, 16)
+
+  expect(power(...vectors)).toStrictEqual(expectedResult)
+})
+
 test("it should subtract multiple vectors", () => {
   const vectors = [v(1, 2, 3), v(4, 5, 6), v(7, 8, 9)]
   const expectedResult = v(-10, -11, -12)

package/types/algorithms.d.ts

@@ -1,26 +1,26 @@
-/**
- * Represents the input conditions to be evaluated by a decision tree node.
- * The `unknown` type is used to allow for flexible condition structures.
- */
-export type Conditions = unknown
-
-/**
- * Represents the result of a decision tree's `test` function, which is used
- * as a key to determine the next branch.
- */
-export type Outcome = string
-
-/**
- * Represents a node in a decision tree. It consists of:
- * - A `test` function that evaluates conditions and returns an outcome.
- * - A map of outcomes to subsequent actions, which can be either a final outcome
- *   or another `DecisionTree` node.
- */
-export type DecisionTree = {
-  /**
-   * A function that takes a set of conditions and returns an outcome string.
-   * @param conditions - The conditions to evaluate.
-   * @returns The outcome of the test.
-   */
-  test: (conditions: Conditions) => Outcome
-} & Record<Outcome, () => Outcome | DecisionTree>
+/**
+ * Represents the input conditions to be evaluated by a decision tree node.
+ * The `unknown` type is used to allow for flexible condition structures.
+ */
+export type Conditions = unknown
+
+/**
+ * Represents the result of a decision tree's `test` function, which is used
+ * as a key to determine the next branch.
+ */
+export type Outcome = string
+
+/**
+ * Represents a node in a decision tree. It consists of:
+ * - A `test` function that evaluates conditions and returns an outcome.
+ * - A map of outcomes to subsequent actions, which can be either a final outcome
+ *   or another `DecisionTree` node.
+ */
+export type DecisionTree = {
+  /**
+   * A function that takes a set of conditions and returns an outcome string.
+   * @param conditions - The conditions to evaluate.
+   * @returns The outcome of the test.
+   */
+  test: (conditions: Conditions) => Outcome
+} & Record<Outcome, () => Outcome | DecisionTree>

package/types/data-structures.d.ts

@@ -1,53 +1,53 @@
-/**
- * Represents a generic tree data structure.
- * Each node in the tree has a value and an array of child nodes.
- * @template T - The type of the value stored in the tree nodes. Defaults to `any`.
- */
-export interface Tree<T = any> {
-  /** The value of the current node. */
-  value: T
-  /** An array of child `Tree` nodes. */
-  children: Tree<T>[]
-}
-
-/**
- * A map where keys are node identifiers and values are their [x, y] coordinates.
- * Used for efficient node lookups by ID.
- */
-export interface NodeMap {
-  [id: string]: [number, number] // [x, y]
-}
-
-/**
- * Represents a node in a graph.
- */
-export interface Node {
-  /** A unique identifier for the node. */
-  id: string
-  /** The [x, y] coordinates of the node. */
-  position: [number, number] // [x, y]
-  /** An optional cost associated with traversing to this node. */
-  cost?: number
-}
-
-/**
- * Represents a directed edge (or arc) between two nodes in a graph.
- */
-export interface Arc {
-  /** The ID of the starting node. */
-  from: string
-  /** The ID of the ending node. */
-  to: string
-  /** An optional cost associated with traversing this arc. */
-  cost?: number
-}
-
-/**
- * Represents a graph structure consisting of nodes and arcs.
- */
-export interface Graph {
-  /** The nodes of the graph, as either an array or a map for efficient lookups. */
-  nodes: NodeMap | Node[]
-  /** An array of arcs connecting the nodes. */
-  arcs: Arc[]
-}
+/**
+ * Represents a generic tree data structure.
+ * Each node in the tree has a value and an array of child nodes.
+ * @template T - The type of the value stored in the tree nodes. Defaults to `any`.
+ */
+export interface Tree<T = any> {
+  /** The value of the current node. */
+  value: T
+  /** An array of child `Tree` nodes. */
+  children: Tree<T>[]
+}
+
+/**
+ * A map where keys are node identifiers and values are their [x, y] coordinates.
+ * Used for efficient node lookups by ID.
+ */
+export interface NodeMap {
+  [id: string]: [number, number] // [x, y]
+}
+
+/**
+ * Represents a node in a graph.
+ */
+export interface Node {
+  /** A unique identifier for the node. */
+  id: string
+  /** The [x, y] coordinates of the node. */
+  position: [number, number] // [x, y]
+  /** An optional cost associated with traversing to this node. */
+  cost?: number
+}
+
+/**
+ * Represents a directed edge (or arc) between two nodes in a graph.
+ */
+export interface Arc {
+  /** The ID of the starting node. */
+  from: string
+  /** The ID of the ending node. */
+  to: string
+  /** An optional cost associated with traversing this arc. */
+  cost?: number
+}
+
+/**
+ * Represents a graph structure consisting of nodes and arcs.
+ */
+export interface Graph {
+  /** The nodes of the graph, as either an array or a map for efficient lookups. */
+  nodes: NodeMap | Node[]
+  /** An array of arcs connecting the nodes. */
+  arcs: Arc[]
+}

package/types/index.d.ts

@@ -1,4 +1,4 @@
-export * from "./algorithms"
-export * from "./data-structures"
-export * from "./math"
-export * from "./v"
+export * from "./algorithms"
+export * from "./data-structures"
+export * from "./math"
+export * from "./v"

package/types/math.d.ts

@@ -1,90 +1,90 @@
-// geometry
-
-/**
- * Represents a point in 3D space using a readonly tuple of numbers.
- * @public
- */
-export type Point = readonly [number, number, number] // [x, y, z]
-
-/**
- * Represents the dimensions of an object in 3D space.
- * @public
- */
-export type Size = readonly [number, number, number] // [width, height, depth]
-
-/**
- * Represents a line in 2D space in the form `ax + by + c = 0`.
- * @public
- */
-export type Line = readonly [number, number, number] // [a, b, c]
-
-/**
- * Represents a circle with a position and radius.
- * @public
- */
-export interface Circle {
-  /** The center point of the circle. */
-  position: Point
-  /** The radius of the circle. */
-  radius: number
-}
-
-/**
- * Represents a rectangle with a position and size.
- * @public
- */
-export interface Rectangle {
-  /** The top-left corner point of the rectangle. */
-  position: Point
-  /** The dimensions of the rectangle. */
-  size: Size
-}
-
-/**
- * Represents a platform, typically for physics or collision detection.
- * @public
- */
-export interface Platform {
-  /** The position of the platform. */
-  position: Point
-  /** The dimensions of the platform. */
-  size: Size
-}
-
-/**
- * Represents a line segment defined by two points.
- * @public
- */
-export interface Segment {
-  /** The starting point of the segment. */
-  from: Point
-  /** The ending point of the segment. */
-  to: Point
-}
-
-// linear algebra
-
-/**
- * A nominal type brand to identify vector types.
- * This prevents accidental assignment of a plain number array to a vector.
- * @internal
- */
-type IsVector = {
-  readonly __isVector__: true
-}
-
-/** A generic, dynamically-sized vector. */
-export type Vector = IsVector & readonly number[]
-
-/** A 2-dimensional vector. */
-export type Vector2 = IsVector & readonly [number, number]
-
-/** A 3-dimensional vector. */
-export type Vector3 = IsVector & readonly [number, number, number]
-
-/** A 4-dimensional vector, often used for quaternions. */
-export type Quaternion = IsVector & readonly [number, number, number, number]
-
-/** A 7-dimensional vector. */
-export type Vector7 = IsVector &
-  readonly [number, number, number, number, number, number, number]
+// geometry
+
+/**
+ * Represents a point in 3D space using a readonly tuple of numbers.
+ * @public
+ */
+export type Point = readonly [number, number, number] // [x, y, z]
+
+/**
+ * Represents the dimensions of an object in 3D space.
+ * @public
+ */
+export type Size = readonly [number, number, number] // [width, height, depth]
+
+/**
+ * Represents a line in 2D space in the form `ax + by + c = 0`.
+ * @public
+ */
+export type Line = readonly [number, number, number] // [a, b, c]
+
+/**
+ * Represents a circle with a position and radius.
+ * @public
+ */
+export interface Circle {
+  /** The center point of the circle. */
+  position: Point
+  /** The radius of the circle. */
+  radius: number
+}
+
+/**
+ * Represents a rectangle with a position and size.
+ * @public
+ */
+export interface Rectangle {
+  /** The top-left corner point of the rectangle. */
+  position: Point
+  /** The dimensions of the rectangle. */
+  size: Size
+}
+
+/**
+ * Represents a platform, typically for physics or collision detection.
+ * @public
+ */
+export interface Platform {
+  /** The position of the platform. */
+  position: Point
+  /** The dimensions of the platform. */
+  size: Size
+}
+
+/**
+ * Represents a line segment defined by two points.
+ * @public
+ */
+export interface Segment {
+  /** The starting point of the segment. */
+  from: Point
+  /** The ending point of the segment. */
+  to: Point
+}
+
+// linear algebra
+
+/**
+ * A nominal type brand to identify vector types.
+ * This prevents accidental assignment of a plain number array to a vector.
+ * @internal
+ */
+type IsVector = {
+  readonly __isVector__: true
+}
+
+/** A generic, dynamically-sized vector. */
+export type Vector = IsVector & readonly number[]
+
+/** A 2-dimensional vector. */
+export type Vector2 = IsVector & readonly [number, number]
+
+/** A 3-dimensional vector. */
+export type Vector3 = IsVector & readonly [number, number, number]
+
+/** A 4-dimensional vector, often used for quaternions. */
+export type Quaternion = IsVector & readonly [number, number, number, number]
+
+/** A 7-dimensional vector. */
+export type Vector7 = IsVector &
+  readonly [number, number, number, number, number, number, number]

package/types/v.d.ts

@@ -1,25 +1,25 @@
-import { Vector } from "./math"
-
-/**
- * Ensures that a given value is a vector.
- *
- * If the value is an array of finite numbers but not already a vector (i.e., it lacks the `__isVector__` property),
- * this function converts it into a vector by calling `v()`. If the value is already a vector or not a numeric array,
- * it is returned unchanged. This is particularly useful for ensuring that the results of standard array operations
- * (like `.map()` or `.filter()`) which return a new array are correctly re-tagged as vectors.
- *
- * @template T
- * @param {T} value The value to check and potentially convert.
- * @returns {T extends number[] ? Vector : T} The value as a vector, or the original value if no conversion was needed.
- */
-export function ensureV<T>(value: T): T extends number[] ? Vector : T
-
-/**
- * A utility function to create a vector from a list of coordinates.
- * 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.
- */
-export function v(...coords: number[]): Vector
+import { Vector } from "./math"
+
+/**
+ * Ensures that a given value is a vector.
+ *
+ * If the value is an array of finite numbers but not already a vector (i.e., it lacks the `__isVector__` property),
+ * this function converts it into a vector by calling `v()`. If the value is already a vector or not a numeric array,
+ * it is returned unchanged. This is particularly useful for ensuring that the results of standard array operations
+ * (like `.map()` or `.filter()`) which return a new array are correctly re-tagged as vectors.
+ *
+ * @template T
+ * @param {T} value The value to check and potentially convert.
+ * @returns {T extends number[] ? Vector : T} The value as a vector, or the original value if no conversion was needed.
+ */
+export function ensureV<T>(value: T): T extends number[] ? Vector : T
+
+/**
+ * A utility function to create a vector from a list of coordinates.
+ * 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.
+ */
+export function v(...coords: number[]): Vector