@inglorious/utils 3.3.0 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "3.3.0",
+  "version": "3.5.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,22 +1,47 @@
 /* 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).
- * - 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.
+ * - If one argument (`to`) is provided, returns a random integer between 0 and `to` (inclusive).
+ * - If two arguments (`from`, `to`) are provided:
+ *   - If they are integers, returns a random integer between `from` and `to` (inclusive).
+ *   - If they are floats, returns a random float between `from` (inclusive) and `to` (exclusive).
+ * - If three arguments (`from`, `to`, `step`) are provided, returns a random integer within the specified range and step.
+ * @param {number} [to] - The upper bound.
+ * @param {number} [from] - The lower bound.
  * @param {number} [step=1] - The step size if two or more arguments are provided.
  * @returns {number} A random number based on the provided arguments.
  */
 export function random(...args) {
-  let step, from, to
-
   if (!args.length) {
     return Math.random()
   }
 
+  if (
+    args.length > 1 &&
+    !Number.isInteger(args[0]) &&
+    !Number.isInteger(args[1])
+  ) {
+    const [from, to] = args
+    return Math.random() * (to - from) + from
+  }
+
+  let step, from, to
+
   if (args.length === 1) {
     step = 1
     from = 0

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()
@@ -31,6 +38,15 @@ test("it should create a random even number in the range [2, 6]", () => {
   expect(randomNumber % 2).toBe(0)
 })
 
+test("it should create a random float in the range [1.5, 6.5)", () => {
+  const from = 1.5
+  const to = 6.5
+  const randomNumber = random(from, to)
+
+  expect(randomNumber).toBeGreaterThanOrEqual(from)
+  expect(randomNumber).toBeLessThan(to)
+})
+
 test("it should create a random number in the range (-1, 1)", () => {
   const randomNumber = randomBinomial()
 

package/src/math/vector.js

@@ -93,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)
 }
 
 /**
@@ -221,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
 }
@@ -254,7 +254,7 @@ export const setLength = setMagnitude
  */
 export function setMagnitude(vector, length) {
   const normalized = normalize(vector)
-  return multiply(normalized, length)
+  return scale(normalized, length)
 }
 
 /**
@@ -389,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/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)