@shirudo/ddd-kit 2.2.0 → 3.0.0-rc.3

package/dist/money.d.ts

@@ -0,0 +1,376 @@
+import { o as DomainError } from "./chunks/errors.js";
+import { Result } from "@shirudo/result";
+
+//#region src/money/money.d.ts
+/**
+ * Currency identifier for {@link Money}. The kit deliberately ships no
+ * currency table: which codes exist and which scale they use is the
+ * consumer's decision (see `createMoneyFactory` for wiring a resolver
+ * once). ISO 4217 alpha-3 codes are the recommended convention.
+ */
+type CurrencyCode = string;
+/**
+ * The canonical money representation for domain state, domain events,
+ * and snapshots: an exact integer amount in minor units plus the
+ * explicit scale that maps minor to major units.
+ *
+ * Plain data by design: values created by `moneyOfMinor` are frozen,
+ * carry no methods or library internals, and survive `structuredClone`,
+ * deep-freeze, and the kit's state diffing. The kit ships exact
+ * operations only (lossless `addMoney`/`subtractMoney`/`negateMoney`
+ * and lossless `rescaleMoney`); everything that carries a rounding or
+ * distribution policy (multiplication, ratios, fees, division, lossy
+ * rescaling, allocation, FX) is domain policy executed by your
+ * calculation library at the use-case boundary (see
+ * `moneyFromSnapshot` / `moneyToSnapshot`).
+ *
+ * Never `number`, never a decimal string, never `amountCents`: `10.99`
+ * EUR is `{ amountMinor: 1099n, currency: "EUR", scale: 2 }`, and JPY
+ * has scale 0, not an assumed 2.
+ */
+interface Money {
+  /**
+   * Exact integer amount in minor units AT THIS VALUE'S SCALE. The
+   * scale may deliberately differ from the currency's default
+   * exponent (intermediate precision; the snapshot interop honors
+   * the same distinction), so the reference unit is always
+   * `this.scale`, never an assumed per-currency constant.
+   */
+  readonly amountMinor: bigint;
+  /** Required currency identifier; operations never mix currencies. */
+  readonly currency: CurrencyCode;
+  /** Number of minor-unit digits per major unit (EUR 2, JPY 0). */
+  readonly scale: number;
+  /**
+   * Type-level brand: a NON-EXPORTED unique symbol, never present at
+   * runtime. A string key ("__brand") could be spelled out by any
+   * caller; the module-private symbol cannot, so only the module's
+   * constructors mint the type. Convert foreign plain shapes with
+   * `moneyFromUnknown` (validates, copies, freezes) or `moneyFromDto`.
+   */
+  readonly [MONEY_BRAND]: true;
+}
+declare const MONEY_BRAND: unique symbol;
+/**
+ * Wire shape for {@link Money}: `amountMinor` travels as a string
+ * because JSON numbers are floats (silent precision loss past 2^53) and
+ * `JSON.stringify` throws on bigint. Validate with `moneyFromDto`
+ * immediately after deserialization; emit with `moneyToDto` right
+ * before serialization.
+ *
+ * A type alias, not an interface, on purpose: only type aliases get the
+ * implicit index signature that makes the DTO assignable to `JsonValue`,
+ * which `PublishedCommand` payloads require.
+ */
+type MoneyDto = {
+  /** Integer string matching `/^-?\d+$/`. */readonly amountMinor: string;
+  readonly currency: string;
+  readonly scale: number;
+};
+/**
+ * Validates an unknown plain shape and mints a FRESH, frozen
+ * {@link Money} from it: the result shares no reference with the
+ * input, so later mutation of the input cannot reach domain state.
+ * The door for re-hydrating foreign minor-units data (rows already
+ * mapped by an ORM, caches, deserialized snapshots); wire strings go
+ * through `moneyFromDto` instead.
+ */
+declare function moneyFromUnknown(value: unknown): Money;
+/**
+ * Constructs a frozen {@link Money} from an exact minor-unit amount.
+ * The only door into the shape: rejects `number` amounts (floats have
+ * no place in stored money), invalid scales, and empty or
+ * whitespace-carrying currency codes with `InvalidMoneyError`.
+ */
+declare function moneyOfMinor(amountMinor: bigint, currency: CurrencyCode, scale: number): Money;
+/**
+ * Validates a {@link MoneyDto} fresh off the wire and converts it to
+ * {@link Money}. Takes `unknown` on purpose: this IS the trust
+ * boundary, so callers never cast before validating. `amountMinor`
+ * must be a plain integer string (`/^-?\d+$/`); anything `Number()`
+ * would tolerate but bigint arithmetic cannot represent exactly
+ * ("1e5", "10.99", "0x10") is rejected with `InvalidMoneyError`.
+ */
+declare function moneyFromDto(dto: unknown): Money;
+/**
+ * Converts {@link Money} to its JSON-safe wire shape. Guards the input
+ * so untyped callers cannot leak a number-amount object onto the wire.
+ */
+declare function moneyToDto(money: Money): MoneyDto;
+/**
+ * Narrows an unknown value to the canonical {@link Money} shape. A
+ * CHECK, not a door: narrowing neither copies nor freezes, so an
+ * external alias can still mutate the underlying object after the
+ * check. For anything entering domain state, mint a fresh frozen
+ * value with {@link moneyFromUnknown} instead.
+ */
+declare function isMoney(value: unknown): value is Money;
+/**
+ * REPRESENTATION equality, deliberately: amount, currency, AND scale.
+ * `10.0` EUR at scale 1 and `10.00` EUR at scale 2 denote the same
+ * monetary value but are NOT equal here, because silently conflating
+ * scales is how precision bugs hide. For monetary-value comparison,
+ * align the scales explicitly first (lossless `rescaleMoney` upscales
+ * the coarser side) and then compare.
+ */
+declare function moneyEquals(a: Money, b: Money): boolean;
+/** True when the amount is exactly zero. */
+declare function isZeroMoney(money: Money): boolean;
+/** True when the amount is strictly greater than zero. */
+declare function isPositiveMoney(money: Money): boolean;
+/** True when the amount is strictly less than zero. */
+declare function isNegativeMoney(money: Money): boolean;
+/**
+ * Renders the exact decimal representation ("10.99", "-0.05", "10").
+ * The inverse of `parseMoneyInput` and the precision-safe input for
+ * display formatting; never feed the result back into arithmetic.
+ * Guards its input like the wire emitters do: a non-Money value fails
+ * loudly instead of rendering garbage.
+ */
+declare function moneyToDecimalString(money: Money): string;
+//#endregion
+//#region src/money/arithmetic.d.ts
+/**
+ * Exact addition of same-currency, same-scale amounts. Mismatches
+ * throw (`MONEY_CURRENCY_MISMATCH` / `MONEY_SCALE_MISMATCH`); there is
+ * no implicit conversion of either. A result past the amount bound
+ * fails as `INVALID_MONEY` instead of wrapping.
+ */
+declare function addMoney(a: Money, b: Money): Money;
+/** Exact subtraction under the same guards as {@link addMoney}. */
+declare function subtractMoney(a: Money, b: Money): Money;
+/** Exact sign flip; useful for ledger reversals and refunds. */
+declare function negateMoney(money: Money): Money;
+/**
+ * Converts to another scale, LOSSLESSLY or not at all: upscaling and
+ * exact downscaling succeed; a downscale that would drop non-zero
+ * digits throws `MONEY_PRECISION_LOSS`. There is deliberately no
+ * rounding parameter; lossy conversions carry a rounding policy and
+ * belong to your calculation library. The intended use is aligning
+ * mixed-scale amounts for `addMoney`/`subtractMoney` by upscaling the
+ * coarser one.
+ */
+declare function rescaleMoney(money: Money, scale: number): Money;
+//#endregion
+//#region src/money/errors.d.ts
+declare class InvalidMoneyError extends DomainError<"INVALID_MONEY"> {
+  constructor(message: string);
+}
+declare class MoneyCurrencyMismatchError extends DomainError<"MONEY_CURRENCY_MISMATCH"> {
+  constructor(left: string, right: string);
+}
+declare class MoneyScaleMismatchError extends DomainError<"MONEY_SCALE_MISMATCH"> {
+  constructor(left: number, right: number);
+}
+declare class MoneyPrecisionLossError extends DomainError<"MONEY_PRECISION_LOSS"> {
+  constructor(message: string);
+}
+declare class UnknownCurrencyError extends DomainError<"UNKNOWN_CURRENCY"> {
+  constructor(currency: string);
+}
+//#endregion
+//#region src/money/factory.d.ts
+/**
+ * Resolves a currency to its scale, or `undefined` for currencies it
+ * does not know. The kit ships no currency table; this is the seam
+ * where the consumer provides one, once, at the composition root. Any
+ * source works as a one-liner: a plain record, the runtime's own data
+ * via {@link currencyScaleFromIntl}, or the currency package of a
+ * calculation library (`(code) => currencies[code]?.exponent`).
+ */
+type CurrencyScaleResolver = (currency: CurrencyCode) => number | undefined;
+/**
+ * Currency-aware construction helpers bound to one
+ * {@link CurrencyScaleResolver}. Unknown currencies fail loudly with
+ * `UNKNOWN_CURRENCY` instead of guessing a scale.
+ */
+interface MoneyFactory {
+  /** `moneyOfMinor` with the scale resolved from the currency. */
+  ofMinor(amountMinor: bigint, currency: CurrencyCode): Money;
+  /** `parseMoneyInput` (exact-only) with the scale resolved from the currency. */
+  parse(input: unknown, currency: CurrencyCode): Money;
+  /** Zero in the given currency at its resolved scale. */
+  zero(currency: CurrencyCode): Money;
+  /** The resolved scale; throws `UNKNOWN_CURRENCY` when unresolved. */
+  scaleOf(currency: CurrencyCode): number;
+}
+/** Options for {@link createMoneyFactory}. */
+interface CreateMoneyFactoryOptions {
+  readonly scaleFor: CurrencyScaleResolver;
+}
+/**
+ * Binds a {@link CurrencyScaleResolver} once and returns construction
+ * helpers that no longer need an explicit scale per call.
+ *
+ * @example
+ * ```ts
+ * const money = createMoneyFactory({
+ *   scaleFor: currencyScaleFromRecord({ EUR: 2, JPY: 0 }),
+ * });
+ * money.parse("10.99", "EUR"); // { amountMinor: 1099n, currency: "EUR", scale: 2 }
+ * ```
+ */
+declare function createMoneyFactory(options: CreateMoneyFactoryOptions): MoneyFactory;
+/**
+ * Resolver over a plain currency-to-scale record
+ * (`{ EUR: 2, JPY: 0 }`). The record is copied into a `Map` at
+ * creation, so later mutation of the input and hostile own keys have
+ * no effect.
+ */
+declare function currencyScaleFromRecord(record: Readonly<Record<string, number>>): CurrencyScaleResolver;
+/**
+ * Resolver backed by the runtime's own currency data (ICU via
+ * `Intl.NumberFormat`), so no currency table ships with the kit or the
+ * consumer. Resolves ONLY canonical uppercase ISO 4217 codes: Intl
+ * itself would accept "eur", but a silent alias would let "eur"-Money
+ * and "EUR"-Money circulate side by side until an operation throws
+ * `MONEY_CURRENCY_MISMATCH`; here "eur" resolves to `undefined` and
+ * fails fast as `UNKNOWN_CURRENCY` at the factory.
+ *
+ * A CONVENIENCE, not an enterprise source of truth: ICU resolves
+ * well-formed but UNASSIGNED codes to its default of 2 rather than
+ * `undefined`, and the data shifts with the runtime's ICU version.
+ * Production money paths should pin a closed, versioned currency map
+ * (`currencyScaleFromRecord`) or a calculation library's versioned
+ * currency package; use this resolver for demos, prototypes, and
+ * internal tooling.
+ */
+declare function currencyScaleFromIntl(): CurrencyScaleResolver;
+//#endregion
+//#region src/money/format.d.ts
+/**
+ * Formats for display via `Intl.NumberFormat`, feeding the exact
+ * decimal string (never a float), with the money's own scale as the
+ * fraction-digit count. Presentation only: the output is
+ * locale-dependent text and must never flow back into parsing,
+ * storage, or arithmetic. Non-Money input fails loudly with
+ * `INVALID_MONEY` before Intl is touched.
+ *
+ * The currency must be well-formed for `Intl` (ISO alpha-3); for
+ * non-ISO codes, format `moneyToDecimalString(money)` yourself.
+ */
+declare function formatMoney(money: Money, locale: string): string;
+/**
+ * Binds the locale once and caches one `Intl.NumberFormat` per
+ * currency/scale pair; constructing formatters is expensive, so use
+ * this over `formatMoney` anywhere hot (lists, tables, exports).
+ */
+declare function createMoneyFormatter(locale: string): (money: Money) => string;
+//#endregion
+//#region src/money/parse.d.ts
+/** Options for {@link parseMoneyInput}. */
+interface ParseMoneyInputOptions {
+  readonly currency: CurrencyCode;
+  /** Target scale; the kit ships no currency table, so it is explicit. */
+  readonly scale: number;
+}
+/**
+ * Parses a plain decimal string ("10.99") into exact minor units,
+ * without ever touching floating point. This is the safe replacement
+ * for the classic bugs `Number(input) * 100` and `parseFloat`: no
+ * exponents, no `Infinity`, no locale separators, and NO rounding; the
+ * kit never rounds.
+ *
+ * EXACT OR REJECTED: missing fraction digits pad losslessly ("10.5" at
+ * scale 2 is 1050n) and all-zero excess digits are accepted ("10.990"
+ * at scale 2 is 1099n), but input that cannot be represented exactly
+ * at the target scale throws `MONEY_PRECISION_LOSS`. Whether "10.999"
+ * should be rejected or become 11.00 is a BUSINESS decision, not a
+ * parsing feature: put it in a domain-named policy function (a
+ * `normalizeQuotedPrice`, a `calculateVat`) that rounds via your
+ * calculation library and returns `Money`.
+ *
+ * The grammar is deliberately strict (`/^-?\d+(\.\d+)?$/`). Locale
+ * input ("10,99", grouping, currency signs) is a UI concern; normalize
+ * it to this grammar before calling.
+ *
+ * Takes `unknown` on purpose: this is the trust boundary for raw
+ * request values, so callers pass `req.body.amount` directly instead
+ * of coercing (`String([...])` silently joins arrays) or casting.
+ */
+declare function parseMoneyInput(input: unknown, options: ParseMoneyInputOptions): Money;
+//#endregion
+//#region src/money/snapshot.d.ts
+/**
+ * The currency part of {@link MoneySnapshotLike}: either a bare code or
+ * a currency object as calculation libraries model it (code, numeric
+ * base, exponent). Structural on purpose; the kit depends on no
+ * calculation library.
+ */
+type MoneySnapshotCurrencyLike = string | {
+  readonly code: string;
+  readonly base?: number | bigint | ReadonlyArray<number | bigint>;
+  readonly exponent?: number | bigint;
+};
+/**
+ * The `{ amount, currency, scale }` shape that calculation libraries
+ * expose when serializing their money objects (a `toJSON()` result,
+ * typically). `scale` falls back to the currency's `exponent` when
+ * absent; number and bigint calculators are both accepted.
+ */
+interface MoneySnapshotLike {
+  readonly amount: number | bigint;
+  readonly currency: MoneySnapshotCurrencyLike;
+  readonly scale?: number | bigint;
+}
+/**
+ * The canonical snapshot {@link moneyToSnapshot} emits: number-based
+ * with an explicit base-10 currency object, which is exactly what the
+ * common calculation-library constructors accept.
+ */
+interface MoneySnapshot {
+  readonly amount: number;
+  readonly currency: {
+    readonly code: CurrencyCode;
+    readonly base: 10;
+    readonly exponent: number;
+  };
+  readonly scale: number;
+}
+/**
+ * Converts a calculation-library snapshot into canonical {@link Money}.
+ * The anti-corruption checks live here so they run exactly once, at
+ * the boundary:
+ *
+ * - non-decimal currencies are rejected (`base` other than 10; some
+ *   library currency packages model MGA/MRU with base 5, and pre-1971
+ *   GBP with a base array): their minor units do not map onto a
+ *   power-of-ten scale
+ * - number amounts must be safe integers; fractional or beyond-2^53
+ *   amounts are rejected instead of silently corrupted
+ * - bigint amounts pass through exactly
+ *
+ * Takes `unknown` on purpose: this is the trust boundary for foreign
+ * library data, so callers never cast before validating (the
+ * {@link MoneySnapshotLike} type documents the expected shape).
+ */
+declare function moneyFromSnapshot(snapshot: unknown): Money;
+/**
+ * Converts {@link Money} into the snapshot shape the common
+ * calculation-library constructors accept. Number-based by design (the
+ * libraries' default calculators are), so amounts past
+ * `Number.MAX_SAFE_INTEGER` are rejected loudly; wire such amounts
+ * into a bigint calculator directly from `money.amountMinor` instead.
+ */
+declare function moneyToSnapshot(money: Money): MoneySnapshot;
+//#endregion
+//#region src/money/try-parse.d.ts
+/**
+ * {@link parseMoneyInput} as a `Result`: `Err` for the documented
+ * rejections (malformed input as `InvalidMoneyError`, over-precise
+ * input as `MoneyPrecisionLossError`), a throw for everything else.
+ */
+declare function tryParseMoneyInput(input: unknown, options: ParseMoneyInputOptions): Result<Money, InvalidMoneyError | MoneyPrecisionLossError>;
+/**
+ * {@link moneyFromDto} as a `Result`: `Err` for the documented
+ * rejection (`InvalidMoneyError`), a throw for everything else.
+ */
+declare function tryMoneyFromDto(dto: unknown): Result<Money, InvalidMoneyError>;
+/**
+ * {@link moneyFromSnapshot} as a `Result`: `Err` for the documented
+ * rejection (`InvalidMoneyError`), a throw for everything else.
+ */
+declare function tryMoneyFromSnapshot(snapshot: unknown): Result<Money, InvalidMoneyError>;
+//#endregion
+export { type CreateMoneyFactoryOptions, type CurrencyCode, type CurrencyScaleResolver, InvalidMoneyError, type Money, MoneyCurrencyMismatchError, type MoneyDto, type MoneyFactory, MoneyPrecisionLossError, MoneyScaleMismatchError, type MoneySnapshot, type MoneySnapshotCurrencyLike, type MoneySnapshotLike, type ParseMoneyInputOptions, UnknownCurrencyError, addMoney, createMoneyFactory, createMoneyFormatter, currencyScaleFromIntl, currencyScaleFromRecord, formatMoney, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, moneyEquals, moneyFromDto, moneyFromSnapshot, moneyFromUnknown, moneyOfMinor, moneyToDecimalString, moneyToDto, moneyToSnapshot, negateMoney, parseMoneyInput, rescaleMoney, subtractMoney, tryMoneyFromDto, tryMoneyFromSnapshot, tryParseMoneyInput };
+//# sourceMappingURL=money.d.ts.map