@inglorious/utils 1.0.0 → 1.2.0

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

@@ -0,0 +1,49 @@
+import { expect, test } from "vitest"
+
+import { distanceFromPoint, intersectsCircle } from "./line.js"
+
+test("it should compute the distance between a line and a point", () => {
+  const line = [-4, 3, 0]
+  const point = [5, 0, 0]
+  const expectedResult = 4
+
+  expect(distanceFromPoint(line, point)).toBe(expectedResult)
+})
+
+test("it should not compute the distance between a line and a point", () => {
+  const line = [-1, 1, 0]
+  const point = [2, 0, 2]
+  const expectedResult = 0
+
+  expect(distanceFromPoint(line, point)).toBe(expectedResult)
+})
+
+test("it should prove that a line that crosses a circle intersects with it", () => {
+  const line = [-2, 2, 0]
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(line, circle)).toBe(true)
+})
+
+test("it should prove that a line tangent to a circle intersects with it", () => {
+  const line = [-2, 0, 0]
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(line, circle)).toBe(true)
+})
+
+test("it should prove that a line that does not cross a circle does not intersect with it", () => {
+  const line = [1, 1, 0]
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(line, circle)).toBe(false)
+})

package/src/math/geometry/point.js

@@ -0,0 +1,78 @@
+/**
+ * @typedef {import("./types").Point} Point
+ * @typedef {import("./types").Line} Line
+ * @typedef {import("./types").Circle} Circle
+ * @typedef {import("./types").Rectangle} Rectangle
+ */
+
+const SQUARED = 2
+const HALF = 2
+
+import { distanceFromPoint } from "./line.js"
+
+/**
+ * Calculates the distance from a point to a line.
+ * @param {Point} point - The point as a 3D coordinate [x, y, z].
+ * @param {Line} line - The line to calculate the distance from.
+ * @returns {number} The distance from the point to the line.
+ */
+export function getDistanceFromLine(point, line) {
+  return distanceFromPoint(line, point)
+}
+
+/**
+ * Checks if two points intersect.
+ * @param {Point} point1 - The first point as a 3D coordinate [x, y, z].
+ * @param {Point} point2 - The second point as a 3D coordinate [x, y, z].
+ * @returns {boolean} True if the points intersect, false otherwise.
+ */
+export function intersectsPoint(point1, point2) {
+  const [x1, y1, z1] = point1
+  const [x2, y2, z2] = point2
+  return x1 === x2 && y1 === y2 && z1 === z2
+}
+
+/**
+ * Checks if a point intersects with a circle.
+ * @param {Point} point - The point as a 3D coordinate [x, y, z].
+ * @param {Circle} circle - The circle with a position and radius.
+ * @returns {boolean} True if the point intersects the circle, false otherwise.
+ */
+export function intersectsCircle(point, circle) {
+  const [x, y, z] = point
+  const [cx, cy, cz] = circle.position
+  const radius = circle.radius
+
+  return (
+    (x - cx) ** SQUARED + (y - cy) ** SQUARED + (z - cz) ** SQUARED <=
+    radius ** SQUARED
+  )
+}
+
+/**
+ * Checks if a point intersects with a rectangle.
+ * @param {Point} point - The point as a 3D coordinate [x, y, z].
+ * @param {Rectangle} rectangle - The rectangle with a position and size.
+ * @returns {boolean} True if the point intersects the rectangle, false otherwise.
+ */
+export function intersectsRectangle(point, rectangle) {
+  const [x, y, z] = point
+  const [rectX, rectY, rectZ] = rectangle.position
+  const [width, height, depth] = rectangle.size
+
+  const left = rectX - width / HALF
+  const right = rectX + width / HALF
+  const bottom = rectY - height / HALF
+  const top = rectY + height / HALF
+  const back = rectZ - depth / HALF
+  const front = rectZ + depth / HALF
+
+  return (
+    x >= left &&
+    x <= right &&
+    y >= bottom &&
+    y <= top &&
+    z >= back &&
+    z <= front
+  )
+}

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

@@ -0,0 +1,81 @@
+import { expect, test } from "vitest"
+
+import {
+  intersectsCircle,
+  intersectsPoint,
+  intersectsRectangle,
+} from "./point.js"
+
+test("it should prove that two equal points intersect", () => {
+  const point1 = [1.5, 1.5, 0]
+  const point2 = [1.5, 1.5, 0]
+
+  expect(intersectsPoint(point1, point2)).toBe(true)
+})
+
+test("it should prove that two different points do not intersect", () => {
+  const point1 = [1.5, 1.5, 0]
+  const point2 = [2, 1, 0]
+
+  expect(intersectsPoint(point1, point2)).toBe(false)
+})
+
+test("it should prove that a point inside of a circle intersects with it", () => {
+  const point = [1.5, 1.5, 0]
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(point, circle)).toBe(true)
+})
+
+test("it should prove that a point on the border of a circle intersects with it", () => {
+  const point = [2, 1, 0]
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(point, circle)).toBe(true)
+})
+
+test("it should prove that a point outside of a circle does not intersect with it", () => {
+  const point = [2, 2, 0]
+  const circle = {
+    position: [1, 1, 0],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(point, circle)).toBe(false)
+})
+
+test("it should prove that a point inside of a rectangle intersects with it", () => {
+  const point = [1.5, 1.5, 0]
+  const rectangle = {
+    position: [1, 1, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(point, rectangle)).toBe(true)
+})
+
+test("it should prove that a point on the border of a rectangle intersects with it", () => {
+  const point = [2, 1, 0]
+  const rectangle = {
+    position: [1, 1, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(point, rectangle)).toBe(true)
+})
+
+test("it should prove that a point outside of a rectangle does not intersect with it", () => {
+  const point = [2.5, 2.5, 0]
+  const rectangle = {
+    position: [1, 1, 0],
+    size: [2, 2, 0],
+  }
+
+  expect(intersectsRectangle(point, rectangle)).toBe(false)
+})

package/src/math/geometry/rectangle.js

@@ -0,0 +1,76 @@
+/**
+ * @typedef {import("./types").Circle} Circle
+ * @typedef {import("./types").Rectangle} Rectangle
+ * @typedef {import("./types").Platform} Platform
+ */
+
+import { intersectsRectangle as circleIntersectsRectangle } from "./circle.js"
+import { intersectsRectangle as pointIntersectsRectangle } from "./point.js"
+
+const HALF = 2
+
+/**
+ * Checks if a rectangle intersects with a point.
+ * @param {Rectangle} rectangle - The rectangle to check.
+ * @param {Point} point - The point to check.
+ * @returns {boolean} True if the point intersects the circle, false otherwise.
+ */
+export function intersectsPoint(rectangle, point) {
+  return pointIntersectsRectangle(point, rectangle)
+}
+
+/**
+ * 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.
+ */
+export function intersectsCircle(rectangle, circle) {
+  return circleIntersectsRectangle(circle, rectangle)
+}
+
+/**
+ * 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.
+ */
+export function intersectsRectangle(rectangle1, rectangle2) {
+  const [x1, y1, z1] = rectangle1.position
+  const [w1, h1, d1] = rectangle1.size
+  const halfW1 = w1 / HALF
+  const halfH1 = h1 / HALF
+  const halfD1 = d1 / HALF
+
+  const left1 = x1 - halfW1
+  const right1 = x1 + halfW1
+  const bottom1 = y1 - halfH1
+  const top1 = y1 + halfH1
+  const back1 = z1 - halfD1
+  const front1 = z1 + halfD1
+
+  const [x2, y2, z2] = rectangle2.position
+  const [w2, h2, d2] = rectangle2.size
+  const halfW2 = w2 / HALF
+  const halfH2 = h2 / HALF
+  const halfD2 = d2 / HALF
+
+  const left2 = x2 - halfW2
+  const right2 = x2 + halfW2
+  const bottom2 = y2 - halfH2
+  const top2 = y2 + halfH2
+  const back2 = z2 - halfD2
+  const front2 = z2 + halfD2
+
+  // AABB intersection test
+  return (
+    left1 <= right2 &&
+    right1 >= left2 &&
+    bottom1 <= top2 &&
+    top1 >= bottom2 &&
+    back1 <= front2 &&
+    front1 >= back2
+  )
+}

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

@@ -0,0 +1,42 @@
+import { expect, test } from "vitest"
+
+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],
+  }
+  const rectangle2 = {
+    position: [1, 1, 1],
+    size: [2, 2, 2],
+  }
+
+  expect(intersectsRectangle(rectangle1, rectangle2)).toBe(true)
+})
+
+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],
+  }
+  const rectangle2 = {
+    position: [0, 0, 0],
+    size: [2, 0, 2],
+  }
+
+  expect(intersectsRectangle(rectangle1, rectangle2)).toBe(true)
+})
+
+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],
+  }
+  const rectangle2 = {
+    position: [3, 3, 3],
+    size: [2, 2, 2],
+  }
+
+  expect(intersectsRectangle(rectangle1, rectangle2)).toBe(false)
+})

package/src/math/geometry/segment.js

@@ -0,0 +1,72 @@
+/**
+ * @typedef {import("./types").Segment} Segment
+ * @typedef {import("./types").Point} Point
+ * @typedef {import("./types").Circle} Circle
+ */
+
+import { magnitude, setMagnitude } from "../linear-algebra/vector.js"
+import { distance, dot, subtract, sum } from "../linear-algebra/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.
+ */
+export function coefficients(segment) {
+  const [x1, , z1] = segment.from
+  const [x2, , z2] = segment.to
+  return [z1 - z2, x2 - x1, (x1 - x2) * z1 + x1 * (z2 - z1)]
+}
+
+/**
+ * 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.
+ */
+export function closestPoint(segment, point) {
+  const shiftedSegment = subtract(segment.to, segment.from)
+  const shiftedPoint = subtract(point, segment.from)
+
+  const projectionLength =
+    dot(shiftedSegment, shiftedPoint) / magnitude(shiftedSegment)
+
+  if (projectionLength < BEFORE_SEGMENT) {
+    return segment.from
+  }
+
+  if (projectionLength > magnitude(shiftedSegment)) {
+    return segment.to
+  }
+
+  const projectedPoint = setMagnitude(shiftedSegment, projectionLength)
+  return sum(segment.from, projectedPoint)
+}
+
+/**
+ * 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.
+ */
+export function distanceFromPoint(segment, point) {
+  const closest = closestPoint(segment, point)
+  return distance(point, closest)
+}
+
+/**
+ * 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`.
+ */
+export function intersectsCircle(segment, circle) {
+  return distanceFromPoint(segment, circle.position) <= circle.radius
+}

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

@@ -0,0 +1,183 @@
+import { expect, test } from "vitest"
+
+import { isClose } from "../numbers.js"
+import {
+  closestPoint,
+  coefficients,
+  distanceFromPoint,
+  intersectsCircle,
+} from "./segment.js"
+
+expect.extend({
+  toStrictEqualVector(received, expected) {
+    const { isNot } = this
+    return {
+      pass: received.every((coord, index) => isClose(coord, expected[index])),
+      message: () =>
+        `${received} is ${isNot ? "" : "not"} close to ${expected}`,
+    }
+  },
+})
+
+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],
+  }
+  const expectedResult = [-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],
+  }
+  const point = [2, 0, 0]
+  const expectedResult = [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],
+  }
+  const point = [1, 0, 1]
+  const expectedResult = [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],
+  }
+  const point = [-2, 0, 0]
+  const expectedResult = [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],
+  }
+  const point = [5, 0, 4]
+  const expectedResult = [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],
+  }
+  const point = [5, 0, 0]
+  const expectedResult = 4
+
+  expect(distanceFromPoint(segment, point)).toBe(expectedResult)
+})
+
+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],
+  }
+  const point = [1, 0, 1]
+  const expectedResult = 0
+
+  expect(distanceFromPoint(segment, point)).toBeCloseTo(expectedResult)
+})
+
+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],
+  }
+  const point = [-2, 0, 0]
+  const expectedResult = 2
+
+  expect(distanceFromPoint(segment, point)).toBe(expectedResult)
+})
+
+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],
+  }
+  const point = [5, 0, 4]
+  const expectedResult = 2
+
+  expect(distanceFromPoint(segment, point)).toBeCloseTo(expectedResult)
+})
+
+test("it should prove that a segment that crosses a circle intersects with it", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [2, 0, 2],
+  }
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(segment, circle)).toBe(true)
+})
+
+test("it should prove that a segment tangent to a circle intersects with it", () => {
+  const segment = {
+    from: [0, 0, 0],
+    to: [0, 0, 2],
+  }
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(segment, circle)).toBe(true)
+})
+
+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],
+  }
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(segment, circle)).toBe(true)
+})
+
+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],
+  }
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(segment, circle)).toBe(false)
+})
+
+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],
+  }
+  const circle = {
+    position: [1, 0, 1],
+    radius: 1,
+  }
+
+  expect(intersectsCircle(segment, circle)).toBe(false)
+})

package/src/math/geometry/triangle.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+export function hypothenuse(...nums) {
+  return Math.hypot(...nums)
+}
+
+/**
+ * Alias for the `hypothenuse` function.
+ */
+export const pythagoras = hypothenuse

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

@@ -0,0 +1,11 @@
+import { expect, test } from "vitest"
+
+import { hypothenuse } from "./triangle.js"
+
+test("it should compute the hypothenuse of two catheti (aka pythagoras)", () => {
+  const cat1 = 3
+  const cat2 = 4
+  const expectedResult = 5
+
+  expect(hypothenuse(cat1, cat2)).toBe(expectedResult)
+})

package/src/math/geometry/types.d.ts

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

package/src/math/linear-algebra/2d.js

@@ -0,0 +1,28 @@
+/**
+ * @typedef {import('../../../types').Vector2} Vector2
+ * @typedef {import('../../../types').Vector3} Vector3
+ */
+
+const NO_Y = 0 // Default Y-coordinate value for 3D vectors derived from 2D vectors.
+
+/**
+ * Converts a 2D vector [x, z] into a 3D vector [x, 0, z].
+ *
+ * @param {Vector2} vector - A 2D vector represented as [x, z].
+ * @returns {Vector3} A 3D vector represented as [x, 0, z].
+ */
+export function from2D(vector) {
+  const [x, z] = vector
+  return [x, NO_Y, z]
+}
+
+/**
+ * Converts a 3D vector [x, y, z] into a 2D vector [x, z].
+ *
+ * @param {Vector3} vector - A 3D vector represented as [x, y, z].
+ * @returns {Vector2} A 2D vector represented as [x, z].
+ */
+export function to2D(vector) {
+  const [x, , z] = vector
+  return [x, z]
+}

package/src/math/linear-algebra/2d.test.js

@@ -0,0 +1,17 @@
+import { expect, test } from "vitest"
+
+import { from2D, to2D } from "./2d.js"
+
+test("build a 3D vector from a 2D one", () => {
+  const vector = [3, 4]
+  const expectedResult = [3, 0, 4]
+
+  expect(from2D(vector)).toStrictEqual(expectedResult)
+})
+
+test("build a 2D vector from a 3D one", () => {
+  const vector = [3, 0, 4]
+  const expectedResult = [3, 4]
+
+  expect(to2D(vector)).toStrictEqual(expectedResult)
+})