@arki/money 0.0.0-stage → 0.0.4

package/dist/money.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Exact money. A `Money` is a whole number of units, a scale (how many of the
+ * digits are decimals) and a currency: `19.99 EUR` is `1999` units at scale 2.
+ *
+ * Rules that protect you from silent loss:
+ * - Nothing rounds unless you pass a rounding mode. An operation whose exact
+ *   result does not fit throws `RoundingNecessaryError`.
+ * - Mixing currencies throws `CurrencyMismatchError`. With literal codes the
+ *   compiler already rejects it: `Money<'EUR'>` cannot be added to `Money<'USD'>`.
+ * - `allocate` and `split` return parts that add back to the whole exactly.
+ * - A `Money` never becomes a float by accident: `+price` throws.
+ *
+ * Speed: units are a plain `number` while they are a safe integer (up to 90
+ * trillion in a two-decimal currency) and a `bigint` only beyond that. Values
+ * are immutable through `readonly` and a private constructor; they are not
+ * frozen, because `Object.freeze` costs more per operation than the arithmetic.
+ */
+import type { RoundingMode } from '@arki/math/rounding';
+import type { Currency, CurrencyLike } from './currency.js';
+import type { Units } from './internal/units.js';
+export type { Units } from './internal/units.js';
+/** An exact decimal such as `@arki/math`'s `Decimal`: `coefficient × 10^-scale`. */
+export type DecimalLike = {
+    readonly coefficient: bigint;
+    readonly scale: number;
+};
+/** An exact fraction such as `@arki/math`'s `Rational`. */
+export type RationalLike = {
+    readonly numerator: bigint;
+    readonly denominator: bigint;
+};
+/**
+ * An amount in major units: `'19.99'`, `19.99`, `20n`, a `Decimal` or a `Rational`.
+ * A `number` is read as written (`19.99` is exactly 19.99); earlier float
+ * arithmetic cannot be undone, so prefer strings for computed values.
+ */
+export type Amount = number | string | bigint | DecimalLike | RationalLike;
+/** A multiplier or divisor: an `Amount` or a `Factor` prepared once with `factor()`. */
+export type FactorInput = Amount | Factor;
+export type MoneyOptions = {
+    /** How to drop digits that do not fit. Without it, extra digits throw `RoundingNecessaryError`. */
+    rounding?: RoundingMode;
+    /** Number of decimals to keep, 0–100. Defaults to the currency's (2 for EUR). Use 4 for unit prices. */
+    scale?: number;
+};
+/** Who gets the leftover units when an amount does not divide evenly. */
+export type RemainderPolicy = 'largest' | 'first' | 'last';
+export type AllocateOptions = {
+    /**
+     * `'largest'` (default): one unit each to the parts whose exact share lost
+     * the most, earlier parts first on ties. `'first'` / `'last'`: one unit each
+     * from the start / end. Parts with a zero ratio never receive a unit.
+     */
+    remainder?: RemainderPolicy;
+};
+export type MoneyJSON = {
+    amount: string;
+    currency: string;
+};
+/** A multiplier read once, for loops: `const vat = factor('0.19')`. */
+export declare class Factor {
+    readonly numerator: Units;
+    /** Always positive. */
+    readonly denominator: Units;
+    private constructor();
+}
+/** Prepares a multiplier once so `times` skips parsing: `price.times(vat, 'halfEven')`. */
+export declare function factor(value: Amount): Factor;
+/** An immutable amount of money. Create one with `money()` or the `Money.*` factories. */
+export declare class Money<C extends string = string> {
+    /** The amount as a whole number of `10^-scale` units, in canonical form: a `number` exactly when it is a safe integer. */
+    readonly units: Units;
+    /** Number of decimals the amount carries. Equals `currency.scale` unless chosen otherwise. */
+    readonly scale: number;
+    readonly currency: Currency<C>;
+    private constructor();
+    /**
+     * `Money.of('19.99', 'EUR')`. Extra digits throw `RoundingNecessaryError`
+     * unless `options.rounding` is given: `Money.of('1.005', 'EUR', { rounding: 'halfEven' })` → `1.00 EUR`.
+     * A `Money` input must be in the same currency; this also narrows `Money<string>` to `Money<'EUR'>`.
+     */
+    static of<const C extends string>(amount: Amount | Money, currency: CurrencyLike<C>, options?: MoneyOptions): Money<C>;
+    /**
+     * From whole minor units: `Money.fromMinor(1999, 'EUR')` → `19.99 EUR`. Accepts a
+     * safe-integer `number`, a `bigint`, or an integer string (as databases return
+     * `BIGINT`). `scale` says how many decimals the units carry; it defaults to the currency's.
+     */
+    static fromMinor<const C extends string>(units: number | bigint | string, currency: CurrencyLike<C>, scale?: number): Money<C>;
+    /** Zero in this currency. */
+    static zero<const C extends string>(currency: CurrencyLike<C>, scale?: number): Money<C>;
+    /**
+     * Reads what `toString()` writes: `'19.99 EUR'`, also `'EUR 19.99'`. Keeps the
+     * text's decimals when there are more than the currency's (`'1.2345 EUR'`
+     * stays at scale 4). Pass `currencies` to resolve custom codes.
+     */
+    static parse(text: string, currencies?: readonly Currency[]): Money;
+    /** Reads `{ amount: '19.99', currency: 'EUR' }`, keeping the amount's decimals. Validates the shape. */
+    static fromJSON(value: unknown, currencies?: readonly Currency[]): Money;
+    /** Comparator for sorting: `prices.sort(Money.compare)`. Throws on mixed currencies. */
+    static compare(this: void, a: Money, b: Money): -1 | 0 | 1;
+    /** Exact sum. Different scales are aligned upward, never rounded. */
+    plus(other: Money<C>): Money<C>;
+    /** Exact difference. Different scales are aligned upward, never rounded. */
+    minus(other: Money<C>): Money<C>;
+    /**
+     * Multiplies and keeps this scale. `money('10.00', 'EUR').times(3)` → `30.00`.
+     * `times('1.19')` on `9.99` is `11.8881`, which does not fit two decimals, so
+     * it throws unless you pass a rounding mode: `times('1.19', 'halfEven')` → `11.89`.
+     */
+    times(multiplier: FactorInput, rounding?: RoundingMode): Money<C>;
+    /** Divides and keeps this scale. Inexact results need a rounding mode. Zero throws `DivisionByZeroError`. */
+    dividedBy(divisor: FactorInput, rounding?: RoundingMode): Money<C>;
+    /** `money(200, 'EUR').percentage(15)` → `30.00 EUR`. Same as `times(percent / 100)`. */
+    percentage(percent: FactorInput, rounding?: RoundingMode): Money<C>;
+    negated(): Money<C>;
+    abs(): Money<C>;
+    /** Changes the number of decimals. Dropping non-zero digits needs a rounding mode. */
+    toScale(scale: number, rounding?: RoundingMode): Money<C>;
+    /**
+     * Rounds to a multiple of `step`, for cash: `chf.roundToStep('0.05', 'halfUp')`.
+     * Cash steps are set by each country's law (CHF 0.05, SEK 1, EUR 0.05 in some
+     * euro countries), so the package does not guess them. The step must fit this scale.
+     */
+    roundToStep(step: FactorInput, rounding?: RoundingMode): Money<C>;
+    /**
+     * Splits by ratios into parts that add back to this amount exactly:
+     * `money(100, 'EUR').allocate([1, 1, 1])` → `[33.34, 33.33, 33.33]`.
+     * Ratios are non-negative numbers, bigints or decimal strings, not all zero.
+     * A negative amount is split like a positive one and each part re-signed.
+     */
+    allocate(ratios: readonly (number | bigint | string)[], options?: AllocateOptions): Money<C>[];
+    /** Splits into `parts` equal shares that differ by at most one unit: `money(10, 'EUR').split(3)` → `[3.34, 3.33, 3.33]`. */
+    split(parts: number, options?: AllocateOptions): Money<C>[];
+    /** Compares values across scales (`1.5` equals `1.50`). Throws on mixed currencies. */
+    compareTo(other: Money<C>): -1 | 0 | 1;
+    eq(other: Money<C>): boolean;
+    lt(other: Money<C>): boolean;
+    lte(other: Money<C>): boolean;
+    gt(other: Money<C>): boolean;
+    gte(other: Money<C>): boolean;
+    isZero(): boolean;
+    isPositive(): boolean;
+    isNegative(): boolean;
+    sign(): -1 | 0 | 1;
+    /** Same currency. Never throws. */
+    hasSameCurrency(other: Money): boolean;
+    /** Units at the currency's scale: `19.99 EUR` → `1999`. Throws `RoundingNecessaryError` if sub-cent digits are not zero. */
+    toMinorUnits(): Units;
+    /** `toMinorUnits()` as a `bigint`. */
+    toMinorBigInt(): bigint;
+    /** `toMinorUnits()` as a `number`, as payment APIs want. Throws `NumericRangeError` past 2^53. */
+    toMinorNumber(): number;
+    /** Plain decimal text with exactly `scale` decimals: `'19.99'`, `'-0.50'`, `'1000'` for JPY. For databases. */
+    toDecimalString(): string;
+    /** The nearest double. For charts and display math only, never for more money math. */
+    toNumber(): number;
+    /** `'19.99 EUR'`. Locale-free; `Money.parse` reads it back. */
+    toString(): string;
+    /** `{ amount: '19.99', currency: 'EUR' }`. The amount is a string, so no digit is ever lost. */
+    toJSON(): MoneyJSON;
+    /** Throws. A `Money` never silently becomes a float. */
+    valueOf(): never;
+    [Symbol.toPrimitive](hint: string): string;
+    get [Symbol.toStringTag](): string;
+}
+/** Shorthand for `Money.of`: `money('19.99', 'EUR')`. */
+export declare function money<const C extends string>(amount: Amount | Money, currency: CurrencyLike<C>, options?: MoneyOptions): Money<C>;
+export declare function isMoney(value: unknown): value is Money;
+/**
+ * Exact total of one currency, with one allocation for the result. An empty
+ * list needs `currency` and returns zero; otherwise it throws `InvalidArgumentError`.
+ */
+export declare function sum<const C extends string>(items: Iterable<Money<C>>, currency?: CurrencyLike<C>): Money<C>;
+/** Mean of one currency. Inexact results need a rounding mode. An empty list throws `EmptyDataError`. */
+export declare function average<const C extends string>(items: Iterable<Money<C>>, rounding?: RoundingMode): Money<C>;
+/** The smallest value; ties return the first. */
+export declare function min<const C extends string>(first: Money<C>, ...rest: Money<C>[]): Money<C>;
+/** The largest value; ties return the first. */
+export declare function max<const C extends string>(first: Money<C>, ...rest: Money<C>[]): Money<C>;
+//# sourceMappingURL=money.d.ts.map

package/dist/money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../src/money.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAWxD,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAkBjD,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD,oFAAoF;AACpF,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AACnF,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAExF;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,CAAC;AAE3E,wFAAwF;AACxF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C,MAAM,MAAM,YAAY,GAAG;IACzB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,wGAAwG;IACxG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAU7D,uEAAuE;AACvE,qBAAa,MAAM;IACjB,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1B,uBAAuB;IACvB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAE5B,OAAO,eAIN;CAMF;AAED,2FAA2F;AAC3F,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG5C;AAgED,0FAA0F;AAC1F,qBAAa,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC1C,0HAA0H;IAC1H,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE/B,OAAO,eAKN;IASD;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAC9B,MAAM,EAAE,MAAM,GAAG,KAAK,EACtB,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EACzB,OAAO,CAAC,EAAE,YAAY,GACrB,KAAK,CAAC,CAAC,CAAC,CAUV;IAED;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EACrC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAC/B,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,KAAK,CAAC,CAAC,CAAC,CAGV;IAED,6BAA6B;IAC7B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAGvF;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,SAAS,QAAQ,EAAE,GAAG,KAAK,CASlE;IAED,wGAAwG;IACxG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,SAAS,QAAQ,EAAE,GAAG,KAAK,CASvE;IAED,wFAAwF;IACxF,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAEzD;IAID,qEAAqE;IACrE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAY9B;IAED,4EAA4E;IAC5E,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAY/B;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAMhE;IAED,6GAA6G;IAC7G,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAOjE;IAED,wFAAwF;IACxF,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAGlE;IAED,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAElB;IAED,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAEd;IAED,sFAAsF;IACtF,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAIxD;IAED;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAYhE;IAID;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CA8B7F;IAED,4HAA4H;IAC5H,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAiB1D;IAID,uFAAuF;IACvF,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAQrC;IAED,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAE3B;IAED,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAE3B;IAED,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAE5B;IAED,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAE3B;IAED,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAE5B;IAED,MAAM,IAAI,OAAO,CAEhB;IAED,UAAU,IAAI,OAAO,CAEpB;IAED,UAAU,IAAI,OAAO,CAEpB;IAED,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAEjB;IAED,mCAAmC;IACnC,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAErC;IAID,4HAA4H;IAC5H,YAAY,IAAI,KAAK,CAEpB;IAED,sCAAsC;IACtC,aAAa,IAAI,MAAM,CAEtB;IAED,kGAAkG;IAClG,aAAa,IAAI,MAAM,CAKtB;IAED,+GAA+G;IAC/G,eAAe,IAAI,MAAM,CASxB;IAED,uFAAuF;IACvF,QAAQ,IAAI,MAAM,CAEjB;IAED,+DAA+D;IAC/D,QAAQ,IAAI,MAAM,CAEjB;IAED,gGAAgG;IAChG,MAAM,IAAI,SAAS,CAElB;IAED,wDAAwD;IACxD,OAAO,IAAI,KAAK,CAEf;IAED,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzC;IAID,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAEjC;CASF;AAkED,yDAAyD;AACzD,wBAAgB,KAAK,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAC1C,MAAM,EAAE,MAAM,GAAG,KAAK,EACtB,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EACzB,OAAO,CAAC,EAAE,YAAY,GACrB,KAAK,CAAC,CAAC,CAAC,CAEV;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAEtD;AAED;;;GAGG;AACH,wBAAgB,GAAG,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CA2B3G;AAED,yGAAyG;AACzG,wBAAgB,OAAO,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAI5G;AAED,iDAAiD;AACjD,wBAAgB,GAAG,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAI1F;AAED,gDAAgD;AAChD,wBAAgB,GAAG,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAI1F"}