@ducatjs/money 0.2.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ducatjs/money",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Exact, fast, typed Money for TypeScript: integer minor units, bigint fallback, Stripe/Adyen views, allocation, cash rounding, Prisma helpers.",
   "homepage": "https://github.com/public/ducat#readme",
   "bugs": {
@@ -22,13 +22,195 @@
   ],
   "type": "module",
   "sideEffects": [
+    "./dist/index.js",
+    "./src/index.ts",
     "./dist/plugins/*.js",
     "./src/plugins/*.ts",
     "./dist/testing/vitest.js",
     "./dist/testing/jest.js",
     "./src/testing/vitest.ts",
-    "./src/testing/jest.ts"
+    "./src/testing/jest.ts",
+    "./dist/entries/*.js",
+    "./src/entries/*.ts",
+    "./dist/generated/iso/*.js",
+    "./src/generated/iso/*.ts"
   ],
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "fn": [
+        "./dist/fn.d.ts"
+      ],
+      "iso": [
+        "./dist/plugins/iso.d.ts"
+      ],
+      "iso/*": [
+        "./dist/generated/iso/*.d.ts"
+      ],
+      "allocate": [
+        "./dist/plugins/allocate.d.ts"
+      ],
+      "tax": [
+        "./dist/plugins/tax.d.ts"
+      ],
+      "math": [
+        "./dist/plugins/math.d.ts"
+      ],
+      "convert": [
+        "./dist/plugins/convert.d.ts"
+      ],
+      "convert/ecb": [
+        "./dist/entries/ecb.d.ts"
+      ],
+      "convert/history": [
+        "./dist/entries/history.d.ts"
+      ],
+      "convert/boc": [
+        "./dist/entries/boc.d.ts"
+      ],
+      "convert/fed": [
+        "./dist/entries/fed.d.ts"
+      ],
+      "words": [
+        "./dist/words.d.ts"
+      ],
+      "words/de": [
+        "./dist/words/de.d.ts"
+      ],
+      "words/en": [
+        "./dist/words/en.d.ts"
+      ],
+      "words/es": [
+        "./dist/words/es.d.ts"
+      ],
+      "words/fr": [
+        "./dist/words/fr.d.ts"
+      ],
+      "words/it": [
+        "./dist/words/it.d.ts"
+      ],
+      "words/nl": [
+        "./dist/words/nl.d.ts"
+      ],
+      "words/pt": [
+        "./dist/words/pt.d.ts"
+      ],
+      "wire": [
+        "./dist/entries/wire.d.ts"
+      ],
+      "crypto": [
+        "./dist/entries/crypto.d.ts"
+      ],
+      "currencies": [
+        "./dist/entries/currencies.d.ts"
+      ],
+      "territories": [
+        "./dist/territories.d.ts"
+      ],
+      "historic": [
+        "./dist/entries/historic.d.ts"
+      ],
+      "finance": [
+        "./dist/entries/finance.d.ts"
+      ],
+      "pricing": [
+        "./dist/entries/pricing.d.ts"
+      ],
+      "convert/boe": [
+        "./dist/entries/boe.d.ts"
+      ],
+      "convert/hmrc": [
+        "./dist/entries/hmrc.d.ts"
+      ],
+      "convert/fetch": [
+        "./dist/entries/fetch.d.ts"
+      ],
+      "exact": [
+        "./dist/plugins/exact.d.ts"
+      ],
+      "policy": [
+        "./dist/entries/policy.d.ts"
+      ],
+      "cash": [
+        "./dist/plugins/cash.d.ts"
+      ],
+      "format": [
+        "./dist/plugins/format.d.ts"
+      ],
+      "fixed": [
+        "./dist/fixed.d.ts"
+      ],
+      "fixed/money": [
+        "./dist/plugins/fixed-money.d.ts"
+      ],
+      "parse": [
+        "./dist/entries/parse.d.ts"
+      ],
+      "stripe": [
+        "./dist/plugins/stripe.d.ts"
+      ],
+      "adyen": [
+        "./dist/plugins/adyen.d.ts"
+      ],
+      "checkout": [
+        "./dist/plugins/checkout.d.ts"
+      ],
+      "paypal": [
+        "./dist/plugins/paypal.d.ts"
+      ],
+      "braintree": [
+        "./dist/plugins/braintree.d.ts"
+      ],
+      "klarna": [
+        "./dist/plugins/klarna.d.ts"
+      ],
+      "stripe-fx": [
+        "./dist/entries/stripe-fx.d.ts"
+      ],
+      "adyen-fx": [
+        "./dist/entries/adyen-fx.d.ts"
+      ],
+      "prisma": [
+        "./dist/plugins/prisma.d.ts"
+      ],
+      "drizzle/pg": [
+        "./dist/entries/drizzle-pg.d.ts"
+      ],
+      "drizzle/mysql": [
+        "./dist/entries/drizzle-mysql.d.ts"
+      ],
+      "drizzle/sqlite": [
+        "./dist/entries/drizzle-sqlite.d.ts"
+      ],
+      "zod": [
+        "./dist/entries/zod.d.ts"
+      ],
+      "valibot": [
+        "./dist/entries/valibot.d.ts"
+      ],
+      "pg": [
+        "./dist/entries/pg.d.ts"
+      ],
+      "testing": [
+        "./dist/entries/testing-index.d.ts"
+      ],
+      "testing/vitest": [
+        "./dist/entries/testing-vitest.d.ts"
+      ],
+      "testing/jest": [
+        "./dist/entries/testing-jest.d.ts"
+      ],
+      "testing/arbitraries": [
+        "./dist/entries/testing-arbitraries.d.ts"
+      ],
+      "kysely": [
+        "./dist/entries/kysely.d.ts"
+      ],
+      "all": [
+        "./dist/plugins/all.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -38,6 +220,14 @@
       "types": "./dist/fn.d.ts",
       "default": "./dist/fn.js"
     },
+    "./iso": {
+      "types": "./dist/plugins/iso.d.ts",
+      "default": "./dist/plugins/iso.js"
+    },
+    "./iso/*": {
+      "types": "./dist/generated/iso/*.d.ts",
+      "default": "./dist/generated/iso/*.js"
+    },
     "./allocate": {
       "types": "./dist/plugins/allocate.d.ts",
       "default": "./dist/plugins/allocate.js"
@@ -46,49 +236,109 @@
       "types": "./dist/plugins/tax.d.ts",
       "default": "./dist/plugins/tax.js"
     },
+    "./math": {
+      "types": "./dist/plugins/math.d.ts",
+      "default": "./dist/plugins/math.js"
+    },
     "./convert": {
       "types": "./dist/plugins/convert.d.ts",
       "default": "./dist/plugins/convert.js"
     },
     "./convert/ecb": {
-      "types": "./dist/ecb.d.ts",
-      "default": "./dist/ecb.js"
+      "types": "./dist/entries/ecb.d.ts",
+      "default": "./dist/entries/ecb.js"
     },
     "./convert/history": {
-      "types": "./dist/history.d.ts",
-      "default": "./dist/history.js"
+      "types": "./dist/entries/history.d.ts",
+      "default": "./dist/entries/history.js"
     },
     "./convert/boc": {
-      "types": "./dist/boc.d.ts",
-      "default": "./dist/boc.js"
+      "types": "./dist/entries/boc.d.ts",
+      "default": "./dist/entries/boc.js"
     },
     "./convert/fed": {
-      "types": "./dist/fed.d.ts",
-      "default": "./dist/fed.js"
+      "types": "./dist/entries/fed.d.ts",
+      "default": "./dist/entries/fed.js"
+    },
+    "./words": {
+      "types": "./dist/words.d.ts",
+      "default": "./dist/words.js"
+    },
+    "./words/de": {
+      "types": "./dist/words/de.d.ts",
+      "default": "./dist/words/de.js"
+    },
+    "./words/en": {
+      "types": "./dist/words/en.d.ts",
+      "default": "./dist/words/en.js"
+    },
+    "./words/es": {
+      "types": "./dist/words/es.d.ts",
+      "default": "./dist/words/es.js"
+    },
+    "./words/fr": {
+      "types": "./dist/words/fr.d.ts",
+      "default": "./dist/words/fr.js"
+    },
+    "./words/it": {
+      "types": "./dist/words/it.d.ts",
+      "default": "./dist/words/it.js"
+    },
+    "./words/nl": {
+      "types": "./dist/words/nl.d.ts",
+      "default": "./dist/words/nl.js"
+    },
+    "./words/pt": {
+      "types": "./dist/words/pt.d.ts",
+      "default": "./dist/words/pt.js"
+    },
+    "./wire": {
+      "types": "./dist/entries/wire.d.ts",
+      "default": "./dist/entries/wire.js"
+    },
+    "./crypto": {
+      "types": "./dist/entries/crypto.d.ts",
+      "default": "./dist/entries/crypto.js"
+    },
+    "./currencies": {
+      "types": "./dist/entries/currencies.d.ts",
+      "default": "./dist/entries/currencies.js"
+    },
+    "./territories": {
+      "types": "./dist/territories.d.ts",
+      "default": "./dist/territories.js"
     },
     "./historic": {
-      "types": "./dist/historic.d.ts",
-      "default": "./dist/historic.js"
+      "types": "./dist/entries/historic.d.ts",
+      "default": "./dist/entries/historic.js"
+    },
+    "./finance": {
+      "types": "./dist/entries/finance.d.ts",
+      "default": "./dist/entries/finance.js"
+    },
+    "./pricing": {
+      "types": "./dist/entries/pricing.d.ts",
+      "default": "./dist/entries/pricing.js"
     },
     "./convert/boe": {
-      "types": "./dist/boe.d.ts",
-      "default": "./dist/boe.js"
+      "types": "./dist/entries/boe.d.ts",
+      "default": "./dist/entries/boe.js"
     },
     "./convert/hmrc": {
-      "types": "./dist/hmrc.d.ts",
-      "default": "./dist/hmrc.js"
+      "types": "./dist/entries/hmrc.d.ts",
+      "default": "./dist/entries/hmrc.js"
     },
     "./convert/fetch": {
-      "types": "./dist/fetch.d.ts",
-      "default": "./dist/fetch.js"
+      "types": "./dist/entries/fetch.d.ts",
+      "default": "./dist/entries/fetch.js"
     },
     "./exact": {
       "types": "./dist/plugins/exact.d.ts",
       "default": "./dist/plugins/exact.js"
     },
     "./policy": {
-      "types": "./dist/policy.d.ts",
-      "default": "./dist/policy.js"
+      "types": "./dist/entries/policy.d.ts",
+      "default": "./dist/entries/policy.js"
     },
     "./cash": {
       "types": "./dist/plugins/cash.d.ts",
@@ -99,12 +349,16 @@
       "default": "./dist/plugins/format.js"
     },
     "./fixed": {
-      "types": "./dist/plugins/fixed.d.ts",
-      "default": "./dist/plugins/fixed.js"
+      "types": "./dist/fixed.d.ts",
+      "default": "./dist/fixed.js"
+    },
+    "./fixed/money": {
+      "types": "./dist/plugins/fixed-money.d.ts",
+      "default": "./dist/plugins/fixed-money.js"
     },
     "./parse": {
-      "types": "./dist/parse.d.ts",
-      "default": "./dist/parse.js"
+      "types": "./dist/entries/parse.d.ts",
+      "default": "./dist/entries/parse.js"
     },
     "./stripe": {
       "types": "./dist/plugins/stripe.d.ts",
@@ -131,60 +385,60 @@
       "default": "./dist/plugins/klarna.js"
     },
     "./stripe-fx": {
-      "types": "./dist/stripe-fx.d.ts",
-      "default": "./dist/stripe-fx.js"
+      "types": "./dist/entries/stripe-fx.d.ts",
+      "default": "./dist/entries/stripe-fx.js"
     },
     "./adyen-fx": {
-      "types": "./dist/adyen-fx.d.ts",
-      "default": "./dist/adyen-fx.js"
+      "types": "./dist/entries/adyen-fx.d.ts",
+      "default": "./dist/entries/adyen-fx.js"
     },
     "./prisma": {
       "types": "./dist/plugins/prisma.d.ts",
       "default": "./dist/plugins/prisma.js"
     },
     "./drizzle/pg": {
-      "types": "./dist/drizzle/pg.d.ts",
-      "default": "./dist/drizzle/pg.js"
+      "types": "./dist/entries/drizzle-pg.d.ts",
+      "default": "./dist/entries/drizzle-pg.js"
     },
     "./drizzle/mysql": {
-      "types": "./dist/drizzle/mysql.d.ts",
-      "default": "./dist/drizzle/mysql.js"
+      "types": "./dist/entries/drizzle-mysql.d.ts",
+      "default": "./dist/entries/drizzle-mysql.js"
     },
     "./drizzle/sqlite": {
-      "types": "./dist/drizzle/sqlite.d.ts",
-      "default": "./dist/drizzle/sqlite.js"
+      "types": "./dist/entries/drizzle-sqlite.d.ts",
+      "default": "./dist/entries/drizzle-sqlite.js"
     },
     "./zod": {
-      "types": "./dist/zod.d.ts",
-      "default": "./dist/zod.js"
+      "types": "./dist/entries/zod.d.ts",
+      "default": "./dist/entries/zod.js"
     },
     "./valibot": {
-      "types": "./dist/valibot.d.ts",
-      "default": "./dist/valibot.js"
+      "types": "./dist/entries/valibot.d.ts",
+      "default": "./dist/entries/valibot.js"
     },
     "./pg": {
-      "types": "./dist/pg.d.ts",
-      "default": "./dist/pg.js"
+      "types": "./dist/entries/pg.d.ts",
+      "default": "./dist/entries/pg.js"
     },
     "./testing": {
-      "types": "./dist/testing/index.d.ts",
-      "default": "./dist/testing/index.js"
+      "types": "./dist/entries/testing-index.d.ts",
+      "default": "./dist/entries/testing-index.js"
     },
     "./testing/vitest": {
-      "types": "./dist/testing/vitest.d.ts",
-      "default": "./dist/testing/vitest.js"
+      "types": "./dist/entries/testing-vitest.d.ts",
+      "default": "./dist/entries/testing-vitest.js"
     },
     "./testing/jest": {
-      "types": "./dist/testing/jest.d.ts",
-      "default": "./dist/testing/jest.js"
+      "types": "./dist/entries/testing-jest.d.ts",
+      "default": "./dist/entries/testing-jest.js"
     },
     "./testing/arbitraries": {
-      "types": "./dist/testing/arbitraries.d.ts",
-      "default": "./dist/testing/arbitraries.js"
+      "types": "./dist/entries/testing-arbitraries.d.ts",
+      "default": "./dist/entries/testing-arbitraries.js"
     },
     "./kysely": {
-      "types": "./dist/kysely.d.ts",
-      "default": "./dist/kysely.js"
+      "types": "./dist/entries/kysely.d.ts",
+      "default": "./dist/entries/kysely.js"
     },
     "./all": {
       "types": "./dist/plugins/all.d.ts",
@@ -193,8 +447,9 @@
     "./package.json": "./package.json"
   },
   "scripts": {
+    "check:consumers": "node scripts/check-consumer-types.mjs",
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.drizzle.json && tsc -p tsconfig.kysely.json && tsc -p tsconfig.peers.json",
-    "typecheck": "tsc -p tsconfig.test.json && tsc -p tsconfig.test-drizzle.json && tsc -p test/core-only/tsconfig.json && tsc -p test/browser/tsconfig.json && tsc -p test/jest-types/tsconfig.json",
+    "typecheck": "tsc -p test/fn-only/tsconfig.json && tsc -p tsconfig.test.json && tsc -p tsconfig.test-drizzle.json && tsc -p test/core-only/tsconfig.json && tsc -p test/browser/tsconfig.json && tsc -p test/jest-types/tsconfig.json",
     "test": "vitest run",
     "test:deep": "DUCAT_DEEP=1 vitest run",
     "compare": "pnpm --dir compare battery && pnpm --dir compare tables",
@@ -202,9 +457,9 @@
     "tables": "pnpm --dir compare tables",
     "test:db": "vitest run --config vitest.db.config.ts",
     "test:browser": "playwright test",
-    "test:mutation": "DUCAT_MAX_RUNS=50 stryker run",
+    "test:mutation": "DUCAT_MAX_RUNS=50 DUCAT_MUTATION=1 stryker run",
     "fetch:dectest": "node scripts/fetch-dectest.mjs",
-    "vectors:check": "python3 scripts/gen-pydecimal-vectors.py --check",
+    "vectors:check": "python3 scripts/gen-pydecimal-vectors.py --check && python3 scripts/gen-finance-vectors.py --check",
     "test:runtimes": "node scripts/smoke-runtimes.mjs",
     "gen": "node scripts/gen-currencies.mjs",
     "gen:check": "node scripts/gen-currencies.mjs --check && node scripts/gen-kernel.mjs --verify",
@@ -213,7 +468,8 @@
     "gen:fetch": "node scripts/gen-currencies.mjs --check --fetch",
     "bench": "node scripts/bench-all.mjs",
     "size": "node scripts/size.mjs",
-    "lint": "oxlint",
+    "lint": "oxlint --deny-warnings",
+    "prepare": "git rev-parse --git-dir >/dev/null 2>&1 && git config core.hooksPath .githooks || true",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "check": "pnpm lint && pnpm fmt:check && pnpm typecheck && pnpm size && pnpm test",
@@ -223,6 +479,7 @@
     "@codspeed/vitest-plugin": "6.1.1",
     "@playwright/test": "1.65.0",
     "@prisma/client": "^6.19.3",
+    "@rollup/plugin-node-resolve": "16.0.3",
     "@stryker-mutator/core": "10.1.1",
     "@stryker-mutator/vitest-runner": "10.1.1",
     "@types/better-sqlite3": "9.6.0",
@@ -243,6 +500,7 @@
     "oxlint": "1.92.0",
     "pg": "8.23.1",
     "pg-cursor": "2.22.1",
+    "rollup": "4.67.5",
     "ts-money": "^0.4.8",
     "typescript": "^5.9.3",
     "valibot": "1.5.0",

package/src/adyen-fx.ts

@@ -59,7 +59,7 @@ function offsetMinutes(zone: string): number | undefined {
 // in one zone, so keep one formatter per zone. The bound stops a stream of distinct zone names
 // (case variants are accepted by Intl) from growing the cache without limit.
 const MAX_CACHED_FORMATTERS = 32;
-const formatters = new Map<string, Intl.DateTimeFormat>();
+const formatters = /* @__PURE__ */ new Map<string, Intl.DateTimeFormat>();
 
 /** The cached wall-clock formatter for an IANA time zone. */
 function wallClockFormatter(timeZone: string): Intl.DateTimeFormat {

package/src/allocate.ts

@@ -1,4 +1,4 @@
-import { parseDecimal, pow10n, normalizeMinor } from './decimal.js';
+import { faithfulDecimal, parseDecimal, pow10n, normalizeMinor } from './decimal.js';
 import {
   CurrencyMismatchError,
   compare,
@@ -45,8 +45,9 @@ function weightsScaled(ws: readonly Weight[]): { ws: bigint[]; scale: number } {
     if (typeof weight === 'number' && Number.isSafeInteger(weight)) {
       return { digits: BigInt(weight), scale: 0 };
     }
-    const item = parseDecimal(String(weight));
-    return item;
+    return parseDecimal(
+      typeof weight === 'number' ? faithfulDecimal(weight, 'pass weights as strings') : weight,
+    );
   });
   for (const item of parsed) {
     if (item.digits < 0n) {

package/src/cash.ts

@@ -10,6 +10,7 @@ import {
 import { roundingPolicy } from './policy.js';
 import { divideAndRound, divideAndRoundBigint, type RoundingMode } from './rounding.js';
 import { currencyExponent } from './currency.js';
+import { formatScaled } from './decimal.js';
 
 /**
  * Rounds to a multiple of `increment` (same currency): roundToIncrement(CHF 10.03, CHF 0.05) = CHF
@@ -180,4 +181,29 @@ export function currencyDigits(currency: string, options?: CurrencyDigitsOptions
   return exponent;
 }
 
+/** Options for `cashUnit`. */
+export interface CashUnitOptions {
+  /** The country (ISO 3166 alpha-2), which EUR needs. */
+  readonly country?: string;
+  /** Whether to use rules backed only by secondary sources (default true). */
+  readonly includeUnverified?: boolean;
+}
+
+/**
+ * The smallest cash step, in major units, as an exact decimal string with the currency's decimals:
+ * the smallest coin in use where the cash rules know one. `cashUnit('CHF')` is '0.05',
+ * `cashUnit('DKK')` is '0.50', `cashUnit('SEK')` is '1.00' and `cashUnit('EUR', { country: 'NL' })`
+ * is '0.05'. A currency without a cash rule (or EUR without a country that has one) gives its minor
+ * unit, '0.01' for GBP. Throws for unknown codes, like `currencyExponent`.
+ */
+export function cashUnit(currency: string, options?: CashUnitOptions): string {
+  const exponent = currencyExponent(currency);
+  const rule = cashRule(currency, options?.country);
+  if (!rule || (options?.includeUnverified === false && !rule.verified)) {
+    return formatScaled(1, exponent);
+  }
+  // with the currency's decimals, as amounts are written everywhere else: SEK's step is '1.00'
+  return formatScaled(rule.increment, exponent);
+}
+
 export { CASH_RULES, type CashRule };

package/src/convert.ts

@@ -1,8 +1,7 @@
 // `ducat/convert` free functions: exact exchange rates and conversion that rounds once.
-import { currencyExponent } from './currency.js';
 import { exact, type Rounded } from './exact.js';
 import { ratio, type Factor } from './decimal.js';
-import { make, type CurrencyInput, type Money, type RoundingInput } from './money.js';
+import { make, resolveScale, type CurrencyInput, type Money, type RoundingInput } from './money.js';
 import { rateOf, type RateProvider } from './provider.js';
 import {
   convertWithPolicy,
@@ -140,7 +139,7 @@ export function convert(
   if (typeof rounding === 'function') {
     return convertWithPolicy(money, to, rate, rounding, maybeOptions);
   }
-  const scale = maybeOptions?.scale ?? currencyExponent(to);
+  const scale = resolveScale(to, maybeOptions?.scale);
   const minor = multiplyByRatioAtScale(money.minor, rate, scale - money.scale, rounding);
   return make(to, minor, scale);
 }