std/decimal

Import from @norbital-ai/std/decimal

std/decimal (§3.7, rule 68): exact decimals. A value is a bigint coefficient and a scale, so no amount ever passes through a float; Decimal.fromNumber is the one explicit door from a double. valueOf throws, so a + b on two decimals fails loudly instead of concatenating strings (> on Decimal is doctor DR-1).

CurrencyCode type

type CurrencyCode = string & {
    readonly __currency: unique symbol;
};

An ISO 4217 currency code, branded.

Source: packages/std/src/decimal.ts:9

Decimal class

class Decimal {
    #private;
    private constructor();
    /** `x instanceof Decimal` holds for a decimal from any std copy; its methods are its own copy's, and `of` re-reads it. */
    static [Symbol.hasInstance](v: unknown): boolean;
    get [BRAND](): true;
    /** Refuses NaN, exponents, blanks and non-numeric text; a JS number must be an integer. */
    static of(v: DecimalLike): Decimal;
    /** The only door from a float: its shortest round-trip digits, rounded to `scale`. */
    static fromNumber(v: number, scale: number, mode?: Rounding): Decimal;
    plus(o: DecimalLike): Decimal;
    minus(o: DecimalLike): Decimal;
    times(o: DecimalLike): Decimal;
    /** Division needs a scale: the result is rounded to it. */
    div(o: DecimalLike, scale: number, mode?: Rounding): Decimal;
    round(scale: number, mode?: Rounding): Decimal;
    /** Rounded to the currency's minor unit (JPY 0, SGD 2, KWD 3). */
    roundTo(c: CurrencyCode | string, mode?: Rounding): Decimal;
    neg(): Decimal;
    abs(): Decimal;
    sign(): -1 | 0 | 1;
    isZero(): boolean;
    /** The number of digits after the point, as stored (`1.20` → 2). */
    get scale(): number;
    cmp(o: DecimalLike): -1 | 0 | 1;
    eq(o: DecimalLike): boolean;
    lt(o: DecimalLike): boolean;
    lte(o: DecimalLike): boolean;
    gt(o: DecimalLike): boolean;
    gte(o: DecimalLike): boolean;
    toString(): string;
    /** The wire form (D6): `{ $dec: '1.20' }`, the one tag the wire carries, in both directions…

An exact decimal: a bigint coefficient and a scale, so no amount passes through a float. Build one with Decimal.of (or dec); arithmetic is plus, minus, times, div with a rounding mode, comparison is cmp. valueOf throws, so a + b on decimals fails loudly.

Members

Name	Type	Description
#private	any
plus	(o: DecimalLike) => Decimal
minus	(o: DecimalLike) => Decimal
times	(o: DecimalLike) => Decimal
div	(o: DecimalLike, scale: number, mode?: Rounding) => Decimal	Division needs a scale: the result is rounded to it.
round	(scale: number, mode?: Rounding) => Decimal
roundTo	(c: CurrencyCode | string, mode?: Rounding) => Decimal	Rounded to the currency's minor unit (JPY 0, SGD 2, KWD 3).
neg	() => Decimal
abs	() => Decimal
sign	() => -1 | 0 | 1
isZero	() => boolean
scale	number	The number of digits after the point, as stored (1.20 → 2).
cmp	(o: DecimalLike) => -1 | 0 | 1
eq	(o: DecimalLike) => boolean
lt	(o: DecimalLike) => boolean
lte	(o: DecimalLike) => boolean
gt	(o: DecimalLike) => boolean
gte	(o: DecimalLike) => boolean
toString	() => string
toJSON	() => { readonly $dec: string; }	The wire form (D6): { $dec: '1.20' }, the one tag the wire carries, in both directions.
toNumber	() => number	Lossy, and named so.
valueOf	() => never

Example

dec('19.90').times(3).round(2, 'halfUp').toString() // '59.70'

Source: packages/std/src/decimal.ts:52

DecimalLike type

type DecimalLike = Decimal | string | bigint | number | {
    readonly $dec: string;
};

A decimal string, a bigint, an integer, or a tagged wire value ({ $dec: '1.20' }).

Source: packages/std/src/decimal.ts:11

Rounding const

const Rounding: readonly ["halfUp", "halfEven", "down", "up", "floor", "ceil"]

The rounding modes; halfUp is Postgres round(numeric): half away from zero.

Source: packages/std/src/decimal.ts:6

currency function

function currency(code: string): CurrencyCode

An ISO 4217 code (from the runtime's Intl data); anything else throws.

Parameters

Name	Type	Description
code	string

Source: packages/std/src/decimal.ts:231

dec function

function dec(v: DecimalLike): Decimal

Shorthand for Decimal.of: a decimal from a string, bigint, integer or tagged wire value.

Parameters

Name	Type	Description
v	DecimalLike

Source: packages/std/src/decimal.ts:200

minorDigits function

function minorDigits(c: CurrencyCode | string): 0 | 2 | 3

ISO 4217 minor-unit digits.

Parameters

Name	Type	Description
c	CurrencyCode | string

Source: packages/std/src/decimal.ts:238

sum function

function sum(values: Iterable<DecimalLike>): Decimal

The exact total of decimal-like values; 0 for none.

Parameters

Name	Type	Description
values	Iterable<DecimalLike>

Source: packages/std/src/decimal.ts:202