@classytic/primitives 0.19.0 → 0.21.0

package/dist/memory-outbox.mjs

@@ -0,0 +1,172 @@
+import { InvalidOutboxEventError, OutboxOwnershipError } from "./outbox.mjs";
+//#region src/events/memory-outbox.ts
+/**
+* In-memory outbox store — reference implementation for dev / testing.
+*
+* Supports the full `OutboxStore` capability set (claim/lease, fail/retry,
+* dedupe, visibleAt). Production deployments should pass a `repository` to
+* `EventOutbox` instead of using this; the memory store exists for unit
+* tests and single-process dev where durable persistence is noise.
+*/
+const DEFAULT_LEASE_MS = 3e4;
+var MemoryOutboxStore = class {
+	entries = [];
+	seenDedupeKeys = /* @__PURE__ */ new Set();
+	/**
+	* Drop every entry (including delivered / failed / dead-lettered rows) and
+	* the dedupe-key memory.
+	*
+	* For tests only — it is the in-memory analogue of truncating the table, and
+	* exists so a suite can isolate cases against ONE store instance (the
+	* `reset` hook of `runOutboxStoreContract`). Not part of `OutboxStore`; a
+	* production store must never expose this.
+	*/
+	clear() {
+		this.entries.length = 0;
+		this.seenDedupeKeys.clear();
+	}
+	/**
+	* For tests only — every stored event regardless of status, in insertion
+	* order. The in-memory analogue of `SELECT * FROM outbox`, used by the
+	* `/event-infra` contract test to assert what a `purge` left behind. Not part
+	* of `OutboxStore`; a production store must never expose this.
+	*/
+	all() {
+		return this.entries.map((e) => e.event);
+	}
+	async save(event, options) {
+		if (!event?.type || typeof event.type !== "string") throw new InvalidOutboxEventError("event.type is required");
+		if (!event.meta?.id || typeof event.meta.id !== "string") throw new InvalidOutboxEventError("event.meta.id is required");
+		if (options?.dedupeKey) {
+			if (this.seenDedupeKeys.has(options.dedupeKey)) return;
+			this.seenDedupeKeys.add(options.dedupeKey);
+		}
+		this.entries.push({
+			createdAt: Date.now(),
+			event,
+			status: "pending",
+			attempts: 0,
+			visibleAt: options?.visibleAt?.getTime() ?? 0,
+			leaseOwner: null,
+			leaseExpiresAt: 0,
+			deliveredAt: null,
+			firstFailedAt: null,
+			lastFailedAt: null,
+			lastError: null,
+			dedupeKey: options?.dedupeKey
+		});
+	}
+	async getPending(limit) {
+		const now = Date.now();
+		return this.entries.filter((e) => e.status === "pending" && e.visibleAt <= now && (e.leaseOwner === null || e.leaseExpiresAt <= now)).slice(0, limit).map((e) => e.event);
+	}
+	async claimPending(options) {
+		const now = Date.now();
+		const limit = options?.limit ?? 100;
+		const leaseMs = options?.leaseMs ?? DEFAULT_LEASE_MS;
+		const consumerId = options?.consumerId ?? "anonymous";
+		const typeFilter = options?.types ? new Set(options.types) : null;
+		const claimed = [];
+		for (const entry of this.entries) {
+			if (claimed.length >= limit) break;
+			if (entry.status !== "pending") continue;
+			if (entry.visibleAt > now) continue;
+			if (entry.leaseOwner !== null && entry.leaseExpiresAt > now) continue;
+			if (typeFilter && !typeFilter.has(entry.event.type)) continue;
+			entry.leaseOwner = consumerId;
+			entry.leaseExpiresAt = now + leaseMs;
+			entry.attempts++;
+			claimed.push(entry.event);
+		}
+		return claimed;
+	}
+	async acknowledge(eventId, options) {
+		const entry = this.entries.find((e) => e.event.meta.id === eventId);
+		if (!entry) return;
+		if (entry.status === "delivered") return;
+		if (options?.consumerId && entry.leaseOwner && entry.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, entry.leaseOwner);
+		entry.status = "delivered";
+		entry.deliveredAt = Date.now();
+		entry.leaseOwner = null;
+	}
+	async fail(eventId, error, options) {
+		const entry = this.entries.find((e) => e.event.meta.id === eventId);
+		if (!entry) return;
+		if (options?.consumerId && entry.leaseOwner && entry.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, entry.leaseOwner);
+		const now = Date.now();
+		entry.lastError = error;
+		entry.leaseOwner = null;
+		entry.leaseExpiresAt = 0;
+		if (entry.firstFailedAt === null) entry.firstFailedAt = now;
+		entry.lastFailedAt = now;
+		if (options?.deadLetter) {
+			entry.status = "dead_letter";
+			return;
+		}
+		entry.status = "pending";
+		entry.visibleAt = options?.retryAt ? options.retryAt.getTime() : 0;
+	}
+	async getDeadLettered(limit) {
+		const out = [];
+		for (const entry of this.entries) {
+			if (out.length >= limit) break;
+			if (entry.status !== "dead_letter") continue;
+			out.push({
+				event: entry.event,
+				error: {
+					message: entry.lastError?.message ?? "unknown",
+					...entry.lastError?.code !== void 0 ? { code: entry.lastError.code } : {}
+				},
+				attempts: entry.attempts,
+				firstFailedAt: new Date(entry.firstFailedAt ?? entry.lastFailedAt ?? Date.now()),
+				lastFailedAt: new Date(entry.lastFailedAt ?? entry.firstFailedAt ?? Date.now())
+			});
+		}
+		return out;
+	}
+	async purge(olderThanMs) {
+		const cutoff = Date.now() - olderThanMs;
+		let purged = 0;
+		for (let i = this.entries.length - 1; i >= 0; i--) {
+			const entry = this.entries[i];
+			if (!entry) continue;
+			if (entry.status === "delivered" && entry.deliveredAt !== null && entry.deliveredAt < cutoff) {
+				if (entry.dedupeKey) this.seenDedupeKeys.delete(entry.dedupeKey);
+				this.entries.splice(i, 1);
+				purged++;
+			}
+		}
+		return purged;
+	}
+	/**
+	* Re-drive one dead-lettered row. Scoped to `dead_letter`: a row that is merely
+	* backing off must keep its attempt count, and the id alone cannot tell the two apart.
+	*/
+	async requeue(eventId) {
+		const entry = this.entries.find((e) => e.event.meta.id === eventId && e.status === "dead_letter");
+		if (!entry) return false;
+		entry.status = "pending";
+		entry.attempts = 0;
+		entry.leaseOwner = null;
+		entry.leaseExpiresAt = 0;
+		entry.visibleAt = 0;
+		entry.lastError = null;
+		return true;
+	}
+	async countByStatus(status) {
+		return this.entries.filter((e) => e.status === status).length;
+	}
+	/** Age of the oldest PENDING row — see `MemoryEntry.createdAt` for why not `visibleAt`. */
+	async oldestPendingAgeMs() {
+		const pending = this.entries.filter((e) => e.status === "pending");
+		if (pending.length === 0) return null;
+		const oldest = Math.min(...pending.map((e) => e.createdAt));
+		return Date.now() - oldest;
+	}
+	/** Test helper: inspect entry by id */
+	_getEntry(eventId) {
+		return this.entries.find((e) => e.event.meta.id === eventId);
+	}
+};
+//#endregion
+export { MemoryOutboxStore };

package/dist/mixin.d.mts

@@ -45,7 +45,7 @@ interface Mixinable {
  * mixin payload through a well-typed accessor.
  */
 type WithMixin<T, K extends string, M> = T & {
-  readonly mixins: Readonly<Record<string, unknown>> & { readonly [P in K]: M };
+  readonly mixins: Readonly<Record<string, unknown>> & { readonly [P in K]: M; };
 };
 /**
  * Attach (or overwrite) a mixin on a base entity. Returns a NEW object —

package/dist/monetization.d.mts

@@ -1,5 +1,4 @@
-import { Money } from "./money.mjs";
-
+import { n as Money } from "./money-CfAvfNiM.mjs";
 //#region src/money/monetization.d.ts
 /**
  * A map of currency code → {@link Money} for explicit per-currency pricing.

package/dist/money-CfAvfNiM.d.mts

@@ -0,0 +1,346 @@
+import { t as Brand } from "./brand-Lj_75Y_r.mjs";
+//#region src/money/currency.d.ts
+/**
+ * ISO 4217 currency code (3 uppercase letters).
+ *
+ * Branded `string` — any 3-letter string is structurally valid, but the brand
+ * prevents accidental mixing with raw strings. Use {@link toCurrencyCode} to
+ * construct one safely.
+ */
+type CurrencyCode = Brand<string, 'CurrencyCode'>;
+/**
+ * Common ISO 4217 codes. Non-exhaustive — add more at the consumer level if
+ * needed. Listed here because shared-types ships with these by default.
+ */
+declare const CURRENCIES: {
+  readonly USD: "USD";
+  readonly EUR: "EUR";
+  readonly GBP: "GBP";
+  readonly JPY: "JPY";
+  readonly CNY: "CNY";
+  readonly INR: "INR";
+  readonly BDT: "BDT";
+  readonly AED: "AED";
+  readonly SAR: "SAR";
+  readonly PKR: "PKR";
+  readonly NPR: "NPR";
+  readonly LKR: "LKR";
+  readonly MYR: "MYR";
+  readonly SGD: "SGD";
+  readonly AUD: "AUD";
+  readonly CAD: "CAD";
+  readonly CHF: "CHF";
+  readonly HKD: "HKD";
+  readonly THB: "THB";
+  readonly IDR: "IDR";
+};
+/**
+ * Number of minor units per major unit, by ISO 4217 code.
+ *
+ * **This table must list EVERY currency whose exponent is not 2.** ISO 4217
+ * defaults to 2 decimals, and {@link minorUnitFactor} falls back to 100 for a
+ * code it does not know — which is correct for the ~150 two-decimal currencies
+ * and catastrophically wrong for the others. A missing zero-decimal entry does
+ * not throw: it makes `fromMajor(1500, 'GNF')` store 150 000 minor units, a
+ * 100× error that reads as a plausible number all the way to the gateway.
+ *
+ * So the exceptions are enumerated EXHAUSTIVELY (all 0-, 3- and 4-decimal
+ * codes), leaving the `?? 100` fallback reachable only by a code that is not a
+ * real ISO 4217 currency — a typo, a lowercased code, or a placeholder. The
+ * two-decimal entries below are redundant with the default and kept only as
+ * documentation of the common set.
+ */
+declare const MINOR_UNIT_FACTOR: Readonly<Record<string, number>>;
+/**
+ * ISO 4217 format — 3 uppercase letters. Exported so consumers can embed
+ * the SAME pattern in JSON-Schema-representable validators (zod `.regex`,
+ * Mongoose `match`, OpenAPI `pattern`) instead of hand-rolling a copy:
+ * `.refine(isCurrencyCode)` validates at runtime but is dropped by
+ * `z.toJSONSchema`, losing the constraint from generated API docs.
+ * `isCurrencyCode` / `toCurrencyCode` remain the runtime API.
+ */
+declare const CURRENCY_PATTERN: RegExp;
+/**
+ * Narrow a raw string to a {@link CurrencyCode}. Returns `null` if the string
+ * is not a valid ISO 4217 format (3 uppercase letters). This does not verify
+ * the code is registered with ISO — use your own whitelist for that.
+ */
+declare function toCurrencyCode(value: string): CurrencyCode | null;
+/**
+ * Validate + brand, or throw. The constructor form — same relationship to
+ * {@link toCurrencyCode} that `civilDate` has to `isCivilDate`.
+ *
+ * `Money` carries a {@link CurrencyCode}, not a bare string, and this is where
+ * an untrusted value earns the brand. Rejecting `'jpy'` here matters: lowercase
+ * misses {@link MINOR_UNIT_FACTOR}, so it silently becomes a 2-decimal currency
+ * and every JPY amount is off by 100×.
+ */
+declare function currencyCode(value: string): CurrencyCode;
+declare class InvalidCurrencyCodeError extends Error {
+  readonly name = "InvalidCurrencyCodeError";
+  readonly value: string;
+  constructor(value: string);
+}
+/**
+ * Raised when an operation combines two currencies.
+ *
+ * Declared HERE rather than in `/money` so the FX seam below can throw it
+ * without a runtime import back into `/money` (which imports
+ * {@link minorUnitFactor} from this file). `/money` re-exports it, so
+ * `import { CurrencyMismatchError } from '@classytic/primitives/money'` still
+ * resolves.
+ */
+declare class CurrencyMismatchError extends Error {
+  readonly name = "CurrencyMismatchError";
+  readonly left: string;
+  readonly right: string;
+  constructor(left: string, right: string);
+}
+/** Type predicate for `unknown` input. */
+declare function isCurrencyCode(value: unknown): value is CurrencyCode;
+/**
+ * Minor units per major unit (100 for USD, 1 for JPY, 1000 for KWD, 10 000 for CLF).
+ *
+ * Falls back to 100 for an unlisted code — the ISO 4217 default exponent. Because
+ * {@link MINOR_UNIT_FACTOR} enumerates every non-2-decimal currency, that fallback
+ * is now only reached by codes that are not ISO 4217 currencies at all; use
+ * {@link isKnownCurrency} at a config/boot boundary if you need to reject those
+ * rather than assume two decimals for them.
+ */
+declare function minorUnitFactor(currency: string): number;
+/**
+ * Does {@link MINOR_UNIT_FACTOR} carry an explicit exponent for this code?
+ *
+ * `false` means {@link minorUnitFactor} would ASSUME two decimals. That
+ * assumption is right for an ordinary ISO 4217 code and wrong by 100× for a
+ * mistyped or lowercased one (`'jpy'`), so a boot-time config validator that
+ * accepts an operator-supplied currency should gate on this instead of letting
+ * the default answer for it.
+ */
+declare function isKnownCurrency(currency: string): boolean;
+/**
+ * Frozen FX conversion record — the cost of record for cross-currency
+ * transactions. Stored alongside a base-currency amount at the seam where
+ * currency crossed (procurement receipt, landed-cost entry, foreign refund).
+ *
+ * Invariant: once written, never mutated. Revaluation is a new snapshot on
+ * a new document — rewriting an existing snapshot corrupts audit history.
+ *
+ * `rate` is expressed as: 1 sourceCurrency = rate * baseCurrency
+ * (e.g. USD→BDT at 110 means rate = 110, so sourceAmount 10 USD → baseAmount 1100 BDT).
+ * This matches how banks quote — the source is the "from" currency.
+ */
+interface FxSnapshot {
+  /** Currency the transaction was invoiced / quoted in. ISO 4217. */
+  sourceCurrency: string;
+  /** Organisation's functional currency the base amount is expressed in. */
+  baseCurrency: string;
+  /** 1 unit of sourceCurrency equals this many units of baseCurrency. */
+  rate: number;
+  /** When the rate was captured — NOT when the document was last touched. */
+  snapshotAt: Date;
+  /**
+   * Optional provenance tag — e.g. 'manual', 'bangladesh-bank',
+   * 'openexchangerates.org', 'supplier-invoice'. Free-form; hosts use it for
+   * audit filtering and re-pricing policy.
+   */
+  source?: string;
+}
+/**
+ * How to land a converted amount on an integer number of minor units.
+ * Required to be deterministic and named, never implicit — the old signature
+ * returned an unrounded float and left the choice to whoever persisted it, so
+ * two call sites rounding differently produced two answers for one conversion.
+ */
+type FxRounding = 'half-away-from-zero' | 'floor' | 'ceil';
+/**
+ * Apply an {@link FxSnapshot} to a source-currency amount.
+ *
+ * ## Why this takes `Money` and not a number
+ *
+ * It used to take a bare `number`, which meant nothing could check the amount
+ * was denominated in `fx.sourceCurrency`. Applying a USD→BDT snapshot to a EUR
+ * amount type-checked, ran, and returned a plausible wrong number — the
+ * arithmetic is identical, only the meaning is wrong, so no test that asserts a
+ * total would notice. Taking `Money` lets the seam enforce its own
+ * precondition: a mismatch throws {@link CurrencyMismatchError}.
+ *
+ * ## Minor-unit exponents are handled
+ *
+ * The rate is quoted in MAJOR units (1 source = `rate` base), while `Money`
+ * holds minor units, and the two currencies need not share an exponent
+ * (USD has 2, JPY has 0). The conversion therefore goes
+ * `minor → major → ×rate → base minor`, not a naive `amount × rate`, which is
+ * off by 100× for any pair whose exponents differ.
+ */
+declare function convertWithSnapshot(source: Money, fx: FxSnapshot, options?: {
+  rounding?: FxRounding;
+}): Money;
+/**
+ * Reverse an {@link FxSnapshot} — reconstruct the source-currency amount
+ * from a stored base amount. Useful for reporting "cost in original
+ * currency". Not round-trip safe under rounding; prefer storing the
+ * original source amount alongside the base amount when audit fidelity
+ * matters.
+ *
+ * Symmetrically guarded: a base amount that is not in `fx.baseCurrency` throws
+ * rather than dividing by a rate that does not describe it.
+ */
+declare function reverseWithSnapshot(base: Money, fx: FxSnapshot, options?: {
+  rounding?: FxRounding;
+}): Money;
+/**
+ * Structural validation — checks shape only. Does NOT verify the rate is
+ * economically sensible (8.5 USD→BDT would pass this check). Host-level
+ * guards / anomaly detection handle that.
+ */
+declare function isFxSnapshot(value: unknown): value is FxSnapshot;
+//#endregion
+//#region src/money/money.d.ts
+/**
+ * Wire-format monetary amount: integer minor units, branded with a phantom
+ * currency type so calls like `formatBdt(usdValue)` fail at compile time.
+ *
+ * Use this for HTTP/JSON fields where transmitting a `Money` struct would be
+ * overkill: `interface Order { grandTotal: MinorUnits<'BDT'>; ... }`. Pair
+ * with the structured {@link Money} for in-process arithmetic.
+ *
+ * Erases at runtime — branded types have zero cost.
+ *
+ * @example
+ * type Paisa = MinorUnits<'BDT'>;
+ * type UsdCents = MinorUnits<'USD'>;
+ * const p: Paisa = MinorUnits(489900, 'BDT');
+ * const c: UsdCents = p; // ❌ type error: BDT vs USD
+ */
+declare const __unitBrand: unique symbol;
+declare const __currencyBrand: unique symbol;
+type MinorUnits<C extends string = string> = number & {
+  readonly [__unitBrand]: 'minor';
+  readonly [__currencyBrand]: C;
+};
+/**
+ * Cast a raw number to {@link MinorUnits}. Pass the currency as the second
+ * argument to fix the phantom type. With no second arg, `MinorUnits<string>`
+ * — useful for generic SDK boundaries that don't know the currency yet.
+ *
+ * @example
+ * MinorUnits(489900, 'BDT')   // typed MinorUnits<'BDT'>
+ * MinorUnits(199, 'USD')      // typed MinorUnits<'USD'>
+ */
+declare function MinorUnits<C extends string = string>(amount: number, _currency?: C): MinorUnits<C>;
+/**
+ * A monetary amount stored as an integer in the currency's minor unit.
+ *
+ * Examples:
+ *  - `{ amount: 19_99,   currency: 'USD' }` — 19.99 USD (2 decimals)
+ *  - `{ amount: 1_500,   currency: 'JPY' }` — 1500 JPY (0 decimals)
+ *  - `{ amount: 500_000, currency: 'KWD' }` — 500.000 KWD (3 decimals)
+ *
+ * Storing as integers avoids IEEE 754 rounding across arithmetic. Never store
+ * `Money.amount` as a float.
+ *
+ * ## `currency` is a branded {@link CurrencyCode}, not a string
+ *
+ * It was declared `CurrencyCode | string`, and a union with `string` collapses
+ * TO `string` — so the brand was decoration on the one type in the package
+ * where it matters, and `money()` validated nothing. Any string reached the
+ * field: `'jpy'`, `''`, `'US Dollar'`, a mistyped `'BTD'`. None of those are in
+ * {@link MINOR_UNIT_FACTOR}, so `minorUnitFactor` assumes two decimals for them
+ * and every JPY-style amount is 100× wrong while looking perfectly ordinary.
+ *
+ * Construct through {@link money} / {@link fromMajor} (which validate and
+ * brand) or through `currencyCode()` at your own boundary. A raw object literal
+ * `{ amount, currency: someString }` is now a compile error — deliberately, so
+ * the validation cannot be bypassed by the shape that skipped it before.
+ */
+interface Money {
+  readonly amount: number;
+  readonly currency: CurrencyCode;
+}
+/**
+ * Construct {@link Money} from an integer minor-unit amount.
+ *
+ * @throws TypeError if `amount` is not a finite integer.
+ * @throws InvalidCurrencyCodeError if `currency` is not ISO 4217 format.
+ */
+declare function money(amount: number, currency: string): Money;
+/**
+ * Construct {@link Money} from a major-unit number (e.g. dollars, taka) by
+ * scaling to the currency's minor unit and rounding half-away-from-zero.
+ *
+ * Uses `toPrecision(15)` to strip the trailing-bit noise that appears in
+ * multiply-then-round (e.g. `0.1 + 0.2 = 0.30000000000000004`). This is
+ * enough for the vast majority of decimals encountered in real-world pricing.
+ *
+ * **Precision caveat.** A handful of decimals cannot be represented exactly
+ * in IEEE 754 and will round to the IEEE-closest integer rather than the
+ * mathematically-expected one — e.g. `1.005` is stored as `1.00499999…` and
+ * rounds to `100` minor units, not `101`. If you need decimal-exact rounding,
+ * construct money from a string or use integer minor units directly via
+ * {@link money}.
+ *
+ * @example
+ * fromMajor(19.99, 'USD')      // { amount: 1999, currency: 'USD' }
+ * fromMajor(0.1 + 0.2, 'USD')  // { amount: 30,   currency: 'USD' }
+ * fromMajor(1500,  'JPY')      // { amount: 1500, currency: 'JPY' }
+ */
+declare function fromMajor(major: number, currency: string): Money;
+/** Convert {@link Money} back to its major-unit floating-point representation. */
+declare function toMajor(m: Money): number;
+declare function addMoney(a: Money, b: Money): Money;
+declare function subtractMoney(a: Money, b: Money): Money;
+/**
+ * Multiply money by a scalar. The result is rounded to an integer number of
+ * minor units using half-away-from-zero rounding.
+ */
+declare function multiplyMoney(m: Money, scalar: number): Money;
+/** Sum a list of {@link Money}. Returns zero in the given currency for empty input. */
+declare function sumMoney(values: readonly Money[], currency: string): Money;
+/** Strict equality (amount and currency both match). */
+declare function equalsMoney(a: Money, b: Money): boolean;
+/**
+ * Ordering predicate. Returns -1, 0, or 1. Throws on currency mismatch — use
+ * {@link equalsMoney} for a total equality check across currencies.
+ */
+declare function compareMoney(a: Money, b: Money): -1 | 0 | 1;
+declare function isZeroMoney(m: Money): boolean;
+declare function isPositiveMoney(m: Money): boolean;
+declare function isNegativeMoney(m: Money): boolean;
+declare function negateMoney(m: Money): Money;
+declare function absMoney(m: Money): Money;
+/**
+ * Decimal major-unit number → integer minor units by decimal exponent.
+ * Rounding: raw IEEE `Math.round` — half-up toward +∞ (so `-10.5 → -10`),
+ * documented above. Throws when the result leaves the safe-integer range
+ * (also catches `NaN`/`Infinity` inputs).
+ *
+ * @example
+ * majorToMinorUnits(10.5)      // 1050
+ * majorToMinorUnits(1000, 0)   // 1000 (JPY-style)
+ * majorToMinorUnits(1.005)     // 100 — IEEE, see note above
+ */
+declare function majorToMinorUnits(major: number, minorUnitDecimals?: number): number;
+/** Integer minor units → decimal major-unit number by decimal exponent: `1050 → 10.5`. */
+declare function minorUnitsToMajor(minor: number, minorUnitDecimals?: number): number;
+/**
+ * Percentage of an integer minor-unit amount → integer minor units.
+ * EXACT multiply-then-round: `Math.round((minor × ratePercent) / 100)` —
+ * one rounding point, half-up toward +∞. Handles genuinely fractional rates
+ * (QST 9.975 %) without precision loss: `percentOfMinor(20000, 9.975) === 1995`.
+ *
+ * Hosts whose domain guarantees at-most-2-decimal rates MAY snap the rate to
+ * integer basis points BEFORE calling (be-prod's `#shared/money` seam does) —
+ * that is host policy layered on top, not part of this primitive.
+ */
+declare function percentOfMinor(minor: number, ratePercent: number): number;
+/**
+ * Integer minor units → plain decimal string (no currency symbol, no locale):
+ * `formatMinorUnits(10550) → "105.50"`, `formatMinorUnits(1000, 0) → "1000"`.
+ * For localized currency strings use `Intl.NumberFormat` at the display layer.
+ */
+declare function formatMinorUnits(minor: number, minorUnitDecimals?: number): string;
+/** Structural type guard. */
+declare function isMoney(value: unknown): value is Money;
+//#endregion
+export { convertWithSnapshot as A, CURRENCY_PATTERN as C, FxSnapshot as D, FxRounding as E, minorUnitFactor as F, reverseWithSnapshot as I, toCurrencyCode as L, isCurrencyCode as M, isFxSnapshot as N, InvalidCurrencyCodeError as O, isKnownCurrency as P, CURRENCIES as S, CurrencyMismatchError as T, negateMoney as _, compareMoney as a, sumMoney as b, fromMajor as c, isPositiveMoney as d, isZeroMoney as f, multiplyMoney as g, money as h, addMoney as i, currencyCode as j, MINOR_UNIT_FACTOR as k, isMoney as l, minorUnitsToMajor as m, Money as n, equalsMoney as o, majorToMinorUnits as p, absMoney as r, formatMinorUnits as s, MinorUnits as t, isNegativeMoney as u, percentOfMinor as v, CurrencyCode as w, toMajor as x, subtractMoney as y };

package/dist/money.d.mts

@@ -1,141 +1,2 @@
-import { r as CurrencyCode } from "./currency-BCJnJBlb.mjs";
-
-//#region src/money/money.d.ts
-/**
- * Wire-format monetary amount: integer minor units, branded with a phantom
- * currency type so calls like `formatBdt(usdValue)` fail at compile time.
- *
- * Use this for HTTP/JSON fields where transmitting a `Money` struct would be
- * overkill: `interface Order { grandTotal: MinorUnits<'BDT'>; ... }`. Pair
- * with the structured {@link Money} for in-process arithmetic.
- *
- * Erases at runtime — branded types have zero cost.
- *
- * @example
- * type Paisa = MinorUnits<'BDT'>;
- * type UsdCents = MinorUnits<'USD'>;
- * const p: Paisa = MinorUnits(489900, 'BDT');
- * const c: UsdCents = p; // ❌ type error: BDT vs USD
- */
-declare const __unitBrand: unique symbol;
-declare const __currencyBrand: unique symbol;
-type MinorUnits<C extends string = string> = number & {
-  readonly [__unitBrand]: 'minor';
-  readonly [__currencyBrand]: C;
-};
-/**
- * Cast a raw number to {@link MinorUnits}. Pass the currency as the second
- * argument to fix the phantom type. With no second arg, `MinorUnits<string>`
- * — useful for generic SDK boundaries that don't know the currency yet.
- *
- * @example
- * MinorUnits(489900, 'BDT')   // typed MinorUnits<'BDT'>
- * MinorUnits(199, 'USD')      // typed MinorUnits<'USD'>
- */
-declare function MinorUnits<C extends string = string>(amount: number, _currency?: C): MinorUnits<C>;
-/**
- * A monetary amount stored as an integer in the currency's minor unit.
- *
- * Examples:
- *  - `{ amount: 19_99,   currency: 'USD' }` — 19.99 USD (2 decimals)
- *  - `{ amount: 1_500,   currency: 'JPY' }` — 1500 JPY (0 decimals)
- *  - `{ amount: 500_000, currency: 'KWD' }` — 500.000 KWD (3 decimals)
- *
- * Storing as integers avoids IEEE 754 rounding across arithmetic. Never store
- * `Money.amount` as a float.
- */
-interface Money {
-  readonly amount: number;
-  readonly currency: CurrencyCode | string;
-}
-declare class CurrencyMismatchError extends Error {
-  readonly name = "CurrencyMismatchError";
-  readonly left: string;
-  readonly right: string;
-  constructor(left: string, right: string);
-}
-/**
- * Construct {@link Money} from an integer minor-unit amount.
- *
- * @throws TypeError if `amount` is not a finite integer.
- */
-declare function money(amount: number, currency: string): Money;
-/**
- * Construct {@link Money} from a major-unit number (e.g. dollars, taka) by
- * scaling to the currency's minor unit and rounding half-away-from-zero.
- *
- * Uses `toPrecision(15)` to strip the trailing-bit noise that appears in
- * multiply-then-round (e.g. `0.1 + 0.2 = 0.30000000000000004`). This is
- * enough for the vast majority of decimals encountered in real-world pricing.
- *
- * **Precision caveat.** A handful of decimals cannot be represented exactly
- * in IEEE 754 and will round to the IEEE-closest integer rather than the
- * mathematically-expected one — e.g. `1.005` is stored as `1.00499999…` and
- * rounds to `100` minor units, not `101`. If you need decimal-exact rounding,
- * construct money from a string or use integer minor units directly via
- * {@link money}.
- *
- * @example
- * fromMajor(19.99, 'USD')      // { amount: 1999, currency: 'USD' }
- * fromMajor(0.1 + 0.2, 'USD')  // { amount: 30,   currency: 'USD' }
- * fromMajor(1500,  'JPY')      // { amount: 1500, currency: 'JPY' }
- */
-declare function fromMajor(major: number, currency: string): Money;
-/** Convert {@link Money} back to its major-unit floating-point representation. */
-declare function toMajor(m: Money): number;
-declare function addMoney(a: Money, b: Money): Money;
-declare function subtractMoney(a: Money, b: Money): Money;
-/**
- * Multiply money by a scalar. The result is rounded to an integer number of
- * minor units using half-away-from-zero rounding.
- */
-declare function multiplyMoney(m: Money, scalar: number): Money;
-/** Sum a list of {@link Money}. Returns zero in the given currency for empty input. */
-declare function sumMoney(values: readonly Money[], currency: string): Money;
-/** Strict equality (amount and currency both match). */
-declare function equalsMoney(a: Money, b: Money): boolean;
-/**
- * Ordering predicate. Returns -1, 0, or 1. Throws on currency mismatch — use
- * {@link equalsMoney} for a total equality check across currencies.
- */
-declare function compareMoney(a: Money, b: Money): -1 | 0 | 1;
-declare function isZeroMoney(m: Money): boolean;
-declare function isPositiveMoney(m: Money): boolean;
-declare function isNegativeMoney(m: Money): boolean;
-declare function negateMoney(m: Money): Money;
-declare function absMoney(m: Money): Money;
-/**
- * Decimal major-unit number → integer minor units by decimal exponent.
- * Rounding: raw IEEE `Math.round` — half-up toward +∞ (so `-10.5 → -10`),
- * documented above. Throws when the result leaves the safe-integer range
- * (also catches `NaN`/`Infinity` inputs).
- *
- * @example
- * majorToMinorUnits(10.5)      // 1050
- * majorToMinorUnits(1000, 0)   // 1000 (JPY-style)
- * majorToMinorUnits(1.005)     // 100 — IEEE, see note above
- */
-declare function majorToMinorUnits(major: number, minorUnitDecimals?: number): number;
-/** Integer minor units → decimal major-unit number by decimal exponent: `1050 → 10.5`. */
-declare function minorUnitsToMajor(minor: number, minorUnitDecimals?: number): number;
-/**
- * Percentage of an integer minor-unit amount → integer minor units.
- * EXACT multiply-then-round: `Math.round((minor × ratePercent) / 100)` —
- * one rounding point, half-up toward +∞. Handles genuinely fractional rates
- * (QST 9.975 %) without precision loss: `percentOfMinor(20000, 9.975) === 1995`.
- *
- * Hosts whose domain guarantees at-most-2-decimal rates MAY snap the rate to
- * integer basis points BEFORE calling (be-prod's `#shared/money` seam does) —
- * that is host policy layered on top, not part of this primitive.
- */
-declare function percentOfMinor(minor: number, ratePercent: number): number;
-/**
- * Integer minor units → plain decimal string (no currency symbol, no locale):
- * `formatMinorUnits(10550) → "105.50"`, `formatMinorUnits(1000, 0) → "1000"`.
- * For localized currency strings use `Intl.NumberFormat` at the display layer.
- */
-declare function formatMinorUnits(minor: number, minorUnitDecimals?: number): string;
-/** Structural type guard. */
-declare function isMoney(value: unknown): value is Money;
-//#endregion
+import { T as CurrencyMismatchError, _ as negateMoney, a as compareMoney, b as sumMoney, c as fromMajor, d as isPositiveMoney, f as isZeroMoney, g as multiplyMoney, h as money, i as addMoney, l as isMoney, m as minorUnitsToMajor, n as Money, o as equalsMoney, p as majorToMinorUnits, r as absMoney, s as formatMinorUnits, t as MinorUnits, u as isNegativeMoney, v as percentOfMinor, x as toMajor, y as subtractMoney } from "./money-CfAvfNiM.mjs";
 export { CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };