@onrail-xyz/amount 1.0.0

package/dist/aggregating.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregating.d.ts","sourceRoot":"","sources":["../src/aggregating.ts"],"names":[],"mappings":"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"}

package/dist/aggregating.js

@@ -0,0 +1,31 @@
+import { Rational } from "./rational.js";
+import { isAmount } from "./amount.js";
+import { isRate } from "./rate.js";
+export function min(first, ...rest) {
+    if (isAmount(first) || isRate(first))
+        return rest.reduce((acc, value) => acc.le(value) ? acc : value, first);
+    return rest.reduce((acc, value) => acc.le(value) ? acc : Rational.from(value), Rational.from(first));
+}
+export function max(first, ...rest) {
+    if (isAmount(first) || isRate(first))
+        return rest.reduce((acc, value) => acc.ge(value) ? acc : value, first);
+    return rest.reduce((acc, value) => acc.ge(value) ? acc : Rational.from(value), Rational.from(first));
+}
+export function sum(first, ...rest) {
+    if (typeof first === "number" || typeof first === "bigint")
+        first = Rational.from(first);
+    return rest.reduce((acc, value) => acc.add(value), first);
+}
+export function compare(a, b) {
+    if (typeof a === "number" || typeof a === "bigint")
+        a = Rational.from(a);
+    if (a instanceof Rational)
+        return a.cmp(b);
+    //no subtraction: a sort calls this n·log n times, and an amount's or rate's own gt/lt check
+    //  the kinds
+    const ordered = a;
+    return ordered.gt(b) ? 1 : ordered.lt(b) ? -1 : 0;
+}
+export function clamp(x, lo, hi) {
+    return min(max(x, lo), hi);
+}

package/dist/allocating.d.ts

@@ -0,0 +1,9 @@
+import type { OfLength, RoArray, RoNeTuple } from "@onrail-xyz/utils";
+import type { Rationalish } from "./rational.js";
+import type { Kind, KindWithAtomic, SymbolsOf } from "./kind.js";
+import type { Amount } from "./amount.js";
+type Allocation<K extends Kind, P extends number | RoArray<Rationalish>> = P extends RoArray<Rationalish> ? OfLength<Amount<K>, P["length"]> : OfLength<Amount<K>, P & number>;
+export declare function allocate<K extends KindWithAtomic, const P extends number | RoNeTuple<Rationalish>>(amount: Amount<K>, parts: P): Allocation<K, P>;
+export declare function allocate<K extends Kind, const P extends number | RoNeTuple<Rationalish>>(amount: Amount<K>, parts: P, unitSymbol: SymbolsOf<K>): Allocation<K, P>;
+export {};
+//# sourceMappingURL=allocating.d.ts.map

package/dist/allocating.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocating.d.ts","sourceRoot":"","sources":["../src/allocating.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI1C,KAAK,UAAU,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,IACrE,CAAC,SAAS,OAAO,CAAC,WAAW,CAAC,GAC5B,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,GAChC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC;AAOpC,wBAAgB,QAAQ,CAChB,CAAC,SAAS,cAAc,EAC9B,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,CAAC,WAAW,CAAC,EAC/C,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACjD,wBAAgB,QAAQ,CAChB,CAAC,SAAS,IAAI,EACpB,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,CAAC,WAAW,CAAC,EAC/C,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/allocating.js

@@ -0,0 +1,31 @@
+import { isArray } from "@onrail-xyz/utils";
+import { Rational } from "./rational.js";
+export function allocate(amount, parts, unitSymbol = "atomic") {
+    if (!amount.eq(amount.floorTo(unitSymbol)))
+        throw new Error(`Amount is not a whole number of ${unitSymbol} units - quantize it first ` +
+            `(floorTo/roundTo/ceilTo)`);
+    if (isArray(parts) ? parts.length === 0 : !(Number.isSafeInteger(parts) && parts > 0))
+        throw new Error("parts must be a nonempty weights list or a positive integer count");
+    const weights = isArray(parts)
+        ? parts.map(w => Rational.from(w))
+        : Array.from({ length: parts }, () => Rational.from(1n));
+    const totalWeight = weights.reduce((acc, w) => acc.add(w), Rational.from(0n));
+    if (totalWeight.eq(0n))
+        throw new Error("weights must not sum to zero");
+    const inUnit = amount.in(unitSymbol);
+    const total = typeof inUnit === "bigint" ? inUnit : inUnit.floor(); //integral, so floor is exact
+    const shares = weights.map(w => Rational.from(total).mul(w).div(totalWeight));
+    const floors = shares.map(s => s.floor());
+    let leftover = total - floors.reduce((acc, f) => acc + f, 0n);
+    const byFraction = shares
+        .map((s, i) => [s.sub(floors[i]), i])
+        .sort((a, b) => a[0].eq(b[0]) ? a[1] - b[1] : a[0].gt(b[0]) ? -1 : 1);
+    const bumped = new Set();
+    for (const [, i] of byFraction) {
+        if (leftover === 0n)
+            break;
+        bumped.add(i);
+        --leftover;
+    }
+    return floors.map((f, i) => amount.ofSame(bumped.has(i) ? f + 1n : f, unitSymbol));
+}

package/dist/amount.d.ts

@@ -0,0 +1,68 @@
+import type { Brand, NarrowTo, Opts, RoArray } from "@onrail-xyz/utils";
+import type { Rationalish, ToFixedOptions } from "./rational.js";
+import { Rational } from "./rational.js";
+import type { Kind, KindWithHuman, SymbolsOf, DecimalSymbolsOf, CandidateKinds } from "./kind.js";
+import { Rate } from "./rate.js";
+export type AmountFromArgs<K extends Kind> = [kind: K, unitSymbol: SymbolsOf<K>];
+export declare const scalar: <const T>(base: T) => import("@onrail-xyz/utils").IsAny<T> extends true ? import("@onrail-xyz/utils").Branded<unknown, "scalar"> : import("@onrail-xyz/utils").Unbrand<T> & import("@onrail-xyz/utils").Branded<import("@onrail-xyz/utils").Unbrand<T>, "scalar" | import("@onrail-xyz/utils").ExtractTags<T>>;
+export declare const kindOf: <K extends Kind>(amount: Amount<K>) => K;
+export declare const isAmount: <T>(value: T) => value is NarrowTo<T, Amount<Kind>>;
+export declare class _Amount<K extends Kind> {
+    private readonly value;
+    readonly kind: K;
+    private constructor();
+    static ofKind<const K extends KindWithHuman>(kind: K): (numericalValue: Rationalish | string, unitSymbol?: SymbolsOf<K>) => Amount<K>;
+    static ofKind<const K extends Kind>(kind: K): (numericalValue: Rationalish | string, unitSymbol: SymbolsOf<K>) => Amount<K>;
+    static from<const K extends KindWithHuman>(numericalValue: Rationalish | string, ...args: [kind: K, unitSymbol?: SymbolsOf<K>]): Amount<K>;
+    static from<const K extends Kind>(numericalValue: Rationalish | string, ...args: AmountFromArgs<K>): Amount<K>;
+    static parse<const KS extends RoArray<Kind>>(str: string, ...kinds: KS): Amount<KS[number]>;
+    static isOfKind<A extends Amount<Kind>, K extends CandidateKinds<A["kind"]>>(amt: A, kind: K): amt is NarrowTo<A, Amount<K>>;
+    static allOfKind<A extends Amount<Kind>, K extends CandidateKinds<A["kind"]>>(amts: RoArray<A>, kind: K): amts is RoArray<NarrowTo<A, Amount<K>>>;
+    zero(): this;
+    ofSame<S extends SymbolsOf<K>>(numericalValue: Rationalish | string, unitSymbol: S): this;
+    toString(): string;
+    toString(system: Extract<keyof K["systems"], string>, opts?: Opts<ToFixedOptions>): string;
+    toString(mode: "approximate" | "exact", opts?: Opts<ToFixedOptions & {
+        system: Extract<keyof K["systems"], string>;
+    }>): string;
+    toString<S extends SymbolsOf<K>>(mode: "inUnit", symbol: S, opts?: Opts<ToFixedOptions & {
+        precision: number | (S extends DecimalSymbolsOf<K> ? DecimalSymbolsOf<K> : never);
+    }>): string;
+    toJSON(): string;
+    in<S extends SymbolsOf<K>>(unitSymbol: S): S extends "atomic" ? bigint : Rational;
+    in(unitSymbol: K extends {
+        human: string;
+    } ? "human" : never): Rational;
+    in(unitSymbol: K extends {
+        atomic: string;
+    } ? "atomic" : never): bigint;
+    ceilTo<S extends SymbolsOf<K>>(unitSymbol: S): this;
+    roundTo<S extends SymbolsOf<K>>(unitSymbol: S): this;
+    floorTo<S extends SymbolsOf<K>>(unitSymbol: S): this;
+    isZero(): boolean;
+    sign(): -1 | 0 | 1;
+    eq(other: this): boolean;
+    ne(other: this): boolean;
+    lt(other: this): boolean;
+    le(other: this): boolean;
+    gt(other: this): boolean;
+    ge(other: this): boolean;
+    abs(): this;
+    neg(): this;
+    add(other: this): this;
+    sub(other: this): this;
+    mul(other: Rationalish | Amount<Brand<Kind, "scalar">>): this;
+    mul<NK extends Kind>(other: Rate<NK, K>): Amount<NK>;
+    div(other: Rationalish | Amount<Brand<Kind, "scalar">>): this;
+    div<DK extends Kind>(other: Rate<K, DK>): Amount<DK>;
+    ratio(other: this): Rational;
+    mod(other: this): this;
+    per<const DK extends Kind>(den: (KindWithHuman & DK) | Amount<DK>): Rate<K, DK>;
+    private static fromInternal;
+    private getIn;
+    private checkKind;
+}
+type Amount<K extends Kind> = K extends Kind ? _Amount<K> : never;
+declare const Amount: typeof _Amount;
+export { Amount };
+//# sourceMappingURL=amount.d.ts.map

package/dist/amount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.d.ts","sourceRoot":"","sources":["../src/amount.ts"],"names":[],"mappings":"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"}

package/dist/amount.js

@@ -0,0 +1,184 @@
+import { brand } from "@onrail-xyz/utils";
+import { Rational } from "./rational.js";
+import { getUnit, identifyKind, sameKind } from "./kind.js";
+import { Rate, isRate } from "./rate.js";
+import { approximate, exact, inUnit, parse as parseFormat } from "./format.js";
+export const scalar = brand();
+//Free functions, not statics: a static is entered with a kind in hand (ofKind, from, parse, the
+//  *OfKind guards) and produces or narrows towards an amount of it; these are entered with an
+//  amount - or with nothing at all - and recover what the receiver's erased K cannot give back
+//  (Amount.md, "Free functions get fresh generic parameters"). rate.ts follows the same split.
+//exact kind reads at an open K, where the `kind` property erases
+export const kindOf = (amount) => amount.kind;
+//class check without touching the underscored class:
+//  a union narrows to exactly its amount constituents
+//  an open Amount<K> keeps its K
+//  an unknown narrows to Amount<Kind>
+export const isAmount = (value) => value instanceof _Amount;
+//see end of file for the actual exports
+//two Amount spellings:
+//  * _Amount<K> is the implementation class that's only exported for type-reachability
+//  * Amount<K> (see end of file) is the  distributive alias over it. It's the only spelling that
+//      should be used by consumers
+//
+//Kind-preserving members return this so things match as intended, even when deferred at an open K
+export class _Amount {
+    value;
+    kind;
+    constructor(value, kind) {
+        this.value = value;
+        this.kind = kind;
+    }
+    static ofKind(kind) {
+        return (numericalValue, unitSymbol) => _Amount.fromInternal(numericalValue, kind, unitSymbol ?? kind.human);
+    }
+    static from(numericalValue, ...args) {
+        return _Amount.fromInternal(numericalValue, args[0], args[1]);
+    }
+    //the candidates are inferred as a tuple, not as one K: a single type param would bind to the
+    //  first kind and reject every other, which is the whole point of passing several
+    static parse(str, ...kinds) {
+        const kind = identifyKind(kinds, str);
+        if (!kind)
+            throw new Error("Could not identify kind from string");
+        const value = parseFormat(kind, str);
+        return _Amount.fromInternal(value, kind, kind.standard.unit);
+    }
+    static isOfKind(amt, kind) {
+        return sameKind(amt.kind, kind);
+    }
+    static allOfKind(amts, kind) {
+        return amts.every(amt => sameKind(amt.kind, kind));
+    }
+    //instance factories — "an amount of my own kind". The kind-generic replacement for reading
+    //  `kind` back and feeding it to ofKind: `kind` erases at an open K, `this` does not.
+    zero() {
+        return new _Amount(Rational.from(0n), this.kind);
+    }
+    ofSame(numericalValue, unitSymbol) {
+        return _Amount.fromInternal(numericalValue, this.kind, unitSymbol);
+    }
+    toString(modeOrSys, symbolOrOpts, opts) {
+        if (modeOrSys === "inUnit") {
+            const symbol = getUnit(this.kind, symbolOrOpts).symbol;
+            const prec = typeof opts?.precision === "string"
+                ? getUnit(this.kind, opts.precision).symbol
+                : opts?.precision;
+            return inUnit(this.kind, this.value, symbol, prec, opts);
+        }
+        const isMode = !modeOrSys || modeOrSys === "approximate" || modeOrSys === "exact";
+        const o = (isMode ? symbolOrOpts : { system: modeOrSys, ...symbolOrOpts });
+        return modeOrSys === "exact"
+            ? exact(this.kind, this.value, o)
+            : approximate(this.kind, this.value, o);
+    }
+    toJSON() {
+        return this.toString("exact");
+    }
+    in(unitSymbol) {
+        const rat = this.getIn(unitSymbol);
+        return (unitSymbol === "atomic" ? rat.floor() : rat);
+    }
+    //the S on the unit-symbol methods might seem pointless, but it's in fact crucial:
+    //  a bare SymbolsOf<K> breaks overload/implementation compatibility of the this-returning methods
+    //  (the compatibility check relates _Amount<K> to _Amount<Kind>, where only same-shape generic
+    //  signatures unify across the deferred SymbolsOf<K> / string constraint divide)
+    ceilTo(unitSymbol) {
+        return _Amount.fromInternal(this.getIn(unitSymbol).ceil(), this.kind, unitSymbol);
+    }
+    roundTo(unitSymbol) {
+        return _Amount.fromInternal(this.getIn(unitSymbol).round(), this.kind, unitSymbol);
+    }
+    floorTo(unitSymbol) {
+        return _Amount.fromInternal(this.getIn(unitSymbol).floor(), this.kind, unitSymbol);
+    }
+    isZero() {
+        return this.value.eq(0n);
+    }
+    sign() {
+        return this.value.sign();
+    }
+    eq(other) {
+        this.checkKind(other.kind);
+        return this.value.eq(other.value);
+    }
+    ne(other) {
+        this.checkKind(other.kind);
+        return this.value.ne(other.value);
+    }
+    lt(other) {
+        this.checkKind(other.kind);
+        return this.value.lt(other.value);
+    }
+    le(other) {
+        this.checkKind(other.kind);
+        return this.value.le(other.value);
+    }
+    gt(other) {
+        this.checkKind(other.kind);
+        return this.value.gt(other.value);
+    }
+    ge(other) {
+        this.checkKind(other.kind);
+        return this.value.ge(other.value);
+    }
+    abs() {
+        return new _Amount(this.value.abs(), this.kind);
+    }
+    neg() {
+        return new _Amount(this.value.neg(), this.kind);
+    }
+    add(other) {
+        this.checkKind(other.kind);
+        return new _Amount(this.value.add(other.value), this.kind);
+    }
+    sub(other) {
+        this.checkKind(other.kind);
+        return new _Amount(this.value.sub(other.value), this.kind);
+    }
+    mul(other) {
+        if (isRate(other)) {
+            this.checkKind(other.den);
+            return new _Amount(this.value.mul(other.ratio), other.num);
+        }
+        const rhs = isAmount(other) ? other.value : other;
+        return new _Amount(this.value.mul(rhs), this.kind);
+    }
+    div(other) {
+        if (isRate(other)) {
+            this.checkKind(other.num);
+            return new _Amount(this.value.div(other.ratio), other.den);
+        }
+        const rhs = isAmount(other) ? other.value : other;
+        return new _Amount(this.value.div(rhs), this.kind);
+    }
+    //the quotient of two amounts of one kind, which is a plain number. It is not a `div` overload
+    //  because an open K may be instantiated as a union (a tranche kind known only at runtime):
+    //  at K1 | K2 an overload for `this` accepts an operand of the other kind - a scalar one
+    //  included, which `div` scales by - and no runtime check can tell which of the two readings
+    //  the types chose. `div` takes scalars only, and this checks the kind like add and sub do
+    ratio(other) {
+        this.checkKind(other.kind);
+        return this.value.div(other.value);
+    }
+    mod(other) {
+        this.checkKind(other.kind);
+        return new _Amount(this.value.mod(other.value), this.kind);
+    }
+    per(den) {
+        return Rate.from(this, den);
+    }
+    static fromInternal(numericalValue, kind, unitSymbol) {
+        const unit = getUnit(kind, (unitSymbol ?? "human"));
+        return new _Amount(Rational.from(numericalValue).mul(unit.scale), kind);
+    }
+    getIn(unitSymbol) {
+        return this.value.div(getUnit(this.kind, unitSymbol).scale);
+    }
+    checkKind(otherKind) {
+        if (!sameKind(this.kind, otherKind))
+            throw new Error(`Kind mismatch: ${this.kind.name} vs ${otherKind.name}`);
+    }
+}
+const Amount = _Amount;
+export { Amount };

package/dist/format.d.ts

@@ -0,0 +1,15 @@
+import type { Opts } from "@onrail-xyz/utils";
+import { type ToFixedOptions, Rational } from "./rational.js";
+import type { Kind, Unit, KindUnitSymbols } from "./kind.js";
+export declare function inUnit<K extends Kind>(kind: K, stdVal: Rational, symbol: KindUnitSymbols<K>, precision?: number | KindUnitSymbols<K>, opts?: Opts<ToFixedOptions>): string;
+export declare function inUnitApprox<K extends Kind>(kind: K, stdVal: Rational, symbol: KindUnitSymbols<K>, opts?: Opts<ToFixedOptions>): string;
+export declare function approximate(kind: Kind, stdVal: Rational, opts?: Opts<ToFixedOptions & {
+    system: string;
+}>): string;
+export declare function exact(kind: Kind, stdVal: Rational, opts?: Opts<ToFixedOptions & {
+    system: string;
+}>): string;
+export declare function parse(kind: Kind, str: string): Rational;
+export declare function exactRate(num: Kind, den: Kind, ratio: Rational, opts?: Opts<ToFixedOptions>): string;
+export declare const bestDenUnit: (num: Kind, den: Kind, ratio: Rational) => Unit;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,KAAK,cAAc,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAK7D,wBAAgB,MAAM,CAAC,CAAC,SAAS,IAAI,EACnC,IAAI,EAAO,CAAC,EACZ,MAAM,EAAK,QAAQ,EACnB,MAAM,EAAK,eAAe,CAAC,CAAC,CAAC,EAC7B,SAAS,GAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAK,EAC1C,IAAI,CAAC,EAAM,IAAI,CAAC,cAAc,CAAC,GAC9B,MAAM,CAWR;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,IAAI,EACzC,IAAI,EAAI,CAAC,EACT,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,EAC1B,IAAI,CAAC,EAAG,IAAI,CAAC,cAAc,CAAC,GAC3B,MAAM,CAKR;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAI,IAAI,EACZ,MAAM,EAAE,QAAQ,EAChB,IAAI,CAAC,EAAG,IAAI,CAAC,cAAc,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAChD,MAAM,CAiBR;AAcD,wBAAgB,KAAK,CACnB,IAAI,EAAI,IAAI,EACZ,MAAM,EAAE,QAAQ,EAChB,IAAI,CAAC,EAAG,IAAI,CAAC,cAAc,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAChD,MAAM,CAUR;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAmCvD;AAED,wBAAgB,SAAS,CACvB,GAAG,EAAI,IAAI,EACX,GAAG,EAAI,IAAI,EACX,KAAK,EAAE,QAAQ,EACf,IAAI,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,GAC1B,MAAM,CAGR;AAED,eAAO,MAAM,WAAW,QAAS,IAAI,OAAO,IAAI,SAAS,QAAQ,KAAG,IAcnE,CAAC"}

package/dist/format.js

@@ -0,0 +1,226 @@
+import { Rational } from "./rational.js";
+import { findUnit, segment } from "./segmenting.js";
+const approxDigits = 3;
+export function inUnit(kind, stdVal, symbol, precision = 0, opts) {
+    const unit = kind.units[symbol];
+    const value = stdVal.div(unit.scale);
+    const decimals = typeof precision === "number"
+        ? precision
+        : unit.oom - kind.units[precision].oom;
+    if (decimals < 0)
+        throw new Error("Precision must be non-negative");
+    return formatWithSymbol(value, decimals, unit, opts);
+}
+export function inUnitApprox(kind, stdVal, symbol, opts) {
+    const unit = kind.units[symbol];
+    const value = stdVal.div(unit.scale);
+    return formatWithSymbol(value, sigDigitPrec(value), unit, opts);
+}
+export function approximate(kind, stdVal, opts) {
+    const sortedByScale = getSystemUnits(kind, opts?.system);
+    if (!isDecimal(kind, opts?.system))
+        return compound(kind, sortedByScale, stdVal, true, opts);
+    if (stdVal.eq(0))
+        return formatZero(kind, sortedByScale, opts);
+    const reading = approxReading(stdVal, sortedByScale);
+    //a reading that rounds up into the next unit's range renders there instead: $0.9996 reads $1,
+    //  not 100c
+    const rounded = roundTo(reading.value, reading.precision).mul(reading.unit.scale);
+    const next = sortedByScale[reading.index - 1];
+    const final = reading.index > 0 && next !== undefined && rounded.abs().ge(next.scale)
+        ? approxReading(rounded, sortedByScale)
+        : reading;
+    return formatWithSymbol(final.value, final.precision, final.unit, opts);
+}
+const approxReading = (stdVal, sortedByScale) => {
+    const { index, unit, value, promoted } = displayUnitInfo(stdVal, sortedByScale);
+    const precision = promoted ? approxDigits : getApproxPrec(index, value);
+    return { index, unit, value, precision };
+};
+//the value as a given number of decimals renders it (half away from zero, as toFixed does)
+const roundTo = (value, decimals) => {
+    const scale = Rational.powerOfTen(decimals);
+    return Rational.from(value.mul(scale).round()).div(scale);
+};
+export function exact(kind, stdVal, opts) {
+    const sortedByScale = getSystemUnits(kind, opts?.system);
+    if (!isDecimal(kind, opts?.system))
+        return compound(kind, sortedByScale, stdVal, false, opts);
+    if (stdVal.eq(0))
+        return formatZero(kind, sortedByScale, opts);
+    const { unit, value } = displayUnitInfo(stdVal, sortedByScale);
+    return renderExact(value, unit, opts);
+}
+export function parse(kind, str) {
+    const processPair = (pair) => {
+        const value = Rational.from(str.substring(pair.value[0], pair.value[1]));
+        const symbol = str.substring(pair.symbol[0], pair.symbol[1]);
+        const unit = findUnit(kind.units, symbol);
+        if (!unit)
+            throw new Error(`Unknown unit: ${symbol}`);
+        return { value, unit };
+    };
+    const { negative, pairs } = segment(str);
+    if (pairs.length === 1) {
+        const { value, unit } = processPair(pairs[0]);
+        const absVal = value.mul(unit.scale);
+        return negative ? absVal.neg() : absVal;
+    }
+    let total = Rational.from(0n);
+    let lastScale = undefined;
+    for (let i = 0; i < pairs.length; ++i) {
+        const { value, unit } = processPair(pairs[i]);
+        if (i !== pairs.length - 1 && !value.isInteger())
+            throw new Error("Decimal only allowed in final unit");
+        if (lastScale && lastScale.le(unit.scale))
+            throw new Error("Units must be in descending order");
+        total = total.add(value.mul(unit.scale));
+        lastScale = unit.scale;
+    }
+    return negative ? total.neg() : total;
+}
+export function exactRate(num, den, ratio, opts) {
+    const denUnit = bestDenUnit(num, den, ratio);
+    return `${exact(num, ratio.mul(denUnit.scale), opts)}/${denUnit.symbol}`;
+}
+export const bestDenUnit = (num, den, ratio) => {
+    if (den.human !== undefined || ratio.eq(0))
+        return den.units[den.human ?? den.standard.unit];
+    let best;
+    for (const unit of getSystemUnits(den)) {
+        const rendered = exact(num, ratio.mul(unit.scale), { thousandsSep: "" });
+        //symbols cannot contain "/", so its presence marks the mixed-number form
+        const mixed = rendered.includes("/");
+        const size = rendered.length + unit.symbol.length;
+        if (!best || (mixed === best.mixed ? size < best.size : best.mixed))
+            best = { mixed, size, unit };
+    }
+    return best.unit;
+};
+const renderExact = (value, unit, opts) => {
+    const valStr = value.toString({ thousandsSep: opts?.thousandsSep ?? "," });
+    return attachSymbol(valStr, unit, valStr === "1" || valStr === "-1");
+};
+const compound = (kind, sortedByScale, stdVal, approx, opts) => {
+    if (stdVal.eq(0))
+        return formatZero(kind, sortedByScale, opts);
+    const sign = stdVal.lt(0) ? "-" : "";
+    const smallest = sortedByScale.length - 1;
+    let absStdVal = stdVal.abs();
+    if (approx) {
+        //a value the smallest unit carries on its own renders in it, to significant digits - unless
+        //  those round up to the next unit, in which case it spans units after all
+        const { lbIndex, lbUnit, lbValue } = lowerBoundInfo(absStdVal, sortedByScale);
+        if (lbIndex === -1 || lbIndex === smallest) {
+            const precision = getApproxPrec(lbIndex, lbValue);
+            const rounded = roundTo(lbValue, precision).mul(lbUnit.scale);
+            if (smallest === 0 || lbIndex === -1 || rounded.lt(sortedByScale[smallest - 1].scale))
+                return sign + formatWithSymbol(lbValue, precision, lbUnit, opts);
+            absStdVal = rounded;
+        }
+        //rounded to whole smallest units first and decomposed exactly after, so no part can round
+        //  up into the next unit's range (no "1 minute 60 seconds")
+        const smallestScale = sortedByScale[smallest].scale;
+        absStdVal = Rational.from(absStdVal.div(smallestScale).round()).mul(smallestScale);
+    }
+    const parts = [];
+    const tolerance = approx ? absStdVal.div(Rational.powerOfTen(approxDigits)) : null;
+    let remainder = absStdVal;
+    let startFrom = 0;
+    while (remainder.ne(0)) {
+        const { lbIndex, lbUnit, lbValue } = lowerBoundInfo(remainder, sortedByScale, startFrom);
+        const atSmallest = lbIndex === -1 || lbIndex === smallest;
+        if (atSmallest && !approx)
+            parts.push(renderExact(lbValue, lbUnit, opts));
+        else
+            parts.push(formatWithSymbol(Rational.from(lbValue.floor()), 0, lbUnit, opts));
+        if (atSmallest)
+            break;
+        const nextRemainder = remainder.mod(lbUnit.scale);
+        if (tolerance !== null && nextRemainder.lt(tolerance))
+            break;
+        remainder = nextRemainder;
+        startFrom = lbIndex + 1;
+    }
+    return sign + parts.join(" ");
+};
+const formatZero = (kind, sortedByScale, opts) => {
+    const preferred = kind.units[kind.human ?? kind.standard.unit];
+    const unit = sortedByScale.find(u => u.scale.eq(preferred.scale)) ?? sortedByScale.at(-1);
+    return formatWithSymbol(Rational.from(0n), 0, unit, opts);
+};
+function formatWithSymbol(value, decimals, unit, opts) {
+    const thousandsSep = opts?.thousandsSep ?? ",";
+    const trimZeros = opts?.trimZeros ?? true;
+    const valStr = value.toFixed(decimals, { thousandsSep, trimZeros });
+    //the plural follows the displayed magnitude, not the exact one (0.9999 at 2 decimals shows as 1)
+    const oneStr = Rational.from(1n).toFixed(decimals, { thousandsSep, trimZeros });
+    return attachSymbol(valStr, unit, valStr === oneStr || valStr === `-${oneStr}`);
+}
+const attachSymbol = (valStr, unit, singular) => {
+    const sym = unit.plural && !singular ? unit.plural : unit.symbol;
+    const space = (unit.spacing ?? "spaced") === "spaced" ? " " : "";
+    if ((unit.position ?? "postfix") === "postfix")
+        return valStr + space + sym;
+    //the sign stays outside the symbol: parsing only takes a "-" that leads the whole pair, so an
+    //  interior one ("$-100") would be read as part of the symbol
+    const [sign, digits] = valStr.startsWith("-") ? ["-", valStr.slice(1)] : ["", valStr];
+    return sign + sym + space + digits;
+};
+const getSystem = (kind, system) => {
+    const name = system ?? kind.standard.system;
+    const sys = kind.systems[name];
+    if (!sys)
+        throw new Error(`Unknown system: ${name}`);
+    return sys;
+};
+const getSystemUnits = (kind, system) => {
+    const units = [];
+    for (const symbol of getSystem(kind, system).symbols) {
+        const unit = kind.units[symbol];
+        if (!units.some(u => u.scale.eq(unit.scale)))
+            units.push(unit);
+    }
+    return units;
+};
+const isDecimal = (kind, system) => getSystem(kind, system).decimal;
+//number of decimals that yields approxDigits significant digits (0 for values >= 10^approxDigits)
+const sigDigitPrec = (value) => {
+    const absVal = value.abs();
+    let precision = approxDigits;
+    while (precision > 0 && absVal.ge(Rational.powerOfTen(approxDigits - precision)))
+        --precision;
+    while (absVal.ne(0) && absVal.lt(Rational.powerOfTen(approxDigits - precision - 1)))
+        ++precision;
+    return precision;
+};
+//below the smallest unit of the kind the precision is capped instead of following the value
+const getApproxPrec = (lbIndex, lbValue) => lbIndex === -1 ? approxDigits : sigDigitPrec(lbValue);
+//the unit both display modes render in: the largest unit the value reaches, promoted to the next
+//  one up when the ladder gap is wide enough for the reading to run long (six orders — ¢/$ never
+//  promotes) and the promoted reading has at least a thousandth of it: 15,000 Gwei stays put,
+//  0.5 ETH is not 500,000,000 Gwei
+const displayUnitInfo = (stdVal, sortedByScale) => {
+    const { lbIndex, lbUnit, lbValue } = lowerBoundInfo(stdVal, sortedByScale);
+    const lb = { index: lbIndex, unit: lbUnit, value: lbValue, promoted: false };
+    if (lbIndex <= 0)
+        return lb;
+    const unit = sortedByScale[lbIndex - 1];
+    const value = stdVal.div(unit.scale);
+    return unit.oom - lbUnit.oom >= 2 * approxDigits
+        && value.abs().ge(Rational.powerOfTen(-approxDigits))
+        ? { index: lbIndex - 1, unit, value, promoted: true }
+        : lb;
+};
+const lowerBoundInfo = (stdVal, sortedByScale, startIndex = 0) => {
+    const absStdVal = stdVal.abs();
+    let lbIndex = startIndex;
+    for (; lbIndex < sortedByScale.length; ++lbIndex)
+        if (absStdVal.ge(sortedByScale[lbIndex].scale))
+            break;
+    if (lbIndex === sortedByScale.length)
+        lbIndex = -1;
+    const lbUnit = sortedByScale.at(lbIndex);
+    const lbValue = stdVal.div(lbUnit.scale);
+    return { lbIndex, lbUnit, lbValue };
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./rational.js";
+export * from "./kind.js";
+export * from "./unitSpecs.js";
+export * from "./amount.js";
+export * from "./rate.js";
+export * from "./aggregating.js";
+export * from "./allocating.js";
+export * from "./jsonCodecs.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./rational.js";
+export * from "./kind.js";
+export * from "./unitSpecs.js";
+export * from "./amount.js";
+export * from "./rate.js";
+export * from "./aggregating.js";
+export * from "./allocating.js";
+export * from "./jsonCodecs.js";

package/dist/jsonCodecs.d.ts

@@ -0,0 +1,9 @@
+import type { JsonCodec, MaybeArray } from "@onrail-xyz/utils";
+import { Rational } from "./rational.js";
+import type { Kind } from "./kind.js";
+import { Amount } from "./amount.js";
+import { Rate } from "./rate.js";
+export declare const rationalCodec: JsonCodec<Rational>;
+export declare const amountCodec: (kinds: MaybeArray<Kind>) => JsonCodec<Amount<Kind>>;
+export declare const rateCodec: (numKinds: MaybeArray<Kind>, denKinds: MaybeArray<Kind>) => JsonCodec<Rate<Kind, Kind>>;
+//# sourceMappingURL=jsonCodecs.d.ts.map

package/dist/jsonCodecs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonCodecs.d.ts","sourceRoot":"","sources":["../src/jsonCodecs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAsB,MAAM,mBAAmB,CAAC;AAEnF,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,MAAM,EAAY,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAU,MAAM,WAAW,CAAC;AA6BzC,eAAO,MAAM,aAAa,EAAE,SAAS,CAAC,QAAQ,CAK7C,CAAC;AAEF,eAAO,MAAM,WAAW,UAAW,UAAU,CAAC,IAAI,CAAC,KAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAQ1E,CAAC;AAEH,eAAO,MAAM,SAAS,aACV,UAAU,CAAC,IAAI,CAAC,YAChB,UAAU,CAAC,IAAI,CAAC,KACzB,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAQ3B,CAAC"}