@storepass/money 0.1.5 → 0.2.1

package/README.md

@@ -111,6 +111,83 @@ const json = m.toJSON();
 
 `amount` is always in minor units.
 
+### Zod schemas and codecs
+
+Zod support is available from a separate entry point, so importing the core
+money primitives does not require Zod:
+
+```ts
+import { Currency, defineCurrency, Money } from "@storepass/money";
+import {
+  createMoneyCodec,
+  currencyDefinitionSchema,
+  moneyCodec,
+  moneyInstanceSchema,
+  moneySchema,
+} from "@storepass/money/zod";
+import { decode, encode } from "zod";
+
+const serialized = moneySchema.parse({ amount: 1234, currency: "USD" });
+const money = decode(moneyCodec, serialized);
+
+moneyInstanceSchema.parse(money); // Money
+encode(moneyCodec, money); // { amount: 1234, currency: "USD" }
+
+currencyDefinitionSchema.parse(Currency.USD);
+
+const XAU = defineCurrency("XAU", 4);
+const goldCodec = createMoneyCodec({ XAU });
+decode(goldCodec, { amount: 12345, currency: "XAU" });
+```
+
+`moneySchema` (also exported as `serializedMoneySchema`) accepts custom
+currency codes and validates that `amount` is a safe integer in minor units.
+`builtInSerializedMoneySchema` and `moneyCodec` restrict values to the
+currencies included in `Currency`.
+
+### Display formatting
+
+`Money#format` wraps `Intl.NumberFormat`, honoring the currency's
+`decimalPlaces` and gracefully degrading for non-ISO codes.
+
+```ts
+Money.fromNumber(Currency.USD, 1234.5).format("en-US"); // "$1,234.50"
+Money.fromNumber(Currency.EUR, 1234.56).format("de-DE"); // "1.234,56 €"
+Money.fromNumber(Currency.JPY, 1500).format("en-US"); // "¥1,500"
+Money.fromNumber(Currency.BTC, 0.12345678).format("en-US"); // "BTC 0.12345678"
+```
+
+For non-ISO codes, you can supply a `displayCode` so `Intl` still renders a
+proper currency symbol while arithmetic precision is preserved separately:
+
+```ts
+const USDH = defineCurrency("USDH", 3, { displayCode: "USD" });
+Money.fromNumber(USDH, 12.345).format("en-US"); // "$12.345"
+```
+
+## ISO 4217 compatibility
+
+Standard currencies in `Currency` carry `numericCode` and `iso4217: true`.
+Custom assets (e.g., `BTC`, `USDH`) are flagged `iso4217: false`. When
+defining your own, pass the metadata explicitly:
+
+```ts
+const SLE = defineCurrency("SLE", 2, { numericCode: 925, iso4217: true });
+const XAU = defineCurrency("XAU", 4); // non-monetary, no ISO flags
+```
+
+`defineCurrency` validates `iso4217` codes against `/^[A-Z]{3}$/` and
+requires a numeric code in `0..999`.
+
+### Staying compliant
+
+ISO 4217 is amended a few times per year by SIX Interbank Clearing
+(deprecations, redenominations, occasional additions). The hardcoded list
+in [src/currency.ts](./src/currency.ts) tracks a pinned revision (see the
+header comment). To stay current, periodically diff against the
+[official XML list](https://www.six-group.com/en/products-services/financial-information/data-standards.html)
+and update both `decimalPlaces` and `numericCode` for any drift.
+
 ## Notes and Guarantees
 
 - Currency mismatch operations throw (for example, adding USD to EUR).

package/dist/currency.d.ts

@@ -1,121 +1,203 @@
+/**
+ * Currency metadata.
+ *
+ * For ISO 4217 currencies, `iso4217` is `true` and `numericCode` is the
+ * official 3-digit numeric code. `displayCode` is an optional override that
+ * `Intl.NumberFormat` should use when the primary `code` is non-standard
+ * (e.g., legacy systems calling Bitcoin "BTC" instead of the unofficial "XBT").
+ *
+ * Standard currencies in this file follow ISO 4217 as of revision 173
+ * (published 2024-06). Run `bun run scripts/sync-iso4217.ts` to refresh.
+ */
 export interface CurrencyDefinition {
+    /** Alpha code (typically ISO 4217 alpha-3, but free-form for custom assets). */
     code: string;
+    /** Minor-unit precision used for internal arithmetic. */
     decimalPlaces: number;
+    /** ISO 4217 numeric code (0-999). Omitted for non-standard assets. */
+    numericCode?: number;
+    /** `true` when `code` is an officially registered ISO 4217 alpha-3 code. */
+    iso4217?: boolean;
+    /**
+     * Optional alpha-3 used for `Intl.NumberFormat` display. Falls back to `code`.
+     * Useful for non-ISO codes that have a registered alias.
+     */
+    displayCode?: string;
 }
 export declare const Currency: {
     readonly USD: {
         readonly code: "USD";
         readonly decimalPlaces: 2;
+        readonly numericCode: 840;
+        readonly iso4217: true;
     };
     readonly USDH: {
         readonly code: "USDH";
         readonly decimalPlaces: 3;
+        readonly iso4217: false;
+        readonly displayCode: "USD";
     };
     readonly EUR: {
         readonly code: "EUR";
         readonly decimalPlaces: 2;
+        readonly numericCode: 978;
+        readonly iso4217: true;
     };
     readonly GBP: {
         readonly code: "GBP";
         readonly decimalPlaces: 2;
+        readonly numericCode: 826;
+        readonly iso4217: true;
     };
     readonly JPY: {
         readonly code: "JPY";
         readonly decimalPlaces: 0;
+        readonly numericCode: 392;
+        readonly iso4217: true;
     };
     readonly CAD: {
         readonly code: "CAD";
         readonly decimalPlaces: 2;
+        readonly numericCode: 124;
+        readonly iso4217: true;
     };
     readonly AUD: {
         readonly code: "AUD";
         readonly decimalPlaces: 2;
+        readonly numericCode: 36;
+        readonly iso4217: true;
     };
     readonly NZD: {
         readonly code: "NZD";
         readonly decimalPlaces: 2;
+        readonly numericCode: 554;
+        readonly iso4217: true;
     };
     readonly CHF: {
         readonly code: "CHF";
         readonly decimalPlaces: 2;
+        readonly numericCode: 756;
+        readonly iso4217: true;
     };
     readonly SEK: {
         readonly code: "SEK";
         readonly decimalPlaces: 2;
+        readonly numericCode: 752;
+        readonly iso4217: true;
     };
     readonly NOK: {
         readonly code: "NOK";
         readonly decimalPlaces: 2;
+        readonly numericCode: 578;
+        readonly iso4217: true;
     };
     readonly DKK: {
         readonly code: "DKK";
         readonly decimalPlaces: 2;
+        readonly numericCode: 208;
+        readonly iso4217: true;
     };
     readonly PLN: {
         readonly code: "PLN";
         readonly decimalPlaces: 2;
+        readonly numericCode: 985;
+        readonly iso4217: true;
     };
     readonly CZK: {
         readonly code: "CZK";
         readonly decimalPlaces: 2;
+        readonly numericCode: 203;
+        readonly iso4217: true;
     };
     readonly HUF: {
         readonly code: "HUF";
         readonly decimalPlaces: 2;
+        readonly numericCode: 348;
+        readonly iso4217: true;
     };
     readonly BRL: {
         readonly code: "BRL";
         readonly decimalPlaces: 2;
+        readonly numericCode: 986;
+        readonly iso4217: true;
     };
     readonly MXN: {
         readonly code: "MXN";
         readonly decimalPlaces: 2;
+        readonly numericCode: 484;
+        readonly iso4217: true;
     };
     readonly ARS: {
         readonly code: "ARS";
         readonly decimalPlaces: 2;
+        readonly numericCode: 32;
+        readonly iso4217: true;
     };
     readonly CLP: {
         readonly code: "CLP";
         readonly decimalPlaces: 0;
+        readonly numericCode: 152;
+        readonly iso4217: true;
     };
     readonly INR: {
         readonly code: "INR";
         readonly decimalPlaces: 2;
+        readonly numericCode: 356;
+        readonly iso4217: true;
     };
     readonly SGD: {
         readonly code: "SGD";
         readonly decimalPlaces: 2;
+        readonly numericCode: 702;
+        readonly iso4217: true;
     };
     readonly HKD: {
         readonly code: "HKD";
         readonly decimalPlaces: 2;
+        readonly numericCode: 344;
+        readonly iso4217: true;
     };
     readonly KRW: {
         readonly code: "KRW";
         readonly decimalPlaces: 0;
+        readonly numericCode: 410;
+        readonly iso4217: true;
     };
     readonly CNY: {
         readonly code: "CNY";
         readonly decimalPlaces: 2;
+        readonly numericCode: 156;
+        readonly iso4217: true;
     };
     readonly ZAR: {
         readonly code: "ZAR";
         readonly decimalPlaces: 2;
+        readonly numericCode: 710;
+        readonly iso4217: true;
     };
     readonly AED: {
         readonly code: "AED";
         readonly decimalPlaces: 2;
+        readonly numericCode: 784;
+        readonly iso4217: true;
     };
     readonly SAR: {
         readonly code: "SAR";
         readonly decimalPlaces: 2;
+        readonly numericCode: 682;
+        readonly iso4217: true;
     };
     readonly BTC: {
         readonly code: "BTC";
         readonly decimalPlaces: 8;
+        readonly iso4217: false;
     };
 };
 export type CurrencyCode = keyof typeof Currency;
 export type CurrencyType = (typeof Currency)[CurrencyCode];
-export declare function defineCurrency(code: string, decimalPlaces: number): CurrencyDefinition;
+export interface DefineCurrencyOptions {
+    numericCode?: number;
+    iso4217?: boolean;
+    displayCode?: string;
+}
+export declare function defineCurrency(code: string, decimalPlaces: number, options?: DefineCurrencyOptions): CurrencyDefinition;

package/dist/index.cjs

@@ -47,43 +47,67 @@ module.exports = __toCommonJS(exports_src);
 
 // src/currency.ts
 var Currency = {
-  USD: { code: "USD", decimalPlaces: 2 },
-  USDH: { code: "USDH", decimalPlaces: 3 },
-  EUR: { code: "EUR", decimalPlaces: 2 },
-  GBP: { code: "GBP", decimalPlaces: 2 },
-  JPY: { code: "JPY", decimalPlaces: 0 },
-  CAD: { code: "CAD", decimalPlaces: 2 },
-  AUD: { code: "AUD", decimalPlaces: 2 },
-  NZD: { code: "NZD", decimalPlaces: 2 },
-  CHF: { code: "CHF", decimalPlaces: 2 },
-  SEK: { code: "SEK", decimalPlaces: 2 },
-  NOK: { code: "NOK", decimalPlaces: 2 },
-  DKK: { code: "DKK", decimalPlaces: 2 },
-  PLN: { code: "PLN", decimalPlaces: 2 },
-  CZK: { code: "CZK", decimalPlaces: 2 },
-  HUF: { code: "HUF", decimalPlaces: 2 },
-  BRL: { code: "BRL", decimalPlaces: 2 },
-  MXN: { code: "MXN", decimalPlaces: 2 },
-  ARS: { code: "ARS", decimalPlaces: 2 },
-  CLP: { code: "CLP", decimalPlaces: 0 },
-  INR: { code: "INR", decimalPlaces: 2 },
-  SGD: { code: "SGD", decimalPlaces: 2 },
-  HKD: { code: "HKD", decimalPlaces: 2 },
-  KRW: { code: "KRW", decimalPlaces: 0 },
-  CNY: { code: "CNY", decimalPlaces: 2 },
-  ZAR: { code: "ZAR", decimalPlaces: 2 },
-  AED: { code: "AED", decimalPlaces: 2 },
-  SAR: { code: "SAR", decimalPlaces: 2 },
-  BTC: { code: "BTC", decimalPlaces: 8 }
+  USD: { code: "USD", decimalPlaces: 2, numericCode: 840, iso4217: true },
+  USDH: { code: "USDH", decimalPlaces: 3, iso4217: false, displayCode: "USD" },
+  EUR: { code: "EUR", decimalPlaces: 2, numericCode: 978, iso4217: true },
+  GBP: { code: "GBP", decimalPlaces: 2, numericCode: 826, iso4217: true },
+  JPY: { code: "JPY", decimalPlaces: 0, numericCode: 392, iso4217: true },
+  CAD: { code: "CAD", decimalPlaces: 2, numericCode: 124, iso4217: true },
+  AUD: { code: "AUD", decimalPlaces: 2, numericCode: 36, iso4217: true },
+  NZD: { code: "NZD", decimalPlaces: 2, numericCode: 554, iso4217: true },
+  CHF: { code: "CHF", decimalPlaces: 2, numericCode: 756, iso4217: true },
+  SEK: { code: "SEK", decimalPlaces: 2, numericCode: 752, iso4217: true },
+  NOK: { code: "NOK", decimalPlaces: 2, numericCode: 578, iso4217: true },
+  DKK: { code: "DKK", decimalPlaces: 2, numericCode: 208, iso4217: true },
+  PLN: { code: "PLN", decimalPlaces: 2, numericCode: 985, iso4217: true },
+  CZK: { code: "CZK", decimalPlaces: 2, numericCode: 203, iso4217: true },
+  HUF: { code: "HUF", decimalPlaces: 2, numericCode: 348, iso4217: true },
+  BRL: { code: "BRL", decimalPlaces: 2, numericCode: 986, iso4217: true },
+  MXN: { code: "MXN", decimalPlaces: 2, numericCode: 484, iso4217: true },
+  ARS: { code: "ARS", decimalPlaces: 2, numericCode: 32, iso4217: true },
+  CLP: { code: "CLP", decimalPlaces: 0, numericCode: 152, iso4217: true },
+  INR: { code: "INR", decimalPlaces: 2, numericCode: 356, iso4217: true },
+  SGD: { code: "SGD", decimalPlaces: 2, numericCode: 702, iso4217: true },
+  HKD: { code: "HKD", decimalPlaces: 2, numericCode: 344, iso4217: true },
+  KRW: { code: "KRW", decimalPlaces: 0, numericCode: 410, iso4217: true },
+  CNY: { code: "CNY", decimalPlaces: 2, numericCode: 156, iso4217: true },
+  ZAR: { code: "ZAR", decimalPlaces: 2, numericCode: 710, iso4217: true },
+  AED: { code: "AED", decimalPlaces: 2, numericCode: 784, iso4217: true },
+  SAR: { code: "SAR", decimalPlaces: 2, numericCode: 682, iso4217: true },
+  BTC: { code: "BTC", decimalPlaces: 8, iso4217: false }
 };
-function defineCurrency(code, decimalPlaces) {
+var ISO_ALPHA3 = /^[A-Z]{3}$/;
+function defineCurrency(code, decimalPlaces, options = {}) {
   if (!code || typeof code !== "string") {
     throw new Error("Currency code must be a non-empty string");
   }
   if (!Number.isInteger(decimalPlaces) || decimalPlaces < 0) {
     throw new Error("Decimal places must be a non-negative integer");
   }
-  return Object.freeze({ code, decimalPlaces });
+  const { numericCode, iso4217, displayCode } = options;
+  if (iso4217 === true) {
+    if (!ISO_ALPHA3.test(code)) {
+      throw new Error(`ISO 4217 currency code must be three uppercase letters: got "${code}"`);
+    }
+    if (numericCode === undefined || !Number.isInteger(numericCode) || numericCode < 0 || numericCode > 999) {
+      throw new Error("ISO 4217 currencies require an integer numericCode in 0..999");
+    }
+  } else if (numericCode !== undefined) {
+    if (!Number.isInteger(numericCode) || numericCode < 0 || numericCode > 999) {
+      throw new Error("numericCode must be an integer in 0..999");
+    }
+  }
+  if (displayCode !== undefined && !ISO_ALPHA3.test(displayCode)) {
+    throw new Error(`displayCode must be three uppercase letters: got "${displayCode}"`);
+  }
+  const def = { code, decimalPlaces };
+  if (numericCode !== undefined)
+    def.numericCode = numericCode;
+  if (iso4217 !== undefined)
+    def.iso4217 = iso4217;
+  if (displayCode !== undefined)
+    def.displayCode = displayCode;
+  return Object.freeze(def);
 }
 // src/money.ts
 var INTERNAL_PRECISION = 20;
@@ -166,6 +190,27 @@ function assertSafeResult(value) {
     throw new Error("Result too large: exceeds safe integer range");
   }
 }
+function minorToDecimalString(minor, decimalPlaces) {
+  const negative = minor < 0n;
+  const absMinor = negative ? -minor : minor;
+  if (decimalPlaces === 0) {
+    return `${negative ? "-" : ""}${absMinor}`;
+  }
+  const scale = 10n ** BigInt(decimalPlaces);
+  const whole = absMinor / scale;
+  const fraction = (absMinor % scale).toString().padStart(decimalPlaces, "0");
+  return `${negative ? "-" : ""}${whole}.${fraction}`;
+}
+function resolveFractionDigits(decimalPlaces, options) {
+  const { minimumFractionDigits, maximumFractionDigits } = options;
+  return {
+    minimumFractionDigits: minimumFractionDigits ?? (maximumFractionDigits === undefined ? decimalPlaces : Math.min(decimalPlaces, maximumFractionDigits)),
+    maximumFractionDigits: maximumFractionDigits ?? (minimumFractionDigits === undefined ? decimalPlaces : Math.max(decimalPlaces, minimumFractionDigits))
+  };
+}
+function formatExactDecimal(format, value) {
+  return format.format(value);
+}
 
 class Money {
   #minor;
@@ -430,4 +475,27 @@ class Money {
       currency: this.#currency.code
     };
   }
+  format(locales, options = {}) {
+    const value = minorToDecimalString(this.#minor, this.#currency.decimalPlaces);
+    const dp = this.#currency.decimalPlaces;
+    const displayCode = this.#currency.displayCode ?? this.#currency.code;
+    const canUseCurrencyStyle = this.#currency.iso4217 === true || this.#currency.displayCode !== undefined;
+    const fractionDigits = resolveFractionDigits(dp, options);
+    if (canUseCurrencyStyle) {
+      try {
+        return formatExactDecimal(new Intl.NumberFormat(locales, {
+          ...options,
+          ...fractionDigits,
+          style: "currency",
+          currency: displayCode
+        }), value);
+      } catch {}
+    }
+    const number = formatExactDecimal(new Intl.NumberFormat(locales, {
+      ...options,
+      ...fractionDigits,
+      style: "decimal"
+    }), value);
+    return `${this.#currency.code} ${number}`;
+  }
 }

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { Currency, type CurrencyCode, type CurrencyDefinition, type CurrencyType, defineCurrency, } from "./currency";
-export { type FromNumberOptions, Money, type RoundingMode } from "./money";
+export { Currency, type CurrencyCode, type CurrencyDefinition, type CurrencyType, type DefineCurrencyOptions, defineCurrency, } from "./currency";
+export { type FromNumberOptions, Money, type RoundingMode, type SerializedMoney, } from "./money";

package/dist/index.mjs

@@ -1,42 +1,66 @@
 // src/currency.ts
 var Currency = {
-  USD: { code: "USD", decimalPlaces: 2 },
-  USDH: { code: "USDH", decimalPlaces: 3 },
-  EUR: { code: "EUR", decimalPlaces: 2 },
-  GBP: { code: "GBP", decimalPlaces: 2 },
-  JPY: { code: "JPY", decimalPlaces: 0 },
-  CAD: { code: "CAD", decimalPlaces: 2 },
-  AUD: { code: "AUD", decimalPlaces: 2 },
-  NZD: { code: "NZD", decimalPlaces: 2 },
-  CHF: { code: "CHF", decimalPlaces: 2 },
-  SEK: { code: "SEK", decimalPlaces: 2 },
-  NOK: { code: "NOK", decimalPlaces: 2 },
-  DKK: { code: "DKK", decimalPlaces: 2 },
-  PLN: { code: "PLN", decimalPlaces: 2 },
-  CZK: { code: "CZK", decimalPlaces: 2 },
-  HUF: { code: "HUF", decimalPlaces: 2 },
-  BRL: { code: "BRL", decimalPlaces: 2 },
-  MXN: { code: "MXN", decimalPlaces: 2 },
-  ARS: { code: "ARS", decimalPlaces: 2 },
-  CLP: { code: "CLP", decimalPlaces: 0 },
-  INR: { code: "INR", decimalPlaces: 2 },
-  SGD: { code: "SGD", decimalPlaces: 2 },
-  HKD: { code: "HKD", decimalPlaces: 2 },
-  KRW: { code: "KRW", decimalPlaces: 0 },
-  CNY: { code: "CNY", decimalPlaces: 2 },
-  ZAR: { code: "ZAR", decimalPlaces: 2 },
-  AED: { code: "AED", decimalPlaces: 2 },
-  SAR: { code: "SAR", decimalPlaces: 2 },
-  BTC: { code: "BTC", decimalPlaces: 8 }
+  USD: { code: "USD", decimalPlaces: 2, numericCode: 840, iso4217: true },
+  USDH: { code: "USDH", decimalPlaces: 3, iso4217: false, displayCode: "USD" },
+  EUR: { code: "EUR", decimalPlaces: 2, numericCode: 978, iso4217: true },
+  GBP: { code: "GBP", decimalPlaces: 2, numericCode: 826, iso4217: true },
+  JPY: { code: "JPY", decimalPlaces: 0, numericCode: 392, iso4217: true },
+  CAD: { code: "CAD", decimalPlaces: 2, numericCode: 124, iso4217: true },
+  AUD: { code: "AUD", decimalPlaces: 2, numericCode: 36, iso4217: true },
+  NZD: { code: "NZD", decimalPlaces: 2, numericCode: 554, iso4217: true },
+  CHF: { code: "CHF", decimalPlaces: 2, numericCode: 756, iso4217: true },
+  SEK: { code: "SEK", decimalPlaces: 2, numericCode: 752, iso4217: true },
+  NOK: { code: "NOK", decimalPlaces: 2, numericCode: 578, iso4217: true },
+  DKK: { code: "DKK", decimalPlaces: 2, numericCode: 208, iso4217: true },
+  PLN: { code: "PLN", decimalPlaces: 2, numericCode: 985, iso4217: true },
+  CZK: { code: "CZK", decimalPlaces: 2, numericCode: 203, iso4217: true },
+  HUF: { code: "HUF", decimalPlaces: 2, numericCode: 348, iso4217: true },
+  BRL: { code: "BRL", decimalPlaces: 2, numericCode: 986, iso4217: true },
+  MXN: { code: "MXN", decimalPlaces: 2, numericCode: 484, iso4217: true },
+  ARS: { code: "ARS", decimalPlaces: 2, numericCode: 32, iso4217: true },
+  CLP: { code: "CLP", decimalPlaces: 0, numericCode: 152, iso4217: true },
+  INR: { code: "INR", decimalPlaces: 2, numericCode: 356, iso4217: true },
+  SGD: { code: "SGD", decimalPlaces: 2, numericCode: 702, iso4217: true },
+  HKD: { code: "HKD", decimalPlaces: 2, numericCode: 344, iso4217: true },
+  KRW: { code: "KRW", decimalPlaces: 0, numericCode: 410, iso4217: true },
+  CNY: { code: "CNY", decimalPlaces: 2, numericCode: 156, iso4217: true },
+  ZAR: { code: "ZAR", decimalPlaces: 2, numericCode: 710, iso4217: true },
+  AED: { code: "AED", decimalPlaces: 2, numericCode: 784, iso4217: true },
+  SAR: { code: "SAR", decimalPlaces: 2, numericCode: 682, iso4217: true },
+  BTC: { code: "BTC", decimalPlaces: 8, iso4217: false }
 };
-function defineCurrency(code, decimalPlaces) {
+var ISO_ALPHA3 = /^[A-Z]{3}$/;
+function defineCurrency(code, decimalPlaces, options = {}) {
   if (!code || typeof code !== "string") {
     throw new Error("Currency code must be a non-empty string");
   }
   if (!Number.isInteger(decimalPlaces) || decimalPlaces < 0) {
     throw new Error("Decimal places must be a non-negative integer");
   }
-  return Object.freeze({ code, decimalPlaces });
+  const { numericCode, iso4217, displayCode } = options;
+  if (iso4217 === true) {
+    if (!ISO_ALPHA3.test(code)) {
+      throw new Error(`ISO 4217 currency code must be three uppercase letters: got "${code}"`);
+    }
+    if (numericCode === undefined || !Number.isInteger(numericCode) || numericCode < 0 || numericCode > 999) {
+      throw new Error("ISO 4217 currencies require an integer numericCode in 0..999");
+    }
+  } else if (numericCode !== undefined) {
+    if (!Number.isInteger(numericCode) || numericCode < 0 || numericCode > 999) {
+      throw new Error("numericCode must be an integer in 0..999");
+    }
+  }
+  if (displayCode !== undefined && !ISO_ALPHA3.test(displayCode)) {
+    throw new Error(`displayCode must be three uppercase letters: got "${displayCode}"`);
+  }
+  const def = { code, decimalPlaces };
+  if (numericCode !== undefined)
+    def.numericCode = numericCode;
+  if (iso4217 !== undefined)
+    def.iso4217 = iso4217;
+  if (displayCode !== undefined)
+    def.displayCode = displayCode;
+  return Object.freeze(def);
 }
 // src/money.ts
 var INTERNAL_PRECISION = 20;
@@ -119,6 +143,27 @@ function assertSafeResult(value) {
     throw new Error("Result too large: exceeds safe integer range");
   }
 }
+function minorToDecimalString(minor, decimalPlaces) {
+  const negative = minor < 0n;
+  const absMinor = negative ? -minor : minor;
+  if (decimalPlaces === 0) {
+    return `${negative ? "-" : ""}${absMinor}`;
+  }
+  const scale = 10n ** BigInt(decimalPlaces);
+  const whole = absMinor / scale;
+  const fraction = (absMinor % scale).toString().padStart(decimalPlaces, "0");
+  return `${negative ? "-" : ""}${whole}.${fraction}`;
+}
+function resolveFractionDigits(decimalPlaces, options) {
+  const { minimumFractionDigits, maximumFractionDigits } = options;
+  return {
+    minimumFractionDigits: minimumFractionDigits ?? (maximumFractionDigits === undefined ? decimalPlaces : Math.min(decimalPlaces, maximumFractionDigits)),
+    maximumFractionDigits: maximumFractionDigits ?? (minimumFractionDigits === undefined ? decimalPlaces : Math.max(decimalPlaces, minimumFractionDigits))
+  };
+}
+function formatExactDecimal(format, value) {
+  return format.format(value);
+}
 
 class Money {
   #minor;
@@ -383,6 +428,29 @@ class Money {
       currency: this.#currency.code
     };
   }
+  format(locales, options = {}) {
+    const value = minorToDecimalString(this.#minor, this.#currency.decimalPlaces);
+    const dp = this.#currency.decimalPlaces;
+    const displayCode = this.#currency.displayCode ?? this.#currency.code;
+    const canUseCurrencyStyle = this.#currency.iso4217 === true || this.#currency.displayCode !== undefined;
+    const fractionDigits = resolveFractionDigits(dp, options);
+    if (canUseCurrencyStyle) {
+      try {
+        return formatExactDecimal(new Intl.NumberFormat(locales, {
+          ...options,
+          ...fractionDigits,
+          style: "currency",
+          currency: displayCode
+        }), value);
+      } catch {}
+    }
+    const number = formatExactDecimal(new Intl.NumberFormat(locales, {
+      ...options,
+      ...fractionDigits,
+      style: "decimal"
+    }), value);
+    return `${this.#currency.code} ${number}`;
+  }
 }
 export {
   defineCurrency,

package/dist/money.d.ts

@@ -4,6 +4,15 @@ export interface FromNumberOptions {
     rounding?: RoundingMode;
     strict?: boolean;
 }
+/** JSON-safe representation of a Money value. Amount is in minor units. */
+export interface SerializedMoney {
+    amount: number;
+    currency: string;
+}
+type MoneyFormatOptions = Omit<Intl.NumberFormatOptions, "style" | "currency" | "minimumFractionDigits" | "maximumFractionDigits"> & {
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+};
 export declare class Money {
     #private;
     private constructor();
@@ -60,8 +69,18 @@ export declare class Money {
     decrementByPercent(percent: number, options?: {
         rounding?: RoundingMode;
     }): Money;
-    toJSON(): {
-        amount: number;
-        currency: string;
-    };
+    toJSON(): SerializedMoney;
+    /**
+     * Format this Money for display using `Intl.NumberFormat`.
+     *
+     * - For ISO 4217 currencies, uses `style: "currency"` with the standard code
+     *   (or `displayCode` if provided), respecting the currency's
+     *   `decimalPlaces` (overrides Intl's locale-default fraction digits).
+     * - For non-ISO codes without a `displayCode`, falls back to a decimal
+     *   format prefixed with the currency code (e.g., `"BTC 0.12345678"`).
+     * - If a runtime rejects the currency code (older engines, exotic locales),
+     *   the same decimal fallback is used.
+     */
+    format(locales?: string | string[], options?: MoneyFormatOptions): string;
 }
+export {};

package/dist/zod.cjs

@@ -0,0 +1,119 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/zod.ts
+var exports_zod = {};
+__export(exports_zod, {
+  serializedMoneySchema: () => serializedMoneySchema,
+  moneySchema: () => moneySchema,
+  moneyInstanceSchema: () => moneyInstanceSchema,
+  moneyCodec: () => moneyCodec,
+  currencyDefinitionSchema: () => currencyDefinitionSchema,
+  currencyCodeSchema: () => currencyCodeSchema,
+  createMoneyCodec: () => createMoneyCodec,
+  builtInSerializedMoneySchema: () => builtInSerializedMoneySchema
+});
+module.exports = __toCommonJS(exports_zod);
+var import_money = require("@storepass/money");
+var import_zod = require("zod");
+var builtInCurrencyCodes = Object.keys(import_money.Currency);
+var currencyCodeSchema = import_zod.z.enum(builtInCurrencyCodes);
+var currencyDefinitionSchema = import_zod.z.object({
+  code: import_zod.z.string().min(1),
+  decimalPlaces: import_zod.z.number().int().nonnegative(),
+  numericCode: import_zod.z.number().int().min(0).max(999).optional(),
+  iso4217: import_zod.z.boolean().optional(),
+  displayCode: import_zod.z.string().regex(/^[A-Z]{3}$/).optional()
+}).superRefine((currency, context) => {
+  try {
+    import_money.defineCurrency(currency.code, currency.decimalPlaces, {
+      numericCode: currency.numericCode,
+      iso4217: currency.iso4217,
+      displayCode: currency.displayCode
+    });
+  } catch (error) {
+    context.addIssue({
+      code: "custom",
+      message: error instanceof Error ? error.message : "Invalid currency definition"
+    });
+  }
+});
+var serializedMoneySchema = import_zod.z.object({
+  amount: import_zod.z.number().int(),
+  currency: import_zod.z.string().min(1)
+});
+var moneySchema = serializedMoneySchema;
+var builtInSerializedMoneySchema = serializedMoneySchema.extend({
+  currency: currencyCodeSchema
+});
+var moneyInstanceSchema = import_zod.z.custom((value) => value instanceof import_money.Money, { error: "Expected Money instance" });
+function assertCurrencyRegistry(currencies) {
+  for (const [code, currency] of Object.entries(currencies)) {
+    if (currency.code !== code) {
+      throw new Error(`Currency registry key "${code}" does not match definition code "${currency.code}"`);
+    }
+    currencyDefinitionSchema.parse(currency);
+  }
+}
+function createMoneyCodec(currencies) {
+  assertCurrencyRegistry(currencies);
+  const registeredCurrencyCodes = new Set(Object.keys(currencies));
+  const registeredCurrencyCodeSchema = import_zod.z.custom((value) => typeof value === "string" && registeredCurrencyCodes.has(value), { error: "Unknown currency code" });
+  const registeredSerializedMoneySchema = serializedMoneySchema.extend({
+    currency: registeredCurrencyCodeSchema
+  });
+  return import_zod.z.codec(registeredSerializedMoneySchema, moneyInstanceSchema, {
+    decode: ({ amount, currency }) => {
+      const registeredCurrency = currencies[currency];
+      if (registeredCurrency === undefined) {
+        throw new Error(`Unknown currency code: ${currency}`);
+      }
+      return import_money.Money.fromMinor(registeredCurrency, amount);
+    },
+    encode: (money) => {
+      const serialized = money.toJSON();
+      const currency = serialized.currency;
+      const registeredCurrency = currencies[currency];
+      if (registeredCurrency === undefined || registeredCurrency.decimalPlaces !== money.currency.decimalPlaces) {
+        throw new Error(`Money currency ${serialized.currency} is not registered with matching precision`);
+      }
+      return { amount: serialized.amount, currency };
+    }
+  });
+}
+var moneyCodec = createMoneyCodec(import_money.Currency);

package/dist/zod.d.ts

@@ -0,0 +1,109 @@
+import { type CurrencyDefinition, Money } from "@storepass/money";
+import { z } from "zod";
+/** Schema for the currency codes included with @storepass/money. */
+export declare const currencyCodeSchema: z.ZodEnum<{
+    USD: "USD";
+    USDH: "USDH";
+    EUR: "EUR";
+    GBP: "GBP";
+    JPY: "JPY";
+    CAD: "CAD";
+    AUD: "AUD";
+    NZD: "NZD";
+    CHF: "CHF";
+    SEK: "SEK";
+    NOK: "NOK";
+    DKK: "DKK";
+    PLN: "PLN";
+    CZK: "CZK";
+    HUF: "HUF";
+    BRL: "BRL";
+    MXN: "MXN";
+    ARS: "ARS";
+    CLP: "CLP";
+    INR: "INR";
+    SGD: "SGD";
+    HKD: "HKD";
+    KRW: "KRW";
+    CNY: "CNY";
+    ZAR: "ZAR";
+    AED: "AED";
+    SAR: "SAR";
+    BTC: "BTC";
+}>;
+/** Schema for built-in and custom currency definitions. */
+export declare const currencyDefinitionSchema: z.ZodObject<{
+    code: z.ZodString;
+    decimalPlaces: z.ZodNumber;
+    numericCode: z.ZodOptional<z.ZodNumber>;
+    iso4217: z.ZodOptional<z.ZodBoolean>;
+    displayCode: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Schema for Money's JSON-safe wire representation.
+ *
+ * `amount` is a safe integer in minor units. Custom currency codes are allowed.
+ */
+export declare const serializedMoneySchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strip>;
+/** Short alias for serializedMoneySchema. */
+export declare const moneySchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strip>;
+/** Serialized Money restricted to the package's built-in currencies. */
+export declare const builtInSerializedMoneySchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodEnum<{
+        USD: "USD";
+        USDH: "USDH";
+        EUR: "EUR";
+        GBP: "GBP";
+        JPY: "JPY";
+        CAD: "CAD";
+        AUD: "AUD";
+        NZD: "NZD";
+        CHF: "CHF";
+        SEK: "SEK";
+        NOK: "NOK";
+        DKK: "DKK";
+        PLN: "PLN";
+        CZK: "CZK";
+        HUF: "HUF";
+        BRL: "BRL";
+        MXN: "MXN";
+        ARS: "ARS";
+        CLP: "CLP";
+        INR: "INR";
+        SGD: "SGD";
+        HKD: "HKD";
+        KRW: "KRW";
+        CNY: "CNY";
+        ZAR: "ZAR";
+        AED: "AED";
+        SAR: "SAR";
+        BTC: "BTC";
+    }>;
+}, z.core.$strip>;
+/** Schema for an already-hydrated Money instance. */
+export declare const moneyInstanceSchema: z.ZodCustom<Money, Money>;
+export type BuiltInSerializedMoney = z.infer<typeof builtInSerializedMoneySchema>;
+export type CurrencyRegistry = Readonly<Record<string, CurrencyDefinition>>;
+/**
+ * Creates a bidirectional Zod codec for a currency registry.
+ *
+ * Decoding turns serialized minor units into Money. Encoding calls toJSON and
+ * rejects Money values whose currency is not represented by the registry with
+ * the same precision.
+ */
+export declare function createMoneyCodec<const TCurrencyRegistry extends CurrencyRegistry>(currencies: TCurrencyRegistry): z.ZodCodec<z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodCustom<Extract<keyof TCurrencyRegistry, string>, Extract<keyof TCurrencyRegistry, string>>;
+}, z.core.$strip>, z.ZodCustom<Money, Money>>;
+/** Codec for the currencies included with @storepass/money. */
+export declare const moneyCodec: z.ZodCodec<z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodCustom<"USD" | "USDH" | "EUR" | "GBP" | "JPY" | "CAD" | "AUD" | "NZD" | "CHF" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "BRL" | "MXN" | "ARS" | "CLP" | "INR" | "SGD" | "HKD" | "KRW" | "CNY" | "ZAR" | "AED" | "SAR" | "BTC", "USD" | "USDH" | "EUR" | "GBP" | "JPY" | "CAD" | "AUD" | "NZD" | "CHF" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "BRL" | "MXN" | "ARS" | "CLP" | "INR" | "SGD" | "HKD" | "KRW" | "CNY" | "ZAR" | "AED" | "SAR" | "BTC">;
+}, z.core.$strip>, z.ZodCustom<Money, Money>>;

package/dist/zod.mjs

@@ -0,0 +1,83 @@
+// src/zod.ts
+import {
+  Currency,
+  defineCurrency,
+  Money
+} from "@storepass/money";
+import { z } from "zod";
+var builtInCurrencyCodes = Object.keys(Currency);
+var currencyCodeSchema = z.enum(builtInCurrencyCodes);
+var currencyDefinitionSchema = z.object({
+  code: z.string().min(1),
+  decimalPlaces: z.number().int().nonnegative(),
+  numericCode: z.number().int().min(0).max(999).optional(),
+  iso4217: z.boolean().optional(),
+  displayCode: z.string().regex(/^[A-Z]{3}$/).optional()
+}).superRefine((currency, context) => {
+  try {
+    defineCurrency(currency.code, currency.decimalPlaces, {
+      numericCode: currency.numericCode,
+      iso4217: currency.iso4217,
+      displayCode: currency.displayCode
+    });
+  } catch (error) {
+    context.addIssue({
+      code: "custom",
+      message: error instanceof Error ? error.message : "Invalid currency definition"
+    });
+  }
+});
+var serializedMoneySchema = z.object({
+  amount: z.number().int(),
+  currency: z.string().min(1)
+});
+var moneySchema = serializedMoneySchema;
+var builtInSerializedMoneySchema = serializedMoneySchema.extend({
+  currency: currencyCodeSchema
+});
+var moneyInstanceSchema = z.custom((value) => value instanceof Money, { error: "Expected Money instance" });
+function assertCurrencyRegistry(currencies) {
+  for (const [code, currency] of Object.entries(currencies)) {
+    if (currency.code !== code) {
+      throw new Error(`Currency registry key "${code}" does not match definition code "${currency.code}"`);
+    }
+    currencyDefinitionSchema.parse(currency);
+  }
+}
+function createMoneyCodec(currencies) {
+  assertCurrencyRegistry(currencies);
+  const registeredCurrencyCodes = new Set(Object.keys(currencies));
+  const registeredCurrencyCodeSchema = z.custom((value) => typeof value === "string" && registeredCurrencyCodes.has(value), { error: "Unknown currency code" });
+  const registeredSerializedMoneySchema = serializedMoneySchema.extend({
+    currency: registeredCurrencyCodeSchema
+  });
+  return z.codec(registeredSerializedMoneySchema, moneyInstanceSchema, {
+    decode: ({ amount, currency }) => {
+      const registeredCurrency = currencies[currency];
+      if (registeredCurrency === undefined) {
+        throw new Error(`Unknown currency code: ${currency}`);
+      }
+      return Money.fromMinor(registeredCurrency, amount);
+    },
+    encode: (money) => {
+      const serialized = money.toJSON();
+      const currency = serialized.currency;
+      const registeredCurrency = currencies[currency];
+      if (registeredCurrency === undefined || registeredCurrency.decimalPlaces !== money.currency.decimalPlaces) {
+        throw new Error(`Money currency ${serialized.currency} is not registered with matching precision`);
+      }
+      return { amount: serialized.amount, currency };
+    }
+  });
+}
+var moneyCodec = createMoneyCodec(Currency);
+export {
+  serializedMoneySchema,
+  moneySchema,
+  moneyInstanceSchema,
+  moneyCodec,
+  currencyDefinitionSchema,
+  currencyCodeSchema,
+  createMoneyCodec,
+  builtInSerializedMoneySchema
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@storepass/money",
-	"version": "0.1.5",
+	"version": "0.2.1",
 	"description": "Money primitive library",
 	"main": "./dist/index.cjs",
 	"module": "./dist/index.mjs",
@@ -15,6 +15,16 @@
 				"types": "./dist/index.d.ts",
 				"default": "./dist/index.cjs"
 			}
+		},
+		"./zod": {
+			"import": {
+				"types": "./dist/zod.d.ts",
+				"default": "./dist/zod.mjs"
+			},
+			"require": {
+				"types": "./dist/zod.d.ts",
+				"default": "./dist/zod.cjs"
+			}
 		}
 	},
 	"files": [
@@ -22,8 +32,8 @@
 	],
 	"scripts": {
 		"build": "bun run build:esm && bun run build:cjs && bun run build:types",
-		"build:esm": "bun build ./src/index.ts --outfile ./dist/index.mjs --format esm --target node",
-		"build:cjs": "bun build ./src/index.ts --outfile ./dist/index.cjs --format cjs --target node",
+		"build:esm": "bun build ./src/index.ts --outfile ./dist/index.mjs --format esm --target node && bun build ./src/zod.ts --outfile ./dist/zod.mjs --format esm --target node --external '@storepass/money' --external zod",
+		"build:cjs": "bun build ./src/index.ts --outfile ./dist/index.cjs --format cjs --target node && bun build ./src/zod.ts --outfile ./dist/zod.cjs --format cjs --target node --external '@storepass/money' --external zod",
 		"build:types": "tsc -p tsconfig.build.json",
 		"test": "bun test",
 		"typecheck": "tsc --noEmit",
@@ -54,9 +64,18 @@
 		"registry": "https://registry.npmjs.org",
 		"access": "public"
 	},
+	"peerDependencies": {
+		"zod": "^4.1.0"
+	},
+	"peerDependenciesMeta": {
+		"zod": {
+			"optional": true
+		}
+	},
 	"devDependencies": {
 		"@biomejs/biome": "2.3.11",
 		"@types/bun": "latest",
-		"typescript": "^5.9.3"
+		"typescript": "^5.9.3",
+		"zod": "^4.4.3"
 	}
 }