@ducatjs/money 0.0.0 → 0.2.0

package/dist/exact.js

@@ -0,0 +1,147 @@
+// ExactMoney: an exact rational amount for chains of arithmetic that should round once, at the end.
+// It has no formatting, JSON or minor units on purpose: it must be rounded back to Money before it
+// leaves the process.
+import { currencyExponent } from './currency.js';
+import { pow10n, ratio } from './decimal.js';
+import { CurrencyMismatchError, make } from './money.js';
+import { DEFAULT_ROUNDING, divideAndRoundBigint } from './rounding.js';
+/**
+ * An exact amount of `currency`: num/den major units, reduced, den > 0. Build it with `exact()`.
+ */
+export class ExactMoney {
+    currency;
+    num;
+    den;
+    /** @internal use exact() */
+    constructor(currency, numerator, denominator) {
+        const reduced = ratio(numerator, denominator); // reduces and makes the denominator positive
+        this.currency = currency;
+        this.num = reduced.num;
+        this.den = reduced.den;
+    }
+    /** this + other, exactly. */
+    add(other) {
+        assertSameCurrency(this, other);
+        const numerator = this.num * other.den + other.num * this.den;
+        return new ExactMoney(this.currency, numerator, this.den * other.den);
+    }
+    /** this − other, exactly. */
+    subtract(other) {
+        return this.add(other.negate());
+    }
+    /** −this. */
+    negate() {
+        return new ExactMoney(this.currency, -this.num, this.den);
+    }
+    /** this × factor, exactly. */
+    multiply(factor) {
+        const factorRatio = ratio(factor);
+        return new ExactMoney(this.currency, this.num * factorRatio.num, this.den * factorRatio.den);
+    }
+    /** this ÷ divisor, exactly. */
+    divide(divisor) {
+        const divisorRatio = ratio(divisor);
+        if (divisorRatio.num === 0n) {
+            throw new RangeError('Division by zero');
+        }
+        return new ExactMoney(this.currency, this.num * divisorRatio.den, this.den * divisorRatio.num);
+    }
+    /** Converts exactly at `rate`; nothing is rounded. */
+    convert(rate) {
+        if (rate.from !== this.currency) {
+            throw new CurrencyMismatchError(rate.from, this.currency);
+        }
+        return new ExactMoney(rate.to, this.num * rate.ratio.num, this.den * rate.ratio.den);
+    }
+    /** −1, 0 or 1. */
+    compare(other) {
+        assertSameCurrency(this, other);
+        // Both denominators are positive, so cross-multiplying keeps the order.
+        const left = this.num * other.den;
+        const right = other.num * this.den;
+        if (left < right) {
+            return -1;
+        }
+        if (left > right) {
+            return 1;
+        }
+        return 0;
+    }
+    /** Same currency and the same exact value. */
+    equals(other) {
+        return this.currency === other.currency && this.num === other.num && this.den === other.den;
+    }
+    /** −1, 0 or 1. */
+    sign() {
+        if (this.num > 0n) {
+            return 1;
+        }
+        if (this.num < 0n) {
+            return -1;
+        }
+        return 0;
+    }
+    /** Whether the amount is zero. */
+    isZero() {
+        return this.num === 0n;
+    }
+    /** Whether the amount fits `scale` (default: the currency's exponent) without rounding. */
+    isExact(scale = currencyExponent(this.currency)) {
+        return (this.num * pow10n(scale)) % this.den === 0n;
+    }
+    /** Rounds once to `scale` (default: the currency's exponent). */
+    round(rounding = DEFAULT_ROUNDING, scale = currencyExponent(this.currency)) {
+        const minor = divideAndRoundBigint(this.num * pow10n(scale), this.den, rounding);
+        return make(this.currency, minor, scale);
+    }
+    /** Rounds once and reports the difference, for booking it (e.g. an "FX rounding" ledger line). */
+    roundWithResidual(rounding = DEFAULT_ROUNDING, scale) {
+        const value = this.round(rounding, scale);
+        const residual = this.subtract(exact(value));
+        return { value, residual };
+    }
+    /** "10/3 EUR", for debugging only. */
+    toString() {
+        if (this.den === 1n) {
+            return `${this.num} ${this.currency}`;
+        }
+        return `${this.num}/${this.den} ${this.currency}`;
+    }
+    /** Blocks `a + b` and `a > b`: round() first. */
+    [Symbol.toPrimitive](hint) {
+        if (hint === 'string') {
+            return this.toString();
+        }
+        throw new TypeError('ExactMoney cannot be converted to a number; round() it first');
+    }
+}
+function assertSameCurrency(money, other) {
+    if (money.currency !== other.currency) {
+        throw new CurrencyMismatchError(money.currency, other.currency);
+    }
+}
+/**
+ * The exact value of `money`, for chained arithmetic: `exact(price).divide(3).round('halfEven')`.
+ */
+export function exact(money) {
+    return new ExactMoney(money.currency, BigInt(money.minor), pow10n(money.scale));
+}
+/**
+ * The exact sum (zero of `currency` for an empty list). Round it once for a batch's rounding line.
+ */
+export function sumExact(items, currency) {
+    const sumCurrency = currency ?? items[0]?.currency;
+    if (sumCurrency === undefined) {
+        throw new RangeError('sumExact of an empty list needs a currency');
+    }
+    let sum = new ExactMoney(sumCurrency, 0n, 1n);
+    for (const item of items) {
+        sum = sum.add(item);
+    }
+    return sum;
+}
+/** Whether `value` is an ExactMoney. */
+export function isExactMoney(value) {
+    return value instanceof ExactMoney;
+}
+//# sourceMappingURL=exact.js.map

package/dist/exact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact.js","sourceRoot":"","sources":["../src/exact.ts"],"names":[],"mappings":"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"}

package/dist/fed.d.ts

@@ -0,0 +1,35 @@
+import type { RateTable } from './provider.js';
+/**
+ * Parses the Federal Reserve Board's H.10 daily foreign exchange rates, as CSV from its Data
+ * Download Program (DDP), into one USD-based table per day, newest first. These are the noon
+ * buying rates in New York, certified by the New York Fed for customs purposes, with `source:
+ * 'FRB'` and `type: 'noon buying'`, back to 1971.
+ *
+ * - **Direction.** H.10 quotes "currency units per U.S. dollar except as noted": AUD, EUR, NZD and
+ *   GBP (series `RXI$US_N.B.*`) are USD per unit. Those four are stored as exact inverses, so
+ *   every table is USD → currency, and the published quote stays on the rate:
+ *   `rate('USD', 'EUR').inverse().toString()` is '1.1750' again.
+ * - **Holidays** are rows of `ND` ("no data"); such a day is left out, so a lookback goes on to
+ *   the day before, and a file of holidays only gives []. A single `ND` cell is a missing value.
+ *   A file with no observation rows at all throws, as it is more likely cut short than empty.
+ * - **Strict:** each column's Unit, Multiplier and Currency must be "Currency", 1 and the code
+ *   its series ID stands for (EU is EUR), a currency can't have two columns, and two different
+ *   values for one day throw.
+ * - **Digits.** H.10 publishes four decimals and keeps trailing zeros; they are kept.
+ * - **Codes.** The Fed's column codes are used as they are, so the bolivar is `VEB`, as the Fed
+ *   labels it.
+ * - **Publication.** The release is weekly (Mondays, 4:15 p.m. ET) and covers the week before,
+ *   so a Tuesday's rate is known only up to six days later. The CSV doesn't say when each row was
+ *   released, so no `availableAt` is set; give each table one yourself if a backtest needs it.
+ *
+ * **Where the data comes from.** The DDP at federalreserve.gov/datadownload (release H10, CSV,
+ * "series in columns", with labels) serves these files today. The Board is retiring the DDP: the
+ * "Build Your Package" feature goes in November 2026 and the rest later, and it points users to
+ * FRED (fred.stlouisfed.org) instead. FRED needs an API key, and its terms forbid storing or
+ * caching its content and any commercial use without consent, which is why ducat has no H.10
+ * fetcher. Board data itself is public domain ("please cite to the Board as the source").
+ *
+ *     const tables = parseFedH10Csv(await readFile('FRB_H10.csv', 'utf8'));
+ */
+export declare function parseFedH10Csv(csv: string): RateTable[];
+//# sourceMappingURL=fed.d.ts.map

package/dist/fed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fed.d.ts","sourceRoot":"","sources":["../src/fed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAqC/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,CAyEvD"}

package/dist/fed.js

@@ -0,0 +1,134 @@
+// `@ducatjs/money/convert/fed`: an offline parser for the Federal Reserve Board's H.10 foreign
+// exchange rates. Parser only, no fetcher: see parseFedH10Csv for where the files come from.
+import { quotedTable } from './history.js';
+import { addDayRate, csvRows, isCalendarDay, newestFirst, readRateCell } from './rate-text.js';
+// RXI$US_N.B.EU is USD per euro; RXI_N.B.JA is yen per USD.
+const SERIES = /^(?:H10\/H10\/)?RXI(\$US)?_N\.B\.([A-Z]{2,3})$/;
+// The country codes in H.10 series IDs, and the currency each one's column must carry.
+const FED_COUNTRIES = {
+    AL: 'AUD',
+    EU: 'EUR',
+    NZ: 'NZD',
+    UK: 'GBP',
+    BZ: 'BRL',
+    CA: 'CAD',
+    CH: 'CNY',
+    DN: 'DKK',
+    HK: 'HKD',
+    IN: 'INR',
+    JA: 'JPY',
+    MA: 'MYR',
+    MX: 'MXN',
+    NO: 'NOK',
+    SF: 'ZAR',
+    SI: 'SGD',
+    KO: 'KRW',
+    SL: 'LKR',
+    SD: 'SEK',
+    SZ: 'CHF',
+    TA: 'TWD',
+    TH: 'THB',
+    VES: 'VEB',
+};
+function notH10(why) {
+    throw new SyntaxError(`Not a Federal Reserve H.10 CSV file: ${why}`);
+}
+/**
+ * Parses the Federal Reserve Board's H.10 daily foreign exchange rates, as CSV from its Data
+ * Download Program (DDP), into one USD-based table per day, newest first. These are the noon
+ * buying rates in New York, certified by the New York Fed for customs purposes, with `source:
+ * 'FRB'` and `type: 'noon buying'`, back to 1971.
+ *
+ * - **Direction.** H.10 quotes "currency units per U.S. dollar except as noted": AUD, EUR, NZD and
+ *   GBP (series `RXI$US_N.B.*`) are USD per unit. Those four are stored as exact inverses, so
+ *   every table is USD → currency, and the published quote stays on the rate:
+ *   `rate('USD', 'EUR').inverse().toString()` is '1.1750' again.
+ * - **Holidays** are rows of `ND` ("no data"); such a day is left out, so a lookback goes on to
+ *   the day before, and a file of holidays only gives []. A single `ND` cell is a missing value.
+ *   A file with no observation rows at all throws, as it is more likely cut short than empty.
+ * - **Strict:** each column's Unit, Multiplier and Currency must be "Currency", 1 and the code
+ *   its series ID stands for (EU is EUR), a currency can't have two columns, and two different
+ *   values for one day throw.
+ * - **Digits.** H.10 publishes four decimals and keeps trailing zeros; they are kept.
+ * - **Codes.** The Fed's column codes are used as they are, so the bolivar is `VEB`, as the Fed
+ *   labels it.
+ * - **Publication.** The release is weekly (Mondays, 4:15 p.m. ET) and covers the week before,
+ *   so a Tuesday's rate is known only up to six days later. The CSV doesn't say when each row was
+ *   released, so no `availableAt` is set; give each table one yourself if a backtest needs it.
+ *
+ * **Where the data comes from.** The DDP at federalreserve.gov/datadownload (release H10, CSV,
+ * "series in columns", with labels) serves these files today. The Board is retiring the DDP: the
+ * "Build Your Package" feature goes in November 2026 and the rest later, and it points users to
+ * FRED (fred.stlouisfed.org) instead. FRED needs an API key, and its terms forbid storing or
+ * caching its content and any commercial use without consent, which is why ducat has no H.10
+ * fetcher. Board data itself is public domain ("please cite to the Board as the source").
+ *
+ *     const tables = parseFedH10Csv(await readFile('FRB_H10.csv', 'utf8'));
+ */
+export function parseFedH10Csv(csv) {
+    const rows = csvRows(csv.charCodeAt(0) === 0xfeff ? csv.slice(1) : csv);
+    const series = rows.find((cells) => cells[0]?.trim() === 'Time Period') ?? notH10('no "Time Period" row');
+    const labelled = (label) => {
+        const row = rows.find((cells) => cells[0]?.trim() === label);
+        if (row === undefined || row.length !== series.length) {
+            notH10(`no "${label}" row matching the columns`);
+        }
+        return row;
+    };
+    const currencies = labelled('Currency:');
+    const multipliers = labelled('Multiplier:');
+    const units = labelled('Unit:');
+    // Each column: its currency, and whether it is quoted as USD per unit (to be inverted).
+    const columns = [];
+    for (let i = 1; i < series.length; i++) {
+        const id = SERIES.exec(series[i].trim());
+        const currency = currencies[i].trim();
+        if (id === null || !/^[A-Z]{3}$/.test(currency) || currency === 'USD') {
+            notH10(`column ${i + 1} is ${series[i]} for ${currency}`);
+        }
+        // The series ID names the country; it must agree with the currency code beside it.
+        const expected = FED_COUNTRIES[id[2]];
+        if (expected !== undefined && expected !== currency) {
+            notH10(`series ${series[i]} is ${expected}, not ${currency}`);
+        }
+        if (columns.some((column) => column.currency === currency)) {
+            notH10(`${currency} has two columns`);
+        }
+        // Other units or a multiplier other than 1 would make the published number mean something else.
+        if (units[i].trim() !== 'Currency' || multipliers[i].trim() !== '1') {
+            throw new SyntaxError(`Unsupported H.10 unit ${units[i]} × ${multipliers[i]} for ${currency}`);
+        }
+        columns.push({ currency, inverted: id[1] !== undefined });
+    }
+    const observations = rows.slice(rows.indexOf(series) + 1);
+    if (observations.length === 0) {
+        notH10('no observations');
+    }
+    const days = new Map();
+    for (const cells of observations) {
+        const day = cells[0].trim();
+        if (!isCalendarDay(day) || cells.length !== series.length) {
+            throw new SyntaxError(`Malformed H.10 row: ${cells.join(',')}`);
+        }
+        columns.forEach(({ currency }, i) => {
+            addDayRate(days, day, currency, readRateCell(cells[i + 1], `${currency} on ${day}`));
+        });
+    }
+    const tables = [];
+    for (const [day, published] of days) {
+        const rates = {};
+        let quoted = 0;
+        for (const { currency, inverted } of columns) {
+            const rate = published[currency] ?? null;
+            rates[currency] = rate === null ? null : { rate, inverted };
+            if (rate !== null) {
+                quoted++;
+            }
+        }
+        if (quoted > 0) {
+            tables.push(quotedTable({ base: 'USD', source: 'FRB', type: 'noon buying', asOf: day, rates }));
+        }
+    }
+    return newestFirst(tables);
+}
+//# sourceMappingURL=fed.js.map

package/dist/fed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fed.js","sourceRoot":"","sources":["../src/fed.ts"],"names":[],"mappings":"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"}

package/dist/fetch.d.ts

@@ -0,0 +1,103 @@
+import type { RateTable } from './provider.js';
+/**
+ * The part of the platform AbortSignal used here. Declared structurally so the library needs no DOM
+ * or Node types; any real AbortSignal fits.
+ */
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+    readonly reason?: unknown;
+    addEventListener(type: 'abort', listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+}
+/** The subset of the platform fetch used here (Node 24+, Deno, Bun, browsers, workers). */
+export type Fetch = (url: string, init?: {
+    signal?: AbortSignalLike;
+    headers?: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** The ECB's eurofxref files: the latest day, the last 90 days, and the full history since 1999. */
+export declare const ECB_URLS: {
+    readonly daily: "https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml";
+    readonly '90d': "https://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist-90d.xml";
+    readonly all: "https://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist.xml";
+};
+/** Options for fetching ECB reference rates. */
+export interface FetchEcbOptions {
+    /** 'daily' (default): the latest day; '90d': the last 90 days; 'all': since 1999 (several MB). */
+    readonly history?: keyof typeof ECB_URLS;
+    /** An AbortSignal to cancel the request; it is combined with the timeout. */
+    readonly signal?: AbortSignalLike;
+    /**
+     * Milliseconds before the request is aborted (default 30 000; 0 for no timeout). It needs the
+     * platform's AbortSignal.timeout, which Node 24, Deno, Bun and current browsers all have.
+     */
+    readonly timeout?: number;
+    /** A fetch to use instead of the global one (for proxies, retries or tests). */
+    readonly fetch?: Fetch;
+}
+/** Thrown when the HTTP request completes without a 2xx status. */
+export declare class FetchRatesError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(url: string, status: number);
+}
+/**
+ * Fetches the ECB euro reference rates and parses them with parseEcbXml: EUR-based tables,
+ * newest first. The ECB publishes once per TARGET working day at about 16:00 CET and states
+ * that its rates are for information purposes only.
+ *
+ *     const [latest] = await fetchEcb(); // the RateTable for the last published day
+ *     const hist = snapshotsFrom(await fetchEcb({ history: '90d' }));
+ */
+export declare function fetchEcb(options?: FetchEcbOptions): Promise<RateTable[]>;
+/** The ECB Data Portal's SDMX REST API (no key, and CORS-enabled, so it works in browsers). */
+export declare const ECB_DATA_API = "https://data-api.ecb.europa.eu/service/data/EXR";
+/** Options for fetching a date range of ECB reference rates. */
+export interface FetchEcbRangeOptions extends Omit<FetchEcbOptions, 'history'> {
+    /** The first day ('1999-01-04' at the earliest). */
+    readonly start: string | Date;
+    /** The last day (default: the latest published). */
+    readonly end?: string | Date;
+    /** ISO codes to fetch (default: every currency, including discontinued series). */
+    readonly currencies?: readonly string[];
+}
+/**
+ * Fetches a date range of ECB euro reference rates from the ECB Data Portal and parses them with
+ * parseEcbSdmxCsv: EUR-based tables, one per TARGET working day, newest first, with the published
+ * digits. It makes two requests: the series' DECIMALS (small) and the observations without
+ * attributes, which keeps the full history since 1999 to about 15 MB. Give a few days before the
+ * first day you need, so that a lookback from it has a table to fall back on. A range with no
+ * rates (a weekend, or after the latest day) gives []. Both requests share one timeout and are
+ * cancelled together: if one fails, the other is aborted. The ECB states that its rates are for
+ * information purposes only.
+ *
+ *     const tables = await fetchEcbRange({ start: '2026-01-01', currencies: ['USD', 'JPY'] });
+ *     const history = rateHistory(tables); // from @ducatjs/money/convert/history
+ */
+export declare function fetchEcbRange(options: FetchEcbRangeOptions): Promise<RateTable[]>;
+/** The Bank of Canada's Valet API for its daily exchange rates (no key; CORS-enabled). */
+export declare const BANK_OF_CANADA_URL = "https://www.bankofcanada.ca/valet/observations/group/FX_RATES_DAILY/json";
+/** Options for fetching Bank of Canada rates. */
+export interface FetchBankOfCanadaOptions extends Omit<FetchEcbOptions, 'history'> {
+    /** The first day (2017-01-03 at the earliest). Default: only the latest published day. */
+    readonly start?: string | Date;
+    /** The last day (default: the latest published). Needs a `start`. */
+    readonly end?: string | Date;
+}
+/**
+ * Fetches the Bank of Canada's daily exchange rates from its Valet API and parses them with
+ * parseBankOfCanadaJson: CAD-based tables, newest first. Without `start`, only the latest day;
+ * without `end`, up to the latest. A range with no business days in it gives [].
+ * The Bank asks users to keep within its request limits, which it doesn't publish, and its rates
+ * are "released for statistical and analytical purposes only", not for transactions.
+ *
+ *     const [latest] = await fetchBankOfCanada();
+ *     const year = await fetchBankOfCanada({ start: '2026-01-01' });
+ */
+export declare function fetchBankOfCanada(options?: FetchBankOfCanadaOptions): Promise<RateTable[]>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1F,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChE;AAED,2FAA2F;AAC3F,MAAM,MAAM,KAAK,GAAG,CAClB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KAClE,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAAC;AAUvE,oGAAoG;AACpG,eAAO,MAAM,QAAQ;;;;CAIX,CAAC;AAEX,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,kGAAkG;IAClG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,OAAO,QAAQ,CAAC;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED,mEAAmE;AACnE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBACT,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMxC;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAI9E;AA0BD,+FAA+F;AAC/F,eAAO,MAAM,YAAY,oDAAoD,CAAC;AAE9E,gEAAgE;AAChE,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC;IAC5E,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mFAAmF;IACnF,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AA2ED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAyDvF;AAED,0FAA0F;AAC1F,eAAO,MAAM,kBAAkB,6EAC6C,CAAC;AAE7E,iDAAiD;AACjD,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC;IAChF,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBhG"}