@ducatjs/money 0.1.0 → 0.2.0

package/src/adyen-fx.ts

@@ -55,9 +55,20 @@ function offsetMinutes(zone: string): number | undefined {
   return numeric[1] === '-' ? -total : total;
 }
 
-/** The offset of an IANA time zone at a UTC instant, in minutes. */
-function ianaOffsetMinutes(timeZone: string, utcMs: number): number {
-  const parts = new Intl.DateTimeFormat('en-US', {
+// 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',
@@ -66,7 +77,17 @@ function ianaOffsetMinutes(timeZone: string, utcMs: number): number {
     hour: 'numeric',
     minute: 'numeric',
     second: 'numeric',
-  }).formatToParts(new Date(utcMs));
+  });
+  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'),

package/src/boc.ts

@@ -0,0 +1,136 @@
+// `@ducatjs/money/convert/boc`: an offline parser for the Bank of Canada's daily exchange rates
+// (the Valet API). No I/O: fetch the JSON yourself, or use fetchBankOfCanada from
+// @ducatjs/money/convert/fetch. Rates are kept exactly as published.
+import { quotedTable } from './history.js';
+import type { RateTable } from './provider.js';
+import { addDayRate, isCalendarDay, newestFirst, readRateCell } from './rate-text.js';
+
+const SERIES = /^FX([A-Z]{3})CAD$/;
+const ZERO = /^0+(?:\.0+)?$/;
+
+// The Bank publishes "once each business day by 16:30 (ET)". One formatter for the zone, built on
+// first use, gives the Toronto offset on any day, summer time included.
+let torontoFormatter: Intl.DateTimeFormat | undefined;
+
+/** 16:30 in Toronto on `day`, as a UTC instant. */
+function publishedBy(day: string): string {
+  torontoFormatter ??= new Intl.DateTimeFormat('en-US', {
+    timeZone: 'America/Toronto',
+    timeZoneName: 'shortOffset',
+  });
+  // Noon UTC is 07:00 or 08:00 in Toronto, after any clock change that day (they happen at 02:00).
+  const noon = new Date(`${day}T12:00:00Z`);
+  const zone = torontoFormatter.formatToParts(noon).find((part) => part.type === 'timeZoneName');
+  const offset = /^GMT([+-]\d+)$/.exec(zone?.value ?? '');
+  if (offset === null) {
+    throw new RangeError(`Can't tell Toronto's UTC offset on ${day} (${zone?.value})`);
+  }
+  const utcMs = Date.parse(`${day}T16:30:00Z`) - Number(offset[1]) * 3_600_000;
+  return new Date(utcMs).toISOString();
+}
+
+function notValet(why: string): never {
+  throw new SyntaxError(`Not a Bank of Canada Valet daily FX file: ${why}`);
+}
+
+/** Options for parseBankOfCanadaJson. */
+export interface BankOfCanadaOptions {
+  /**
+   * When each day's rates were published, or false for none. Default: 16:30 Toronto time that day,
+   * when the Bank says it publishes them.
+   */
+  readonly availableAt?: false | ((day: string) => string | Date);
+}
+
+/**
+ * Parses the Bank of Canada's daily exchange rates from the Valet API's JSON (the
+ * `FX_RATES_DAILY` group, or single `FX…CAD` series) into one CAD-based table per business day,
+ * newest first. The Bank quotes CAD per unit of each currency (FXUSDCAD 1.3748), so each table
+ * holds the exact inverse, CAD → currency, and keeps the published quote: `rate.inverse()` prints
+ * '1.3748' again. Rates have `source: 'BoC'`, `type: 'average'` (an average of a day's quotes, not
+ * a market rate) and `availableAt` 16:30 Toronto time, when the Bank says it publishes them (a late
+ * rate can come later; pass `availableAt` to change it). Valet leaves a series out of a day
+ * without a value, so a series listed in `seriesDetail` but absent on a day, an empty value or a
+ * null one, is in that day's `missing`. Anything but daily `FX…CAD` series (monthly or annual
+ * groups, other data) throws SyntaxError, as do two different values for one series on one day.
+ *
+ * Precision: the Bank quotes four decimals, up to six for small rates, so a small rate has only
+ * about four significant digits (JPY 0.008760, KRW 0.000929, and IDR 0.000082 with two). Its
+ * inverse is exact, but only as precise as that. For such currencies, prefer a source that quotes
+ * them the other way round.
+ *
+ *     const tables = parseBankOfCanadaJson(await (await fetch(url)).text());
+ *     tables[0].rate('CAD', 'USD')?.inverse().toString(); // '1.3748'
+ */
+export function parseBankOfCanadaJson(json: string, options?: BankOfCanadaOptions): RateTable[] {
+  const parsed = JSON.parse(json) as {
+    observations?: unknown;
+    seriesDetail?: Record<string, unknown>;
+  } | null;
+  const observations = parsed?.observations;
+  if (!Array.isArray(observations)) {
+    notValet('no observations');
+  }
+
+  // The series the file says it has; each must be a daily FX…CAD series.
+  const expected = new Set<string>();
+  for (const series of Object.keys(parsed?.seriesDetail ?? {})) {
+    if (!SERIES.test(series)) {
+      notValet(`series ${series} isn't a daily FX…CAD rate`);
+    }
+    expected.add(series);
+  }
+
+  const days = new Map<string, Record<string, string | null>>();
+  for (const observation of observations as readonly Record<string, unknown>[]) {
+    const day = observation?.['d'];
+    if (typeof day !== 'string' || !isCalendarDay(day)) {
+      notValet(`bad date ${JSON.stringify(day)}`);
+    }
+
+    for (const [series, cell] of Object.entries(observation)) {
+      if (series === 'd') {
+        continue;
+      }
+      const currency = SERIES.exec(series)?.[1];
+      if (currency === undefined) {
+        notValet(`series ${series} isn't a daily FX…CAD rate`);
+      }
+      const where = `${series} on ${day}`;
+      const value = (cell as { v?: unknown } | null)?.v;
+      if (value !== null && typeof value !== 'string') {
+        throw new SyntaxError(`Malformed Valet value for ${where}`);
+      }
+      const rate = value === null ? null : readRateCell(value, where);
+      if (rate !== null && ZERO.test(rate)) {
+        throw new SyntaxError(`A zero rate for ${where}`);
+      }
+      addDayRate(days, day, currency, rate);
+    }
+    // Valet leaves out a series without a value that day.
+    for (const series of expected) {
+      const currency = SERIES.exec(series)![1]!;
+      if (days.get(day)?.[currency] === undefined) {
+        addDayRate(days, day, currency, null);
+      }
+    }
+  }
+
+  const tables: RateTable[] = [];
+  for (const [day, rates] of days) {
+    if (!Object.values(rates).some((rate) => rate !== null)) {
+      continue;
+    }
+    let availableAt: string | Date | undefined;
+    if (options?.availableAt === undefined) {
+      availableAt = publishedBy(day);
+    } else if (options.availableAt !== false) {
+      availableAt = options.availableAt(day);
+    }
+    const info = { base: 'CAD', inverted: true, source: 'BoC', type: 'average', asOf: day };
+    tables.push(
+      quotedTable({ ...info, ...(availableAt === undefined ? {} : { availableAt }), rates }),
+    );
+  }
+  return newestFirst(tables);
+}

package/src/boe.ts

@@ -0,0 +1,131 @@
+// `@ducatjs/money/convert/boe`: an offline parser for the Bank of England's daily spot exchange
+// rates against sterling. Parser only: see parseBankOfEnglandCsv on licensing.
+import { quotedTable } from './history.js';
+import type { RateTable } from './provider.js';
+import { addDayRate, csvRows, isCalendarDay, newestFirst, readRateCell } from './rate-text.js';
+
+// The Bank's daily spot series against sterling, by code (currency units per £1).
+const BOE_SERIES: Readonly<Record<string, string>> = {
+  XUDLADS: 'AUD',
+  XUDLZOS3: 'BGN',
+  XUDLCDS: 'CAD',
+  XUDLBK89: 'CNY',
+  XUDLBK25: 'CZK',
+  XUDLDKS: 'DKK',
+  XUDLERS: 'EUR',
+  XUDLHDS: 'HKD',
+  XUDLBK33: 'HUF',
+  XUDLBK97: 'INR',
+  XUDLBK78: 'ILS',
+  XUDLJYS: 'JPY',
+  XUDLBK83: 'MYR',
+  XUDLNDS: 'NZD',
+  XUDLNKS: 'NOK',
+  XUDLBK47: 'PLN',
+  XUDLZOS4: 'RON',
+  XUDLSRS: 'SAR',
+  XUDLSGS: 'SGD',
+  XUDLZRS: 'ZAR',
+  XUDLBK93: 'KRW',
+  XUDLSKS: 'SEK',
+  XUDLSFS: 'CHF',
+  XUDLTWS: 'TWD',
+  XUDLBK87: 'THB',
+  XUDLBK95: 'TRY',
+  XUDLUSS: 'USD',
+};
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+function notBoe(why: string): never {
+  throw new SyntaxError(`Not a Bank of England spot rates CSV file: ${why}`);
+}
+
+/** '22 Dec 2025' as an ISO date, or SyntaxError. */
+function isoDate(text: string): string {
+  const match = /^(\d\d) ([A-Z][a-z]{2}) (\d{4})$/.exec(text.trim());
+  const month = match === null ? 0 : MONTHS.indexOf(match[2]!) + 1;
+  const day = match === null ? '' : `${match[3]}-${String(month).padStart(2, '0')}-${match[1]}`;
+  if (month === 0 || !isCalendarDay(day)) {
+    notBoe(`bad date ${JSON.stringify(text)}`);
+  }
+  return day;
+}
+
+/** Options for parseBankOfEnglandCsv. */
+export interface BankOfEnglandOptions {
+  /**
+   * The decimals the Bank publishes, rebuilt because its CSV strips trailing zeros ('1.35' for
+   * 1.3500). Default 4, as its database shows every spot series.
+   */
+  readonly decimals?: number;
+}
+
+/**
+ * Parses the Bank of England database's CSV of daily spot rates against sterling (series XUDL…,
+ * downloaded with codes as column titles: `DATE,XUDLUSS,XUDLERS,…` and dates like `22 Dec 2025`)
+ * into one GBP-based table per day, newest first. Rates are currency units per £1, with `source:
+ * 'BoE'` and `type: 'spot'`. The CSV strips trailing zeros, so they are rebuilt to `decimals`
+ * (default 4). Holidays have no row; an empty cell (before a series starts, or after it ends, as
+ * for BGN) is a missing value. An unknown series code, a bad date, two different values for a day
+ * or any other unreadable cell throws SyntaxError. No `availableAt` is set: the Bank says only
+ * that daily rates are updated "no more than two working days after the date to which they
+ * relate".
+ *
+ * **Licensing: you must check the licence of every Bank of England series you load.** The database
+ * is under the Open Government Licence,
+ * but the Bank's legal page says "selected exchange rate data and series are excluded from this
+ * licence" and "reproduced by the Bank under licence from third parties", and its spot rates
+ * page says LSEG and Bloomberg BFIX may be sources, with LSEG content not to be redistributed
+ * without LSEG's consent. No series is named either way, so ducat ships no Bank of England data
+ * and no fetcher. Parse only files you have downloaded and are allowed to use, and get the Bank's
+ * (or LSEG's) permission before you republish any of it. The Bank also says these "are not
+ * official rates". For a licensed UK source, see HMRC's monthly rates
+ * (@ducatjs/money/convert/hmrc).
+ */
+export function parseBankOfEnglandCsv(csv: string, options?: BankOfEnglandOptions): RateTable[] {
+  const decimals = options?.decimals ?? 4;
+  const [header, ...rows] = csvRows(csv.charCodeAt(0) === 0xfeff ? csv.slice(1) : csv);
+  if (header === undefined || header[0]?.trim() !== 'DATE' || header.length < 2) {
+    notBoe('no DATE column');
+  }
+  const currencies = header.slice(1).map((code) => {
+    const currency = BOE_SERIES[code.trim()];
+    if (currency === undefined) {
+      notBoe(`unknown series ${code} (use the daily spot series against sterling, XUDL…)`);
+    }
+    return currency;
+  });
+  if (new Set(currencies).size !== currencies.length) {
+    notBoe('a series appears twice');
+  }
+
+  // A download always has a row per business day, so none at all is a cut-off file, not a range
+  // of holidays.
+  if (rows.length === 0) {
+    notBoe('no observations');
+  }
+  const days = new Map<string, Record<string, string | null>>();
+  for (const cells of rows) {
+    if (cells.length !== header.length) {
+      notBoe(`a row has ${cells.length} cells, the header ${header.length}`);
+    }
+    const day = isoDate(cells[0]!);
+    currencies.forEach((currency, i) => {
+      addDayRate(days, day, currency, readRateCell(cells[i + 1]!, `${currency} on ${day}`));
+    });
+  }
+
+  const tables: RateTable[] = [];
+  for (const [day, rates] of days) {
+    if (Object.values(rates).some((rate) => rate !== null)) {
+      tables.push(
+        quotedTable({ base: 'GBP', source: 'BoE', type: 'spot', asOf: day, decimals, rates }),
+      );
+    }
+  }
+  // A download only has rows for business days, so rows without a single rate aren't data.
+  if (tables.length === 0) {
+    notBoe('no rates in any row');
+  }
+  return newestFirst(tables);
+}

package/src/cash.ts

@@ -1,5 +1,13 @@
 import { CASH_RULES, type CashRule } from './generated/cash.js';
-import { CurrencyMismatchError, make, scaleUp, toScale, type Money } from './money.js';
+import {
+  CurrencyMismatchError,
+  make,
+  scaleUp,
+  toScale,
+  type Money,
+  type RoundingPolicy,
+} from './money.js';
+import { roundingPolicy } from './policy.js';
 import { divideAndRound, divideAndRoundBigint, type RoundingMode } from './rounding.js';
 import { currencyExponent } from './currency.js';
 
@@ -109,7 +117,67 @@ export function cashRound<C extends string>(money: Money<C>, options?: CashRound
     return money;
   }
   const inc = make(money.currency, rule.increment, currencyExponent(money.currency));
-  return roundToIncrement(money, inc, options?.rounding ?? 'halfExpand');
+  return roundToIncrement(money, inc, options?.rounding ?? rule.rounding ?? 'halfExpand');
+}
+
+/**
+ * The cash-rounding rule for a currency as a `RoundingPolicy`, to pass wherever a rounding mode
+ * goes: `m.multiply('1.075', cashPolicy('CHF'))` rounds once, straight to CHF 0.05. The policy only
+ * accepts amounts in `currency`. Throws a RangeError when no rule applies (EUR needs a country);
+ * use `isoPolicy` for currencies without cash rounding.
+ */
+export function cashPolicy(currency: string, options?: CashRoundOptions): RoundingPolicy {
+  const rule = cashRule(currency, options?.country);
+  if (!rule || (options?.includeUnverified === false && !rule.verified)) {
+    const where = options?.country === undefined ? '' : ` in ${options.country}`;
+    throw new RangeError(`No cash-rounding rule for ${currency}${where}`);
+  }
+  return roundingPolicy({
+    scale: currencyExponent(currency),
+    increment: rule.increment,
+    rounding: options?.rounding ?? rule.rounding ?? 'halfExpand',
+    currency,
+  });
+}
+
+/** Options for `currencyDigits`. */
+export interface CurrencyDigitsOptions {
+  /** 'standard' (the default): the ISO 4217 exponent. 'cash': the decimals of a cash amount. */
+  readonly usage?: 'standard' | 'cash';
+  /** For cash: the country (ISO 3166 alpha-2), which EUR needs. */
+  readonly country?: string;
+  /** For cash: whether to use rules backed only by secondary sources (default true). */
+  readonly includeUnverified?: boolean;
+}
+
+/**
+ * The number of decimals a currency's amounts are shown with: its ISO 4217 exponent, or with
+ * `{ usage: 'cash' }`, the decimals of a cash amount (what CLDR calls `cashDigits`): none when cash
+ * is rounded to whole units, the exponent otherwise.
+ *
+ *     currencyDigits('SEK')                       // 2
+ *     currencyDigits('SEK', { usage: 'cash' })    // 0: cash is rounded to whole kronor
+ *     currencyDigits('CHF', { usage: 'cash' })    // 2: CHF 0.05 still needs two decimals
+ *
+ * A currency without a cash rule (or EUR without a country that has one) takes its exponent.
+ * Throws for unknown codes, like `currencyExponent`.
+ */
+export function currencyDigits(currency: string, options?: CurrencyDigitsOptions): number {
+  const exponent = currencyExponent(currency);
+  if (options?.usage !== 'cash') {
+    return exponent;
+  }
+  const rule = cashRule(currency, options.country);
+  if (!rule || (options.includeUnverified === false && !rule.verified)) {
+    return exponent;
+  }
+
+  // Cash amounts show no decimals once the step is whole units (SEK 1, HUF 5, UZS 50), and the
+  // currency's usual decimals otherwise: DKK 0.50 is shown as 10.50, not 10.5, as in CLDR.
+  if (rule.increment % 10 ** exponent === 0) {
+    return 0;
+  }
+  return exponent;
 }
 
 export { CASH_RULES, type CashRule };

package/src/convert.ts

@@ -2,10 +2,16 @@
 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 } from './money.js';
+import { make, type CurrencyInput, type Money, type RoundingInput } from './money.js';
 import { rateOf, type RateProvider } from './provider.js';
-import { isRate, multiplyByRatioAtScale, type ConvertOptions, type Rate } from './rate.js';
-import { DEFAULT_ROUNDING, type RoundingMode } from './rounding.js';
+import {
+  convertWithPolicy,
+  isRate,
+  multiplyByRatioAtScale,
+  type ConvertOptions,
+  type Rate,
+} from './rate.js';
+import { DEFAULT_ROUNDING } from './rounding.js';
 
 export {
   exchangeRate,
@@ -18,6 +24,7 @@ export {
   type ConvertOptions,
   type RateInfo,
   type RateJSON,
+  type RateQuote,
   type RateType,
 } from './rate.js';
 export {
@@ -58,7 +65,8 @@ function isProvider(value: unknown): value is RateProvider {
 }
 
 /**
- * Converts `money` at a Rate, rounding once to the target currency's exponent (or `options.scale`).
+ * Converts `money` at a Rate, rounding once to the target currency's exponent (or `options.scale`),
+ * or with a rounding policy to its scale and increment (`@ducatjs/money/policy`).
  * The rate's pair is checked, at compile time for literal currencies and at run time otherwise.
  *
  *     convert(money('100', 'EUR'), eurUsd, 'halfEven')               // 111.65 USD
@@ -67,7 +75,7 @@ function isProvider(value: unknown): value is RateProvider {
 export function convert<From extends string, To extends string>(
   money: Money<From>,
   rate: Rate<NoInfer<From>, To>,
-  rounding?: RoundingMode,
+  rounding?: RoundingInput,
   options?: ConvertOptions,
 ): Money<To>;
 /**
@@ -80,7 +88,7 @@ export function convert<To extends CurrencyInput>(
   money: Money,
   to: To,
   rate: Factor,
-  rounding?: RoundingMode,
+  rounding?: RoundingInput,
   options?: ConvertOptions,
 ): Money<To>;
 /**
@@ -93,18 +101,18 @@ export function convert<To extends CurrencyInput>(
   money: Money,
   to: To,
   provider: RateProvider,
-  rounding?: RoundingMode,
+  rounding?: RoundingInput,
   options?: ProviderConvertOptions,
 ): Money<To>;
 export function convert(
   money: Money,
   rateOrTarget: Rate | string,
-  roundingOrRate?: RoundingMode | Factor | RateProvider,
-  optionsOrRounding?: ConvertOptions | RoundingMode,
+  roundingOrRate?: RoundingInput | Factor | RateProvider,
+  optionsOrRounding?: ConvertOptions | RoundingInput,
   maybeOptions?: ProviderConvertOptions,
 ): Money {
   if (isRate(rateOrTarget)) {
-    const rounding = roundingOrRate as RoundingMode | undefined;
+    const rounding = roundingOrRate as RoundingInput | undefined;
     return rateOrTarget.convert(money, rounding, optionsOrRounding as ConvertOptions | undefined);
   }
 
@@ -115,7 +123,7 @@ export function convert(
       query = { asOf: maybeOptions.asOf };
     }
     const rate = rateOf(roundingOrRate, money.currency, to, query);
-    return rate.convert(money, optionsOrRounding as RoundingMode | undefined, maybeOptions);
+    return rate.convert(money, optionsOrRounding as RoundingInput | undefined, maybeOptions);
   }
 
   // The bare-rate form converts directly, without building a Rate, to keep it allocation-light.
@@ -128,7 +136,10 @@ export function convert(
   if (rate.num <= 0n) {
     throw new RangeError('Exchange rate must be positive');
   }
-  const rounding = (optionsOrRounding as RoundingMode | undefined) ?? DEFAULT_ROUNDING;
+  const rounding = (optionsOrRounding as RoundingInput | undefined) ?? DEFAULT_ROUNDING;
+  if (typeof rounding === 'function') {
+    return convertWithPolicy(money, to, rate, rounding, maybeOptions);
+  }
   const scale = maybeOptions?.scale ?? currencyExponent(to);
   const minor = multiplyByRatioAtScale(money.minor, rate, scale - money.scale, rounding);
   return make(to, minor, scale);
@@ -143,7 +154,8 @@ export interface DetailedConversion<From extends string, To extends string> exte
 
 /**
  * Converts at `rate` like convert(), and also reports the residual: `value + residual` is exactly
- * money × rate, so a ledger can book the rounding difference.
+ * money × rate, so a ledger can book the rounding difference. With a rounding policy, the value
+ * is on the policy's scale and increment, and the residual is still the exact difference.
  *
  *     const { value, residual } = convertDetailed(money('0.07', 'EUR'), eurUsd, 'halfEven');
  *     // value 0.08 USD, residual -0.001845 USD (as an exact ExactMoney)
@@ -151,9 +163,15 @@ export interface DetailedConversion<From extends string, To extends string> exte
 export function convertDetailed<From extends string, To extends string>(
   money: Money<From>,
   rate: Rate<NoInfer<From>, To>,
-  rounding: RoundingMode = DEFAULT_ROUNDING,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
   options?: ConvertOptions,
 ): DetailedConversion<From, To> {
-  const rounded = exact(money).convert(rate).roundWithResidual(rounding, options?.scale);
+  const converted = exact(money).convert(rate);
+  if (typeof rounding === 'function') {
+    // The policy rounds; the residual is still exactly what it left out.
+    const value = rate.convert(money, rounding, options);
+    return { value, residual: converted.subtract(exact(value)), rate };
+  }
+  const rounded = converted.roundWithResidual(rounding, options?.scale);
   return { value: rounded.value, residual: rounded.residual, rate };
 }

package/src/drizzle/mysql.ts

@@ -0,0 +1,78 @@
+/**
+ * `@ducatjs/money/drizzle/mysql`: Drizzle ORM column types for MySQL and MariaDB (mysql2,
+ * PlanetScale). Selects return `Money`, inserts and updates accept it, and the currency is part of
+ * the column's type.
+ *
+ *     import { mysqlTable } from 'drizzle-orm/mysql-core';
+ *     import { moneyMinor } from '@ducatjs/money/drizzle/mysql';
+ *
+ *     const orders = mysqlTable('orders', { total: moneyMinor('EUR')('total_minor').notNull() });
+ */
+import { customType } from 'drizzle-orm/mysql-core';
+import type { CurrencyInput, Money, MoneyJSON } from '../money.js';
+import {
+  checkDecimalSize,
+  decimalFromDriver,
+  decimalToDriver,
+  DEFAULT_DECIMAL_SIZE,
+  jsonFromDriver,
+  jsonToDriver,
+  minorFromDriver,
+  minorToDriver,
+  type DecimalColumnSize,
+} from '../sql.js';
+
+export { DEFAULT_DECIMAL_SIZE, type DecimalColumnSize } from '../sql.js';
+
+/**
+ * A BIGINT column of minor units in a fixed currency (`1234` is 12.34 EUR), read back as
+ * `Money<C>`. Exact up to the column's limit of ±9.2·10^18 minor units. mysql2 returns BIGINT as a
+ * number by default, which is exact only below 2^53; beyond that it throws, so set
+ * `supportBigNumbers: true` (with `bigNumberStrings: true`) on the connection for larger amounts.
+ * Writing another currency, or a value at a scale other than the currency's, throws.
+ *
+ *     total: moneyMinor('EUR')('total_minor').notNull()
+ */
+export function moneyMinor<const C extends CurrencyInput>(currency: C) {
+  return customType<{ data: Money<C>; driverData: string | number | bigint }>({
+    dataType: () => 'bigint',
+    toDriver: (money) => minorToDriver(money, currency).toString(),
+    fromDriver: (value) => minorFromDriver(value, currency),
+  });
+}
+
+/**
+ * A DECIMAL(precision, scale) column, DECIMAL(19,4) by default, read back as `Money<C>`. The driver
+ * must return DECIMAL as a string (mysql2's default; don't set `decimalNumbers`): a number has been
+ * through a float and throws. Writing a value the column could not hold unchanged throws (outside
+ * strict mode MySQL would clamp it), and so does a column scale below the currency's exponent.
+ *
+ *     price: moneyDecimal('EUR', { precision: 19, scale: 4 })('price').notNull()
+ */
+export function moneyDecimal<const C extends CurrencyInput>(
+  currency: C,
+  size: DecimalColumnSize = DEFAULT_DECIMAL_SIZE,
+) {
+  checkDecimalSize(currency, size);
+
+  return customType<{ data: Money<C>; driverData: string }>({
+    dataType: () => `decimal(${size.precision}, ${size.scale})`,
+    toDriver: (money) => decimalToDriver(money, currency, size),
+    fromDriver: (value) => decimalFromDriver(value, currency),
+  });
+}
+
+/**
+ * A JSON column holding `{"amount":"12.34","currency":"EUR"}`, with the currency in each value.
+ * Pass a currency to fix it: then a value in another currency throws, on write and on read.
+ *
+ *     refund: moneyJson()('refund')
+ */
+export function moneyJson<const C extends CurrencyInput = CurrencyInput>(currency?: C) {
+  return customType<{ data: Money<C>; driverData: string | MoneyJSON }>({
+    dataType: () => 'json',
+    toDriver: (money) => jsonToDriver(money, currency),
+    // mysql2 parses JSON columns itself; other drivers may return the text
+    fromDriver: (value) => jsonFromDriver(value, currency),
+  });
+}

package/src/drizzle/pg.ts

@@ -0,0 +1,78 @@
+/**
+ * `@ducatjs/money/drizzle/pg`: Drizzle ORM column types for Postgres (node-postgres, postgres.js,
+ * PGlite, Neon). Selects return `Money`, inserts and updates accept it, and the currency is part of
+ * the column's type.
+ *
+ *     import { pgTable } from 'drizzle-orm/pg-core';
+ *     import { moneyMinor } from '@ducatjs/money/drizzle/pg';
+ *
+ *     const orders = pgTable('orders', { total: moneyMinor('EUR')('total_minor').notNull() });
+ */
+import { customType } from 'drizzle-orm/pg-core';
+import type { CurrencyInput, Money, MoneyJSON } from '../money.js';
+import {
+  checkDecimalSize,
+  decimalFromDriver,
+  decimalToDriver,
+  DEFAULT_DECIMAL_SIZE,
+  jsonFromDriver,
+  jsonToDriver,
+  minorFromDriver,
+  minorToDriver,
+  type DecimalColumnSize,
+} from '../sql.js';
+
+export { DEFAULT_DECIMAL_SIZE, type DecimalColumnSize } from '../sql.js';
+
+/**
+ * A BIGINT column of minor units in a fixed currency (`1234` is 12.34 EUR), read back as
+ * `Money<C>`. Exact up to the column's limit of ±9.2·10^18 minor units. Writing another currency, or
+ * a value at a scale other than the currency's, throws.
+ *
+ *     total: moneyMinor('EUR')('total_minor').notNull()
+ */
+export function moneyMinor<const C extends CurrencyInput>(currency: C) {
+  return customType<{ data: Money<C>; driverData: string | number | bigint }>({
+    dataType: () => 'bigint',
+    // a string, not a bigint: node-postgres cannot bind a bigint parameter
+    toDriver: (money) => minorToDriver(money, currency).toString(),
+    // node-postgres returns int8 as a string, postgres.js as a string or a bigint
+    fromDriver: (value) => minorFromDriver(value, currency),
+  });
+}
+
+/**
+ * A NUMERIC(precision, scale) column, NUMERIC(19,4) by default, read back as `Money<C>`. The
+ * driver must return NUMERIC as a string (node-postgres and postgres.js do); a number has been
+ * through a float and throws, as do `NaN` and `Infinity`. Writing a value the column could not hold
+ * unchanged throws, and so does a column scale below the currency's exponent.
+ *
+ *     price: moneyDecimal('EUR', { precision: 19, scale: 4 })('price').notNull()
+ */
+export function moneyDecimal<const C extends CurrencyInput>(
+  currency: C,
+  size: DecimalColumnSize = DEFAULT_DECIMAL_SIZE,
+) {
+  checkDecimalSize(currency, size);
+
+  return customType<{ data: Money<C>; driverData: string }>({
+    dataType: () => `numeric(${size.precision}, ${size.scale})`,
+    toDriver: (money) => decimalToDriver(money, currency, size),
+    fromDriver: (value) => decimalFromDriver(value, currency),
+  });
+}
+
+/**
+ * A JSONB column holding `{"amount":"12.34","currency":"EUR"}`, with the currency in each value.
+ * Pass a currency to fix it: then a value in another currency throws, on write and on read.
+ *
+ *     refund: moneyJson()('refund')
+ */
+export function moneyJson<const C extends CurrencyInput = CurrencyInput>(currency?: C) {
+  return customType<{ data: Money<C>; driverData: string | MoneyJSON }>({
+    dataType: () => 'jsonb',
+    toDriver: (money) => jsonToDriver(money, currency),
+    // node-postgres parses JSONB itself; other drivers may return the text
+    fromDriver: (value) => jsonFromDriver(value, currency),
+  });
+}