@ducatjs/money 0.0.0 → 0.2.0

package/src/allocate.ts

@@ -0,0 +1,393 @@
+import { parseDecimal, pow10n, normalizeMinor } from './decimal.js';
+import {
+  CurrencyMismatchError,
+  compare,
+  make,
+  negate,
+  scaleUp,
+  subtract,
+  toScale,
+  type Money,
+} from './money.js';
+
+const MAX_SAFE_MINOR = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Where the indivisible remainder (always fewer minor units than there are non-zero buckets for
+ * the spreading strategies) goes:
+ * - 'largest'  largest-remainder (Hamilton) method: units go to the buckets with the biggest
+ *              fractional part, ties to the earlier bucket. The default; minimises error per bucket.
+ * - 'first'    one unit each to the first buckets (with non-zero weight)
+ * - 'last'     one unit each to the last buckets
+ * - 'toFirst'  the whole remainder to the first bucket
+ * - 'toLast'   the whole remainder to the last bucket
+ */
+export type Remainder = 'largest' | 'first' | 'last' | 'toFirst' | 'toLast';
+
+/** Options for `allocate` and `split`: where the indivisible remainder goes. */
+export interface AllocateOptions {
+  readonly remainder?: Remainder;
+}
+
+/** A ratio weight: a non-negative integer, bigint or decimal string ('33.3'). */
+export type Weight = number | bigint | string;
+
+function weightsToBig(ws: readonly Weight[]): bigint[] {
+  return weightsScaled(ws).ws;
+}
+
+function weightsScaled(ws: readonly Weight[]): { ws: bigint[]; scale: number } {
+  let scale = 0;
+  const parsed = ws.map((weight) => {
+    if (typeof weight === 'bigint') {
+      return { digits: weight, scale: 0 };
+    }
+    if (typeof weight === 'number' && Number.isSafeInteger(weight)) {
+      return { digits: BigInt(weight), scale: 0 };
+    }
+    const item = parseDecimal(String(weight));
+    return item;
+  });
+  for (const item of parsed) {
+    if (item.digits < 0n) {
+      throw new RangeError('Allocation weights must not be negative');
+    }
+    if (item.scale > scale) {
+      scale = item.scale;
+    }
+  }
+  return { ws: parsed.map((item) => item.digits * pow10n(scale - item.scale)), scale };
+}
+
+/**
+ * Distributes `rem` extra units among the buckets; `frac` are the per-bucket remainders (for
+ * 'largest').
+ */
+function distribute<T extends number | bigint>(
+  shares: T[],
+  rem: number,
+  weights: readonly (number | bigint)[],
+  frac: readonly (number | bigint)[] | null,
+  mode: Remainder,
+  one: T,
+): void {
+  if (rem === 0) {
+    return;
+  }
+  const count = shares.length;
+  const eligible: number[] = [];
+  for (let i = 0; i < count; i++) {
+    if (weights[i]! > 0) {
+      eligible.push(i);
+    }
+  }
+  const plus = (i: number, k: number) => {
+    shares[i] = (
+      typeof one === 'number' ? (shares[i] as number) + k : (shares[i] as bigint) + BigInt(k)
+    ) as T;
+  };
+  switch (mode) {
+    case 'toFirst':
+      return plus(eligible[0]!, rem);
+    case 'toLast':
+      return plus(eligible[eligible.length - 1]!, rem);
+    case 'first':
+      for (let k = 0; k < rem; k++) {
+        plus(eligible[k]!, 1);
+      }
+      return;
+    case 'last':
+      for (let k = 0; k < rem; k++) {
+        plus(eligible[eligible.length - 1 - k]!, 1);
+      }
+      return;
+    case 'largest': {
+      const remainders = frac!;
+      // Largest remainder first; equal remainders keep bucket order.
+      eligible.sort((left, right) => {
+        if (remainders[left]! !== remainders[right]!) {
+          return remainders[left]! > remainders[right]! ? -1 : 1;
+        }
+        return left - right;
+      });
+      for (let k = 0; k < rem; k++) {
+        plus(eligible[k]!, 1);
+      }
+      return;
+    }
+  }
+  throw new RangeError(`Unknown remainder strategy "${String(mode)}"`);
+}
+
+/**
+ * Splits `m` into parts proportional to `weights`. Exact: the parts always sum to `m`, and zero
+ * weights get zero. With 'largest' each part is less than one minor unit from its exact share; with
+ * 'first' and 'last', at most one unit. Negative amounts are allocated as the negation of the
+ * positive allocation. These properties are proved for a Lean model of this function
+ * (proofs/Ducat/Allocate.lean), and test/allocate.oracle.test.ts checks this code against that
+ * model.
+ *
+ *     allocate(money('100', 'EUR'), [1, 1, 1])        // 33.34, 33.33, 33.33
+ *     allocate(money('0.05', 'EUR'), ['70', '30'])    // 0.04, 0.01
+ */
+export function allocate<C extends string>(
+  money: Money<C>,
+  weights: readonly Weight[],
+  options?: AllocateOptions,
+): Money<C>[] {
+  const count = weights.length;
+  if (count === 0) {
+    throw new RangeError('allocate() needs at least one weight');
+  }
+  const mode = options?.remainder ?? 'largest';
+  if (money.minor < 0) {
+    return allocate(negate(money), weights, options).map(negate);
+  }
+  const minor = money.minor;
+
+  // fast path: integer weights whose products with the amount fit exactly in a double
+  if (typeof minor === 'number') {
+    let total = 0;
+    let maxWeight = 0;
+    let ok = true;
+    for (let i = 0; i < count; i++) {
+      const weight = weights[i];
+      if (typeof weight !== 'number' || !(weight >= 0) || !Number.isSafeInteger(weight)) {
+        ok = false;
+        break;
+      }
+      total += weight;
+      if (weight > maxWeight) {
+        maxWeight = weight;
+      }
+    }
+    if (ok && total > 0 && total <= MAX_SAFE_MINOR && minor * maxWeight <= MAX_SAFE_MINOR - total) {
+      const ws = weights as readonly number[];
+      const shares = new Array<number>(count);
+      const frac = new Array<number>(count);
+      let rem = minor;
+      for (let i = 0; i < count; i++) {
+        const product = minor * ws[i]!;
+        let quotient = Math.floor(product / total);
+        let remainder = product - quotient * total;
+        if (remainder < 0) {
+          quotient -= 1;
+          remainder += total;
+        } else if (remainder >= total) {
+          quotient += 1;
+          remainder -= total;
+        } // float-quotient fix-up
+        shares[i] = quotient;
+        frac[i] = remainder;
+        rem -= quotient;
+      }
+      if (rem > 0) {
+        if (mode === 'largest' && count <= 32) {
+          // selection instead of sort: rem < number of non-zero weights, n small
+          for (; rem > 0; rem--) {
+            let best = -1;
+            for (let i = 0; i < count; i++) {
+              if (ws[i]! > 0 && frac[i]! >= 0 && (best < 0 || frac[i]! > frac[best]!)) {
+                best = i;
+              }
+            }
+            shares[best]! += 1;
+            frac[best] = -1;
+          }
+        } else {
+          distribute(shares, rem, ws, frac, mode, 1);
+        }
+      }
+      const out = new Array<Money<C>>(count);
+      for (let i = 0; i < count; i++) {
+        out[i] = make(money.currency, shares[i]!, money.scale);
+      }
+      return out;
+    }
+  }
+
+  const ws = weightsToBig(weights);
+  let total = 0n;
+  for (const weight of ws) {
+    total += weight;
+  }
+  if (total === 0n) {
+    throw new RangeError('Allocation weights must not all be zero');
+  }
+  const xb = BigInt(minor);
+  const shares: bigint[] = new Array(count);
+  const frac: bigint[] = new Array(count);
+  let assigned = 0n;
+  for (let i = 0; i < count; i++) {
+    const product = xb * ws[i]!;
+    shares[i] = product / total;
+    frac[i] = product % total;
+    assigned += shares[i]!;
+  }
+  distribute(shares, Number(xb - assigned), ws, frac, mode, 1n);
+  return shares.map((share) => make(money.currency, share, money.scale));
+}
+
+/** Splits into `count` equal parts; the remainder goes per `remainder` (default 'first'). */
+export function split<C extends string>(
+  money: Money<C>,
+  count: number,
+  options?: AllocateOptions,
+): Money<C>[] {
+  if (!Number.isSafeInteger(count) || count < 1) {
+    throw new RangeError(`Invalid count ${count}`);
+  }
+  const weights = new Array<number>(count).fill(1);
+  return allocate(money, weights, { remainder: options?.remainder ?? 'first' });
+}
+
+/**
+ * Options for `instalments`: where the remainder goes, and an optional unit every regular
+ * instalment is a multiple of.
+ */
+export interface InstalmentOptions<C extends string> {
+  /** Where the remainder goes: default 'toFirst' (first instalment absorbs it). */
+  readonly remainder?: Exclude<Remainder, 'largest'>;
+  /** Make every regular instalment a multiple of this (e.g. money('1', 'EUR') for whole euros). */
+  readonly unit?: Money<C>;
+}
+
+/**
+ * Instalment plan: `count` equal payments, one of which absorbs the remainder.
+ *
+ *     instalments(money('100', 'EUR'), 3)                                   // 33.34, 33.33, 33.33
+ *     instalments(money('100', 'EUR'), 3, { remainder: 'toLast' })          // 33.33, 33.33, 33.34
+ *     instalments(money('100', 'EUR'), 3, { unit: money('1', 'EUR') })      // 34.00, 33.00, 33.00
+ */
+export function instalments<C extends string>(
+  total: Money<C>,
+  count: number,
+  options?: InstalmentOptions<NoInfer<C>>,
+): Money<C>[] {
+  if (!Number.isSafeInteger(count) || count < 1) {
+    throw new RangeError(`Invalid count ${count}`);
+  }
+  const mode = options?.remainder ?? 'toFirst';
+  const unit = options?.unit;
+  if (!unit) {
+    return allocate(total, new Array<number>(count).fill(1), { remainder: mode });
+  }
+  if (unit.currency !== total.currency) {
+    throw new CurrencyMismatchError(total.currency, unit.currency);
+  }
+  if (!(unit.minor > 0)) {
+    throw new RangeError('unit must be positive');
+  }
+  const scale = Math.max(total.scale, unit.scale);
+  const scaledTotal = toScale(total, scale);
+  const unitMinor = BigInt(scaleUp(unit.minor, scale - unit.scale));
+  const neg = scaledTotal.minor < 0;
+  const tv = BigInt(scaledTotal.minor) * (neg ? -1n : 1n);
+  const per = (tv / (unitMinor * BigInt(count))) * unitMinor;
+  const parts = new Array<bigint>(count).fill(per);
+  let left = tv - per * BigInt(count);
+  // spread whole units first (for 'first'/'last'), then the sub-unit leftover
+  if (mode === 'first' || mode === 'last') {
+    for (let k = 0; left >= unitMinor; k++, left -= unitMinor) {
+      parts[mode === 'first' ? k : count - 1 - k]! += unitMinor;
+    }
+  }
+  parts[mode === 'toLast' || mode === 'last' ? count - 1 : 0]! += left;
+  return parts.map((part) => make(total.currency, neg ? -part : part, scale));
+}
+
+/** One tranche of a `schedule`: a fixed amount, a (capped) percentage, or the rest. */
+export type Tranche<C extends string> =
+  | { readonly amount: Money<C> }
+  | { readonly percent: Weight; readonly cap?: Money<C> }
+  | { readonly rest: true };
+
+/**
+ * A payment schedule mixing fixed amounts, percentages of the total (optionally capped) and one
+ * `rest` tranche that receives whatever is left. Percent tranches are computed together with
+ * largest-remainder allocation, so no rounding mode is needed and the schedule is exact.
+ * Throws if the tranches cannot add up to exactly `total`.
+ *
+ *     schedule(money('1000', 'EUR'), [{ percent: 30 }, { amount: money('200', 'EUR') }, { rest: true }])
+ *     // 300.00, 200.00, 500.00
+ */
+export function schedule<C extends string>(
+  total: Money<C>,
+  tranches: readonly Tranche<NoInfer<C>>[],
+): Money<C>[] {
+  const pctIdx: number[] = [];
+  const pcts: Weight[] = [];
+  let restIdx = -1;
+  tranches.forEach((tranche, i) => {
+    if ('percent' in tranche) {
+      pctIdx.push(i);
+      pcts.push(tranche.percent);
+    } else if ('rest' in tranche) {
+      if (restIdx >= 0) {
+        throw new RangeError('schedule() allows only one rest tranche');
+      }
+      restIdx = i;
+    }
+  });
+  const out: (Money<C> | undefined)[] = new Array(tranches.length);
+  let left = total;
+  if (pcts.length) {
+    const { ws, scale } = weightsScaled(pcts);
+    let sum = 0n;
+    for (const weight of ws) {
+      sum += weight;
+    }
+    const hundred = 100n * pow10n(scale);
+    if (sum > hundred) {
+      throw new RangeError('schedule() percentages exceed 100');
+    }
+    const parts = allocate(
+      total,
+      [...ws, hundred - sum].map((weight) => normalizeMinor(weight)),
+    );
+    pctIdx.forEach((trancheIndex, k) => {
+      let part = parts[k]!;
+      const cap = (tranches[trancheIndex] as { cap?: Money<C> }).cap;
+      if (cap && compare(part, cap) > 0) {
+        part = cap;
+      }
+      out[trancheIndex] = part;
+      left = subtract(left, part);
+    });
+  }
+  tranches.forEach((tranche, i) => {
+    if ('amount' in tranche) {
+      out[i] = tranche.amount;
+      left = subtract(left, tranche.amount);
+    }
+  });
+  if (left.minor < 0) {
+    throw new RangeError(`schedule() tranches exceed the total by ${negate(left)}`);
+  }
+  if (restIdx >= 0) {
+    out[restIdx] = left;
+  } else if (left.minor != 0) {
+    throw new RangeError(`schedule() leaves ${left} unassigned; add { rest: true }`);
+  }
+  return out as Money<C>[];
+}
+
+/** Splits into tranches of at most `max` each: chunk(EUR 1000, EUR 300) -> 300, 300, 300, 100. */
+export function chunk<C extends string>(total: Money<C>, max: Money<NoInfer<C>>): Money<C>[] {
+  if (!(max.minor > 0)) {
+    throw new RangeError('chunk() max must be positive');
+  }
+  if (total.minor < 0) {
+    throw new RangeError('chunk() total must not be negative');
+  }
+  const out: Money<C>[] = [];
+  let left = total;
+  while (compare(left, max) > 0) {
+    out.push(max as Money<C>);
+    left = subtract(left, max);
+  }
+  if (left.minor > 0 || out.length === 0) {
+    out.push(left);
+  }
+  return out;
+}

package/src/bag.ts

@@ -0,0 +1,170 @@
+// Mixed-currency amounts: a bag of per-currency totals, converted and rounded once when a single
+// total is needed, and a cross-currency comparator through one base currency (a total preorder, so
+// sorting is well defined).
+import { exact, sumExact, type ExactMoney } from './exact.js';
+import { add, type Money } from './money.js';
+import { rateOf, type RateProvider, type RateQuery } from './provider.js';
+import type { Rate } from './rate.js';
+import type { RoundingMode } from './rounding.js';
+
+/** Options for MoneyBag#total. */
+export interface TotalOptions {
+  readonly asOf?: string | Date;
+  /** Result scale (default: the target currency's exponent). */
+  readonly scale?: number;
+}
+
+function queryFor(asOf: string | Date | undefined): RateQuery | undefined {
+  if (asOf === undefined) {
+    return undefined;
+  }
+  return { asOf };
+}
+
+/** Per-currency totals of `items`, in first-seen order. */
+export function sumByCurrency(items: Iterable<Money>): Map<string, Money> {
+  const totals = new Map<string, Money>();
+  for (const money of items) {
+    const previous = totals.get(money.currency);
+    if (previous === undefined) {
+      totals.set(money.currency, money);
+    } else {
+      totals.set(money.currency, add(previous, money));
+    }
+  }
+  return totals;
+}
+
+/** An immutable set of per-currency totals: `bag(eur10, usd5, eur2).get('EUR')` is EUR 12. */
+export class MoneyBag {
+  readonly #totals: ReadonlyMap<string, Money>;
+
+  /** @internal use bag() */
+  constructor(totals: ReadonlyMap<string, Money>) {
+    // Copied, so a caller who keeps the Map can't change an immutable bag.
+    this.#totals = new Map(totals);
+  }
+
+  /** A new bag with `items` added. */
+  add(...items: Money[]): MoneyBag {
+    return new MoneyBag(sumByCurrency([...this.#totals.values(), ...items]));
+  }
+
+  /** The total in `currency`, or undefined when the bag has none. */
+  get<C extends string>(currency: C): Money<C> | undefined {
+    return this.#totals.get(currency) as Money<C> | undefined;
+  }
+
+  /** The currencies held, in first-seen order. */
+  currencies(): string[] {
+    return [...this.#totals.keys()];
+  }
+
+  /** The per-currency totals, in first-seen order. */
+  values(): Money[] {
+    return [...this.#totals.values()];
+  }
+
+  /** Every entry converted exactly into `to` and summed. Nothing is rounded. */
+  exactTotal<To extends string>(
+    to: To,
+    provider: RateProvider,
+    options?: Pick<TotalOptions, 'asOf'>,
+  ): ExactMoney<To> {
+    const query = queryFor(options?.asOf);
+    const parts: ExactMoney<To>[] = [];
+    for (const money of this.#totals.values()) {
+      if (money.currency === to) {
+        parts.push(exact(money as Money<To>));
+      } else {
+        const rate = rateOf(provider, money.currency, to, query);
+        parts.push(exact(money).convert(rate));
+      }
+    }
+    return sumExact(parts, to);
+  }
+
+  /** The total in `to`, rounded once: `bag.total('EUR', fx, 'halfEven')`. */
+  total<To extends string>(
+    to: To,
+    provider: RateProvider,
+    rounding: RoundingMode,
+    options?: TotalOptions,
+  ): Money<To> {
+    return this.exactTotal(to, provider, options).round(rounding, options?.scale);
+  }
+
+  /** The totals as a list of Money JSON values. */
+  toJSON(): unknown[] {
+    return this.values().map((money) => money.toJSON());
+  }
+}
+
+/** A bag of the per-currency totals of `items`. */
+export function bag(...items: Money[]): MoneyBag {
+  return new MoneyBag(sumByCurrency(items));
+}
+
+/** Options for comparator(). */
+export interface ComparatorOptions {
+  /** Every amount is compared as its exact value in this currency. */
+  readonly base: string;
+  readonly asOf?: string | Date;
+}
+
+/** Converts amounts exactly into `options.base`, looking each currency's rate up once. */
+function baseConverter(
+  provider: RateProvider,
+  options: ComparatorOptions,
+): (money: Money) => ExactMoney {
+  const base = options.base;
+  const query = queryFor(options.asOf);
+  const ratesToBase = new Map<string, Rate>();
+
+  return (money) => {
+    if (money.currency === base) {
+      return exact(money);
+    }
+    let rate = ratesToBase.get(money.currency);
+    if (rate === undefined) {
+      rate = rateOf(provider, money.currency, base, query);
+      ratesToBase.set(money.currency, rate);
+    }
+    return exact(money).convert(rate);
+  };
+}
+
+/**
+ * Compares amounts in any currencies through one base currency, exactly (no rounding, so rounding
+ * makes no ties). One rate per currency makes it a total preorder, so `list.sort(comparator(fx, {
+ * base: 'USD' }))` is consistent. Pairwise conversion with bid/ask or slightly inconsistent mids is
+ * not, and Array#sort's result then differs between engines. Rates are looked up once per currency,
+ * lazily: a missing rate throws from inside `sort`, after the list may already be partly reordered.
+ * `sortByValue` looks every rate up first.
+ */
+export function comparator(
+  provider: RateProvider,
+  options: ComparatorOptions,
+): (money: Money, other: Money) => -1 | 0 | 1 {
+  const inBase = baseConverter(provider, options);
+  return (money, other) => inBase(money).compare(inBase(other));
+}
+
+/**
+ * A new array of `items` in ascending order of their value in `options.base`, as `comparator`
+ * orders them. Every amount is converted before sorting, so a missing rate throws
+ * RateUnavailableError before anything is reordered, and each amount is converted only once.
+ *
+ *     sortByValue([jpy100, gbp1, usd1], fx, { base: 'EUR' })   // [jpy100, usd1, gbp1]
+ */
+export function sortByValue<Item extends Money>(
+  items: Iterable<Item>,
+  provider: RateProvider,
+  options: ComparatorOptions,
+): Item[] {
+  const inBase = baseConverter(provider, options);
+  const keyed = Array.from(items, (item) => ({ item, value: inBase(item) }));
+  // Array#sort is stable, so equal values keep their input order.
+  keyed.sort((first, second) => first.value.compare(second.value));
+  return keyed.map((entry) => entry.item);
+}

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