@arki/math

Zero-dependency math toolkit for TypeScript. Exact where it must be, fast where it can be, and honest about which is which. Runs unchanged in Node 22+, Bun, Deno, browsers, and React Native (Hermes).

Install

bun add @arki/math
# or: npm install @arki/math
# or: deno add npm:@arki/math

Quick start

Total an invoice exactly. Only the tax step rounds, and it says how.

import { decimal } from '@arki/math/decimal';
 
type InvoiceLine = { readonly price: string; readonly quantity: number };
 
/** Totals an invoice exactly. Only the tax step rounds, and it says how. */
export function invoiceTotals(lines: readonly InvoiceLine[], taxRate: string) {
  const subtotal = lines.reduce((total, line) => total.plus(decimal(line.price).times(line.quantity)), decimal(0));
  const tax = subtotal.times(taxRate).toScale(2, 'halfEven');
  return { subtotal: subtotal.toString(), tax: tax.toString(), total: subtotal.plus(tax).toString() };
}
 
invoiceTotals(
  [
    { price: '19.99', quantity: 3 },
    { price: '0.10', quantity: 3 },
  ],
  '0.19',
);
// { subtotal: '60.27', tax: '11.45', total: '71.72' }

Float math gives 60.269999999999996 here. Decimal gives 60.27.

When not to use this

• You need symbolic algebra or expression parsing. Use @arki/expr and @arki/cas, built on this package.
• You need money with a currency. Use @arki/money. It builds on this package: same rounding modes, same error family, and it accepts Decimal and Rational as amounts.
• You need sparse matrices or big numerical linear algebra. linear-algebra works on plain arrays of float64.
• You need arbitrary-precision trigonometry. complex, geometry and the rest of the numeric layer are float64.
• You only add and compare small integers. Plain number is enough.

Runtime support

• Node 22+, Bun, Deno, browsers: everything, verified by the test suite and a smoke run of the built package in each runtime (bun run test:runtimes).
• React Native (Hermes V1): everything runs; bun run test:runtimes checks it when HERMES_BIN points at a Hermes binary. Two Intl gaps shape formatting and parsing:
  • Hermes formats decimal text through a double. Decimal values are rounded exactly first, so anything up to 15 shown digits (every normal amount) prints exactly; more throws UnsupportedFeatureError instead of printing a wrong digit. Compact notation accepts whole numbers only.
  • Hermes on iOS has no formatToParts, so locale parsing throws UnsupportedFeatureError; pass symbols to parse without Intl.
  • A non-default rounding mode throws UnsupportedFeatureError.
• Pure ESM, no runtime-specific globals; the lint config rejects any node:*/bun:* import or process/Buffer use in library code.

Public imports

Everything is a subpath import, tree-shakeable by concern. The root @arki/math re-exports it all except linear-algebra, whose short names (plus, times, norm, inverse) would clash at the root.

Deliberately not here: expression parsing and symbolic algebra (they are languages with their own security surface; they live in the sibling packages @arki/expr and @arki/cas), sparse matrices, and arbitrary-precision trigonometry. geometry, linear-algebra, complex, polynomial, roots, integrate and differentiate work on plain number (float64), like the rest of the numeric layer.

Failure behaviour

Every error has a stable code (ARKI_MATH_E001 to E011, also exported as MATH_ERROR_CODES) and a one-sentence remediation. Match on the code, never on the message. Wrong runtime types still throw the built-in TypeError.

import { decimal } from '@arki/math/decimal';
import { MathError, RoundingNecessaryError } from '@arki/math/errors';
 
try {
  decimal(1).dividedBy(3);
} catch (error) {
  if (error instanceof RoundingNecessaryError) {
    /* ask for a scale */
  }
  if (error instanceof MathError) {
    /* any failure from this package */
  }
}

Limits

Every Decimal and Rational — input or result — has at most 10 000 digits (integer digits plus scale) and an exponent magnitude of at most 10 000; anything larger throws ResourceLimitError, early from an estimate and exactly on the result. Internal guard digits do not count, so PI(9999) is the largest π, and every value the library returns parses back from its own toString(). Bigint factorial, permutations and combinations allow results up to 100 000 digits; fibonacci and fromBase keep 10 000. These are resource guards against hostile input, not precision settings — within them, arithmetic is exact.

Boundary example: a Decimal with 10 000 digits is the largest allowed. One more digit throws ResourceLimitError.

import { decimal } from '@arki/math/decimal';
import { ResourceLimitError } from '@arki/math/errors';
 
decimal('9'.repeat(10_000)); // the largest allowed
let limited = false;
try {
  decimal('9'.repeat(10_001));
} catch (error) {
  limited = error instanceof ResourceLimitError;
}
if (!limited) throw new Error('10 001 digits must throw ResourceLimitError');

Documentation

One page per module, with the full reference and examples. The accuracy claims and their evidence are in Accuracy.

• Accuracy: what is exact, what is correctly rounded, and the reference data behind each claim.
• Agent guide: the model, the task map and the rules.
• llms.txt: the short index for agents.
• CHANGELOG: what changed in each version.

Support

Report a bug or ask a question in the Arki issue tracker. Include the module, the input and the error code.

Two layers, by design

Exact types for money, measurements, calculators — anything where 0.1 + 0.2 !== 0.3 is a bug:

import { decimal } from '@arki/math/decimal';
import { ratio } from '@arki/math/rational';
 
decimal('0.1').plus('0.2').toString(); // '0.3'
decimal('19.99').times(3).toString(); // '59.97'  (scale is kept: 1.10 × 3 = 3.30)
decimal(1).dividedBy(8).toString(); // '0.125'  (exact, so no rounding needed)
decimal(1).dividedBy(3); // throws RoundingNecessaryError — say how to round:
decimal(1).dividedBy(3, { scale: 4, rounding: 'halfEven' }).toString(); // '0.3333'
 
ratio(1, 3).plus(ratio(1, 6)).toString(); // '1/2'
ratio('0.(3)').eq(ratio(1, 3)); // true  — repeating decimals parse
ratio('3.14159265').approximate(1000).toString(); // '355/113'

Plain-number helpers for UI, geometry, charts — fast float math with the sharp edges filed off:

import { clamp, inRange, lerp, round, roundTo } from '@arki/math/number';
 
round(1.005, 2); // 1.01  — rounds the number you typed, not its binary approximation
round(2.5, 0, 'halfEven'); // 2
roundTo(127.3, 5); // 125
clamp(105, 0, 100); // 100
lerp(0, 10, 0.5); // 5
inRange(5, 0, 5); // false — default bounds are [min, max)

Nothing in this package returns NaN or null to signal failure. Every deliberate failure is a typed error under MathError; wrong runtime types throw TypeError.

Accuracy

Every claim is checked by a test against independent reference data: mpmath for decimal-math, the special functions and the distributions, and the NIST StRD certified values for statistics and regression. The guarantees come in three kinds: exact, correctly rounded, and accurate to a stated bound. The table of every row, with its evidence, is in Accuracy.

Benchmarks

Speed of @arki/math against the libraries most people reach for: decimal.js, big.js and bignumber.js for decimal arithmetic; fraction.js for exact fractions; simple-statistics and jstat for descriptive statistics; jstat for probability distributions; simple-statistics and regression (regression-js) for curve fitting; ml-matrix and mathjs for linear algebra; complex.js and mathjs for complex numbers; mathjs for polynomial roots. Each table only ranks libraries that returned the same result on every checked input. The published tables come from a publish run on an idle machine and keep every case, including the ones where @arki/math is slower.

Node v22.13.1 on Apple M2 Max, 2026-10-13. Median time per operation, lower is better.

Decimal plus (1234.5678 + 98.76)

Decimal times

Decimal divide, 10 places, half-even

Every library rounds the quotient to 10 decimal places, half-even. The other libraries divide at a working precision first and round after; @arki/math rounds once, exactly.

Decimal parse a string

Decimal toString (30 integer digits, 9 decimals)

Rational plus (355/113 + 22/7)

Rational times

Mean of 1,000 numbers

Standard deviation of 1,000 numbers (population)

90th percentile of 1,000 numbers

Both interpolate linearly between ranks, so results agree to rounding.

Normal distribution cdf at 1.96

Normal distribution quantile at 0.975

Student t (10 degrees of freedom) quantile at 0.975

@arki/math solves the quantile until |cdf(x) − p| ≤ 1e-12 and rejects bad input; jstat uses a looser fixed approximation with no input checks.

Read the rows with the contracts in mind:

• @arki/math Decimal is exact: it stores a bigint plus a scale and never rounds unless you ask. Division throws when the result does not terminate, so every divide case below passes an explicit { scale, rounding }.
• decimal.js and bignumber.js round to a working precision on every operation (here 40 significant digits for decimal.js, 20 decimal places for bignumber.js and big.js). They are fast because they give up exactness; @arki/math gives up some speed to keep it.
• Rational is exact and always reduced to lowest terms, as in fraction.js.
• Statistics functions in @arki/math check every element is a finite number, copy the input, sum with Neumaier compensation (so the total is accurate) and sort the full array for percentiles. simple-statistics skips the checks and the copy, uses plain summation and selects the percentile without a full sort. That is why they are much faster on 1,000 numbers: @arki/math trades speed for validated input and accurate sums.

Reproduce with bun run bench in the package directory; regenerate this section with bun run bench --write-readme.

License

MIT