@ducatjs/money 0.0.0 → 0.2.0

package/src/pg.ts

@@ -0,0 +1,410 @@
+/**
+ * `@ducatjs/money/pg`: node-postgres type parsers that keep NUMERIC and BIGINT exact, a Postgres
+ * composite type for Money with a `sum` aggregate, and a guard for NUMERIC(p, s) columns.
+ *
+ *     import pg from 'pg';
+ *     import { exactTypes } from '@ducatjs/money/pg';
+ *
+ *     const pool = new pg.Pool({ types: exactTypes(pg.types) });
+ *
+ * It imports nothing from pg at run time: pass `pg.types` in.
+ */
+import { currencyExponent } from './currency.js';
+import { money as parseMoney, toDecimal, type CurrencyInput, type Money } from './money.js';
+import { checkDecimalSize, checkIntegerDigits, type DecimalColumnSize } from './sql.js';
+
+export { DEFAULT_DECIMAL_SIZE, type DecimalColumnSize } from './sql.js';
+
+/** A text-format value parser, as node-postgres calls it. */
+export type TypeParser = (text: string) => unknown;
+
+/** The part of `pg.types` (or a client's `types` option) these parsers build on. */
+export interface TypeParserSource {
+  getTypeParser(oid: number, format?: 'text' | 'binary'): TypeParser;
+}
+
+/** The OIDs of a composite money type and its array type, from `moneyTypeOids`. */
+export interface MoneyTypeOids {
+  readonly oid: number;
+  readonly arrayOid: number;
+}
+
+/** Options for `exactTypes`. */
+export interface ExactTypesOptions {
+  /** Also parse this composite money type (and its array) into Money. */
+  readonly money?: MoneyTypeOids;
+  /**
+   * How BIGINT (and BIGINT[]) values come back: `'bigint'` (the default) or `'string'`, pg's own
+   * exact format. A bigint is what `fromMinor` takes, but it applies to every BIGINT on the client,
+   * `count(*)` and bigserial ids included, and `JSON.stringify` throws on it.
+   */
+  readonly int8?: 'bigint' | 'string';
+}
+
+const INT8_OID = 20;
+const NUMERIC_OID = 1700;
+const INT8_ARRAY_OID = 1016;
+const NUMERIC_ARRAY_OID = 1231;
+
+const INTEGER_TEXT = /^-?\d+$/;
+const NUMERIC_TEXT = /^-?\d+(?:\.\d+)?$/;
+
+/**
+ * BIGINT text as a bigint. node-postgres returns it as a string by default, which is exact but not
+ * a number type the Money constructors accept.
+ */
+export function parseBigInt(text: string): bigint {
+  if (!INTEGER_TEXT.test(text)) {
+    throw new SyntaxError(`Expected BIGINT text, got "${text}"`);
+  }
+  return BigInt(text);
+}
+
+/** BIGINT text, checked and kept as the string. */
+function checkBigIntText(text: string): string {
+  parseBigInt(text);
+  return text;
+}
+
+/**
+ * NUMERIC text, checked and returned as the exact decimal string. Postgres NUMERIC can hold `NaN`
+ * and `±Infinity`, which are not amounts, so they throw.
+ */
+export function parseNumeric(text: string): string {
+  if (!NUMERIC_TEXT.test(text)) {
+    throw new SyntaxError(`Expected a finite NUMERIC, got "${text}"`);
+  }
+  return text;
+}
+
+/**
+ * Splits Postgres array text (`{1,2,NULL}`, `{{1,2},{3,4}}`, `{"(1.00,EUR)"}`) into nested arrays of
+ * element text, with `null` for NULL. Quoted elements are unescaped.
+ */
+export function parseArray(text: string): unknown[] {
+  let position = 0;
+
+  // an array may start with explicit bounds, `[1:2]={...}`
+  if (text.startsWith('[')) {
+    position = text.indexOf('=') + 1;
+  }
+
+  function parseLevel(): unknown[] {
+    if (text[position] !== '{') {
+      throw new SyntaxError(`Malformed array text "${text}"`);
+    }
+    position++;
+    const items: unknown[] = [];
+    if (text[position] === '}') {
+      position++;
+      return items;
+    }
+
+    for (;;) {
+      if (text[position] === '{') {
+        items.push(parseLevel());
+      } else if (text[position] === '"') {
+        position++;
+        let value = '';
+        while (text[position] !== '"') {
+          if (position >= text.length) {
+            throw new SyntaxError(`Unterminated quote in array text "${text}"`);
+          }
+          if (text[position] === '\\') {
+            position++;
+          }
+          value += text[position];
+          position++;
+        }
+        position++;
+        items.push(value);
+      } else {
+        const start = position;
+        while (position < text.length && text[position] !== ',' && text[position] !== '}') {
+          position++;
+        }
+        const value = text.slice(start, position);
+        items.push(value === 'NULL' ? null : value);
+      }
+
+      if (text[position] === ',') {
+        position++;
+        continue;
+      }
+      if (text[position] === '}') {
+        position++;
+        return items;
+      }
+      throw new SyntaxError(`Malformed array text "${text}"`);
+    }
+  }
+
+  const result = parseLevel();
+  if (position !== text.length) {
+    throw new SyntaxError(`Malformed array text "${text}"`);
+  }
+  return result;
+}
+
+function mapArray(items: unknown[], parseElement: (text: string) => unknown): unknown[] {
+  return items.map((item) => {
+    if (item === null) {
+      return null;
+    }
+    if (Array.isArray(item)) {
+      return mapArray(item, parseElement);
+    }
+    return parseElement(item as string);
+  });
+}
+
+/**
+ * Splits record text, `(12.34,EUR)` or `(12.34,"A\\B")`, into its fields, with `null` for an empty
+ * unquoted field. Quoted fields are unescaped: Postgres doubles `"` and `\` inside them on output,
+ * and accepts a backslash before any character on input.
+ */
+function parseRecord(text: string): (string | null)[] {
+  if (!text.startsWith('(') || !text.endsWith(')')) {
+    throw new SyntaxError(`Expected record text in parentheses, got "${text}"`);
+  }
+  const fields: (string | null)[] = [];
+  let position = 1;
+  const end = text.length - 1;
+
+  for (;;) {
+    let field = '';
+    let isQuotedOrNonEmpty = false;
+    while (position < end && text[position] !== ',') {
+      const character = text[position]!;
+      if (character === '"') {
+        isQuotedOrNonEmpty = true;
+        position++;
+        for (;;) {
+          if (position >= end) {
+            throw new SyntaxError(`Unbalanced quote in record text "${text}"`);
+          }
+          const quoted = text[position]!;
+          if (quoted === '\\') {
+            field += text[position + 1] ?? '';
+            position += 2;
+          } else if (quoted === '"' && text[position + 1] === '"') {
+            field += '"';
+            position += 2;
+          } else if (quoted === '"') {
+            position++;
+            break;
+          } else {
+            field += quoted;
+            position++;
+          }
+        }
+        continue;
+      }
+      if (character === '\\') {
+        field += text[position + 1] ?? '';
+        position += 2;
+      } else {
+        field += character;
+        position++;
+      }
+      isQuotedOrNonEmpty = true;
+    }
+    fields.push(isQuotedOrNonEmpty ? field : null);
+    if (position >= end) {
+      return fields;
+    }
+    position++;
+  }
+}
+
+/**
+ * Money from the text of the composite type, `(12.34,EUR)`. The amount keeps the scale it was
+ * stored with, and never less than the currency's exponent. NULL fields, `NaN`, `Infinity` and
+ * malformed text throw.
+ */
+export function parseMoneyComposite(text: string): Money {
+  const fields = parseRecord(text);
+  if (fields.length !== 2) {
+    throw new SyntaxError(`Expected (amount,currency) composite text, got "${text}"`);
+  }
+  const [amount, currency] = fields;
+  if (amount === null || amount === undefined || currency === null || currency === undefined) {
+    throw new TypeError(`A money composite needs both an amount and a currency, got "${text}"`);
+  }
+  parseNumeric(amount);
+
+  const fractionDigits = amount.includes('.') ? amount.length - amount.indexOf('.') - 1 : 0;
+  const scale = Math.max(fractionDigits, currencyExponent(currency));
+  return parseMoney(amount, currency, { scale });
+}
+
+/**
+ * The composite type's text for a query parameter: `(12.34,"EUR")`, at the Money's own scale. The
+ * currency is always quoted and escaped, so custom codes containing `\`, `"`, `,` or `)` survive.
+ * Cast it in SQL (`$1::ducat_money`) where Postgres can't infer the type.
+ */
+export function toMoneyComposite(money: Money): string {
+  const currency = money.currency.replace(/["\\]/g, (character) => `\\${character}`);
+  return `(${toDecimal(money)},"${currency}")`;
+}
+
+/**
+ * Type parsers for node-postgres that never turn an amount into a float: BIGINT as bigint, NUMERIC
+ * as an exact string (rejecting `NaN` and `Infinity`), their arrays the same way (pg's default
+ * parses NUMERIC arrays as floats), and optionally the composite money type as Money. Every other
+ * type uses `base`.
+ *
+ *     new pg.Pool({ types: exactTypes(pg.types, { money: await moneyTypeOids(client) }) })
+ */
+export function exactTypes(base: TypeParserSource, options?: ExactTypesOptions): TypeParserSource {
+  const moneyOids = options?.money;
+  const parseInt8 = options?.int8 === 'string' ? checkBigIntText : parseBigInt;
+
+  return {
+    getTypeParser(oid: number, format?: 'text' | 'binary'): TypeParser {
+      // the binary format is only used when a query asks for it; leave it to pg
+      if (format === 'binary') {
+        return base.getTypeParser(oid, format);
+      }
+      if (oid === INT8_OID) {
+        return parseInt8;
+      }
+      if (oid === NUMERIC_OID) {
+        return parseNumeric;
+      }
+      if (oid === INT8_ARRAY_OID) {
+        return (text) => mapArray(parseArray(text), parseInt8);
+      }
+      if (oid === NUMERIC_ARRAY_OID) {
+        return (text) => mapArray(parseArray(text), parseNumeric);
+      }
+      if (moneyOids !== undefined && oid === moneyOids.oid) {
+        return parseMoneyComposite;
+      }
+      if (moneyOids !== undefined && oid === moneyOids.arrayOid) {
+        return (text) => mapArray(parseArray(text), parseMoneyComposite);
+      }
+      return base.getTypeParser(oid, format);
+    },
+  };
+}
+
+/** The default name of the composite money type. */
+export const MONEY_TYPE_NAME = 'ducat_money';
+
+const IDENTIFIER = /^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)?$/;
+// Postgres truncates longer names, which would make `name` and `name_add` collide with others
+const MAX_IDENTIFIER_LENGTH = 63;
+
+/**
+ * The DDL for a composite money type, `(amount numeric, currency text)`, and a `sum` aggregate over
+ * it that throws on mixed currencies, and on a value with a NULL amount or currency. The amount is
+ * an unconstrained NUMERIC, so it keeps every digit and its scale. A schema-qualified name puts the
+ * type, its add function and the aggregate in that schema.
+ *
+ * Run the statements once, in order, in a migration: they are not idempotent, and a second run
+ * fails with `duplicate_object`.
+ *
+ *     for (const statement of moneyTypeSql()) await client.query(statement);
+ *     SELECT sum(price) FROM items;   -- (37.50,EUR)
+ */
+export function moneyTypeSql(name: string = MONEY_TYPE_NAME): string[] {
+  if (!IDENTIFIER.test(name)) {
+    throw new RangeError(`"${name}" is not a plain lower-case SQL name (optionally schema.name)`);
+  }
+  const dot = name.indexOf('.');
+  const schemaPrefix = dot < 0 ? '' : name.slice(0, dot + 1);
+  const typeName = name.slice(dot + 1);
+  if (`${typeName}_add`.length > MAX_IDENTIFIER_LENGTH) {
+    throw new RangeError(`"${typeName}" is too long for a Postgres name with an "_add" suffix`);
+  }
+  const add = `${name}_add`;
+
+  return [
+    `CREATE TYPE ${name} AS (amount numeric, currency text)`,
+    // search_path FROM CURRENT: the cast below resolves the same way whatever the caller's path
+    `CREATE FUNCTION ${add}(total ${name}, item ${name}) RETURNS ${name}
+LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE SET search_path FROM CURRENT AS $$
+BEGIN
+  IF item IS NULL THEN
+    RETURN total;
+  END IF;
+  IF item.amount IS NULL OR item.currency IS NULL THEN
+    RAISE EXCEPTION 'a money value needs both an amount and a currency'
+      USING ERRCODE = 'null_value_not_allowed';
+  END IF;
+  IF total IS NULL THEN
+    RETURN item;
+  END IF;
+  IF total.currency IS DISTINCT FROM item.currency THEN
+    RAISE EXCEPTION 'cannot add % and % amounts', total.currency, item.currency
+      USING ERRCODE = 'data_exception';
+  END IF;
+  RETURN ROW(total.amount + item.amount, total.currency)::${name};
+END
+$$`,
+    `CREATE AGGREGATE ${schemaPrefix}sum(${name}) ` +
+      `(SFUNC = ${add}, STYPE = ${name}, COMBINEFUNC = ${add}, PARALLEL = SAFE)`,
+  ];
+}
+
+/** The part of a pg Client or Pool that `moneyTypeOids` uses. */
+export interface Queryable {
+  query(
+    sql: string,
+    values: unknown[],
+  ): Promise<{ rows: { oid: number | string; typarray: number | string }[] }>;
+}
+
+/**
+ * Looks up the OIDs of the composite money type, for `exactTypes`. Run it once at start-up on a
+ * client without the money parser. OIDs differ between databases, and change if the type is
+ * dropped and recreated; values of a type whose OID `exactTypes` wasn't given come back as pg's
+ * raw text. With a type per schema, look up and pass each one's OIDs.
+ */
+export async function moneyTypeOids(
+  client: Queryable,
+  name: string = MONEY_TYPE_NAME,
+): Promise<MoneyTypeOids> {
+  const result = await client.query(
+    'SELECT oid, typarray FROM pg_type WHERE oid = to_regtype($1)',
+    [name],
+  );
+  const row = result.rows[0];
+  if (row === undefined) {
+    throw new RangeError(`No type "${name}" in this database; run moneyTypeSql() first`);
+  }
+  return { oid: Number(row.oid), arrayOid: Number(row.typarray) };
+}
+
+/**
+ * The exact decimal string for a NUMERIC(precision, scale) column, or a throw if Postgres would
+ * change it: it rounds extra decimals silently on insert, and rejects too many integer digits.
+ * Unlike the column types, any scale up to the column's is accepted, and trailing zeros beyond it
+ * are dropped since they don't change the value.
+ */
+export function toNumeric<C extends CurrencyInput>(
+  money: Money<C>,
+  size: DecimalColumnSize,
+): string {
+  checkDecimalSize(money.currency, size);
+  const decimal = toDecimal(money);
+  const [integerPart, fraction = ''] = decimal.replace('-', '').split('.');
+
+  const significantFraction = fraction.replace(/0+$/, '');
+  if (significantFraction.length > size.scale) {
+    throw new RangeError(
+      `${money} has ${significantFraction.length} decimals; NUMERIC(${size.precision},${size.scale}) ` +
+        `would round it to ${size.scale}`,
+    );
+  }
+
+  checkIntegerDigits(money, decimal, size);
+
+  if (fraction.length <= size.scale) {
+    return decimal;
+  }
+  const sign = decimal.startsWith('-') ? '-' : '';
+  const kept = fraction.slice(0, size.scale);
+  return kept === '' ? `${sign}${integerPart}` : `${sign}${integerPart}.${kept}`;
+}

package/src/plugins/adyen.ts

@@ -0,0 +1,25 @@
+/** `@ducatjs/money/adyen`: Adyen's minor-unit view. Importing this module adds `toAdyen`. */
+import { toAdyen } from '../adyen.js';
+import { extendMoney, type Money } from '../money.js';
+import type { RoundingMode } from '../rounding.js';
+
+export * from '../adyen.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /**
+     * Adyen `amount` object: `money('15000', 'IDR').toAdyen()` is `{ value: 15000, currency: 'IDR'
+     * }`.
+     */
+    toAdyen(rounding?: RoundingMode): { value: number; currency: string };
+  }
+}
+
+extendMoney(
+  {
+    toAdyen(this: Money, rounding?: RoundingMode) {
+      return toAdyen(this, rounding);
+    },
+  },
+  { owner: '@ducatjs/money/adyen' },
+);

package/src/plugins/all.ts

@@ -0,0 +1,57 @@
+/** `@ducatjs/money/all`: core plus every opt-in module, with all methods installed. */
+export * from '../index.js';
+// The core Money methods as plain functions too, as in /fn: /all is everything.
+export {
+  add,
+  subtract,
+  negate,
+  abs,
+  multiply,
+  divide,
+  round,
+  toScale,
+  compare,
+  equals,
+  identical,
+  lessThan,
+  lessThanOrEqual,
+  greaterThan,
+  greaterThanOrEqual,
+  isZero,
+  isPositive,
+  isNegative,
+  sign,
+  min,
+  max,
+  clamp,
+  majorPart,
+  minorPart,
+  toDecimal,
+  toMinor,
+  toMinorNumber,
+} from '../money.js';
+export { roundingPolicy, isoPolicy, assertScale, type RoundingPolicyOptions } from '../policy.js';
+export * from './allocate.js';
+export * from './tax.js';
+export * from './convert.js';
+export * from './exact.js';
+export * from '../ecb.js';
+export * from '../boc.js';
+export * from '../boe.js';
+export * from '../hmrc.js';
+export * from '../fed.js';
+export * from '../history.js';
+export * from '../stripe-fx.js';
+export * from '../adyen-fx.js';
+export * from './cash.js';
+export * from '../historic.js';
+export * from './format.js';
+export * from '../parse.js';
+export * from './stripe.js';
+export * from './adyen.js';
+export * from './checkout.js';
+export * from './paypal.js';
+export * from './braintree.js';
+export * from './klarna.js';
+export * from './prisma.js';
+export * from './fixed.js';

package/src/plugins/allocate.ts

@@ -0,0 +1,53 @@
+/**
+ * `@ducatjs/money/allocate`: allocation, splitting and tranches. Importing this module adds the
+ * methods below to every Money; the free functions are exported too (and from `@ducatjs/money/fn`,
+ * which changes no prototypes).
+ */
+import {
+  allocate,
+  chunk,
+  instalments,
+  schedule,
+  split,
+  type AllocateOptions,
+  type InstalmentOptions,
+  type Tranche,
+  type Weight,
+} from '../allocate.js';
+import { extendMoney, type Money } from '../money.js';
+
+export * from '../allocate.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** Splits by weights; the parts always sum to this. */
+    allocate(weights: readonly Weight[], options?: AllocateOptions): Money<C>[];
+    /** Splits into `count` near-equal parts that sum to this. */
+    split(count: number, options?: AllocateOptions): Money<C>[];
+    instalments(count: number, options?: InstalmentOptions<C>): Money<C>[];
+    schedule(tranches: readonly Tranche<C>[]): Money<C>[];
+    /** Tranches of at most `max`: 1000 by 300 gives 300, 300, 300, 100. */
+    chunk(max: Money<C>): Money<C>[];
+  }
+}
+
+extendMoney(
+  {
+    allocate(this: Money, weights: readonly Weight[], options?: AllocateOptions) {
+      return allocate(this, weights, options);
+    },
+    split(this: Money, count: number, options?: AllocateOptions) {
+      return split(this, count, options);
+    },
+    instalments(this: Money, count: number, options?: InstalmentOptions<string>) {
+      return instalments(this, count, options);
+    },
+    schedule(this: Money, tranches: readonly Tranche<string>[]) {
+      return schedule(this, tranches);
+    },
+    chunk(this: Money, max: Money) {
+      return chunk(this, max);
+    },
+  },
+  { owner: '@ducatjs/money/allocate' },
+);

package/src/plugins/braintree.ts

@@ -0,0 +1,23 @@
+/**
+ * `@ducatjs/money/braintree`: Braintree's amount view. Importing this module adds `toBraintree`.
+ */
+import { toBraintree, type BraintreeAmountOptions } from '../braintree.js';
+import { extendMoney, type Money } from '../money.js';
+
+export * from '../braintree.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** The exact `amount` string for Braintree: `money('10', 'USD').toBraintree()` is '10.00'. */
+    toBraintree(options?: BraintreeAmountOptions): string;
+  }
+}
+
+extendMoney(
+  {
+    toBraintree(this: Money, options?: BraintreeAmountOptions) {
+      return toBraintree(this, options);
+    },
+  },
+  { owner: '@ducatjs/money/braintree' },
+);

package/src/plugins/cash.ts

@@ -0,0 +1,33 @@
+/**
+ * `@ducatjs/money/cash`: cash rounding (cash tenders only; card payments are never rounded) and
+ * rounding to an increment. Importing this module adds the methods below.
+ */
+import { cashRound, roundToIncrement, type CashRoundOptions } from '../cash.js';
+import { extendMoney, type Money } from '../money.js';
+import type { RoundingMode } from '../rounding.js';
+
+export * from '../cash.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /**
+     * Rounds a cash total to the local cash step (CHF 0.05, SEK 1, ...); unchanged when no rule
+     * applies.
+     */
+    cashRound(options?: CashRoundOptions): Money<C>;
+    /** Rounds to a multiple of `increment`, e.g. CHF 10.03 to CHF 0.05 gives CHF 10.05. */
+    roundToIncrement(increment: Money<C>, rounding?: RoundingMode): Money<C>;
+  }
+}
+
+extendMoney(
+  {
+    cashRound(this: Money, options?: CashRoundOptions) {
+      return cashRound(this, options);
+    },
+    roundToIncrement(this: Money, increment: Money, rounding?: RoundingMode) {
+      return roundToIncrement(this, increment, rounding);
+    },
+  },
+  { owner: '@ducatjs/money/cash' },
+);

package/src/plugins/checkout.ts

@@ -0,0 +1,32 @@
+/**
+ * `@ducatjs/money/checkout`: Checkout.com's amount view. Importing this module adds `toCheckout`
+ * and `toCheckoutAmount`.
+ */
+import { toCheckout, toCheckoutAmount, type CheckoutAmountOptions } from '../checkout.js';
+import { extendMoney, type Money } from '../money.js';
+
+export * from '../checkout.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /**
+     * The integer `amount` to send to Checkout.com: `money('5000', 'CLP').toCheckoutAmount()` is
+     * 500000.
+     */
+    toCheckoutAmount(options?: CheckoutAmountOptions): number;
+    /** `{ amount, currency }` for a Checkout.com payment request. */
+    toCheckout(options?: CheckoutAmountOptions): { amount: number; currency: string };
+  }
+}
+
+extendMoney(
+  {
+    toCheckoutAmount(this: Money, options?: CheckoutAmountOptions) {
+      return toCheckoutAmount(this, options);
+    },
+    toCheckout(this: Money, options?: CheckoutAmountOptions) {
+      return toCheckout(this, options);
+    },
+  },
+  { owner: '@ducatjs/money/checkout' },
+);

package/src/plugins/convert.ts

@@ -0,0 +1,49 @@
+/**
+ * `@ducatjs/money/convert`: currency conversion at exact rates. Importing this module adds
+ * `Money#convert`.
+ */
+import { convert } from '../convert.js';
+import type { Factor } from '../decimal.js';
+import { extendMoney, type CurrencyInput, type Money, type RoundingInput } from '../money.js';
+import type { ProviderConvertOptions } from '../convert.js';
+import type { RateProvider } from '../provider.js';
+import type { ConvertOptions, Rate } from '../rate.js';
+
+export * from '../convert.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** Converts at a Rate, rounding once: `eur.convert(eurUsd, 'halfEven')`. */
+    convert<To extends string>(
+      rate: Rate<NoInfer<C>, To>,
+      rounding?: RoundingInput,
+      options?: ConvertOptions,
+    ): Money<To>;
+    /** Converts at an exact decimal-string rate: `eur.convert('USD', '1.0832', 'halfEven')`. */
+    convert<To extends CurrencyInput>(
+      to: To,
+      rate: Factor,
+      rounding?: RoundingInput,
+      options?: ConvertOptions,
+    ): Money<To>;
+    /**
+     * Converts through a provider, rounding once: `usd.convert('JPY', via('EUR', ecb),
+     * 'halfEven')`.
+     */
+    convert<To extends CurrencyInput>(
+      to: To,
+      provider: RateProvider,
+      rounding?: RoundingInput,
+      options?: ProviderConvertOptions,
+    ): Money<To>;
+  }
+}
+
+extendMoney(
+  {
+    convert(this: Money, ...args: [never, never?, never?, never?]) {
+      return (convert as (money: Money, ...rest: unknown[]) => Money)(this, ...args);
+    },
+  },
+  { owner: '@ducatjs/money/convert' },
+);