@inglorious/utils 3.4.0 → 3.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "3.4.0",
+  "version": "3.5.1",
   "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",
@@ -21,10 +21,18 @@
   ],
   "type": "module",
   "exports": {
-    "./*": "./src/*"
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./*": {
+      "types": "./types/*.d.ts",
+      "import": "./src/*"
+    }
   },
   "files": [
-    "src"
+    "src",
+    "types"
   ],
   "publishConfig": {
     "access": "public"

package/src/algorithms/decision-tree.js

@@ -1,7 +1,7 @@
 /**
- * @typedef {import("./types").Conditions} Conditions
- * @typedef {import("./types").Outcome} Outcome
- * @typedef {import("./types").DecisionTree} DecisionTree
+ * @typedef {import("../../types/algorithms").Conditions} Conditions
+ * @typedef {import("../../types/algorithms").Outcome} Outcome
+ * @typedef {import("../../types/algorithms").DecisionTree} DecisionTree
  */
 
 /**

package/src/algorithms/path-finding.js

@@ -1,6 +1,6 @@
 /**
- * @typedef {import("./types").Node} Node
- * @typedef {import("./types").Graph} Graph
+ * @typedef {import("../../types/data-structures").Node} Node
+ * @typedef {import("../../types/data-structures").Graph} Graph
  */
 
 import { contains, push, remove, root } from "../data-structures/heap.js"

package/src/data-structures/tree.js

@@ -1,4 +1,4 @@
-/** @typedef {import('./types').Tree} Tree */
+/** @typedef {import('../../types/data-structures').Tree} Tree */
 
 /**
  * Performs a breadth-first search (BFS) traversal on a tree structure.

package/src/math/circle.js

@@ -1,8 +1,8 @@
 /**
- * @typedef {import("./geometry/types.js").Point} Point
- * @typedef {import("./geometry/types.js").Circle} Circle
- * @typedef {import("./geometry/types.js").Rectangle} Rectangle
- * @typedef {import("./geometry/types.js").Platform} Platform
+ * @typedef {import("../../types/math").Point} Point
+ * @typedef {import("../../types/math").Circle} Circle
+ * @typedef {import("../../types/math").Rectangle} Rectangle
+ * @typedef {import("../../types/math").Platform} Platform
  */
 
 import { intersectsCircle as pointIntersectsCircle } from "./point.js"

package/src/math/hitmask.js

@@ -1,10 +1,11 @@
 // @see https://jonathanwhiting.com/tutorial/collision/
 
+import { isBetween } from "./numbers.js"
 import { intersectsRectangle } from "./rectangle.js"
 
-const FIRST_TILE = 0
+const FIRST = 0
 const HALF = 2
-const LAST_ROW = 1
+const LAST = 1
 
 export function findCollisions(hitmask, target) {
   const [tilemapX, tilemapY, tilemapZ] = hitmask.position
@@ -37,15 +38,13 @@ export function findCollisions(hitmask, target) {
   for (let i = minTileX; i <= maxTileX; i++) {
     for (let j = minTileZ; j <= maxTileZ; j++) {
       if (
-        i < FIRST_TILE ||
-        i >= hitmask.columns ||
-        j < FIRST_TILE ||
-        j >= dRows
+        !isBetween(i, FIRST, hitmask.columns - LAST) ||
+        !isBetween(j, FIRST, dRows - LAST)
       ) {
         continue
       }
 
-      const invertedRow = dRows - LAST_ROW - j
+      const invertedRow = dRows - LAST - j
       const tileIndex = invertedRow * hitmask.columns + i
       const tileHeightValue = hitmask.heights[tileIndex]
 

package/src/math/line.js

@@ -1,7 +1,7 @@
 /**
- * @typedef {import("./geometry/types.js").Line} Line
- * @typedef {import("./geometry/types.js").Point} Point
- * @typedef {import("./geometry/types.js").Circle} Circle
+ * @typedef {import("../../types/math").Line} Line
+ * @typedef {import("../../types/math").Point} Point
+ * @typedef {import("../../types/math").Circle} Circle
  */
 
 import { abs } from "./numbers.js"

package/src/math/numbers.js

@@ -30,6 +30,17 @@ export function clamp(num, min, max) {
   return num
 }
 
+/**
+ * Checks if a number is between a minimum and maximum value, inclusive.
+ * @param {number} num - The number to check.
+ * @param {number} min - The minimum value.
+ * @param {number} max - The maximum value.
+ * @returns {boolean} True if the number is between min and max, false otherwise.
+ */
+export function isBetween(num, min, max) {
+  return num >= min && num <= max
+}
+
 /**
  * Checks if two numbers are close to each other within a given tolerance.
  * @param {number} num1 - The first number.

package/src/math/numbers.test.js

@@ -1,6 +1,15 @@
 import { expect, test } from "vitest"
 
-import { abs, clamp, isClose, mod, sign, snap, sqrt } from "./numbers.js"
+import {
+  abs,
+  clamp,
+  isBetween,
+  isClose,
+  mod,
+  sign,
+  snap,
+  sqrt,
+} from "./numbers.js"
 
 test("it should return the same number if already positive", () => {
   const num = 42
@@ -43,6 +52,51 @@ test("it should clamp a number too big", () => {
   expect(clamp(num, min, max)).toBe(expectedResult)
 })
 
+test("it should return true if a number is between min and max", () => {
+  const num = 50
+  const min = 0
+  const max = 100
+  const expectedResult = true
+
+  expect(isBetween(num, min, max)).toBe(expectedResult)
+})
+
+test("it should return true if a number is equal to min", () => {
+  const num = 0
+  const min = 0
+  const max = 100
+  const expectedResult = true
+
+  expect(isBetween(num, min, max)).toBe(expectedResult)
+})
+
+test("it should return true if a number is equal to max", () => {
+  const num = 100
+  const min = 0
+  const max = 100
+  const expectedResult = true
+
+  expect(isBetween(num, min, max)).toBe(expectedResult)
+})
+
+test("it should return false if a number is lower than min", () => {
+  const num = -1
+  const min = 0
+  const max = 100
+  const expectedResult = false
+
+  expect(isBetween(num, min, max)).toBe(expectedResult)
+})
+
+test("it should return false if a number is greater than max", () => {
+  const num = 101
+  const min = 0
+  const max = 100
+  const expectedResult = false
+
+  expect(isBetween(num, min, max)).toBe(expectedResult)
+})
+
 test("it should check if two numbers are close given some tolerance", () => {
   const num1 = 42
   const num2 = 42.1

package/src/math/point.js

@@ -1,14 +1,15 @@
 /**
- * @typedef {import("./geometry/types.js").Point} Point
- * @typedef {import("./geometry/types.js").Line} Line
- * @typedef {import("./geometry/types.js").Circle} Circle
- * @typedef {import("./geometry/types.js").Rectangle} Rectangle
+ * @typedef {import("../../types/math").Point} Point
+ * @typedef {import("../../types/math").Line} Line
+ * @typedef {import("../../types/math").Circle} Circle
+ * @typedef {import("../../types/math").Rectangle} Rectangle
  */
 
 const SQUARED = 2
 const HALF = 2
 
 import { distanceFromPoint } from "./line.js"
+import { isBetween } from "./numbers.js"
 import { isVector } from "./vector.js"
 
 /**
@@ -69,12 +70,9 @@ export function intersectsRectangle(point, rectangle) {
   const front = rectZ + depth / HALF
 
   return (
-    x >= left &&
-    x <= right &&
-    y >= bottom &&
-    y <= top &&
-    z >= back &&
-    z <= front
+    isBetween(x, left, right) &&
+    isBetween(y, bottom, top) &&
+    isBetween(z, back, front)
   )
 }
 

package/src/math/quaternion.js

@@ -1,6 +1,6 @@
 /**
- * @typedef {import('../../../types').Vector3} Vector3
- * @typedef {import('../../../types').Quaternion} Quaternion
+ * @typedef {import("../../types/math").Vector3} Vector3
+ * @typedef {import("../../types/math").Quaternion} Quaternion
  */
 
 import { v } from "../v.js"

package/src/math/quaternions.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('./types').Quaternion} Quaternion
+ * @typedef {import("../../types/math").Quaternion} Quaternion
  */
 
 import { v } from "../v.js"

package/src/math/rectangle.js

@@ -1,7 +1,7 @@
 /**
- * @typedef {import("./geometry/types.js").Circle} Circle
- * @typedef {import("./geometry/types.js").Rectangle} Rectangle
- * @typedef {import("./geometry/types.js").Platform} Platform
+ * @typedef {import("../../types/math").Circle} Circle
+ * @typedef {import("../../types/math").Rectangle} Rectangle
+ * @typedef {import("../../types/math").Platform} Platform
  */
 
 import { intersectsRectangle as circleIntersectsRectangle } from "./circle.js"

package/src/math/rng.js

@@ -16,20 +16,32 @@ export function choose(...values) {
 /**
  * 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

@@ -38,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/segment.js

@@ -1,7 +1,7 @@
 /**
- * @typedef {import("./geometry/types.js").Segment} Segment
- * @typedef {import("./geometry/types.js").Point} Point
- * @typedef {import("./geometry/types.js").Circle} Circle
+ * @typedef {import("../../types/math").Segment} Segment
+ * @typedef {import("../../types/math").Point} Point
+ * @typedef {import("../../types/math").Circle} Circle
  */
 
 import { magnitude, setMagnitude } from "./vector.js"

package/src/math/vector.js

@@ -1,7 +1,7 @@
 /**
- * @typedef {import('./types').Vector} Vector
- * @typedef {import('./types').Vector2} Vector2
- * @typedef {import('./types').Vector3} Vector3
+ * @typedef {import("../../types/math").Vector} Vector
+ * @typedef {import("../../types/math").Vector2} Vector2
+ * @typedef {import("../../types/math").Vector3} Vector3
  */
 
 import { v } from "../v.js"

package/src/math/vectors.js

@@ -1,7 +1,7 @@
 /**
- * @typedef {import('./types').Vector2} Vector2
- * @typedef {import('./types').Vector3} Vector3
- * @typedef {import('./types').Vector7} Vector7
+ * @typedef {import("../../types/math").Vector2} Vector2
+ * @typedef {import("../../types/math").Vector3} Vector3
+ * @typedef {import("../../types/math").Vector7} Vector7
  */
 
 import { v } from "../v.js"

package/src/physics/acceleration.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('../math/types.js').Vector3} Vector3
+ * @typedef {import("../../types/math").Vector3} Vector3
  */
 
 import { clamp, multiply, zero } from "../math/vector.js"

package/src/physics/friction.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('../math/types.js').Vector3} Vector3
+ * @typedef {import("../../types/math").Vector3} Vector3
  */
 
 import { magnitude, setMagnitude, zero } from "../math/vector.js"

package/src/physics/gravity.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('../math/types.js').Vector3} Vector3
+ * @typedef {import("../../types/math").Vector3} Vector3
  */
 
 /* eslint-disable no-magic-numbers */

package/src/physics/jump.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('../math/types').Vector3} Vector3
+ * @typedef {import("../../types/math").Vector3} Vector3
  */
 
 /* eslint-disable no-magic-numbers */

package/src/physics/velocity.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('../math/types.js').Vector3} Vector3
+ * @typedef {import("../../types/math").Vector3} Vector3
  */
 
 import { clamp, multiply, zero } from "../math/vector.js"

package/src/v.js

@@ -1,3 +1,7 @@
+/**
+ * @typedef {import("../types/math").Vector} Vector
+ */
+
 import { isArray } from "./data-structures/array"
 
 /**

package/types/algorithms.d.ts

@@ -0,0 +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>

package/types/data-structures.d.ts

@@ -0,0 +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[]
+}

package/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./algorithms"
+export * from "./data-structures"
+export * from "./math"

package/types/math.d.ts

@@ -0,0 +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]

package/src/algorithms/types.d.ts

@@ -1,28 +0,0 @@
-export type Conditions = unknown
-export type Outcome = string | boolean
-
-export interface DecisionTree {
-  test: (conditions: Conditions) => Outcome
-  [outcome: Outcome]: () => Outcome | DecisionTree
-}
-
-interface NodeMap {
-  [id: string]: [number, number] // [x, y]
-}
-
-interface Node {
-  id: string
-  position: [number, number] // [x, y]
-  cost?: number
-}
-
-interface Arc {
-  from: string
-  to: string
-  cost?: number
-}
-
-export interface Graph {
-  nodes: NodeMap | Node[]
-  arcs: Arc[]
-}

package/src/data-structures/types.d.ts

@@ -1,4 +0,0 @@
-export interface Tree {
-  value: any
-  children: Tree[]
-}

package/src/math/types.d.ts

@@ -1,33 +0,0 @@
-// geometry
-
-export type Point = [number, number, number] // [x, y, z]
-export type Size = [number, number, number] // [width, height, depth]
-export type Line = [number, number, number] // [a, b, c]
-
-export interface Circle {
-  position: Point
-  radius: number
-}
-
-export interface Rectangle {
-  position: Point
-  size: Size
-}
-
-export interface Platform {
-  position: Point
-  size: Size
-}
-
-export interface Segment {
-  from: Point
-  to: Point
-}
-
-// linear algebra
-
-export type Vector = number[]
-export type Vector2 = [number, number]
-export type Vector3 = [number, number, number]
-export type Quaternion = [number, number, number, number]
-export type Vector7 = [number, number, number, number, number, number, number]