@inglorious/utils 2.3.0 → 3.1.0

package/src/math/{linear-algebra/quaternions.test.js → quaternions.test.js}

@@ -1,8 +1,8 @@
 import { expect, test } from "vitest"
 
-import { cos, pi, sin } from "../trigonometry.js"
 import { quaternion } from "./quaternion.js"
 import { combine } from "./quaternions.js"
+import { cos, pi, sin } from "./trigonometry.js"
 
 test("it should combine two zero-angle quaternions by giving the same 0-angle quaternion", () => {
   const q1 = quaternion(0)

package/src/math/{geometry/rectangle.js → rectangle.js}

@@ -1,7 +1,7 @@
 /**
- * @typedef {import("./types").Circle} Circle
- * @typedef {import("./types").Rectangle} Rectangle
- * @typedef {import("./types").Platform} Platform
+ * @typedef {import("./geometry/types.js").Circle} Circle
+ * @typedef {import("./geometry/types.js").Rectangle} Rectangle
+ * @typedef {import("./geometry/types.js").Platform} Platform
  */
 
 import { intersectsRectangle as circleIntersectsRectangle } from "./circle.js"
@@ -21,7 +21,6 @@ export function intersectsPoint(rectangle, point) {
 
 /**
  * Checks if a rectangle intersects with a circle.
- *
  * @param {Rectangle} rectangle - The rectangle to check.
  * @param {Circle} circle - The circle to check.
  * @returns {boolean} True if the rectangle intersects the circle, false otherwise.
@@ -32,7 +31,6 @@ export function intersectsCircle(rectangle, circle) {
 
 /**
  * Determines whether a rectangle intersects another in 3D space.
- *
  * @param {Rectangle} rectangle1 - The first rectangle, defined by its position (x, y, z) and size (width, height, depth).
  * @param {Rectangle} rectangle2 - The second rectangle, defined by its position (x, y, z) and size (width, height, depth).
  * @returns {boolean} True if the two rectangles intersect, false otherwise.

package/src/math/{geometry/rectangle.test.js → rectangle.test.js}

@@ -1,15 +1,16 @@
 import { expect, test } from "vitest"
 
+import { v } from "../v.js"
 import { intersectsRectangle } from "./rectangle.js"
 
 test("it should prove that a rectangle crossing another one intersects with it", () => {
   const rectangle1 = {
-    position: [0, 0, 0],
-    size: [2, 2, 2],
+    position: v(0, 0, 0),
+    size: v(2, 2, 2),
   }
   const rectangle2 = {
-    position: [1, 1, 1],
-    size: [2, 2, 2],
+    position: v(1, 1, 1),
+    size: v(2, 2, 2),
   }
 
   expect(intersectsRectangle(rectangle1, rectangle2)).toBe(true)
@@ -17,12 +18,12 @@ test("it should prove that a rectangle crossing another one intersects with it",
 
 test("it should prove that a rectangle right on top of another intersects with it", () => {
   const rectangle1 = {
-    position: [0, 0, 0],
-    size: [2, 2, 2],
+    position: v(0, 0, 0),
+    size: v(2, 2, 2),
   }
   const rectangle2 = {
-    position: [0, 0, 0],
-    size: [2, 0, 2],
+    position: v(0, 0, 0),
+    size: v(2, 0, 2),
   }
 
   expect(intersectsRectangle(rectangle1, rectangle2)).toBe(true)
@@ -30,12 +31,12 @@ test("it should prove that a rectangle right on top of another intersects with i
 
 test("it should prove that a rectangle not crossing another one does not intersect with it", () => {
   const rectangle1 = {
-    position: [0, 0, 0],
-    size: [2, 2, 2],
+    position: v(0, 0, 0),
+    size: v(2, 2, 2),
   }
   const rectangle2 = {
-    position: [3, 3, 3],
-    size: [2, 2, 2],
+    position: v(3, 3, 3),
+    size: v(2, 2, 2),
   }
 
   expect(intersectsRectangle(rectangle1, rectangle2)).toBe(false)

package/src/math/rng.js

@@ -5,7 +5,6 @@
  * - 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.
  * @param {number} [step=1] - The step size if two or more arguments are provided.
@@ -36,7 +35,6 @@ export function random(...args) {
 /**
  * Generates a random binomial value.
  * The result is the difference between two random numbers.
- *
  * @returns {number} A random binomial value.
  */
 export function randomBinomial() {

package/src/math/{geometry/segment.js → segment.js}

@@ -1,18 +1,17 @@
 /**
- * @typedef {import("./types").Segment} Segment
- * @typedef {import("./types").Point} Point
- * @typedef {import("./types").Circle} Circle
+ * @typedef {import("./geometry/types.js").Segment} Segment
+ * @typedef {import("./geometry/types.js").Point} Point
+ * @typedef {import("./geometry/types.js").Circle} Circle
  */
 
-import { magnitude, setMagnitude } from "../linear-algebra/vector.js"
-import { distance, dot, subtract, sum } from "../linear-algebra/vectors.js"
+import { magnitude, setMagnitude } from "./vector.js"
+import { distance, dot, subtract, sum } from "./vectors.js"
 
 const BEFORE_SEGMENT = 0
 
 /**
  * Calculates the coefficients [a, b, c] of the line equation ax + bz + c = 0
  * for a given segment in 2D space.
- *
  * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
  * @returns {[number, number, number]} An array [a, b, c] representing the line equation.
  */
@@ -24,7 +23,6 @@ export function coefficients(segment) {
 
 /**
  * Finds the closest point on a segment to a given point in 3D space.
- *
  * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
  * @param {Point} point - The point in 3D space represented as [x, y, z].
  * @returns {Point} The closest point on the segment to the given point.
@@ -50,7 +48,6 @@ export function closestPoint(segment, point) {
 
 /**
  * Calculates the shortest distance from a point to a segment in 3D space.
- *
  * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
  * @param {Point} point - The point in 3D space represented as [x, y, z].
  * @returns {number} The shortest distance from the point to the segment.
@@ -62,7 +59,6 @@ export function distanceFromPoint(segment, point) {
 
 /**
  * Determines whether a segment intersects with the perimeter of a circle.
- *
  * @param {Segment} segment - The segment defined by its start (`from`) and end (`to`) points.
  * @param {Circle} circle - The circle defined by its position (center) and radius.
  * @returns {boolean} `true` if the segment intersects the circle's perimeter, otherwise `false`.

package/src/math/{geometry/segment.test.js → segment.test.js}

@@ -1,6 +1,7 @@
 import { expect, test } from "vitest"
 
-import { isClose } from "../numbers.js"
+import { v } from "../v.js"
+import { isClose } from "./numbers.js"
 import {
   closestPoint,
   coefficients,
@@ -21,64 +22,64 @@ expect.extend({
 
 test("it should retrieve values of *a*, *b*, and *c* from a segment, so it looks like a line in the form *ax + by + c = 0*", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [1, 0, 2],
+    from: v(0, 0, 0),
+    to: v(1, 0, 2),
   }
-  const expectedResult = [-2, 1, 0]
+  const expectedResult = v(-2, 1, 0)
 
   expect(coefficients(segment)).toStrictEqual(expectedResult)
 })
 
 test("it should find the closest point in a segment to a point projectable on it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [2, 0, 2],
+    from: v(0, 0, 0),
+    to: v(2, 0, 2),
   }
-  const point = [2, 0, 0]
-  const expectedResult = [1, 0, 1]
+  const point = v(2, 0, 0)
+  const expectedResult = v(1, 0, 1)
 
   expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it should find the closest point as the point itself when resting on the segment", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [2, 0, 2],
+    from: v(0, 0, 0),
+    to: v(2, 0, 2),
   }
-  const point = [1, 0, 1]
-  const expectedResult = [1, 0, 1]
+  const point = v(1, 0, 1)
+  const expectedResult = v(1, 0, 1)
 
   expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it return the start of a segment when the point is close to its start", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [3, 0, 4],
+    from: v(0, 0, 0),
+    to: v(3, 0, 4),
   }
-  const point = [-2, 0, 0]
-  const expectedResult = [0, 0, 0]
+  const point = v(-2, 0, 0)
+  const expectedResult = v(0, 0, 0)
 
   expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it should return the end of a segment when the point is close to its end", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [3, 0, 4],
+    from: v(0, 0, 0),
+    to: v(3, 0, 4),
   }
-  const point = [5, 0, 4]
-  const expectedResult = [3, 0, 4]
+  const point = v(5, 0, 4)
+  const expectedResult = v(3, 0, 4)
 
   expect(closestPoint(segment, point)).toStrictEqualVector(expectedResult)
 })
 
 test("it should compute the distance between a segment and a point projectable on it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [3, 0, 4],
+    from: v(0, 0, 0),
+    to: v(3, 0, 4),
   }
-  const point = [5, 0, 0]
+  const point = v(5, 0, 0)
   const expectedResult = 4
 
   expect(distanceFromPoint(segment, point)).toBe(expectedResult)
@@ -86,10 +87,10 @@ test("it should compute the distance between a segment and a point projectable o
 
 test("it should compute the distance between a segment and a point resting on it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [2, 0, 2],
+    from: v(0, 0, 0),
+    to: v(2, 0, 2),
   }
-  const point = [1, 0, 1]
+  const point = v(1, 0, 1)
   const expectedResult = 0
 
   expect(distanceFromPoint(segment, point)).toBeCloseTo(expectedResult)
@@ -97,10 +98,10 @@ test("it should compute the distance between a segment and a point resting on it
 
 test("it should compute the distance between a segment and a point close to the start", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [3, 0, 4],
+    from: v(0, 0, 0),
+    to: v(3, 0, 4),
   }
-  const point = [-2, 0, 0]
+  const point = v(-2, 0, 0)
   const expectedResult = 2
 
   expect(distanceFromPoint(segment, point)).toBe(expectedResult)
@@ -108,10 +109,10 @@ test("it should compute the distance between a segment and a point close to the
 
 test("it should compute the distance between a segment and a point close to the end", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [3, 0, 4],
+    from: v(0, 0, 0),
+    to: v(3, 0, 4),
   }
-  const point = [5, 0, 4]
+  const point = v(5, 0, 4)
   const expectedResult = 2
 
   expect(distanceFromPoint(segment, point)).toBeCloseTo(expectedResult)
@@ -119,11 +120,11 @@ test("it should compute the distance between a segment and a point close to the
 
 test("it should prove that a segment that crosses a circle intersects with it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [2, 0, 2],
+    from: v(0, 0, 0),
+    to: v(2, 0, 2),
   }
   const circle = {
-    position: [1, 0, 1],
+    position: v(1, 0, 1),
     radius: 1,
   }
 
@@ -132,11 +133,11 @@ test("it should prove that a segment that crosses a circle intersects with it",
 
 test("it should prove that a segment tangent to a circle intersects with it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [0, 0, 2],
+    from: v(0, 0, 0),
+    to: v(0, 0, 2),
   }
   const circle = {
-    position: [1, 0, 1],
+    position: v(1, 0, 1),
     radius: 1,
   }
 
@@ -145,11 +146,11 @@ test("it should prove that a segment tangent to a circle intersects with it", ()
 
 test("it should prove that a segment inside of a circle intersects with it", () => {
   const segment = {
-    from: [0.5, 0, 0.5],
-    to: [1.5, 0, 1.5],
+    from: v(0.5, 0, 0.5),
+    to: v(1.5, 0, 1.5),
   }
   const circle = {
-    position: [1, 0, 1],
+    position: v(1, 0, 1),
     radius: 1,
   }
 
@@ -158,11 +159,11 @@ test("it should prove that a segment inside of a circle intersects with it", ()
 
 test("it should prove that a segment that does not cross a circle does not intersect with it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [-2, 0, 2],
+    from: v(0, 0, 0),
+    to: v(-2, 0, 2),
   }
   const circle = {
-    position: [1, 0, 1],
+    position: v(1, 0, 1),
     radius: 1,
   }
 
@@ -171,11 +172,11 @@ test("it should prove that a segment that does not cross a circle does not inter
 
 test("it should prove that a segment that reaches outside of a circle does not intersect with it", () => {
   const segment = {
-    from: [0, 0, 0],
-    to: [-1, 0, -2],
+    from: v(0, 0, 0),
+    to: v(-1, 0, -2),
   }
   const circle = {
-    position: [1, 0, 1],
+    position: v(1, 0, 1),
     radius: 1,
   }
 

package/src/math/{geometry/triangle.js → triangle.js}

@@ -1,7 +1,6 @@
 /**
  * Calculates the length of the hypothenuse (or magnitude) for a given set of numbers
  * using the Pythagorean theorem.
- *
  * @param {number[]} nums - A list of numbers representing the sides of a right triangle.
  * @returns {number} The length of the hypothenuse.
  */
@@ -11,5 +10,6 @@ export function hypothenuse(...nums) {
 
 /**
  * Alias for the `hypothenuse` function.
+ *  @type {typeof hypothenuse}
  */
 export const pythagoras = hypothenuse

package/src/math/{geometry/types.d.ts → types.d.ts}

@@ -1,3 +1,5 @@
+// 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]
@@ -21,3 +23,11 @@ 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]