0
# @thi.ng/math
1

2
@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.
3

4
## Package Information
5

6
- **Package Name**: @thi.ng/math
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @thi.ng/math`
10

11
## Core Imports
12

13
```typescript
14
import * as math from "@thi.ng/math";
15
```
16

17
Individual module imports (tree-shakeable):
18

19
```typescript
20
import { PI, TAU, PHI } from "@thi.ng/math/api";
21
import { mix, clamp } from "@thi.ng/math/interval";
22
import { easeInOut3, easeOutBounce } from "@thi.ng/math/easing";
23
```
24

25
For CommonJS:
26

27
```javascript
28
const math = require("@thi.ng/math");
29
const { PI, TAU } = require("@thi.ng/math/api");
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { PI, TAU, clamp, mix, deg, rad } from "@thi.ng/math";
36

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

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

44
// Angle conversions
45
const degrees = deg(PI); // 180
46
const radians = rad(90); // 1.5707...
47
```
48

49
## Architecture
50

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

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

59
## Capabilities
60

61
### Mathematical Constants & Types
62

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

65
```typescript { .api }
66
const PI: number;
67
const TAU: number;
68
const PHI: number;
69
const EPS: number;
70

71
type Crossing = "equal" | "flat" | "under" | "over" | "other";
72
```
73

74
[Constants & Types](./constants-types.md)
75

76
### Interval & Range Operations
77

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

80
```typescript { .api }
81
function clamp(x: number, min: number, max: number): number;
82
function wrap(x: number, min: number, max: number): number;
83
function inRange(x: number, min: number, max: number): boolean;
84
```
85

86
[Interval Operations](./intervals.md)
87

88
### Interpolation & Mixing
89

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

92
```typescript { .api }
93
function mix(a: number, b: number, t: number): number;
94
function mixCubic(a: number, b: number, c: number, d: number, t: number): number;
95
function smoothStep(edge: number, edge2: number, x: number): number;
96
```
97

98
[Interpolation & Mixing](./interpolation.md)
99

100
### Angle Mathematics & Trigonometry
101

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

104
```typescript { .api }
105
function deg(theta: number): number;
106
function rad(theta: number): number;
107
function angleDist(a: number, b: number): number;
108
function sincos(theta: number, n?: number): [number, number];
109
```
110

111
[Angle & Trigonometry](./angles.md)
112

113
### Easing Functions
114

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

117
```typescript { .api }
118
function easeInOut3(t: number): number;
119
function easeOutBounce(t: number): number;
120
function defEaseInExp(k: number): (t: number) => number;
121
```
122

123
[Easing Functions](./easing.md)
124

125
### Integer Mathematics
126

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

129
```typescript { .api }
130
function addi32(a: number, b: number): number;
131
function mulu16(a: number, b: number): number;
132
function signExtend8(a: number): number;
133
```
134

135
[Integer Mathematics](./integers.md)
136

137
### Precision & Rounding
138

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

141
```typescript { .api }
142
function roundTo(x: number, prec?: number): number;
143
function mod(a: number, b: number): number;
144
function fract(x: number): number;
145
```
146

147
[Precision Control](./precision.md)
148

149
### Mathematical Solvers
150

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

153
```typescript { .api }
154
function solveQuadratic(a: number, b: number, c: number, eps?: number): number[];
155
function solveCubic(a: number, b: number, c: number, d: number, eps?: number): number[];
156
function derivative(f: (x: number) => number, eps?: number): (x: number) => number;
157
```
158

159
[Mathematical Solvers](./solvers.md)
160

161
### Value Fitting & Mapping
162

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

165
```typescript { .api }
166
function norm(x: number, a: number, b: number): number;
167
function fit(x: number, a: number, b: number, c: number, d: number): number;
168
function fitClamped(x: number, a: number, b: number, c: number, d: number): number;
169
```
170

171
[Value Fitting & Mapping](./fit.md)
172

173
### LibC Math Functions
174

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

177
```typescript { .api }
178
function copysign(x: number, y: number): number;
179
function exp2(x: number): number;
180
function fmod(x: number, y: number): number;
181
function frexp(x: number): [number, number];
182
```
183

184
[LibC Math Functions](./libc.md)
185

186
### Epsilon-Based Equality
187

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

190
```typescript { .api }
191
function eqDelta(a: number, b: number, eps?: number): boolean;
192
function eqDeltaScaled(a: number, b: number, eps?: number): boolean;
193
```
194

195
[Epsilon-Based Equality](./eqdelta.md)
196

197
### Local Extrema Analysis
198

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

201
```typescript { .api }
202
function isMinima(a: number, b: number, c: number): boolean;
203
function minimaIndex(values: number[], from?: number, to?: number): number;
204
function minimaIndices(values: number[], from?: number, to?: number): Generator<number>;
205
```
206

207
[Local Extrema Analysis](./extrema.md)
208

209
### Utility Functions
210

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

213
```typescript { .api }
214
function factorial(n: number): number;
215
function nearestPrime(x: number): number;
216
function safeDiv(a: number, b: number): number;
217
function absDiff(a: number, b: number): number;
218
```
219

220
[Utility Functions](./utilities.md)