@thi.ng/math

@thi.ng/math provides a comprehensive collection of common mathematical functions and utilities for TypeScript/JavaScript applications. It includes modules for angle calculations, bezier curves, easing functions, interpolation, interval arithmetic, prime number operations, trigonometry, precision handling, and various mathematical solvers.

Package Information

• Package Name: @thi.ng/math
• Package Type: npm
• Language: TypeScript
• Installation: npm install @thi.ng/math

Core Imports

import * as math from "@thi.ng/math";

Individual module imports (tree-shakeable):

import { PI, TAU, PHI } from "@thi.ng/math/api";
import { mix, clamp } from "@thi.ng/math/interval";
import { easeInOut3, easeOutBounce } from "@thi.ng/math/easing";

For CommonJS:

const math = require("@thi.ng/math");
const { PI, TAU } = require("@thi.ng/math/api");

Basic Usage

import { PI, TAU, clamp, mix, deg, rad } from "@thi.ng/math";

// Mathematical constants
console.log(PI, TAU); // 3.14159..., 6.28318...

// Interval operations
const clamped = clamp(15, 0, 10); // 10
const interpolated = mix(0, 100, 0.5); // 50

// Angle conversions
const degrees = deg(PI); // 180
const radians = rad(90); // 1.5707...

Architecture

@thi.ng/math is designed with modularity and performance in mind:

• Zero Dependencies: No external dependencies except @thi.ng/api (type-only)
• Tree-shakeable: Import only the functions you need via subpath imports
• Type Safety: Full TypeScript definitions with precise type annotations
• Performance Optimized: Fast implementations suitable for real-time applications
• Modular Design: 20 specialized modules for different mathematical domains

Capabilities

Mathematical Constants & Types

Core mathematical constants, type definitions, and utility types used throughout the library.

const PI: number;
const TAU: number;
const PHI: number;
const EPS: number;

type Crossing = "equal" | "flat" | "under" | "over" | "other";

Constants & Types

Interval & Range Operations

Functions for clamping, wrapping, and constraining values within intervals. Essential for bounds checking and value normalization.

function clamp(x: number, min: number, max: number): number;
function wrap(x: number, min: number, max: number): number;
function inRange(x: number, min: number, max: number): boolean;

Interval Operations

Interpolation & Mixing

Comprehensive interpolation functions including linear, bezier, hermite, and specialized interpolation methods for animation and graphics.

function mix(a: number, b: number, t: number): number;
function mixCubic(a: number, b: number, c: number, d: number, t: number): number;
function smoothStep(edge: number, edge2: number, x: number): number;

Interpolation & Mixing

Angle Mathematics & Trigonometry

Angle manipulation, trigonometric functions, and geometric calculations. Includes fast approximations and specialized angle operations.

function deg(theta: number): number;
function rad(theta: number): number;
function angleDist(a: number, b: number): number;
function sincos(theta: number, n?: number): [number, number];

Angle & Trigonometry

Easing Functions

Pre-built easing functions for animations and smooth transitions. Includes polynomial, exponential, elastic, and bounce easing curves.

function easeInOut3(t: number): number;
function easeOutBounce(t: number): number;
function defEaseInExp(k: number): (t: number) => number;

Easing Functions

Integer Mathematics

Specialized integer operations with overflow handling for 8-bit, 16-bit, and 32-bit signed and unsigned arithmetic.

function addi32(a: number, b: number): number;
function mulu16(a: number, b: number): number;
function signExtend8(a: number): number;

Integer Mathematics

Precision & Rounding

Functions for controlling numerical precision, rounding to specific increments, and handling floating-point precision issues.

function roundTo(x: number, prec?: number): number;
function mod(a: number, b: number): number;
function fract(x: number): number;

Precision Control

Mathematical Solvers

Equation solving functions for linear, quadratic, and cubic equations, plus numerical methods and derivative calculations.

function solveQuadratic(a: number, b: number, c: number, eps?: number): number[];
function solveCubic(a: number, b: number, c: number, d: number, eps?: number): number[];
function derivative(f: (x: number) => number, eps?: number): (x: number) => number;

Mathematical Solvers

Value Fitting & Mapping

Functions for mapping and fitting values between different numeric ranges, essential for scaling, normalization, and coordinate transformations.

function norm(x: number, a: number, b: number): number;
function fit(x: number, a: number, b: number, c: number, d: number): number;
function fitClamped(x: number, a: number, b: number, c: number, d: number): number;

Value Fitting & Mapping

LibC Math Functions

C standard library math functions providing low-level mathematical operations for compatibility and enhanced precision control.

function copysign(x: number, y: number): number;
function exp2(x: number): number;
function fmod(x: number, y: number): number;
function frexp(x: number): [number, number];

LibC Math Functions

Epsilon-Based Equality

Floating-point equality comparison functions using epsilon tolerance to handle precision issues in numeric computations.

function eqDelta(a: number, b: number, eps?: number): boolean;
function eqDeltaScaled(a: number, b: number, eps?: number): boolean;

Epsilon-Based Equality

Local Extrema Analysis

Functions for finding local minima and maxima in numeric data sequences, useful for signal processing and data analysis.

function isMinima(a: number, b: number, c: number): boolean;
function minimaIndex(values: number[], from?: number, to?: number): number;
function minimaIndices(values: number[], from?: number, to?: number): Generator<number>;

Local Extrema Analysis

Utility Functions

Additional mathematical utilities including prime numbers, permutations, safe operations, and specialized calculations.

function factorial(n: number): number;
function nearestPrime(x: number): number;
function safeDiv(a: number, b: number): number;
function absDiff(a: number, b: number): number;

Utility Functions