title: API Reference description: Complete API reference for @primebrick/decimal — every exported symbol.
API Reference
Every exported symbol from @primebrick/decimal, rendered mechanically from the
TypeDoc extraction. This page is regenerated from docs/dev-guide/_extracted/api.json
on every pnpm extract-docs run — do not edit by hand.
Classes
Decimal
| Property | Type | Description |
|---|---|---|
| v | bigint | Unscaled integer: value = v × 10^-scale. |
| scale | number | Number of base-10 digits after the decimal point. Always >= 0. |
| periodic | boolean | Provenance flag: the producing operation truncated a non-terminating expansion. |
Decimal(v, scale, periodic)
Internal constructor — prefer dec(), fromPG(), fromNumber(), fromBigInt().
| Parameter | Type | Description |
|---|---|---|
| v | bigint | |
| scale | number | |
| periodic | boolean |
Decimal.toString(): string
Canonical plain decimal string, e.g. -12.3400 (scale preserved).
Decimal.toJSON(): string
Wire form for ext-json / JSON.stringify: "12.34d" — a self-describing
string so the value survives naive JSON.parse visibly typed and can be
revived by schema-aware hydration (fromWire).
Decimal.toNumber(): number
Lossy coercion — may round. Use only for display hints, never for math.
DecimalError
Errors raised by @primebrick/decimal.
| Property | Type | Description |
|---|---|---|
| code | "INVALID_INPUT" | "NON_FINITE" | "DIVISION_BY_ZERO" | "INVALID_SCALE" | "INVALID_ROUNDING" |
DecimalError(code, message)
| Parameter | Type | Description |
|---|---|---|
| code | "INVALID_INPUT" | "NON_FINITE" | "DIVISION_BY_ZERO" | "INVALID_SCALE" | "INVALID_ROUNDING" | |
| message | string |
Types & Enums
DecimalInput
Anything coercion functions accept: Decimal, native number, bigint, or a decimal string.
Type: Decimal \| number \| bigint \| string
RoundingMode
Type: "UP" \| "DOWN" \| "CEILING" \| "FLOOR" \| "HALF_UP" \| "HALF_DOWN" \| "HALF_EVEN"
Constants
fromPG
Alias of dec() — parse a PostgreSQL numeric/decimal text value.
Type: (input: DecimalInput) => Decimal
fromString
Type: (input: DecimalInput) => Decimal
fromWire
Alias of dec() — tolerates the "…d" wire suffix.
Type: (input: DecimalInput) => Decimal
NUMERIC_MIN_SIG_DIGITS
Minimum significant digits preserved by automatic div scale — mirrors
PostgreSQL NUMERIC_MIN_SIG_DIGITS (16). See pgDivScale.
Type: 16
ONE
Type: Decimal
TEN
Type: Decimal
ZERO
Type: Decimal
Functions
abs(d): Decimal
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput |
add(a, b): Decimal
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput |
ceil(d): Decimal
Smallest integer >= d.
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput |
cmp(a, b): -1 \| 0 \| 1
Numeric comparison ignoring scale: cmp(1.0, 1.00) === 0. Returns -1 | 0 | 1.
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput |
dec(input): Decimal
Decimal — pass-through. string — parsed (PG text form or "…d" wire form). number — via shortest round-trip toString so 0.1 stays "0.1". bigint — scale 0.
| Parameter | Type | Description |
|---|---|---|
| input | DecimalInput |
div(a, b, opts): Decimal
a / b. Without scale, the result uses the PostgreSQL numeric
division rule (pgDivScale — e.g. 1/3 → scale 20, 10/4 → 16), so
Decimal↔DB computations compare equal digit-for-digit. Rounding defaults
to HALF_UP. When the true quotient does not terminate at the target
scale the result is flagged periodic (isPeriodic(d) → true).
div(1, 3) // 0.33333333333333333333 — periodic div(10, 4) // 2.5000000000000000 div(1, 3, 2) // 0.33 div(a, b, { scale: 6, rounding: "HALF_EVEN" })
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput | |
| opts | number | { scale: number; rounding: RoundingMode } |
eq(a, b): boolean
Numeric equality ignoring scale — eq(1.0, 1.00) is true.
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput |
floor(d): Decimal
Largest integer <= d.
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput |
fromBigInt(v, scale): Decimal
| Parameter | Type | Description |
|---|---|---|
| v | bigint | |
| scale | number |
fromNumber(n): Decimal
| Parameter | Type | Description |
|---|---|---|
| n | number |
isDecimal(v): v is Decimal
| Parameter | Type | Description |
|---|---|---|
| v | unknown |
isPeriodic(d): boolean
true when the value was produced by a truncated non-terminating division.
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput |
max(a, b): Decimal
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput |
min(a, b): Decimal
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput |
mod(a, b): Decimal
a mod b — remainder of truncated division at the common scale.
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput |
mul(a, b): Decimal
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput |
neg(d): Decimal
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput |
normalize(d): Decimal
Strip trailing fractional zeros — 1.230 → 1.23, 12.000 → 12.
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput |
parseDecimal(input): Decimal
Parse a decimal string into unscaled form.
Accepts: "12", "-0.5", ".5", "5.", "1.5e3", "1E-3", "+4".
Rejects: NaN, Infinity, empty strings, hex, non-numeric garbage.
Scale is preserved as written ("1.230" → scale 3).
| Parameter | Type | Description |
|---|---|---|
| input | string |
pgDivScale(a, b): number
PostgreSQL-faithful result scale for x / y (mirrors select_div_scale):
max(16 - 4·qweight, x.scale, y.scale) — 16 significant digits minimum.
Verified live: 1/3→20, 10/4→16, 1.00/8→20, 2/1→16, 100/3→16.
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput |
pow10(n): bigint
| Parameter | Type | Description |
|---|---|---|
| n | number |
rescale(d, newScale, mode): Decimal
Re-express d at newScale. Growing is exact; shrinking applies mode
(default HALF_UP, matching PostgreSQL round()).
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput | |
| newScale | number | |
| mode | RoundingMode |
round(d, scale, mode): Decimal
Round to scale fractional digits (default HALF_UP).
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput | |
| scale | number | |
| mode | RoundingMode |
signum(d): -1 \| 0 \| 1
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput |
strictEq(a, b): boolean
Exact structural equality — value AND scale must match (strictEq(1.0, 1.00) is false).
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput |
sub(a, b): Decimal
| Parameter | Type | Description |
|---|---|---|
| a | DecimalInput | |
| b | DecimalInput |
toPG(d): string
PostgreSQL parameter form — plain canonical decimal string, no d suffix.
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput |
toWire(d): string
Wire form — "…d" suffixed string.
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput |
trunc(d): Decimal
Integer part, toward zero.
| Parameter | Type | Description |
|---|---|---|
| d | DecimalInput |