@storepass/money 0.2.0 → 0.2.1

package/README.md

@@ -111,6 +111,40 @@ 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

package/dist/index.d.ts

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

package/dist/money.d.ts

@@ -4,6 +4,11 @@ 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;
@@ -64,10 +69,7 @@ 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`.
      *

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.2.0",
+	"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"
 	}
 }