@ducatjs/money 0.0.0 → 0.2.0

package/src/plugins/exact.ts

@@ -0,0 +1,23 @@
+/**
+ * `@ducatjs/money/exact`: exact rational amounts that round once. Importing this module adds
+ * `Money#exact`.
+ */
+import { exact, type ExactMoney } from '../exact.js';
+import { extendMoney, type Money } from '../money.js';
+
+export * from '../exact.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /**
+     * The exact value, for chained arithmetic that rounds once: `price.exact().divide(3).round()`.
+     */
+    exact(): ExactMoney<C>;
+  }
+}
+
+extendMoney({
+  exact(this: Money) {
+    return exact(this);
+  },
+});

package/src/plugins/fixed.ts

@@ -0,0 +1,28 @@
+/**
+ * `@ducatjs/money/fixed`: exact fixed-point decimals without a currency, on the same engine as
+ * Money. Importing this module adds `Money#toFixedPoint()`.
+ */
+import { moneyToFixed, type Fixed } from '../fixed.js';
+import { extendMoney, type Money } from '../money.js';
+
+export * from '../fixed.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /**
+     * The exact Fixed of this amount, at its scale: `money('12.34', 'EUR').toFixedPoint()` is
+     * 12.34. Not `toFixed`, which Number, decimal.js and big.js all use for `toFixed(places):
+     * string`.
+     */
+    toFixedPoint(): Fixed;
+  }
+}
+
+extendMoney(
+  {
+    toFixedPoint(this: Money) {
+      return moneyToFixed(this);
+    },
+  },
+  { owner: '@ducatjs/money/fixed' },
+);

package/src/plugins/format.ts

@@ -0,0 +1,28 @@
+/**
+ * `@ducatjs/money/format`: locale formatting through Intl. Importing this module adds the methods
+ * below.
+ */
+import { format, formatToParts } from '../format.js';
+import { extendMoney, type Money } from '../money.js';
+
+export * from '../format.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** Locale formatting via Intl: `price.format('de-DE')` gives "19,99 €" */
+    format(locale?: string, options?: Intl.NumberFormatOptions): string;
+    formatToParts(locale?: string, options?: Intl.NumberFormatOptions): Intl.NumberFormatPart[];
+  }
+}
+
+extendMoney(
+  {
+    format(this: Money, locale?: string, options?: Intl.NumberFormatOptions) {
+      return format(this, locale, options);
+    },
+    formatToParts(this: Money, locale?: string, options?: Intl.NumberFormatOptions) {
+      return formatToParts(this, locale, options);
+    },
+  },
+  { owner: '@ducatjs/money/format' },
+);

package/src/plugins/klarna.ts

@@ -0,0 +1,21 @@
+/** `@ducatjs/money/klarna`: Klarna's amount view. Importing this module adds `toKlarna`. */
+import { toKlarna, type KlarnaAmountOptions } from '../klarna.js';
+import { extendMoney, type Money } from '../money.js';
+
+export * from '../klarna.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** The integer for any Klarna amount field: `money('25', 'EUR').toKlarna()` is 2500. */
+    toKlarna(options?: KlarnaAmountOptions): number;
+  }
+}
+
+extendMoney(
+  {
+    toKlarna(this: Money, options?: KlarnaAmountOptions) {
+      return toKlarna(this, options);
+    },
+  },
+  { owner: '@ducatjs/money/klarna' },
+);

package/src/plugins/paypal.ts

@@ -0,0 +1,29 @@
+/**
+ * `@ducatjs/money/paypal`: PayPal's amount view. Importing this module adds `toPayPal` and
+ * `toPayPalValue`.
+ */
+import { extendMoney, type Money } from '../money.js';
+import { toPayPal, toPayPalValue, type PayPalAmountOptions } from '../paypal.js';
+
+export * from '../paypal.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** The exact `value` string for PayPal: `money('1000', 'HUF').toPayPalValue()` is '1000'. */
+    toPayPalValue(options?: PayPalAmountOptions): string;
+    /** A PayPal `money` object: `{ currency_code, value }`. */
+    toPayPal(options?: PayPalAmountOptions): { currency_code: string; value: string };
+  }
+}
+
+extendMoney(
+  {
+    toPayPalValue(this: Money, options?: PayPalAmountOptions) {
+      return toPayPalValue(this, options);
+    },
+    toPayPal(this: Money, options?: PayPalAmountOptions) {
+      return toPayPal(this, options);
+    },
+  },
+  { owner: '@ducatjs/money/paypal' },
+);

package/src/plugins/prisma.ts

@@ -0,0 +1,24 @@
+/**
+ * `@ducatjs/money/prisma`: Prisma and SQL column helpers. Importing this module adds
+ * `toDecimalValue`.
+ */
+import { extendMoney, type Money } from '../money.js';
+import { toDecimalValue } from '../prisma.js';
+
+export * from '../prisma.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** A Decimal for a NUMERIC column: `m.toDecimalValue(Prisma.Decimal)`. */
+    toDecimalValue<D>(Decimal: new (value: string) => D): D;
+  }
+}
+
+extendMoney(
+  {
+    toDecimalValue(this: Money, Decimal: new (value: string) => unknown) {
+      return toDecimalValue(this, Decimal);
+    },
+  },
+  { owner: '@ducatjs/money/prisma' },
+);

package/src/plugins/stripe.ts

@@ -0,0 +1,29 @@
+/**
+ * `@ducatjs/money/stripe`: Stripe's minor-unit view. Importing this module adds `toStripe` and
+ * `toStripeAmount`.
+ */
+import { extendMoney, type Money } from '../money.js';
+import { toStripe, toStripeAmount, type StripeAmountOptions } from '../stripe.js';
+
+export * from '../stripe.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** The integer `amount` to send to Stripe: `money('5', 'ISK').toStripeAmount()` is 500. */
+    toStripeAmount(options?: StripeAmountOptions): number;
+    /** `{ amount, currency }` with Stripe's lowercase currency code, ready for a PaymentIntent. */
+    toStripe(options?: StripeAmountOptions): { amount: number; currency: string };
+  }
+}
+
+extendMoney(
+  {
+    toStripeAmount(this: Money, options?: StripeAmountOptions) {
+      return toStripeAmount(this, options);
+    },
+    toStripe(this: Money, options?: StripeAmountOptions) {
+      return toStripe(this, options);
+    },
+  },
+  { owner: '@ducatjs/money/stripe' },
+);

package/src/plugins/tax.ts

@@ -0,0 +1,40 @@
+/**
+ * `@ducatjs/money/tax`: percentages, discounts and tax breakdowns. Importing this module adds the
+ * methods below.
+ */
+import type { Factor } from '../decimal.js';
+import { extendMoney, type Money, type RoundingInput } from '../money.js';
+import { addTax, discount, extractTax, percentage, type TaxBreakdown } from '../tax.js';
+
+export * from '../tax.js';
+
+declare module '../money.js' {
+  interface Money<C extends string> {
+    /** `percent`% of this, e.g. `price.percentage(15, 'halfEven')` */
+    percentage(percent: Factor, rounding?: RoundingInput): Money<C>;
+    /** this minus `percent`% */
+    discount(percent: Factor, rounding?: RoundingInput): Money<C>;
+    /** Treats this as net: `{ net, tax, gross }`, net + tax = gross exactly. */
+    addTax(percent: Factor, rounding?: RoundingInput): TaxBreakdown<C>;
+    /** Treats this as gross: `{ net, tax, gross }`, net + tax = gross exactly. */
+    extractTax(percent: Factor, rounding?: RoundingInput): TaxBreakdown<C>;
+  }
+}
+
+extendMoney(
+  {
+    percentage(this: Money, percent: Factor, rounding?: RoundingInput) {
+      return percentage(this, percent, rounding);
+    },
+    discount(this: Money, percent: Factor, rounding?: RoundingInput) {
+      return discount(this, percent, rounding);
+    },
+    addTax(this: Money, percent: Factor, rounding?: RoundingInput) {
+      return addTax(this, percent, rounding);
+    },
+    extractTax(this: Money, percent: Factor, rounding?: RoundingInput) {
+      return extractTax(this, percent, rounding);
+    },
+  },
+  { owner: '@ducatjs/money/tax' },
+);

package/src/policy.ts

@@ -0,0 +1,124 @@
+/**
+ * `@ducatjs/money/policy`: rounding policies, reusable values for a scale, an increment and a
+ * rounding mode ("CHF cash", "4 decimals, half even"), accepted wherever a rounding mode is. The
+ * core only hands the work to the policy, so none of this code is in a bundle that never imports
+ * this entry (or `cashPolicy` from `@ducatjs/money/cash`).
+ */
+import { currencyExponent, isCurrency } from './currency.js';
+import { MAX_DECIMAL_SCALE, type Ratio } from './decimal.js';
+import {
+  CurrencyMismatchError,
+  multiply,
+  multiplyByRatio,
+  ratio,
+  ROUND_PRODUCT,
+  type Money,
+  type RoundingPolicy,
+} from './money.js';
+import { DEFAULT_ROUNDING, Rounding, type RoundingMode } from './rounding.js';
+
+export type { RoundingInput, RoundingPolicy } from './money.js';
+
+/** Options for `roundingPolicy`. Every field is optional. */
+export interface RoundingPolicyOptions {
+  /** Decimal places of the result (default: the currency's ISO exponent). */
+  readonly scale?: number;
+  /** A positive safe integer count of 10^-scale units to round to (default 1). */
+  readonly increment?: number;
+  /** The rounding mode (default 'halfExpand'). */
+  readonly rounding?: RoundingMode;
+  /** Restrict the policy to one currency. */
+  readonly currency?: string;
+}
+
+const ONE = ratio(1);
+const MODES = new Set<unknown>(Object.values(Rounding));
+
+/**
+ * Builds a reusable rounding policy (see `RoundingPolicy`). The options are checked here, once, so
+ * applying the policy needs no checks.
+ *
+ *     const unitPrice = roundingPolicy({ scale: 4, rounding: 'halfEven' })
+ *     const fiveCents = roundingPolicy({ increment: 5 })   // 0.05 in a 2-decimal currency
+ */
+export function roundingPolicy(options: RoundingPolicyOptions = {}): RoundingPolicy {
+  const scale = options.scale;
+  const increment = options.increment ?? 1;
+  const rounding = options.rounding ?? DEFAULT_ROUNDING;
+  const currency = options.currency;
+
+  if (
+    scale !== undefined &&
+    !(Number.isInteger(scale) && scale >= 0 && scale <= MAX_DECIMAL_SCALE)
+  ) {
+    throw new RangeError(`Invalid scale ${scale}`);
+  }
+  if (!(Number.isSafeInteger(increment) && increment >= 1)) {
+    throw new RangeError(`Invalid increment ${increment}; it must be a positive integer`);
+  }
+  if (!MODES.has(rounding)) {
+    throw new RangeError(`Invalid rounding mode ${String(rounding)}`);
+  }
+  // A typo such as 'chf' would otherwise make a policy that rejects every amount.
+  if (currency !== undefined && !isCurrency(currency)) {
+    throw new RangeError(`Unknown currency ${currency}`);
+  }
+
+  const incrementAsBigint = BigInt(increment);
+
+  // money × factor rounded once to the policy: with an increment, count whole increments
+  // (money × factor / increment, rounded at the policy's scale) and multiply back, which is
+  // rounding to the nearest multiple of the increment. The count's ratio is left unreduced: the
+  // division rounds the same either way, and a gcd per call would cost more than it saves.
+  const roundProduct = <C extends string>(money: Money<C>, factor: Ratio): Money<C> => {
+    if (currency !== undefined && currency !== money.currency) {
+      throw new CurrencyMismatchError(currency, money.currency);
+    }
+    const resultScale = scale ?? currencyExponent(money.currency);
+    if (increment === 1) {
+      return multiplyByRatio(money, factor, rounding, resultScale);
+    }
+    const stepDenominator = factor.d * increment;
+    const perStep: Ratio = {
+      num: factor.num,
+      den: factor.den * incrementAsBigint,
+      n: factor.n,
+      // NaN (not a safe integer) sends multiplyByRatio down its bigint path
+      d: Number.isSafeInteger(stepDenominator) ? stepDenominator : NaN,
+    };
+    return multiply(multiplyByRatio(money, perStep, rounding, resultScale), increment);
+  };
+
+  const policy = <C extends string>(money: Money<C>): Money<C> => roundProduct(money, ONE);
+  return Object.freeze(
+    Object.assign(policy, { scale, increment, rounding, currency, [ROUND_PRODUCT]: roundProduct }),
+  );
+}
+
+/**
+ * Rounding to the currency's ISO exponent, half up: the policy most amounts should end with.
+ * `assertScale(m, isoPolicy)` checks that an amount is already there.
+ */
+export const isoPolicy: RoundingPolicy = /* @__PURE__ */ roundingPolicy();
+
+/**
+ * Throws a RangeError unless `money` is exactly what `policy` produces: at the policy's scale and a
+ * multiple of its increment (and in its currency, if it has one). Use it where an amount must
+ * already be rounded, such as before booking it or sending it to a processor.
+ */
+export function assertScale(money: Money, policy: RoundingPolicy): void {
+  if (policy.currency !== undefined && policy.currency !== money.currency) {
+    throw new CurrencyMismatchError(policy.currency, money.currency);
+  }
+  const scale = policy.scale ?? currencyExponent(money.currency);
+  if (money.scale !== scale) {
+    throw new RangeError(`${money} has scale ${money.scale}, expected ${scale}`);
+  }
+  const minor = money.minor;
+  const increment = policy.increment;
+  const isMultiple =
+    typeof minor === 'number' ? minor % increment === 0 : minor % BigInt(increment) === 0n;
+  if (!isMultiple) {
+    throw new RangeError(`${money} is not a multiple of ${increment} at scale ${scale}`);
+  }
+}

package/src/prisma.ts

@@ -0,0 +1,199 @@
+/**
+ * Prisma / SQL interop with no dependency on @prisma/client (works with any Decimal class that has
+ * toFixed(): Prisma.Decimal, decimal.js, big.js).
+ *
+ * Storage options (see README "Databases"):
+ *  1. two columns: amount_minor BIGINT + currency CHAR(3)
+ *     -> minorMoneyField / toMinorColumns
+ *  2. a DECIMAL/NUMERIC column (+ a currency column or constant)
+ *     -> decimalMoneyField / toDecimalValue
+ */
+import { MAX_DECIMAL_SCALE } from './decimal.js';
+import {
+  fromMinor,
+  money,
+  toDecimal,
+  toMinor,
+  type CurrencyInput,
+  type Money,
+  type MoneyOptions,
+} from './money.js';
+
+/** Structural type of Prisma.Decimal / decimal.js / big.js values. */
+export interface DecimalLike {
+  toFixed(): string;
+}
+
+/**
+ * Money from a Decimal (or decimal string) column. Exact; throws if it has more decimals than the
+ * currency.
+ */
+export function fromDecimal<C extends CurrencyInput>(
+  value: DecimalLike | string,
+  currency: C,
+  options?: MoneyOptions,
+): Money<C> {
+  return money(typeof value === 'string' ? value : value.toFixed(), currency, options);
+}
+
+/** A Decimal for a NUMERIC column: toDecimalValue(m, Prisma.Decimal). */
+export function toDecimalValue<D>(money: Money, Decimal: new (value: string) => D): D {
+  return new Decimal(toDecimal(money));
+}
+
+type Row<A extends string, V> = { [P in A]: V };
+
+/** Options for `minorMoneyField` and `toMinorColumns`: a column that records each amount's scale. */
+export interface ScaleColumnOption<S extends string> {
+  /**
+   * The integer column holding the number of decimals the minor units are counted in (2 for
+   * cents). With it, any scale round-trips, and stored amounts keep their meaning even if a
+   * currency's exponent changes.
+   */
+  readonly scale: S;
+}
+
+/** A scale read from a row: a safe, non-negative integer (a SMALLINT or INT column). */
+function readScale(value: unknown, column: string): number {
+  const scale = typeof value === 'bigint' ? Number(value) : value;
+  // capped like parsed decimals: a corrupt row must not make toDecimal build a huge power of ten
+  const isValid =
+    typeof scale === 'number' &&
+    Number.isInteger(scale) &&
+    scale >= 0 &&
+    scale <= MAX_DECIMAL_SCALE;
+  if (!isValid) {
+    throw new RangeError(
+      `Expected an integer scale from 0 to ${MAX_DECIMAL_SCALE} in "${column}", got ${String(value)}`,
+    );
+  }
+  return scale;
+}
+
+/**
+ * A Prisma result-extension field that exposes a Money built from `amount_minor` + `currency`
+ * columns, and optionally a scale column:
+ *
+ *     const db = new PrismaClient().$extends({
+ *       result: { order: { total: minorMoneyField('totalMinor', 'currency') } },
+ *     });
+ *     (await db.order.findFirstOrThrow()).total   // Money
+ *
+ * Without a scale column the minor units are read at the currency's current exponent.
+ */
+export function minorMoneyField<const A extends string, const K extends string>(
+  amount: A,
+  currency: K,
+): {
+  needs: { [P in A | K]: true };
+  compute: (row: Row<A, bigint | number> & Row<K, string>) => Money;
+};
+export function minorMoneyField<
+  const A extends string,
+  const K extends string,
+  const S extends string,
+>(
+  amount: A,
+  currency: K,
+  options: ScaleColumnOption<S>,
+): {
+  needs: { [P in A | K | S]: true };
+  compute: (row: Row<A, bigint | number> & Row<K, string> & Row<S, bigint | number>) => Money;
+};
+export function minorMoneyField(
+  amount: string,
+  currency: string,
+  options?: ScaleColumnOption<string>,
+): { needs: Record<string, true>; compute: (row: Record<string, unknown>) => Money } {
+  if (options === undefined) {
+    return {
+      needs: { [amount]: true, [currency]: true },
+      compute: (row) => fromMinor(row[amount] as bigint | number, row[currency] as string),
+    };
+  }
+
+  const scaleColumn = options.scale;
+  return {
+    needs: { [amount]: true, [currency]: true, [scaleColumn]: true },
+    compute: (row) =>
+      fromMinor(
+        row[amount] as bigint | number,
+        row[currency] as string,
+        readScale(row[scaleColumn], scaleColumn),
+      ),
+  };
+}
+
+/**
+ * A Prisma result-extension field for a Decimal column, with the currency taken from another column
+ * (`{ currencyField: 'currency' }`) or fixed (`{ currency: 'EUR' }`).
+ */
+export function decimalMoneyField<const A extends string, const K extends string>(
+  amount: A,
+  currency: { currencyField: K },
+): { needs: { [P in A | K]: true }; compute: (row: Row<A, DecimalLike> & Row<K, string>) => Money };
+export function decimalMoneyField<const A extends string, const C extends CurrencyInput>(
+  amount: A,
+  currency: { currency: C },
+): { needs: { [P in A]: true }; compute: (row: Row<A, DecimalLike>) => Money<C> };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function decimalMoneyField(
+  amount: string,
+  currencySource: { currencyField: string } | { currency: string },
+): { needs: Record<string, true>; compute: (row: any) => Money } {
+  if ('currencyField' in currencySource) {
+    return {
+      needs: { [amount]: true, [currencySource.currencyField]: true },
+      compute: (row: Record<string, unknown>) =>
+        fromDecimal(row[amount] as DecimalLike, row[currencySource.currencyField] as string),
+    };
+  }
+  return {
+    needs: { [amount]: true },
+    compute: (row: Record<string, unknown>) =>
+      fromDecimal(row[amount] as DecimalLike, currencySource.currency),
+  };
+}
+
+/**
+ * Column values for writes: `data: { ...toMinorColumns(total, 'totalMinor', 'currency') }`.
+ * Minor units are a bigint (Prisma BigInt). Without a scale column, throws if the value has a
+ * non-standard scale, because the columns cannot record it. With `{ scale: 'amountScale' }`, any
+ * scale is stored, next to the minor units it counts.
+ */
+export function toMinorColumns<const A extends string, const K extends string>(
+  money: Money,
+  amount: A,
+  currency: K,
+): Row<A, bigint> & Row<K, string>;
+export function toMinorColumns<
+  const A extends string,
+  const K extends string,
+  const S extends string,
+>(
+  money: Money,
+  amount: A,
+  currency: K,
+  options: ScaleColumnOption<S>,
+): Row<A, bigint> & Row<K, string> & Row<S, number>;
+export function toMinorColumns(
+  money: Money,
+  amount: string,
+  currency: string,
+  options?: ScaleColumnOption<string>,
+): Record<string, unknown> {
+  if (options === undefined) {
+    return { [amount]: toMinorAtIsoScale(money), [currency]: money.currency };
+  }
+  return { [amount]: toMinor(money), [currency]: money.currency, [options.scale]: money.scale };
+}
+
+function toMinorAtIsoScale(money: Money): bigint {
+  const iso = fromMinor(0, money.currency).scale;
+  if (money.scale !== iso) {
+    throw new RangeError(
+      `${money} has scale ${money.scale}; round() it to ${iso} decimals before storing minor units`,
+    );
+  }
+  return toMinor(money);
+}