@inglorious/utils 3.2.0 → 3.4.0

package/package.json

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

package/src/math/rng.js

@@ -1,5 +1,18 @@
 /* eslint-disable no-magic-numbers */
 
+/**
+ * Chooses a random value from the given arguments.
+ * @param {...*} values - The values to choose from.
+ * @returns {*} A randomly selected value.
+ */
+export function choose(...values) {
+  if (!values.length) {
+    return undefined
+  }
+  const index = random(values.length - 1)
+  return values[index]
+}
+
 /**
  * Generates a random number.
  * - If no arguments are provided, returns a random float between 0 (inclusive) and 1 (exclusive).

package/src/math/rng.test.js

@@ -1,6 +1,13 @@
 import { expect, test } from "vitest"
 
-import { random, randomBinomial } from "./rng.js"
+import { choose, random, randomBinomial } from "./rng.js"
+
+test("it should choose a random value from the given arguments", () => {
+  const values = ["a", "b", "c"]
+  const chosenValue = choose(...values)
+
+  expect(values).toContain(chosenValue)
+})
 
 test("it should create a random number in the range [0, 1)", () => {
   const randomNumber = random()

package/src/math/vector.js

@@ -4,7 +4,6 @@
  * @typedef {import('./types').Vector3} Vector3
  */
 
-import { isArray } from "../data-structures/array.js"
 import { v } from "../v.js"
 import {
   abs as nAbs,
@@ -94,7 +93,7 @@ export function conjugate(vector) {
  * @returns {Vector3} The created 3D vector.
  */
 export function createVector(magnitude, angle) {
-  return multiply(fromAngle(angle), magnitude)
+  return scale(fromAngle(angle), magnitude)
 }
 
 /**
@@ -128,17 +127,13 @@ 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.
+ * This is determined by checking for the `__isVector__` property, which is
+ * added by the `v()` factory function for efficient type checking.
  * @param {*} value - The value to check.
  * @returns {boolean} True if the value is a vector, false otherwise.
  */
 export function isVector(value) {
-  return (
-    value?.__isVector__ ||
-    (isArray(value) &&
-      value.every((coordinate) => typeof coordinate === "number"))
-  )
+  return !!value?.__isVector__
 }
 
 /**
@@ -226,9 +221,9 @@ export const remainder = mod
 export function rotate(vector, angle) {
   const is2D = vector.length === TWO_COORDINATES
 
-  let v = is2D ? from2D(vector) : vector
+  const vector3 = is2D ? from2D(vector) : vector
 
-  let result = rotateWithQuaternion(v, angle)
+  const result = rotateWithQuaternion(vector3, angle)
 
   return is2D ? to2D(result) : result
 }
@@ -259,7 +254,7 @@ export const setLength = setMagnitude
  */
 export function setMagnitude(vector, length) {
   const normalized = normalize(vector)
-  return multiply(normalized, length)
+  return scale(normalized, length)
 }
 
 /**
@@ -394,7 +389,7 @@ function rotateWithQuaternion(vector, angle) {
   const [w, ...r] = quaternion(angle)
   const result = sum(
     vector,
-    cross(multiply(r, 2), sum(cross(r, vector), multiply(vector, w))), // eslint-disable-line no-magic-numbers
+    cross(scale(r, 2), sum(cross(r, vector), scale(vector, w))), // eslint-disable-line no-magic-numbers
   )
 
   return conjugate(result) // HACK: not really sure why I should invert the result, it just works this way

package/src/math/vector.test.js

@@ -126,8 +126,7 @@ test("it should compute the magnitude of a vector (aka length)", () => {
 })
 
 test("it should check if a value is a vector", () => {
-  expect(isVector([1, 2, 3])).toBe(true)
-  expect(isVector([])).toBe(true)
+  expect(isVector([1, 2, 3])).toBe(false)
   expect(isVector(v(1, 2, 3))).toBe(true)
 })
 

package/src/v.js

@@ -1,3 +1,27 @@
+import { isArray } from "./data-structures/array"
+
+/**
+ * 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.
+ * @param {*} value The value to check and potentially convert.
+ * @returns {Vector|*} The value as a vector, or the original value if no conversion was needed.
+ */
+export function ensureV(value) {
+  if (
+    isArray(value) &&
+    !value.__isVector__ &&
+    value.every((coord) => isFinite(coord))
+  ) {
+    return v(...value)
+  }
+
+  return value
+}
+
 /**
  * A utility function to create a vector from a list of coordinates.
  * This is a shorthand for `[x, y, z, ...]`.

package/src/v.test.js

@@ -1,6 +1,41 @@
 import { expect, test } from "vitest"
 
-import { v } from "./v"
+import { ensureV, v } from "./v"
+
+test("ensureV() should convert a numeric array into a vector", () => {
+  const array = [1, 2, 3]
+  const result = ensureV(array)
+  expect(result).toStrictEqual([1, 2, 3])
+  expect(result.__isVector__).toBe(true)
+})
+
+test("ensureV() should return an existing vector unchanged", () => {
+  const vector = v(4, 5, 6)
+  const result = ensureV(vector)
+  expect(result).toBe(vector)
+  expect(result.__isVector__).toBe(true)
+})
+
+test("ensureV() should not convert an array with non-finite numbers", () => {
+  const array = [1, Infinity, 3]
+  const result = ensureV(array)
+  expect(result).toBe(array)
+  expect(result.__isVector__).toBeUndefined()
+})
+
+test("ensureV() should not convert an array with non-numeric values", () => {
+  const array = [1, "a", 3]
+  const result = ensureV(array)
+  expect(result).toBe(array)
+  expect(result.__isVector__).toBeUndefined()
+})
+
+test("ensureV() should return non-array values unchanged", () => {
+  expect(ensureV(123)).toBe(123)
+  expect(ensureV("hello")).toBe("hello")
+  const obj = { a: 1 }
+  expect(ensureV(obj)).toBe(obj)
+})
 
 test("a vector created with the v() function is just a number array", () => {
   const vector = v(1, 2, 3)