@ducatjs/money 0.0.0 → 0.2.0

package/package.json

@@ -1,9 +1,284 @@
 {
   "name": "@ducatjs/money",
-  "version": "0.0.0",
-  "description": "Exact, fast, typed money for TypeScript (in development; not usable yet)",
-  "repository": { "type": "git", "url": "git+https://github.com/public/ducat.git" },
-  "homepage": "https://github.com/public/ducat",
+  "version": "0.2.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": {
+    "url": "https://github.com/public/ducat/issues"
+  },
   "license": "MIT",
-  "files": ["README.md"]
+  "author": "Alex Stapleton <alexs@prol.etari.at>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/public/ducat.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "data",
+    "assets/CREDITS.md",
+    "NOTICE",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./dist/plugins/*.js",
+    "./src/plugins/*.ts",
+    "./dist/testing/vitest.js",
+    "./dist/testing/jest.js",
+    "./src/testing/vitest.ts",
+    "./src/testing/jest.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./fn": {
+      "types": "./dist/fn.d.ts",
+      "default": "./dist/fn.js"
+    },
+    "./allocate": {
+      "types": "./dist/plugins/allocate.d.ts",
+      "default": "./dist/plugins/allocate.js"
+    },
+    "./tax": {
+      "types": "./dist/plugins/tax.d.ts",
+      "default": "./dist/plugins/tax.js"
+    },
+    "./convert": {
+      "types": "./dist/plugins/convert.d.ts",
+      "default": "./dist/plugins/convert.js"
+    },
+    "./convert/ecb": {
+      "types": "./dist/ecb.d.ts",
+      "default": "./dist/ecb.js"
+    },
+    "./convert/history": {
+      "types": "./dist/history.d.ts",
+      "default": "./dist/history.js"
+    },
+    "./convert/boc": {
+      "types": "./dist/boc.d.ts",
+      "default": "./dist/boc.js"
+    },
+    "./convert/fed": {
+      "types": "./dist/fed.d.ts",
+      "default": "./dist/fed.js"
+    },
+    "./historic": {
+      "types": "./dist/historic.d.ts",
+      "default": "./dist/historic.js"
+    },
+    "./convert/boe": {
+      "types": "./dist/boe.d.ts",
+      "default": "./dist/boe.js"
+    },
+    "./convert/hmrc": {
+      "types": "./dist/hmrc.d.ts",
+      "default": "./dist/hmrc.js"
+    },
+    "./convert/fetch": {
+      "types": "./dist/fetch.d.ts",
+      "default": "./dist/fetch.js"
+    },
+    "./exact": {
+      "types": "./dist/plugins/exact.d.ts",
+      "default": "./dist/plugins/exact.js"
+    },
+    "./policy": {
+      "types": "./dist/policy.d.ts",
+      "default": "./dist/policy.js"
+    },
+    "./cash": {
+      "types": "./dist/plugins/cash.d.ts",
+      "default": "./dist/plugins/cash.js"
+    },
+    "./format": {
+      "types": "./dist/plugins/format.d.ts",
+      "default": "./dist/plugins/format.js"
+    },
+    "./fixed": {
+      "types": "./dist/plugins/fixed.d.ts",
+      "default": "./dist/plugins/fixed.js"
+    },
+    "./parse": {
+      "types": "./dist/parse.d.ts",
+      "default": "./dist/parse.js"
+    },
+    "./stripe": {
+      "types": "./dist/plugins/stripe.d.ts",
+      "default": "./dist/plugins/stripe.js"
+    },
+    "./adyen": {
+      "types": "./dist/plugins/adyen.d.ts",
+      "default": "./dist/plugins/adyen.js"
+    },
+    "./checkout": {
+      "types": "./dist/plugins/checkout.d.ts",
+      "default": "./dist/plugins/checkout.js"
+    },
+    "./paypal": {
+      "types": "./dist/plugins/paypal.d.ts",
+      "default": "./dist/plugins/paypal.js"
+    },
+    "./braintree": {
+      "types": "./dist/plugins/braintree.d.ts",
+      "default": "./dist/plugins/braintree.js"
+    },
+    "./klarna": {
+      "types": "./dist/plugins/klarna.d.ts",
+      "default": "./dist/plugins/klarna.js"
+    },
+    "./stripe-fx": {
+      "types": "./dist/stripe-fx.d.ts",
+      "default": "./dist/stripe-fx.js"
+    },
+    "./adyen-fx": {
+      "types": "./dist/adyen-fx.d.ts",
+      "default": "./dist/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"
+    },
+    "./drizzle/mysql": {
+      "types": "./dist/drizzle/mysql.d.ts",
+      "default": "./dist/drizzle/mysql.js"
+    },
+    "./drizzle/sqlite": {
+      "types": "./dist/drizzle/sqlite.d.ts",
+      "default": "./dist/drizzle/sqlite.js"
+    },
+    "./zod": {
+      "types": "./dist/zod.d.ts",
+      "default": "./dist/zod.js"
+    },
+    "./valibot": {
+      "types": "./dist/valibot.d.ts",
+      "default": "./dist/valibot.js"
+    },
+    "./pg": {
+      "types": "./dist/pg.d.ts",
+      "default": "./dist/pg.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./testing/vitest": {
+      "types": "./dist/testing/vitest.d.ts",
+      "default": "./dist/testing/vitest.js"
+    },
+    "./testing/jest": {
+      "types": "./dist/testing/jest.d.ts",
+      "default": "./dist/testing/jest.js"
+    },
+    "./testing/arbitraries": {
+      "types": "./dist/testing/arbitraries.d.ts",
+      "default": "./dist/testing/arbitraries.js"
+    },
+    "./kysely": {
+      "types": "./dist/kysely.d.ts",
+      "default": "./dist/kysely.js"
+    },
+    "./all": {
+      "types": "./dist/plugins/all.d.ts",
+      "default": "./dist/plugins/all.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "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",
+    "test": "vitest run",
+    "test:deep": "DUCAT_DEEP=1 vitest run",
+    "compare": "pnpm --dir compare battery && pnpm --dir compare tables",
+    "compare:check": "pnpm --dir compare battery:check && pnpm --dir compare tables:check",
+    "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",
+    "fetch:dectest": "node scripts/fetch-dectest.mjs",
+    "vectors:check": "python3 scripts/gen-pydecimal-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",
+    "gen:kernel": "node scripts/gen-kernel.mjs",
+    "gen:kernel:check": "node scripts/gen-kernel.mjs --check",
+    "gen:fetch": "node scripts/gen-currencies.mjs --check --fetch",
+    "bench": "node scripts/bench-all.mjs",
+    "size": "node scripts/size.mjs",
+    "lint": "oxlint",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "check": "pnpm lint && pnpm fmt:check && pnpm typecheck && pnpm size && pnpm test",
+    "bench:vitest": "vitest bench --run"
+  },
+  "devDependencies": {
+    "@codspeed/vitest-plugin": "6.1.1",
+    "@playwright/test": "1.65.0",
+    "@prisma/client": "^6.19.3",
+    "@stryker-mutator/core": "10.1.1",
+    "@stryker-mutator/vitest-runner": "10.1.1",
+    "@types/better-sqlite3": "9.6.0",
+    "@types/big.js": "^7.0.0",
+    "@types/node": "^26.6.6",
+    "@types/pg": "8.23.1",
+    "better-sqlite3": "13.0.3",
+    "big.js": "^7.0.1",
+    "currency.js": "^2.0.4",
+    "decimal.js": "^10.6.0",
+    "dinero.js": "^2.0.2",
+    "drizzle-orm": "0.45.4",
+    "esbuild": "^0.28.2",
+    "fast-check": "^4.10.2",
+    "kysely": "0.29.8",
+    "mysql2": "3.24.6",
+    "oxfmt": "0.77.0",
+    "oxlint": "1.92.0",
+    "pg": "8.23.1",
+    "pg-cursor": "2.22.1",
+    "ts-money": "^0.4.8",
+    "typescript": "^5.9.3",
+    "valibot": "1.5.0",
+    "vitest": "^4.1.12",
+    "zod": "4.6.7"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.45.0 <1",
+    "fast-check": "^4.0.0",
+    "kysely": ">=0.28.0 <1",
+    "valibot": "^1.0.0",
+    "vitest": ">=3.2.0 <5",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    },
+    "fast-check": {
+      "optional": true
+    },
+    "kysely": {
+      "optional": true
+    },
+    "valibot": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@12.18.0"
 }

package/src/adyen-fx.ts

@@ -0,0 +1,175 @@
+// Adyen exchange rates as exact Rates, from settlement details report rows.
+import { exchangeRate, type Rate, type RateInfo } from './rate.js';
+
+// UTC offsets, in minutes, of the zone abbreviations that name one offset. Ambiguous ones are left
+// out on purpose: IST is India, Ireland or Israel; CST is US Central or China; BST is British or
+// Bangladesh.
+const ZONE_OFFSET_MINUTES: Readonly<Record<string, number>> = {
+  UTC: 0,
+  GMT: 0,
+  WET: 0,
+  WEST: 60,
+  CET: 60,
+  CEST: 120,
+  EET: 120,
+  EEST: 180,
+  MSK: 180,
+  SGT: 480,
+  HKT: 480,
+  JST: 540,
+  KST: 540,
+  AEST: 600,
+  AEDT: 660,
+  NZST: 720,
+  NZDT: 780,
+  EST: -300,
+  EDT: -240,
+  MST: -420,
+  MDT: -360,
+  PST: -480,
+  PDT: -420,
+};
+
+const LOCAL_TIME = /^(\d{4}-\d\d-\d\d)[ T](\d\d:\d\d(?::\d\d(?:\.\d+)?)?)$/;
+const NUMERIC_OFFSET = /^(?:UTC|GMT)?\s*([+-])(\d{1,2})(?::?(\d\d))?$/;
+
+// Real UTC offsets run from -12:00 to +14:00.
+const MAX_OFFSET_MINUTES = 14 * 60;
+
+/** The zone's offset in minutes, or undefined when it can't be read unambiguously. */
+function offsetMinutes(zone: string): number | undefined {
+  const named = ZONE_OFFSET_MINUTES[zone.toUpperCase()];
+  if (named !== undefined) {
+    return named;
+  }
+  const numeric = NUMERIC_OFFSET.exec(zone);
+  if (numeric === null) {
+    return undefined;
+  }
+  const hours = Number(numeric[2]);
+  const minutes = Number(numeric[3] ?? 0);
+  const total = hours * 60 + minutes;
+  if (minutes >= 60 || total > MAX_OFFSET_MINUTES) {
+    return undefined;
+  }
+  return numeric[1] === '-' ? -total : total;
+}
+
+// Building an Intl.DateTimeFormat is far slower than using one, and a report has thousands of rows
+// 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>();
+
+/** The cached wall-clock formatter for an IANA time zone. */
+function wallClockFormatter(timeZone: string): Intl.DateTimeFormat {
+  let formatter = formatters.get(timeZone);
+  if (formatter !== undefined) {
+    return formatter;
+  }
+
+  formatter = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    hourCycle: 'h23',
+    year: 'numeric',
+    month: 'numeric',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: 'numeric',
+    second: 'numeric',
+  });
+  if (formatters.size >= MAX_CACHED_FORMATTERS) {
+    formatters.clear();
+  }
+  formatters.set(timeZone, formatter);
+  return formatter;
+}
+
+/** The offset of an IANA time zone at a UTC instant, in minutes. */
+function ianaOffsetMinutes(timeZone: string, utcMs: number): number {
+  const parts = wallClockFormatter(timeZone).formatToParts(new Date(utcMs));
+  const field = (type: string): number => Number(parts.find((part) => part.type === type)!.value);
+  const wallClockAsUtc = Date.UTC(
+    field('year'),
+    field('month') - 1,
+    field('day'),
+    field('hour'),
+    field('minute'),
+    field('second'),
+  );
+  return Math.round((wallClockAsUtc - Math.floor(utcMs / 1000) * 1000) / 60_000);
+}
+
+/** The UTC instant of a wall-clock time in an IANA zone, summer time included. */
+function ianaToUtc(localAsUtcMs: number, timeZone: string): number {
+  // The offset at the guess can differ from the offset at the answer across a clock change, so
+  // look it up again at the first answer.
+  const firstGuess = localAsUtcMs - ianaOffsetMinutes(timeZone, localAsUtcMs) * 60_000;
+  return localAsUtcMs - ianaOffsetMinutes(timeZone, firstGuess) * 60_000;
+}
+
+/** Creation Date as a UTC instant when its zone is known; otherwise its local day. */
+function creationAsOf(
+  created: string,
+  label: string | undefined,
+  timeZone: string | undefined,
+): string | undefined {
+  const local = LOCAL_TIME.exec(created.trim());
+  if (local === null) {
+    return /^\d{4}-\d\d-\d\d/.test(created) ? created.slice(0, 10) : undefined;
+  }
+  const localAsUtcMs = Date.parse(`${local[1]}T${local[2]}Z`);
+  if (timeZone !== undefined) {
+    return new Date(ianaToUtc(localAsUtcMs, timeZone)).toISOString();
+  }
+  const offset = label === undefined ? undefined : offsetMinutes(label.trim());
+  if (offset === undefined) {
+    return local[1];
+  }
+  return new Date(localAsUtcMs - offset * 60_000).toISOString();
+}
+
+/** Options for adyenRate. */
+export interface AdyenRateOptions {
+  /**
+   * The account's IANA time zone ('Europe/Amsterdam'). When given, Creation Date is read in it,
+   * summer time included, and the TimeZone column is not used.
+   */
+  readonly timeZone?: string;
+}
+
+/** A settlement details report row, keyed by column name (as from a CSV parser with headers). */
+export type AdyenSettlementRow = Readonly<Record<string, string | undefined>>;
+
+/**
+ * The rate in a settlement details report row: "The exchange rate used for converting the gross
+ * amount into the net amount", Gross Currency → Net Currency (1 when they are the same). The
+ * decimal string is kept exactly. `asOf` comes from Creation Date, which Adyen gives in local time,
+ * with the zone in the TimeZone column. Pass `{ timeZone: 'Europe/Amsterdam' }` (the account's IANA
+ * zone) to read it correctly all year. Without it, an unambiguous abbreviation (CET, PST, ...) or
+ * offset (+01:00) is taken literally: Adyen's documentation doesn't say whether the column switches
+ * to CEST in summer, and if it doesn't, a literal CET is an hour off then. Any other label gives
+ * the local day, which can be a day off from UTC. `undefined` when the row has no rate. For
+ * externally settled payments Adyen lists its reference rate, not the acquirer's, so check those
+ * with impliedRate().
+ */
+export function adyenRate(row: AdyenSettlementRow, options?: AdyenRateOptions): Rate | undefined {
+  const gross = row['Gross Currency'];
+  const net = row['Net Currency'];
+  const rate = row['Exchange Rate']?.trim();
+  if (gross === undefined || gross === '' || net === undefined || net === '') {
+    return undefined;
+  }
+  if (rate === undefined || rate === '') {
+    return undefined;
+  }
+
+  const created = row['Creation Date'];
+  let info: RateInfo = { source: 'adyen' };
+  const asOf =
+    created === undefined ? undefined : creationAsOf(created, row['TimeZone'], options?.timeZone);
+  if (asOf !== undefined) {
+    info = { source: 'adyen', asOf };
+  }
+  return exchangeRate(gross, net, rate, info);
+}

package/src/adyen.ts

@@ -0,0 +1,46 @@
+/**
+ * Adyen's minor-unit view (https://docs.adyen.com/development-resources/currency-codes, encoded in
+ * data/adyen.json). Adyen's table is authoritative where it differs from ISO 4217: CLP 2 (ISO 0),
+ * ISK 2 (ISO 0), IDR 0 (ISO 2), CVE 0 (ISO 2). The Terminal API uses major units instead.
+ */
+import { ADYEN_EXPONENTS } from './generated/adyen.js';
+import { type CurrencyInput, type Money } from './money.js';
+import { fromProcessorAmount, toProcessorAmount } from './processor.js';
+import type { RoundingMode } from './rounding.js';
+
+export { ADYEN_EXPONENTS };
+
+function exponent(currency: string): number {
+  const found = ADYEN_EXPONENTS[currency];
+  // typeof, not !== undefined: the table is a plain object, so 'toString' or 'constructor' would
+  // otherwise find an inherited method instead of failing.
+  if (typeof found !== 'number') {
+    throw new RangeError(`${currency} is not in Adyen's currency table`);
+  }
+  return found;
+}
+
+/** Whether Adyen lists the currency (its table, not ISO 4217). */
+export const isAdyenCurrency = (currency: string): boolean =>
+  typeof ADYEN_EXPONENTS[currency] === 'number';
+/** The exponent Adyen's API uses for a currency (CLP 2, ISK 2, IDR 0, CVE 0 differ from ISO). */
+export const adyenExponent = exponent;
+
+/** Adyen `amount` object: toAdyen(money('15000', 'IDR')) -> { value: 15000, currency: 'IDR' }. */
+export function toAdyen(
+  money: Money,
+  rounding: RoundingMode = 'unnecessary',
+): { value: number; currency: string } {
+  return {
+    value: toProcessorAmount('Adyen', money, exponent(money.currency), 1, rounding),
+    currency: money.currency,
+  };
+}
+
+/** Reads an Adyen `amount` object: fromAdyen({ value: 15000, currency: 'IDR' }) is 15000 IDR. */
+export function fromAdyen<C extends CurrencyInput>(amount: {
+  value: number | bigint;
+  currency: C;
+}): Money<C> {
+  return fromProcessorAmount('Adyen', amount.value, amount.currency, exponent(amount.currency));
+}