@inglorious/utils 1.1.0 → 1.2.0

package/README.md

@@ -1,4 +1,4 @@
-# @inglorious/utils
+# Inglorious Utils
 
 [![NPM version](https://img.shields.io/npm/v/@inglorious/utils.svg)](https://www.npmjs.com/package/@inglorious/utils)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -24,7 +24,7 @@ Here are a few examples of how you can use the utilities in this package.
 Compose functions together in a readable, left-to-right sequence.
 
 ```javascript
-import { pipe } from "@inglorious/utils/function"
+import { pipe } from "@inglorious/utils/functions/functions"
 
 const add = (a) => (b) => a + b
 const multiply = (a) => (b) => a * b
@@ -43,24 +43,23 @@ const result = calculate(10) // 40
 Perform vector operations on plain objects.
 
 ```javascript
-import { add } from "@inglorious/utils/vector"
+import { add } from "@inglorious/utils/math/linear-algebra/vector"
 
-const position = { x: 10, y: 20 }
-const velocity = { x: 2, y: -1 }
+const position = [10, 20]
+const velocity = [2, -1]
 
 const newPosition = add(position, velocity)
-// => { x: 12, y: 19 }
+// => [12, 19]
 ```
 
 ## API
 
 This package is designed to be used with subpath imports, which helps with tree-shaking.
 
-- **`@inglorious/utils/function`**: Utilities for function composition.
-- **`@inglorious/utils/vector`**: Utilities for 2D vector math on plain objects.
-- **`@inglorious/utils/random`**: Utilities for random number and data generation.
-
-_(This is a sample API. Please update it to reflect the actual exported functions.)_
+- **`@inglorious/utils/algorithms`**: Utilities for AI algorithms, like decision trees and A\*.
+- **`@inglorious/utils/functions`**: Utilities for function composition.
+- **`@inglorious/utils/math`**: Utilities for math operations.
+- **`@inglorious/utils/physics`**: Utilities for calculations on friction, acceleration, and gravity.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "1.1.0",
+  "version": "1.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",
@@ -20,14 +20,14 @@
     "utils"
   ],
   "type": "module",
+  "exports": {
+    "./*": "./src/*"
+  },
   "files": [
     "src",
     "README.md",
     "LICENSE"
   ],
-  "exports": {
-    "./*": "./src/*"
-  },
   "publishConfig": {
     "access": "public"
   },

package/src/data-structures/array.js

@@ -22,6 +22,16 @@ export function contains(arr, item) {
   return arr.includes(item)
 }
 
+/**
+ * Ensures that the given value is an array. If it's not an array, it wraps it in one.
+ *
+ * @param {*} arr - The value to check.
+ * @returns {Array} - The original array or the value wrapped in a new array.
+ */
+export function ensureArray(arr) {
+  return Array.isArray(arr) ? arr : [arr]
+}
+
 /**
  * Finds the maximum item in an array based on a comparator function.
  *

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

@@ -1,6 +1,6 @@
 import { expect, test } from "vitest"
 
-import { contains, max, min, pop, push, remove } from "./array.js"
+import { contains, ensureArray, max, min, pop, push, remove } from "./array.js"
 
 test("it should check if an array contains a value", () => {
   const arr = [3, 2, 6, 1, 7, 4, 5]
@@ -26,6 +26,18 @@ test("it should check if an array contains an object", () => {
   expect(contains(arr, item)).toBe(expectedResult)
 })
 
+test("it should return the same array if the value is already an array", () => {
+  const arr = [1, "two", { three: 3 }]
+
+  expect(ensureArray(arr)).toBe(arr)
+})
+
+test("it should wrap the value in an array if it is not an array", () => {
+  const str = "hello"
+
+  expect(ensureArray(str)).toStrictEqual([str])
+})
+
 test("it should find the maximum value of an array", () => {
   const arr = [3, 2, 6, 1, 7, 4, 5]
   const expectedResult = 7

package/src/data-structures/set.js

@@ -0,0 +1,9 @@
+/**
+ * Ensures that the given value is a Set. If it's not a Set, it creates one from the value.
+ *
+ * @param {*} value - The value to check.
+ * @returns {Set} - The original Set or a new Set created from the value.
+ */
+export function ensureSet(value) {
+  return value instanceof Set ? value : new Set(value)
+}

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

@@ -0,0 +1,15 @@
+import { expect, test } from "vitest"
+
+import { ensureSet } from "./set.js"
+
+test("it should return the same array if the value is already an array", () => {
+  const set = new Set([1, "two", { three: 3 }])
+
+  expect(ensureSet(set)).toBe(set)
+})
+
+test("it should wrap the value in an array if it is not an array", () => {
+  const str = "hello"
+
+  expect(ensureSet(str)).toStrictEqual(new Set(["h", "e", "l", "o"]))
+})

package/src/math/geometry/segment.test.js

@@ -9,7 +9,7 @@ import {
 } from "./segment.js"
 
 expect.extend({
-  toEqualVector(received, expected) {
+  toStrictEqualVector(received, expected) {
     const { isNot } = this
     return {
       pass: received.every((coord, index) => isClose(coord, expected[index])),
@@ -26,7 +26,7 @@ test("it should retrieve values of *a*, *b*, and *c* from a segment, so it looks
   }
   const expectedResult = [-2, 1, 0]
 
-  expect(coefficients(segment)).toEqual(expectedResult)
+  expect(coefficients(segment)).toStrictEqual(expectedResult)
 })
 
 test("it should find the closest point in a segment to a point projectable on it", () => {
@@ -37,7 +37,7 @@ test("it should find the closest point in a segment to a point projectable on it
   const point = [2, 0, 0]
   const expectedResult = [1, 0, 1]
 
-  expect(closestPoint(segment, point)).toEqualVector(expectedResult)
+  expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it should find the closest point as the point itself when resting on the segment", () => {
@@ -48,7 +48,7 @@ test("it should find the closest point as the point itself when resting on the s
   const point = [1, 0, 1]
   const expectedResult = [1, 0, 1]
 
-  expect(closestPoint(segment, point)).toEqualVector(expectedResult)
+  expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it return the start of a segment when the point is close to its start", () => {
@@ -59,7 +59,7 @@ test("it return the start of a segment when the point is close to its start", ()
   const point = [-2, 0, 0]
   const expectedResult = [0, 0, 0]
 
-  expect(closestPoint(segment, point)).toEqualVector(expectedResult)
+  expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it should return the end of a segment when the point is close to its end", () => {
@@ -70,7 +70,7 @@ test("it should return the end of a segment when the point is close to its end",
   const point = [5, 0, 4]
   const expectedResult = [3, 0, 4]
 
-  expect(closestPoint(segment, point)).toEqualVector(expectedResult)
+  expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it should compute the distance between a segment and a point projectable on it", () => {

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

@@ -169,6 +169,14 @@ export function rotate(vector, angle) {
   return is2D ? to2D(result) : result
 }
 
+/**
+ * Scales the vector by the given scalar. Alias of `multiply`.
+ * @param {Vector3} vector - The input vector.
+ * @param {number} scalar - The scalar value.
+ * @returns {Vector3} The resulting vector.
+ */
+export const scale = multiply
+
 /**
  * Sets the angle of the vector while maintaining its magnitude.
  * @param {Vector3} vector - The input vector.
@@ -181,6 +189,9 @@ export function setAngle(vector, angle) {
   return [x, NO_Y, z]
 }
 
+/**
+ * Sets the length of the vector while maintaining its direction. Alias of `setMagnitude`.
+ */
 export const setLength = setMagnitude
 
 /**