@ducatjs/money 0.1.0 → 0.2.1

package/src/rate.ts

@@ -12,7 +12,15 @@ import {
   type Factor,
   type Ratio,
 } from './decimal.js';
-import { CurrencyMismatchError, make, type CurrencyInput, type Money } from './money.js';
+import {
+  CurrencyMismatchError,
+  make,
+  roundWithPolicy,
+  type CurrencyInput,
+  type Money,
+  type RoundingInput,
+  type RoundingPolicy,
+} from './money.js';
 import {
   DEFAULT_ROUNDING,
   divideAndRound,
@@ -26,13 +34,39 @@ const MAX_SAFE_MINOR = Number.MAX_SAFE_INTEGER;
 export type RateType = 'mid' | 'bid' | 'ask' | (string & {});
 
 /**
- * Where a rate came from. `asOf` and `validUntil` are ISO-8601 dates ('2026-11-06') or instants.
+ * How a source published a rate, kept with the Rate for audit and display. The published direction
+ * is `from` → `to`, or `to` → `from` when `inverted`.
+ */
+export interface RateQuote {
+  /** The number exactly as published, trailing zeros included ('136.80'). */
+  readonly rate: string;
+  /**
+   * How many units of the published direction's first currency the number is for: 100 for "NOK
+   * per 100 JPY". Omitted for 1.
+   */
+  readonly per?: number;
+  /** The source quoted `to` → `from`; this Rate is its exact inverse. */
+  readonly inverted?: boolean;
+}
+
+/**
+ * Where a rate came from. `asOf`, `availableAt` and `validUntil` are ISO-8601 dates ('2026-11-06')
+ * or instants.
  */
 export interface RateInfo {
   readonly source?: string;
+  /** The date or time the rate applies to. */
   readonly asOf?: string | Date;
+  /**
+   * When the rate was published. A lookup for an earlier time doesn't get it, so a historical
+   * lookup sees only what was known then. A date means from the start of that UTC day.
+   */
+  readonly availableAt?: string | Date;
+  /** The last date or time the rate applies to. A date is valid all day (UTC). */
   readonly validUntil?: string | Date;
   readonly type?: RateType;
+  /** The rate as the source published it. */
+  readonly quote?: RateQuote;
 }
 
 /** Options for converting an amount. */
@@ -64,12 +98,22 @@ export interface RateJSON {
   rate: string;
   source?: string;
   asOf?: string;
+  availableAt?: string;
   validUntil?: string;
   type?: string;
+  /** Present only when it says more than `rate` does: a `per` or an inverted quote. */
+  quote?: RateQuote;
   derivedFrom?: RateJSON[];
 }
 
-type MutableInfo = { source?: string; asOf?: string; validUntil?: string; type?: RateType };
+type MutableInfo = {
+  source?: string;
+  asOf?: string;
+  availableAt?: string;
+  validUntil?: string;
+  type?: RateType;
+  quote?: RateQuote;
+};
 /** RateInfo that may also hold explicit undefineds (as optional parameters do). */
 type LooseInfo = { readonly [Key in keyof RateInfo]?: RateInfo[Key] | undefined };
 
@@ -93,18 +137,52 @@ export function toIsoString(time: string | Date): string {
   return date.toISOString();
 }
 
+/** A date as the first instant of its UTC day; an instant as it is. */
+function asInstant(time: string): string {
+  return ISO_DATE.test(time) ? `${time}T00:00:00.000Z` : time;
+}
+
 /**
- * The earlier of two ISO-8601 strings (one format compares lexicographically); undefined = no
- * limit.
+ * @internal
+ * Whether `time` has come by `at`. A date `at` means the whole of that UTC day, so anything on or
+ * before that day counts; a date `time` means the start of its day.
+ */
+export function hasStarted(time: string, at: string | Date): boolean {
+  const instant = toIsoString(at);
+  if (ISO_DATE.test(instant)) {
+    return time.slice(0, 10) <= instant;
+  }
+  return asInstant(time) <= instant;
+}
+
+/** @internal Whether `validUntil` (a date: valid all day, UTC) has passed at `at`. */
+export function hasEnded(validUntil: string, at: string | Date): boolean {
+  const instant = asInstant(toIsoString(at));
+  if (ISO_DATE.test(validUntil)) {
+    return instant.slice(0, 10) > validUntil;
+  }
+  return instant > validUntil;
+}
+
+/**
+ * The earlier of two ISO-8601 strings (one format compares lexicographically), or the later one
+ * with `later`; undefined = no limit.
  */
-function earlier(first: string | undefined, second: string | undefined): string | undefined {
+function earlier(
+  first: string | undefined,
+  second: string | undefined,
+  later?: boolean,
+): string | undefined {
   if (first === undefined) {
     return second;
   }
-  if (second === undefined || first <= second) {
+  if (second === undefined) {
     return first;
   }
-  return second;
+  if (later === true) {
+    return first >= second ? first : second;
+  }
+  return first <= second ? first : second;
 }
 
 /**
@@ -163,8 +241,10 @@ export class Rate<From extends string = string, To extends string = string> {
   // field semantics would otherwise define them all as undefined.
   declare readonly source?: string;
   declare readonly asOf?: string;
+  declare readonly availableAt?: string;
   declare readonly validUntil?: string;
   declare readonly type?: RateType;
+  declare readonly quote?: RateQuote;
   declare readonly derivedFrom?: readonly Rate[];
 
   /** @internal use exchangeRate() */
@@ -181,17 +261,19 @@ export class Rate<From extends string = string, To extends string = string> {
 
     // Only defined fields are assigned, so rates compare and serialise without undefined keys.
     const writable = this as { -readonly [Key in keyof Rate]?: unknown };
-    if (info?.source !== undefined) {
-      writable.source = info.source;
-    }
-    if (info?.asOf !== undefined) {
-      writable.asOf = toIsoString(info.asOf);
-    }
-    if (info?.validUntil !== undefined) {
-      writable.validUntil = toIsoString(info.validUntil);
+    const quote = info?.quote;
+    if (quote !== undefined) {
+      // toString prints a one-for-one quote, so it must be this rate. (rateFromQuote derives a
+      // scaled or inverted rate from its quote, so that one can't disagree.)
+      const direct = quote.per === undefined && quote.inverted !== true;
+      // ratio() caches strings, so for a rate built from the same text this is two lookups.
+      const quoted = direct ? ratio(quote.rate) : normalized;
+      if (quoted.num !== normalized.num || quoted.den !== normalized.den) {
+        throw new RangeError(`Quote ${quote.rate} isn't the rate ${from}→${to}`);
+      }
     }
-    if (info?.type !== undefined) {
-      writable.type = info.type;
+    if (info !== undefined) {
+      Object.assign(this, infoOf(info));
     }
     if (derivedFrom !== undefined) {
       writable.derivedFrom = derivedFrom;
@@ -205,7 +287,15 @@ export class Rate<From extends string = string, To extends string = string> {
       type = OPPOSITE_SIDE[type] ?? type;
     }
     const reciprocal = ratio(this.ratio.den, this.ratio.num);
-    return new Rate(this.to, this.from, reciprocal, timingOf(this, type), [this]);
+    let info = timingOf(this, type);
+    // The published number reads the other way round now, so the inverse of a quoted rate keeps
+    // its digits too: the inverse of CAD→USD quoted as 1.3650 inverted prints '1.3650'.
+    const quote = this.quote;
+    if (quote !== undefined) {
+      const { inverted, ...rest } = quote;
+      info = { ...info, quote: inverted === true ? rest : { ...rest, inverted: true } };
+    }
+    return new Rate(this.to, this.from, reciprocal, info, [this]);
   }
 
   /**
@@ -223,9 +313,12 @@ export class Rate<From extends string = string, To extends string = string> {
     if (this.type === next.type) {
       type = this.type;
     }
+    // A composite is known only once both legs are, and is valid only while both are.
     const asOf = earlier(this.asOf, next.asOf);
+    const availableAt = earlier(this.availableAt, next.availableAt, true);
     const validUntil = earlier(this.validUntil, next.validUntil);
-    return new Rate(this.from, next.to, product, timing(asOf, validUntil, type), [this, next]);
+    const info = timing(asOf, availableAt, validUntil, type);
+    return new Rate(this.from, next.to, product, info, [this, next]);
   }
 
   /** This rate × (1 + margin), exactly: `withMargin('-0.02')` gives 2% less `to` per `from`. */
@@ -251,14 +344,26 @@ export class Rate<From extends string = string, To extends string = string> {
     return formatScaled(scaled, places);
   }
 
-  /** The exact rate: '1.1165', or '2000/2233' when its decimal expansion doesn't terminate. */
+  /**
+   * The exact rate: '1.1165', or '2000/2233' when its decimal expansion doesn't terminate. A rate
+   * published one unit for one unit keeps the published digits ('136.80').
+   */
   toString(): string {
+    const quote = this.quote;
+    if (quote !== undefined && quote.per === undefined && quote.inverted !== true) {
+      return quote.rate;
+    }
     return ratioToDecimal(this.ratio) ?? `${this.ratio.num}/${this.ratio.den}`;
   }
 
   /** The rate, its metadata and its audit chain as JSON. `rateFromJSON` reverses it. */
   toJSON(): RateJSON {
-    const json: RateJSON = { from: this.from, to: this.to, rate: this.toString(), ...infoOf(this) };
+    const { quote, ...info } = infoOf(this);
+    const json: RateJSON = { from: this.from, to: this.to, rate: this.toString(), ...info };
+    // A direct quote is the `rate` string itself, so only a scaled or inverted one is written.
+    if (quote !== undefined && (quote.per !== undefined || quote.inverted === true)) {
+      json.quote = quote;
+    }
     if (this.derivedFrom !== undefined) {
       json.derivedFrom = this.derivedFrom.map((input) => input.toJSON());
     }
@@ -273,20 +378,27 @@ export class Rate<From extends string = string, To extends string = string> {
     if (this.validUntil === undefined) {
       return false;
     }
-    let instant = toIsoString(now);
-    if (ISO_DATE.test(instant)) {
-      instant = `${instant}T00:00:00.000Z`;
-    }
-    if (ISO_DATE.test(this.validUntil)) {
-      return instant.slice(0, 10) > this.validUntil;
+    return hasEnded(this.validUntil, now);
+  }
+
+  /**
+   * Whether the rate had been published by `at`: always, without an `availableAt`. A date `at`
+   * means by the end of that UTC day.
+   */
+  isAvailable(at: string | Date): boolean {
+    if (this.availableAt === undefined) {
+      return true;
     }
-    return instant > this.validUntil;
+    return hasStarted(this.availableAt, at);
   }
 
-  /** Converts `money`, rounding once to the target currency's exponent (or `options.scale`). */
+  /**
+   * Converts `money`, rounding once: with a mode, to the target currency's exponent (or
+   * `options.scale`); with a rounding policy, to the policy's scale and increment.
+   */
   convert(
     money: Money<From>,
-    rounding: RoundingMode = DEFAULT_ROUNDING,
+    rounding: RoundingInput = DEFAULT_ROUNDING,
     options?: ConvertOptions,
   ): Money<To> {
     if (money.currency !== this.from) {
@@ -295,12 +407,35 @@ export class Rate<From extends string = string, To extends string = string> {
     if (options?.strictValidity === true && this.validUntil !== undefined && this.isExpired()) {
       throw new RateExpiredError(this.from, this.to, this.validUntil);
     }
+    if (typeof rounding === 'function') {
+      return convertWithPolicy(money, this.to, this.ratio, rounding, options);
+    }
     const scale = options?.scale ?? currencyExponent(this.to);
     const minor = multiplyByRatioAtScale(money.minor, this.ratio, scale - money.scale, rounding);
     return make(this.to, minor, scale);
   }
 }
 
+/**
+ * @internal
+ * money × rate in `to`, rounded once by a policy. The amount is relabelled `to` at its own scale,
+ * so the policy rounds the product exactly as it would a multiplication in `to`: to its scale
+ * (default `to`'s exponent) and increment, checking its currency against `to`.
+ */
+export function convertWithPolicy<To extends string>(
+  money: Money,
+  to: To,
+  rate: Ratio,
+  policy: RoundingPolicy,
+  options?: ConvertOptions,
+): Money<To> {
+  // Two scales would leave it unclear which one the result has.
+  if (options?.scale !== undefined) {
+    throw new TypeError('options.scale with a rounding policy');
+  }
+  return roundWithPolicy(make(to, money.minor, money.scale), rate, policy);
+}
+
 /** The metadata fields of `info` that are defined (no undefined keys). */
 function infoOf(info: LooseInfo): MutableInfo {
   const defined: MutableInfo = {};
@@ -310,24 +445,57 @@ function infoOf(info: LooseInfo): MutableInfo {
   if (info.asOf !== undefined) {
     defined.asOf = toIsoString(info.asOf);
   }
+  if (info.availableAt !== undefined) {
+    defined.availableAt = toIsoString(info.availableAt);
+  }
   if (info.validUntil !== undefined) {
     defined.validUntil = toIsoString(info.validUntil);
   }
   if (info.type !== undefined) {
     defined.type = info.type;
   }
+  if (info.quote !== undefined) {
+    defined.quote = info.quote;
+  }
   return defined;
 }
 
-function timing(asOf?: string, validUntil?: string, type?: RateType): RateInfo {
-  return infoOf({ asOf, validUntil, type });
+function timing(
+  asOf?: string,
+  availableAt?: string,
+  validUntil?: string,
+  type?: RateType,
+): RateInfo {
+  return infoOf({ asOf, availableAt, validUntil, type });
 }
 
 /**
  * A derived rate keeps the timing of its input; the input's source stays with it, in derivedFrom.
  */
 function timingOf(input: Rate, type?: RateType): RateInfo {
-  return timing(input.asOf, input.validUntil, type);
+  return timing(input.asOf, input.availableAt, input.validUntil, type);
+}
+
+// A published decimal whose canonical form drops digits: trailing fraction zeros only. Leading
+// zeros ('01.50') aren't published digits, so those are left to the canonical form.
+const PUBLISHED_DECIMAL = /^(?:0|[1-9]\d*)\.\d*0$/;
+
+/**
+ * Keeps the published digits of `text` on a Rate just built from it, when its canonical form would
+ * drop some ('1.1650' prints as '1.165'). Assigned directly: the quote is the rate's own text, so
+ * there is nothing to check, and building a rate inline stays cheap.
+ */
+function keepDigits<R extends Rate>(rate: R, text: Factor): R {
+  // Only a last character of '0' can be dropped, so most rates are settled by one comparison.
+  const dropsDigits =
+    typeof text === 'string' &&
+    text.charCodeAt(text.length - 1) === 48 &&
+    rate.quote === undefined &&
+    PUBLISHED_DECIMAL.test(text);
+  if (dropsDigits) {
+    (rate as { quote?: RateQuote }).quote = { rate: text };
+  }
+  return rate;
 }
 
 /**
@@ -345,13 +513,14 @@ export function exchangeRate<From extends CurrencyInput, To extends CurrencyInpu
   rate: Factor,
   info?: RateInfo,
 ): Rate<From, To> {
-  return new Rate(from, to, ratio(rate), info);
+  return keepDigits(new Rate(from, to, ratio(rate), info), rate);
 }
 
 /** Rebuilds a Rate, with its audit chain, from `rate.toJSON()`. */
 export function rateFromJSON(json: RateJSON): Rate {
   const derivedFrom = json.derivedFrom?.map(rateFromJSON);
-  return new Rate(json.from, json.to, ratio(json.rate), infoOf(json), derivedFrom);
+  const rate = new Rate(json.from, json.to, ratio(json.rate), infoOf(json), derivedFrom);
+  return keepDigits(rate, json.rate);
 }
 
 /** Whether `value` is a Rate. */

package/src/rounding.ts

@@ -65,7 +65,7 @@ const MAX_SAFE_MINOR = Number.MAX_SAFE_INTEGER;
  */
 export function divideAndRound(dividend: number, divisor: number, mode: RoundingMode): number {
   if (divisor === 1) {
-    return dividend;
+    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.

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 };
+  }
+}