Module numbers

General-purpose number operations.

Computing Over Either Numeric Type

Combine values without committing to number or to bigint, so that code handling both, like aggregates and statistics, states an operation once and each call keeps the numeric type it was given:

import { add, sub } from '@metreeca/core/numbers';

add(1, 2);   // 3
sub(1n, 2n); // -1n
Copy

Operands are held to a single numeric type: JavaScript refuses to mix a number with a bigint, and a mixed pair is reported rather than silently coerced.

Scaling Without Losing the Numeric Type

Scale by a plain factor, taking a fractional result where the scaled value is a number and an integral one where it is a bigint, so that averages and shares stay in the type they were computed from:

import { div, mul } from '@metreeca/core/numbers';

mul(7, 0.5); // 3.5
div(7, 2);   // 3.5
div(7n, 2);  // 4n, as no fractional bigint can carry the remainder
Copy

bigint quotients are rounded to the nearest integer, halves away from zero, whatever the sign of the operands. Scaling a bigint takes an integral factor, as a fractional one has no bigint counterpart.