@temelj/math

A collection of math utilities for common operations including 2D vector math, rectangle operations, and value clamping.

Installation

npm install @temelj/math

Clamping operations

Utilities for constraining numeric values within specified ranges.

clamp

Clamps a value between a minimum and maximum.

function clamp<T extends number | bigint>(x: T, min: T, max: T): T

import { clamp } from "@temelj/math";

clamp(5, 0, 10);   // 5
clamp(12, 0, 10);  // 10
clamp(-2, 0, 10);  // 0

import { clamp } from "@temelj/math";

clamp(50n, 0n, 100n);  // 50n
clamp(150n, 0n, 100n); // 100n

clampWithOverflow

Clamps a value with wrapping overflow behavior.

function clampWithOverflow<T extends number | bigint>(x: T, min: T, max: T): T

import { clampWithOverflow } from "@temelj/math";

clampWithOverflow(5, 0, 10);   // 5
clampWithOverflow(12, 0, 10);  // 2
clampWithOverflow(-2, 0, 10);  // 8

import { clampWithOverflow } from "@temelj/math";

// Useful for wrapping array indices
const items = ['a', 'b', 'c', 'd', 'e'];
const index = clampWithOverflow(7, 0, items.length);
console.log(items[index]); // 'c'

clampWithOverflow wraps values that exceed the range back into the valid range, making it useful for circular buffers and cyclic operations.

Vector2

A 2D vector type with comprehensive operations.

Types

interface Vector2 {
  x: number;
  y: number;
}

Construction

of
zero
copy

Creates a new vector from x and y coordinates.

vector2.of(x: number, y: number): Vector2

import { vector2 } from "@temelj/math";

const v = vector2.of(10, 20);
// { x: 10, y: 20 }

Creates a zero vector.

vector2.zero(): Vector2

import { vector2 } from "@temelj/math";

const origin = vector2.zero();
// { x: 0, y: 0 }

Creates a copy of a vector.

vector2.copy(v: Vector2): Vector2

import { vector2 } from "@temelj/math";

const v1 = vector2.of(5, 10);
const v2 = vector2.copy(v1);

Arithmetic operations

Addition
Subtraction
Multiplication
Division

vector2.plus(a: Vector2, b: Vector2): Vector2
vector2.add(v: Vector2, x: number, y: number): Vector2

import { vector2 } from "@temelj/math";

const v1 = vector2.of(1, 2);
const v2 = vector2.of(3, 4);

vector2.plus(v1, v2);    // { x: 4, y: 6 }
vector2.add(v1, 10, 20); // { x: 11, y: 22 }

vector2.minus(a: Vector2, b: Vector2): Vector2
vector2.subtract(v: Vector2, x: number, y: number): Vector2

import { vector2 } from "@temelj/math";

const v1 = vector2.of(10, 20);
const v2 = vector2.of(3, 5);

vector2.minus(v1, v2);      // { x: 7, y: 15 }
vector2.subtract(v1, 2, 3); // { x: 8, y: 17 }

vector2.times(a: Vector2, b: Vector2): Vector2
vector2.multiply(v: Vector2, x: number, y: number): Vector2
vector2.scale(v: Vector2, x: number): Vector2

import { vector2 } from "@temelj/math";

const v1 = vector2.of(2, 3);
const v2 = vector2.of(4, 5);

vector2.times(v1, v2);      // { x: 8, y: 15 }
vector2.multiply(v1, 2, 3); // { x: 4, y: 9 }
vector2.scale(v1, 2);       // { x: 4, y: 6 }

vector2.divided(a: Vector2, b: Vector2): Vector2
vector2.divide(v: Vector2, x: number, y: number): Vector2

import { vector2 } from "@temelj/math";

const v1 = vector2.of(10, 20);
const v2 = vector2.of(2, 4);

vector2.divided(v1, v2);   // { x: 5, y: 5 }
vector2.divide(v1, 2, 2);  // { x: 5, y: 10 }

Manipulation

negate
snap
clamp

Negates both components of a vector.

vector2.negate(v: Vector2): Vector2

import { vector2 } from "@temelj/math";

const v = vector2.of(5, -10);
vector2.negate(v); // { x: -5, y: 10 }

Snaps a vector to the nearest grid point.

vector2.snap(v: Vector2, size: number): Vector2

import { vector2 } from "@temelj/math";

const v = vector2.of(23, 47);
vector2.snap(v, 10); // { x: 20, y: 50 }

Clamps vector components between min and max vectors.

vector2.clamp(v: Vector2, min: Vector2, max: Vector2): Vector2
vector2.clampMin(v: Vector2, min: Vector2): Vector2
vector2.clampMax(v: Vector2, max: Vector2): Vector2

import { vector2 } from "@temelj/math";

const v = vector2.of(15, -5);
const min = vector2.of(0, 0);
const max = vector2.of(10, 10);

vector2.clamp(v, min, max);    // { x: 10, y: 0 }
vector2.clampMin(v, min);      // { x: 15, y: 0 }
vector2.clampMax(v, max);      // { x: 10, y: -5 }

Utility

vector2.equals(a: Vector2, b: Vector2): boolean
vector2.displayString(v: Vector2): string

import { vector2 } from "@temelj/math";

const v1 = vector2.of(5, 10);
const v2 = vector2.of(5, 10);
const v3 = vector2.of(3, 7);

vector2.equals(v1, v2); // true
vector2.equals(v1, v3); // false

vector2.displayString(v1); // "Vector2(5, 10)"

Rectangle

Rectangle type and operations for 2D bounding boxes.

Types

interface Rectangle {
  position: Vector2;
  size: Vector2;
}

Construction

of
ofBounds
fromDOM

Creates a rectangle from position and size vectors.

rectangle.of(position: Vector2, size: Vector2): Rectangle

import { rectangle, vector2 } from "@temelj/math";

const rect = rectangle.of(
  vector2.of(10, 20),
  vector2.of(100, 50)
);

Creates a rectangle from explicit bounds.

rectangle.ofBounds(x: number, y: number, width: number, height: number): Rectangle

import { rectangle } from "@temelj/math";

const rect = rectangle.ofBounds(10, 20, 100, 50);
// position: { x: 10, y: 20 }
// size: { x: 100, y: 50 }

Creates a rectangle from a DOM DOMRect object.

rectangle.fromDOM(rect: DOMRect): Rectangle

import { rectangle } from "@temelj/math";

const element = document.getElementById('myElement');
const domRect = element.getBoundingClientRect();
const rect = rectangle.fromDOM(domRect);

Operations

expand
center
overlaps

Expands rectangle to include another rectangle.

rectangle.expand(a: Rectangle, b: Rectangle): Rectangle

import { rectangle } from "@temelj/math";

const rect1 = rectangle.ofBounds(0, 0, 100, 100);
const rect2 = rectangle.ofBounds(50, 50, 100, 100);

const expanded = rectangle.expand(rect1, rect2);
// position: { x: 0, y: 0 }
// size: { x: 150, y: 150 }

Gets the center point of a rectangle.

rectangle.center(r: Rectangle): Vector2

import { rectangle } from "@temelj/math";

const rect = rectangle.ofBounds(0, 0, 100, 50);
const center = rectangle.center(rect);
// { x: 50, y: 25 }

Checks if two rectangles overlap.

rectangle.overlaps(a: Rectangle, b: Rectangle): boolean

import { rectangle } from "@temelj/math";

const rect1 = rectangle.ofBounds(0, 0, 100, 100);
const rect2 = rectangle.ofBounds(50, 50, 100, 100);
const rect3 = rectangle.ofBounds(200, 200, 50, 50);

rectangle.overlaps(rect1, rect2); // true
rectangle.overlaps(rect1, rect3); // false

Utility

rectangle.displayString(r: Rectangle): string

import { rectangle } from "@temelj/math";

const rect = rectangle.ofBounds(10, 20, 100, 50);
rectangle.displayString(rect);
// "Rectangle(10, 20, 100, 50)"

All vector and rectangle operations are immutable - they return new objects rather than modifying existing ones.

Getting Started

Core Packages

Data & Utilities

Web & Templating

Guides

Installation

Clamping operations

clamp

clampWithOverflow

Vector2

Types

Construction

Arithmetic operations

Manipulation

Utility

Rectangle

Types

Construction

Operations

Utility

​Installation

​Clamping operations

​clamp

​clampWithOverflow

​Vector2

​Types

​Construction

​Arithmetic operations

​Manipulation

​Utility

​Rectangle

​Types

​Construction

​Operations

​Utility

Installation

Clamping operations

clamp

clampWithOverflow

Vector2

Types

Construction

Arithmetic operations

Manipulation

Utility

Rectangle

Types

Construction

Operations

Utility