A lightweight, dependency-free JavaScript library that fills the
gaps the native Math object leaves behind — statistics, number theory, and numeric
helpers in under 1 kb.
npm
npm install @peterbenoit/mathsjsCDN (jsDelivr)
<script src="https://cdn.jsdelivr.net/npm/@peterbenoit/mathsjs/Maths.js"></script>Clone
git clone https://github.com/peterbenoit/Maths.js.gitNode.js
const Maths = require('@peterbenoit/mathsjs');
Maths.avg(10, 20, 30); // 20
Maths.median(7, 1, 4); // 4
Maths.gcd(48, 18); // 6Browser (script tag)
<script src="/path/to/Maths.js"></script>
<script>
Maths.sum(1, 2, 3); // 6
Maths.clamp(12, 0, 10); // 10
</script>Attaches to globalThis.Maths in browser
contexts. No bundler or build step needed.
All methods are static on the Maths object.
No instantiation required.
| Method | Description | Returns |
|---|---|---|
avg(...values) |
Arithmetic mean of all provided values | number |
sum(...values) |
Total of all provided values | number |
| Method | Description | Returns |
|---|---|---|
median(...values) |
Middle value; mean of two middle values for even-length inputs | number |
mode(...values) |
Most frequently occurring value(s); null
when all values are unique |
number[] | null |
range(...values) |
Difference between max and min | number |
percentile(values, p) |
Value at the pth percentile (0–100) | number |
| Method | Description | Returns |
|---|---|---|
factorial(n) |
Product of all positive integers up to n | number |
gcd(a, b) |
Greatest common divisor of two integers | number |
lcm(a, b) |
Least common multiple of two integers | number |
| Method | Description | Returns |
|---|---|---|
clamp(value, min, max) |
Constrains a value to the range [min, max] | number |
distance(x1, y1, x2, y2) |
Euclidean distance between two 2D points | number |
Statistics
Maths.avg(10, 20, 30); // 20
Maths.median(1, 3, 2); // 2
Maths.median(1, 2, 3, 4); // 2.5
Maths.mode(1, 2, 2, 3); // [2]
Maths.mode(1, 1, 2, 3, 3); // [1, 3]
Maths.mode(1, 2, 3); // null
Maths.range(1, 8, 3); // 7
Maths.percentile([1,2,3,4,5], 90); // 5Number Theory
Maths.factorial(5); // 120
Maths.factorial(0); // 1
Maths.gcd(48, 18); // 6
Maths.gcd(100, 75); // 25
Maths.lcm(4, 6); // 12
Maths.lcm(7, 0); // 0Utility
Maths.clamp(12, 0, 10); // 10
Maths.clamp(-5, 0, 10); // 0
Maths.clamp(7, 0, 10); // 7
Maths.distance(0, 0, 3, 4); // 5
Maths.distance(1, 1, 4, 5); // 5Drop it in anywhere — dashboards, data scripts, static pages — without adding meaningful weight to your bundle.
Every method throws typed
TypeError or RangeError with clear messages instead of silently
returning NaN.
Works in browser via
<script> tag or in Node.js via require() with no build step
and no transitive packages.
Tests use Node's native node:test
module — run them with node --test Maths.test.js, no extra dev dependencies.
Maths.js validates all inputs and throws typed errors
with descriptive messages. No silent NaN returns, no swallowed exceptions.
| Error type | When thrown |
|---|---|
TypeError |
Non-numeric input, non-finite number, non-integer where integer required, or wrong argument type |
RangeError |
Empty input, p outside [0, 100],
n < 0 for factorial, or min > max for clamp |
try {
Maths.avg();
} catch (e) {
e instanceof RangeError; // true
e.message; // "avg requires at least one numeric value."
}
try {
Maths.factorial(-1);
} catch (e) {
e instanceof RangeError; // true
e.message; // "n must be a non-negative integer."
}variance / stdDev — population and sample variance
iqr / mad —
interquartile range and median absolute deviation
nCr / nPr —
combinations and permutations
roundTo — precision-safe rounding
zScore / normalize — standard score and normalization
Suggestions welcome — open an issue or PR on GitHub.
One import, eleven methods, zero dependencies. Covers the math that comes up in real projects without pulling in a full symbolic algebra system.