@ducatjs/money 0.0.0 → 0.2.0

package/src/rounding.ts

@@ -0,0 +1,122 @@
+import {
+  divideAndRoundBigint as provedDivideAndRoundBigint,
+  roundTruncatedQuotient,
+} from './generated/kernel.js';
+import { RoundingError } from './rounding-error.js';
+
+/**
+ * Rounding modes. The string values are the ones `Intl.NumberFormat` uses for its `roundingMode`
+ * option (ES2023), so a mode can be passed straight through to formatting. `Rounding` gives the
+ * familiar names (HalfUp, HalfEven, ...) for the same strings.
+ *
+ * An invalid mode (possible only from untyped code) is reported, with a RangeError, only when
+ * rounding is actually needed: an exact result is returned without looking at the mode, which keeps
+ * the exact path as fast as it can be.
+ */
+export type RoundingMode =
+  // ties to even ("banker's rounding"; IEEE 754 default, EU VAT practice in many states)
+  | 'halfEven'
+  | 'halfExpand' // ties away from zero ("half up" in commercial usage)
+  | 'halfTrunc' // ties towards zero ("half down")
+  | 'halfCeil' // ties towards +infinity
+  | 'halfFloor' // ties towards -infinity
+  | 'expand' // away from zero ("up")
+  | 'trunc' // towards zero ("down")
+  | 'ceil' // towards +infinity
+  | 'floor' // towards -infinity
+  // throw RoundingError if the result is inexact (the default for parsing and processor amounts)
+  | 'unnecessary';
+
+/**
+ * Familiar names for the rounding modes (HalfUp, HalfEven, Bankers, ...), mapped to the mode
+ * strings.
+ */
+export const Rounding = {
+  HalfEven: 'halfEven',
+  Bankers: 'halfEven',
+  HalfUp: 'halfExpand',
+  HalfDown: 'halfTrunc',
+  HalfCeil: 'halfCeil',
+  HalfFloor: 'halfFloor',
+  Up: 'expand',
+  Down: 'trunc',
+  Ceil: 'ceil',
+  Floor: 'floor',
+  Unnecessary: 'unnecessary',
+} as const satisfies Record<string, RoundingMode>;
+
+/**
+ * The rounding mode arithmetic uses when none is given: ties away from zero ('half up'). It is the
+ * default of decimal.js, big.js, bignumber.js, Prisma.Decimal and Intl.NumberFormat, and what
+ * Math.round-based money libraries (currency.js, js-money, ts-money) intend. Parsing
+ * (`money('1.005', 'EUR')`, `fromDecimal`) and processor amounts (`toStripeAmount`, `toAdyen`) stay
+ * strict: they throw unless a mode is passed.
+ */
+export const DEFAULT_ROUNDING: RoundingMode = 'halfExpand';
+
+export { RoundingError };
+
+const MAX_SAFE_MINOR = Number.MAX_SAFE_INTEGER;
+
+/**
+ * dividend / divisor rounded with `mode`, for safe-integer dividends and divisor > 0. Exact: the
+ * float quotient is only a first guess, corrected until the remainder has the dividend's sign and
+ * is smaller than the divisor.
+ */
+export function divideAndRound(dividend: number, divisor: number, mode: RoundingMode): number {
+  if (divisor === 1) {
+    return dividend + 0; // + 0 normalises -0 (0 * -1 from a caller)
+  }
+  // Beyond MAX_SAFE_MINOR the product quotient * divisor below could round, so take the bigint
+  // path.
+  if (!(Math.abs(dividend) + divisor <= MAX_SAFE_MINOR)) {
+    return Number(divideAndRoundBigint(BigInt(dividend), BigInt(divisor), mode));
+  }
+
+  let quotient = Math.trunc(dividend / divisor);
+  // exact: |quotient * divisor| <= |dividend| + divisor <= MAX_SAFE_MINOR
+  let remainder = dividend - quotient * divisor;
+
+  // The float quotient can be off by one ulp; fix it so the remainder has the dividend's sign and
+  // is smaller than the divisor in magnitude.
+  if (dividend >= 0) {
+    if (remainder < 0) {
+      quotient -= 1;
+      remainder += divisor;
+    } else if (remainder >= divisor) {
+      quotient += 1;
+      remainder -= divisor;
+    }
+  } else if (remainder > 0) {
+    quotient += 1;
+    remainder -= divisor;
+  } else if (remainder <= -divisor) {
+    quotient -= 1;
+    remainder += divisor;
+  }
+
+  // The generated switch handles a zero remainder too; returning here saves the call on the hottest
+  // path.
+  if (remainder === 0) {
+    return quotient + 0; // + 0 normalises -0
+  }
+  // quotient and remainder are now the exact truncated quotient and remainder, as the generated
+  // switch expects
+  return roundTruncatedQuotient(dividend, divisor, quotient, remainder, mode) + 0;
+}
+
+/**
+ * dividend / divisor rounded with `mode`, for divisor > 0n. The bigint kernel is generated from the
+ * Lean proofs in proofs/Ducat/Rounding.lean (`src/generated/kernel.ts`), and so is the mode switch
+ * `divideAndRound` uses.
+ */
+export function divideAndRoundBigint(
+  dividend: bigint,
+  divisor: bigint,
+  mode: RoundingMode,
+): bigint {
+  if (divisor === 1n) {
+    return dividend;
+  }
+  return provedDivideAndRoundBigint(dividend, divisor, mode);
+}

package/src/schema.ts

@@ -0,0 +1,119 @@
+import { isCurrency } from './currency.js';
+import { MAX_DECIMAL_SCALE } from './decimal.js';
+import { money, type Money, type MoneyJSON } from './money.js';
+import { Rounding, type RoundingMode } from './rounding.js';
+
+/** Options for the Zod and Valibot money schemas. */
+export interface MoneySchemaOptions<C extends string = string> {
+  /**
+   * The currency, or the currencies, to accept. Without it, any ISO 4217 code or code registered
+   * with `defineCurrency` is accepted, and nothing else.
+   */
+  readonly currency?: C | readonly C[];
+  /** Decimal places to keep (default: the currency's exponent), as in `money()`. */
+  readonly scale?: number;
+  /**
+   * How to round an amount with more decimals than the scale. The default, 'unnecessary', rejects
+   * such amounts, as `fromJSON` does.
+   */
+  readonly rounding?: RoundingMode;
+  /**
+   * The most digits the amount may have, not counting the sign and the decimal point (default
+   * 50). It keeps an oversized request body from building a huge bigint.
+   */
+  readonly maxDigits?: number;
+}
+
+/** The default `maxDigits`: far beyond any real amount, small enough to be cheap to reject. */
+export const DEFAULT_MAX_DIGITS = 50;
+
+const MODES = new Set<unknown>(Object.values(Rounding));
+
+/**
+ * @internal Checks the options when the schema is built, so a mistake there throws at once
+ * instead of turning every input into a validation error.
+ */
+export function checkSchemaOptions(options: MoneySchemaOptions | undefined): void {
+  if (options === undefined) {
+    return;
+  }
+  const allowed = options.currency;
+  const codes = typeof allowed === 'string' || allowed === undefined ? [allowed] : allowed;
+  for (const code of codes) {
+    if (code !== undefined && !isCurrency(code)) {
+      throw new RangeError(`Unknown currency ${String(code)}`);
+    }
+  }
+  const scale = options.scale;
+  if (
+    scale !== undefined &&
+    !(Number.isInteger(scale) && scale >= 0 && scale <= MAX_DECIMAL_SCALE)
+  ) {
+    throw new RangeError(`Invalid scale ${scale}`);
+  }
+  if (options.rounding !== undefined && !MODES.has(options.rounding)) {
+    throw new RangeError(`Invalid rounding mode ${String(options.rounding)}`);
+  }
+  const maxDigits = options.maxDigits;
+  if (maxDigits !== undefined && !(Number.isSafeInteger(maxDigits) && maxDigits >= 1)) {
+    throw new RangeError(`Invalid maxDigits ${maxDigits}`);
+  }
+}
+
+/** The Money type a schema produces: one Money per allowed currency, not a mixed-currency Money. */
+export type MoneyFor<C extends string> = C extends string ? Money<C> : never;
+
+/** @internal A problem with one field of the input, for the schema libraries' issue paths. */
+export interface MoneyIssue {
+  readonly field: 'amount' | 'currency';
+  readonly message: string;
+}
+
+// The exact decimal strings `toJSON` writes: an optional minus, digits, and an optional fraction.
+// No exponent, no plus sign, no whitespace and no grouping, so the wire format stays unambiguous.
+const DECIMAL = /^-?\d+(?:\.\d+)?$/;
+
+/**
+ * @internal Reads `{ amount, currency }` (already known to have two string fields) into Money, or
+ * says what is wrong with it. Shared by the Zod and Valibot entries, so both accept exactly the
+ * same inputs.
+ */
+export function readMoneyJSON<C extends string>(
+  json: MoneyJSON,
+  options: MoneySchemaOptions<C> | undefined,
+): Money | MoneyIssue {
+  const currency = json.currency;
+  const allowed = options?.currency;
+
+  if (allowed === undefined) {
+    if (!isCurrency(currency)) {
+      return { field: 'currency', message: `Unknown currency "${currency}"` };
+    }
+  } else if (
+    typeof allowed === 'string' ? currency !== allowed : !allowed.includes(currency as C)
+  ) {
+    const expected = typeof allowed === 'string' ? allowed : allowed.join(', ');
+    return { field: 'currency', message: `Expected currency ${expected}, got "${currency}"` };
+  }
+
+  const amount = json.amount;
+  // Checked before the pattern, so a huge string is rejected without scanning it.
+  const maxLength = (options?.maxDigits ?? DEFAULT_MAX_DIGITS) + 2;
+  if (amount.length > maxLength || !DECIMAL.test(amount)) {
+    return { field: 'amount', message: 'Expected a decimal string such as "12.34"' };
+  }
+  const digitCount = amount.length - (amount[0] === '-' ? 1 : 0) - (amount.includes('.') ? 1 : 0);
+  if (digitCount > (options?.maxDigits ?? DEFAULT_MAX_DIGITS)) {
+    return {
+      field: 'amount',
+      message: `More than ${options?.maxDigits ?? DEFAULT_MAX_DIGITS} digits`,
+    };
+  }
+
+  try {
+    return money(amount, currency, options);
+  } catch (error) {
+    // the options are checked up front, so this is too many decimals for the scale
+    return { field: 'amount', message: (error as Error).message };
+  }
+}

package/src/sql.ts

@@ -0,0 +1,178 @@
+// Conversions between Money and the values SQL drivers send and receive, shared by the ORM and
+// query-builder integrations (`/drizzle/*`, `/kysely`). Every reader is strict: a driver value that
+// may already have lost digits (an unsafe number, a float for a DECIMAL) is rejected rather than
+// trusted, and every writer refuses a value the column would change.
+import { currencyExponent } from './currency.js';
+import {
+  CurrencyMismatchError,
+  fromJSON,
+  fromMinor,
+  money as parseMoney,
+  toDecimal,
+  toMinor,
+  type Money,
+  type MoneyJSON,
+} from './money.js';
+
+const INTEGER_TEXT = /^-?\d+$/;
+// a BIGINT (SQLite INTEGER) column's range: MySQL outside strict mode clips anything beyond it
+const BIGINT_MIN = -(2n ** 63n);
+const BIGINT_MAX = 2n ** 63n - 1n;
+
+/** The declared size of a NUMERIC/DECIMAL column. */
+export interface DecimalColumnSize {
+  /** Total number of significant digits the column holds. */
+  readonly precision: number;
+  /** Digits after the decimal point. */
+  readonly scale: number;
+}
+
+/** NUMERIC(19,4): 15 integer digits and 4 decimals, enough for every ISO 4217 exponent. */
+export const DEFAULT_DECIMAL_SIZE: DecimalColumnSize = { precision: 19, scale: 4 };
+
+/** Throws unless the money is in the column's currency (when the column has a fixed currency). */
+export function checkCurrency(money: Money, currency: string | undefined): void {
+  if (currency !== undefined && money.currency !== currency) {
+    throw new CurrencyMismatchError(currency, money.currency);
+  }
+}
+
+/**
+ * Throws unless the money is at its currency's exponent. Columns store amounts at the currency's
+ * scale, so a value with sub-minor digits would have to be rounded, and the caller should choose how.
+ */
+export function checkIsoScale(money: Money): void {
+  const exponent = currencyExponent(money.currency);
+  if (money.scale !== exponent) {
+    throw new RangeError(
+      `${money} has scale ${money.scale}; round() it to ${exponent} decimals before storing it`,
+    );
+  }
+}
+
+/**
+ * Minor units for a BIGINT column, as a bigint. Throws beyond the column's range, ±9.2·10^18:
+ * MySQL outside strict mode would store the nearest limit instead.
+ */
+export function minorToDriver(money: Money, currency: string | undefined): bigint {
+  checkCurrency(money, currency);
+  checkIsoScale(money);
+  const minor = toMinor(money);
+
+  if (minor < BIGINT_MIN || minor > BIGINT_MAX) {
+    throw new RangeError(`${money} is ${minor} minor units, beyond the range of a BIGINT column`);
+  }
+  return minor;
+}
+
+/**
+ * Money from a BIGINT driver value. Accepts a bigint, a safe-integer number, or an integer string
+ * (node-postgres returns int8 as a string). A number beyond 2^53 has already lost digits, so it
+ * throws.
+ */
+export function minorFromDriver<C extends string>(value: unknown, currency: C): Money<C> {
+  if (typeof value === 'string') {
+    if (!INTEGER_TEXT.test(value)) {
+      throw new SyntaxError(`Expected an integer from a BIGINT column, got "${value}"`);
+    }
+    return fromMinor(BigInt(value), currency);
+  }
+  if (typeof value === 'number' || typeof value === 'bigint') {
+    return fromMinor(value, currency);
+  }
+  throw new TypeError(`Expected an integer from a BIGINT column, got ${typeof value}`);
+}
+
+/** Throws if a decimal column of this size would round amounts in this currency. */
+export function checkDecimalSize(currency: string, size: DecimalColumnSize): void {
+  const { precision, scale } = size;
+  const isValidSize =
+    Number.isInteger(precision) &&
+    Number.isInteger(scale) &&
+    precision >= 1 &&
+    scale >= 0 &&
+    scale <= precision;
+  if (!isValidSize) {
+    throw new RangeError(`NUMERIC(${precision},${scale}) is not a valid column size`);
+  }
+
+  const exponent = currencyExponent(currency);
+  if (size.scale < exponent) {
+    throw new RangeError(
+      `NUMERIC(${size.precision},${size.scale}) would round ${currency}, which has ${exponent} decimals`,
+    );
+  }
+}
+
+/**
+ * The exact decimal string for a NUMERIC/DECIMAL column. Throws if the column could not hold it
+ * unchanged: MySQL outside strict mode clamps an out-of-range value instead of failing.
+ */
+export function decimalToDriver(
+  money: Money,
+  currency: string | undefined,
+  size: DecimalColumnSize | undefined,
+): string {
+  checkCurrency(money, currency);
+  checkIsoScale(money);
+  const decimal = toDecimal(money);
+
+  if (size !== undefined) {
+    checkIntegerDigits(money, decimal, size);
+  }
+  return decimal;
+}
+
+/**
+ * Throws if the decimal (the money's `toDecimal`) has more integer digits than a column of this
+ * size holds: Postgres rejects it, and MySQL outside strict mode clamps it.
+ */
+export function checkIntegerDigits(money: Money, decimal: string, size: DecimalColumnSize): void {
+  const integerPart = decimal.replace('-', '').split('.')[0]!;
+  // "0.12" has no integer digits: NUMERIC(4,4) holds it
+  const integerDigits = integerPart === '0' ? 0 : integerPart.length;
+  if (integerDigits > size.precision - size.scale) {
+    throw new RangeError(
+      `${money} does not fit NUMERIC(${size.precision},${size.scale}), which holds ` +
+        `${size.precision - size.scale} integer digits`,
+    );
+  }
+}
+
+/**
+ * Money from a NUMERIC/DECIMAL driver value, which must be a string: a number has been through a
+ * float. Trailing zeros (`12.3400` from NUMERIC(19,4)) are fine; more decimals than the currency
+ * has, `NaN` and `Infinity` throw.
+ */
+export function decimalFromDriver<C extends string>(value: unknown, currency: C): Money<C> {
+  if (typeof value !== 'string') {
+    throw new TypeError(
+      `Expected a string from a DECIMAL column, got ${typeof value}; ` +
+        'configure the driver to return decimals as strings',
+    );
+  }
+  return parseMoney(value, currency);
+}
+
+/** `{"amount":"12.34","currency":"EUR"}` for a JSON, JSONB or TEXT column. */
+export function jsonToDriver(money: Money, currency: string | undefined): string {
+  checkCurrency(money, currency);
+  checkIsoScale(money);
+  return JSON.stringify(money);
+}
+
+/**
+ * Money from a JSON column: the parsed object (JSONB in node-postgres, JSON in mysql2) or the
+ * text (SQLite).
+ */
+export function jsonFromDriver<C extends string>(
+  value: unknown,
+  currency: C | undefined,
+): Money<C> {
+  if (typeof value !== 'string' && (typeof value !== 'object' || value === null)) {
+    throw new TypeError(`Expected JSON from a money column, got ${String(value)}`);
+  }
+  const parsed = fromJSON(value as MoneyJSON | string) as Money<C>;
+  checkCurrency(parsed, currency);
+  return parsed;
+}

package/src/stripe-fx.ts

@@ -0,0 +1,49 @@
+// Stripe exchange rates as exact Rates, for converting and reconciling balance transactions.
+import type { Money } from './money.js';
+import { exchangeRate, impliedRate, type Rate, type RateInfo } from './rate.js';
+import { fromStripe } from './stripe.js';
+
+/** The fields of a Stripe BalanceTransaction used here. */
+export interface StripeBalanceTransaction {
+  readonly amount: number;
+  readonly currency: string;
+  readonly exchange_rate?: number | null;
+  /** Seconds since the Unix epoch. */
+  readonly created?: number;
+}
+
+function stripeInfo(transaction: StripeBalanceTransaction): RateInfo {
+  if (transaction.created === undefined) {
+    return { source: 'stripe' };
+  }
+  return { source: 'stripe', asOf: new Date(transaction.created * 1000) };
+}
+
+/**
+ * The rate Stripe quotes on a balance transaction, from the charge currency `from` to the balance
+ * currency: "the amount in currency A, multiplied by the exchange_rate, equals the amount in
+ * currency B". The JSON number is read at its shortest decimal form, so 1.234 is exactly 1234/1000.
+ * `asOf` is the balance transaction's `created` time, the closest timestamp Stripe gives for the
+ * conversion; it is not the charge's creation time, and Stripe doesn't say when the rate was
+ * quoted. `undefined` when nothing was converted.
+ */
+export function stripeRate<From extends string>(
+  from: From,
+  transaction: StripeBalanceTransaction,
+): Rate<Uppercase<From>, Uppercase<string>> | undefined {
+  if (transaction.exchange_rate === undefined || transaction.exchange_rate === null) {
+    return undefined;
+  }
+  const charged = from.toUpperCase() as Uppercase<From>;
+  const balance = transaction.currency.toUpperCase() as Uppercase<string>;
+  return exchangeRate(charged, balance, transaction.exchange_rate, stripeInfo(transaction));
+}
+
+/** The exact rate Stripe applied: the balance transaction's gross amount ÷ the charged amount. */
+export function stripeImpliedRate<From extends string>(
+  charged: Money<From>,
+  transaction: StripeBalanceTransaction,
+): Rate<From, Uppercase<string>> {
+  const settled = fromStripe(transaction.amount, transaction.currency.toUpperCase());
+  return impliedRate(charged, settled, stripeInfo(transaction));
+}

package/src/stripe.ts

@@ -0,0 +1,69 @@
+/**
+ * Stripe's minor-unit view. Stripe uses ISO exponents except where documented otherwise
+ * (https://docs.stripe.com/currencies, encoded in data/stripe.json):
+ * - zero-decimal: BIF CLP DJF GNF JPY KMF KRW MGA PYG RWF VND VUV XAF XOF XPF (note MGA: ISO says
+ *   2)
+ * - ISK, UGX: sent as two-decimal values whose last two digits are 00 (5 ISK -> 500)
+ * - HUF, TWD: two decimals for charges, but payouts must be whole units (multiple of 100)
+ * - BHD JOD KWD OMR TND: three decimals, last digit must be 0 (UAE accounts only)
+ */
+import { STRIPE_RULES } from './generated/stripe.js';
+import { type CurrencyInput, type Money } from './money.js';
+import { fromProcessorAmount, toProcessorAmount } from './processor.js';
+import type { RoundingMode } from './rounding.js';
+
+export { STRIPE_RULES };
+
+function rule(currency: string) {
+  const found = STRIPE_RULES[currency.toUpperCase()];
+  if (!found) {
+    throw new RangeError(`${currency} is not a Stripe presentment currency`);
+  }
+  return found;
+}
+
+/** Whether Stripe supports the currency as a presentment currency. */
+export const isStripeCurrency = (currency: string): boolean =>
+  STRIPE_RULES[currency.toUpperCase()] !== undefined;
+
+/** The exponent Stripe's API uses for a currency (ISK 2, JPY 0, KWD 3, MGA 0). */
+export const stripeExponent = (currency: string): number => rule(currency)[0];
+
+/**
+ * Options for the Stripe amount: payout rules and how to round when Stripe needs a coarser amount.
+ */
+export interface StripeAmountOptions {
+  /** Payout amounts have stricter rules (HUF, TWD: whole units). */
+  readonly payout?: boolean;
+  /** How to round when Stripe needs a coarser amount (default 'unnecessary': throw). */
+  readonly rounding?: RoundingMode;
+}
+
+/** The integer `amount` to send to Stripe, e.g. toStripeAmount(money('5', 'ISK')) === 500. */
+export function toStripeAmount(money: Money, options?: StripeAmountOptions): number {
+  const [exp, charge, payout] = rule(money.currency);
+  return toProcessorAmount(
+    'Stripe',
+    money,
+    exp,
+    options?.payout ? payout : charge,
+    options?.rounding ?? 'unnecessary',
+  );
+}
+
+/** `{ amount, currency }` with Stripe's lowercase currency code, ready for a PaymentIntent. */
+export function toStripe(
+  money: Money,
+  options?: StripeAmountOptions,
+): { amount: number; currency: string } {
+  return { amount: toStripeAmount(money, options), currency: money.currency.toLowerCase() };
+}
+
+/** Reads a Stripe amount (e.g. from a webhook): fromStripe(500, 'isk') is 5 ISK. */
+export function fromStripe<C extends CurrencyInput>(
+  amount: number | bigint,
+  currency: C,
+): Money<Uppercase<C>> {
+  const code = currency.toUpperCase() as Uppercase<C>;
+  return fromProcessorAmount('Stripe', amount, code, rule(code)[0]);
+}

package/src/tax.ts

@@ -0,0 +1,102 @@
+import { ratio, type Factor, type Ratio } from './decimal.js';
+import {
+  add,
+  multiplyByRatio,
+  roundWithPolicy,
+  subtract,
+  type Money,
+  type RoundingInput,
+} from './money.js';
+import { DEFAULT_ROUNDING } from './rounding.js';
+
+const percentRatio = (percent: Factor): Ratio => {
+  const asRatio = ratio(percent);
+  return ratio(asRatio.num, asRatio.den * 100n);
+};
+
+/**
+ * percent% of m: percentage(EUR 80, '12.5', 'halfEven') = EUR 10.00. Rounding defaults to
+ * 'halfExpand'.
+ */
+export function percentage<C extends string>(
+  money: Money<C>,
+  percent: Factor,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
+): Money<C> {
+  return multiplyByRatio(money, percentRatio(percent), rounding);
+}
+
+/** A tax split: net + tax is always exactly gross. */
+export interface TaxBreakdown<C extends string> {
+  readonly net: Money<C>;
+  readonly tax: Money<C>;
+  /** Always exactly net + tax. */
+  readonly gross: Money<C>;
+}
+
+/**
+ * Tax-exclusive: adds percent% tax to a net amount. addTax(EUR 10, '20', 'halfEven') -> net 10, tax
+ * 2, gross 12. A rounding mode rounds the tax; a rounding policy rounds the gross (the amount
+ * charged) to its scale and increment. The other part is always the exact difference.
+ */
+export function addTax<C extends string>(
+  net: Money<C>,
+  percent: Factor,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
+): TaxBreakdown<C> {
+  // A rounding mode rounds the tax; a policy rounds the gross, the amount charged, so it lands on
+  // the policy's increment (CHF 0.05 for cash). Either way the other part is the exact difference.
+  if (typeof rounding === 'function') {
+    const percentAsRatio = ratio(percent);
+    const gross = roundWithPolicy(
+      net,
+      ratio(100n * percentAsRatio.den + percentAsRatio.num, 100n * percentAsRatio.den),
+      rounding,
+    );
+    return { net, tax: subtract(gross, net), gross };
+  }
+  const tax = multiplyByRatio(net, percentRatio(percent), rounding);
+  const gross = add(net, tax);
+  return { net, tax, gross };
+}
+
+/**
+ * Tax-inclusive: extracts percent% tax contained in a gross amount (VAT extraction).
+ * net = gross / (1 + percent/100) rounded; tax = gross - net, so the parts always add up.
+ * extractTax(EUR 12, '20', 'halfEven') -> net 10.00, tax 2.00. A rounding policy rounds the net; the
+ * tax is on the policy's increment too whenever the gross is.
+ */
+export function extractTax<C extends string>(
+  gross: Money<C>,
+  percent: Factor,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
+): TaxBreakdown<C> {
+  const percentAsRatio = ratio(percent);
+  // 1 / (1 + p/100) = 100 den / (100 den + num)
+  const net = multiplyByRatio(
+    gross,
+    ratio(100n * percentAsRatio.den, 100n * percentAsRatio.den + percentAsRatio.num),
+    rounding,
+  );
+  return { net, tax: subtract(gross, net), gross };
+}
+
+/**
+ * Price after a percent% discount. A rounding mode rounds the discount amount; a rounding policy
+ * rounds the discounted price itself, so the price lands on the policy's scale and increment.
+ */
+export function discount<C extends string>(
+  price: Money<C>,
+  percent: Factor,
+  rounding: RoundingInput = DEFAULT_ROUNDING,
+): Money<C> {
+  if (typeof rounding === 'function') {
+    const percentAsRatio = ratio(percent);
+    return roundWithPolicy(
+      price,
+      ratio(100n * percentAsRatio.den - percentAsRatio.num, 100n * percentAsRatio.den),
+      rounding,
+    );
+  }
+  return subtract(price, multiplyByRatio(price, percentRatio(percent), rounding));
+}