@ducatjs/money 0.1.0 → 0.2.0

package/dist/sql.d.ts

@@ -0,0 +1,54 @@
+import { type Money } from './money.js';
+/** 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 declare const DEFAULT_DECIMAL_SIZE: DecimalColumnSize;
+/** Throws unless the money is in the column's currency (when the column has a fixed currency). */
+export declare function checkCurrency(money: Money, currency: string | undefined): void;
+/**
+ * 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 declare function checkIsoScale(money: Money): void;
+/**
+ * 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 declare function minorToDriver(money: Money, currency: string | undefined): bigint;
+/**
+ * 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 declare function minorFromDriver<C extends string>(value: unknown, currency: C): Money<C>;
+/** Throws if a decimal column of this size would round amounts in this currency. */
+export declare function checkDecimalSize(currency: string, size: DecimalColumnSize): void;
+/**
+ * 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 declare function decimalToDriver(money: Money, currency: string | undefined, size: DecimalColumnSize | undefined): string;
+/**
+ * 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 declare function checkIntegerDigits(money: Money, decimal: string, size: DecimalColumnSize): void;
+/**
+ * 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 declare function decimalFromDriver<C extends string>(value: unknown, currency: C): Money<C>;
+/** `{"amount":"12.34","currency":"EUR"}` for a JSON, JSONB or TEXT column. */
+export declare function jsonToDriver(money: Money, currency: string | undefined): string;
+/**
+ * Money from a JSON column: the parsed object (JSONB in node-postgres, JSON in mysql2) or the
+ * text (SQLite).
+ */
+export declare function jsonFromDriver<C extends string>(value: unknown, currency: C | undefined): Money<C>;
+//# sourceMappingURL=sql.d.ts.map

package/dist/sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../src/sql.ts"],"names":[],"mappings":"AAKA,OAAO,EAOL,KAAK,KAAK,EAEX,MAAM,YAAY,CAAC;AAOpB,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,EAAE,iBAA+C,CAAC;AAEnF,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAI9E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAOhD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAShF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAWvF;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAkBhF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,iBAAiB,GAAG,SAAS,GAClC,MAAM,CASR;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAU/F;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAQzF;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI/E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAC7C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,CAAC,GAAG,SAAS,GACtB,KAAK,CAAC,CAAC,CAAC,CAOV"}

package/dist/sql.js

@@ -0,0 +1,131 @@
+// 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, } 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;
+/** NUMERIC(19,4): 15 integer digits and 4 decimals, enough for every ISO 4217 exponent. */
+export const DEFAULT_DECIMAL_SIZE = { 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, currency) {
+    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) {
+    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, currency) {
+    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(value, currency) {
+    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, size) {
+    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, currency, size) {
+    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, decimal, size) {
+    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(value, currency) {
+    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, currency) {
+    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(value, currency) {
+    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);
+    checkCurrency(parsed, currency);
+    return parsed;
+}
+//# sourceMappingURL=sql.js.map

package/dist/sql.js.map

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

package/dist/tax.d.ts

@@ -1,11 +1,10 @@
 import { type Factor } from './decimal.js';
-import { type Money } from './money.js';
-import { type RoundingMode } from './rounding.js';
+import { type Money, type RoundingInput } from './money.js';
 /**
  * percent% of m: percentage(EUR 80, '12.5', 'halfEven') = EUR 10.00. Rounding defaults to
  * 'halfExpand'.
  */
-export declare function percentage<C extends string>(money: Money<C>, percent: Factor, rounding?: RoundingMode): Money<C>;
+export declare function percentage<C extends string>(money: Money<C>, percent: Factor, rounding?: RoundingInput): Money<C>;
 /** A tax split: net + tax is always exactly gross. */
 export interface TaxBreakdown<C extends string> {
     readonly net: Money<C>;
@@ -15,15 +14,20 @@ export interface TaxBreakdown<C extends string> {
 }
 /**
  * Tax-exclusive: adds percent% tax to a net amount. addTax(EUR 10, '20', 'halfEven') -> net 10, tax
- * 2, gross 12.
+ * 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 declare function addTax<C extends string>(net: Money<C>, percent: Factor, rounding?: RoundingMode): TaxBreakdown<C>;
+export declare function addTax<C extends string>(net: Money<C>, percent: Factor, rounding?: RoundingInput): TaxBreakdown<C>;
 /**
  * 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.
+ * 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 declare function extractTax<C extends string>(gross: Money<C>, percent: Factor, rounding?: RoundingMode): TaxBreakdown<C>;
-/** Price after a percent% discount; the discount amount is rounded with `rounding`. */
-export declare function discount<C extends string>(price: Money<C>, percent: Factor, rounding?: RoundingMode): Money<C>;
+export declare function extractTax<C extends string>(gross: Money<C>, percent: Factor, rounding?: RoundingInput): TaxBreakdown<C>;
+/**
+ * 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 declare function discount<C extends string>(price: Money<C>, percent: Factor, rounding?: RoundingInput): Money<C>;
 //# sourceMappingURL=tax.d.ts.map

package/dist/tax.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tax.d.ts","sourceRoot":"","sources":["../src/tax.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,MAAM,EAAc,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAkC,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAOpE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,YAA+B,GACxC,KAAK,CAAC,CAAC,CAAC,CAEV;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM;IAC5C,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EACrC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,YAA+B,GACxC,YAAY,CAAC,CAAC,CAAC,CAIjB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,YAA+B,GACxC,YAAY,CAAC,CAAC,CAAC,CASjB;AAED,uFAAuF;AACvF,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,YAA+B,GACxC,KAAK,CAAC,CAAC,CAAC,CAEV"}
+{"version":3,"file":"tax.d.ts","sourceRoot":"","sources":["../src/tax.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,MAAM,EAAc,MAAM,cAAc,CAAC;AAC9D,OAAO,EAKL,KAAK,KAAK,EACV,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,aAAgC,GACzC,KAAK,CAAC,CAAC,CAAC,CAEV;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM;IAC5C,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EACrC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,aAAgC,GACzC,YAAY,CAAC,CAAC,CAAC,CAejB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,aAAgC,GACzC,YAAY,CAAC,CAAC,CAAC,CASjB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,aAAgC,GACzC,KAAK,CAAC,CAAC,CAAC,CAUV"}

package/dist/tax.js

@@ -1,5 +1,5 @@
 import { ratio } from './decimal.js';
-import { add, multiplyByRatio, subtract } from './money.js';
+import { add, multiplyByRatio, roundWithPolicy, subtract, } from './money.js';
 import { DEFAULT_ROUNDING } from './rounding.js';
 const percentRatio = (percent) => {
     const asRatio = ratio(percent);
@@ -14,9 +14,17 @@ export function percentage(money, percent, rounding = DEFAULT_ROUNDING) {
 }
 /**
  * Tax-exclusive: adds percent% tax to a net amount. addTax(EUR 10, '20', 'halfEven') -> net 10, tax
- * 2, gross 12.
+ * 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(net, percent, rounding = DEFAULT_ROUNDING) {
+    // 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 };
@@ -24,7 +32,8 @@ export function addTax(net, percent, rounding = DEFAULT_ROUNDING) {
 /**
  * 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.
+ * 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(gross, percent, rounding = DEFAULT_ROUNDING) {
     const percentAsRatio = ratio(percent);
@@ -32,8 +41,15 @@ export function extractTax(gross, percent, rounding = DEFAULT_ROUNDING) {
     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; the discount amount is rounded with `rounding`. */
+/**
+ * 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(price, percent, rounding = DEFAULT_ROUNDING) {
+    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));
 }
 //# sourceMappingURL=tax.js.map

package/dist/tax.js.map

@@ -1 +1 @@
-{"version":3,"file":"tax.js","sourceRoot":"","sources":["../src/tax.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAA2B,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,GAAG,EAAE,eAAe,EAAE,QAAQ,EAAc,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAqB,MAAM,eAAe,CAAC;AAEpE,MAAM,YAAY,GAAG,CAAC,OAAe,EAAS,EAAE;IAC9C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;AAChD,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,KAAe,EACf,OAAe,EACf,WAAyB,gBAAgB;IAEzC,OAAO,eAAe,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC;AAUD;;;GAGG;AACH,MAAM,UAAU,MAAM,CACpB,GAAa,EACb,OAAe,EACf,WAAyB,gBAAgB;IAEzC,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5B,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,KAAe,EACf,OAAe,EACf,WAAyB,gBAAgB;IAEzC,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IACtC,8CAA8C;IAC9C,MAAM,GAAG,GAAG,eAAe,CACzB,KAAK,EACL,KAAK,CAAC,IAAI,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,GAAG,cAAc,CAAC,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,EAChF,QAAQ,CACT,CAAC;IACF,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC;AACnD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,QAAQ,CACtB,KAAe,EACf,OAAe,EACf,WAAyB,gBAAgB;IAEzC,OAAO,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;AAClF,CAAC"}
+{"version":3,"file":"tax.js","sourceRoot":"","sources":["../src/tax.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAA2B,MAAM,cAAc,CAAC;AAC9D,OAAO,EACL,GAAG,EACH,eAAe,EACf,eAAe,EACf,QAAQ,GAGT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,YAAY,GAAG,CAAC,OAAe,EAAS,EAAE;IAC9C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;AAChD,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,KAAe,EACf,OAAe,EACf,WAA0B,gBAAgB;IAE1C,OAAO,eAAe,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC;AAUD;;;;GAIG;AACH,MAAM,UAAU,MAAM,CACpB,GAAa,EACb,OAAe,EACf,WAA0B,gBAAgB;IAE1C,gGAAgG;IAChG,iGAAiG;IACjG,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACnC,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,eAAe,CAC3B,GAAG,EACH,KAAK,CAAC,IAAI,GAAG,cAAc,CAAC,GAAG,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,EAChF,QAAQ,CACT,CAAC;QACF,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5B,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,KAAe,EACf,OAAe,EACf,WAA0B,gBAAgB;IAE1C,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IACtC,8CAA8C;IAC9C,MAAM,GAAG,GAAG,eAAe,CACzB,KAAK,EACL,KAAK,CAAC,IAAI,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,GAAG,cAAc,CAAC,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,EAChF,QAAQ,CACT,CAAC;IACF,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAe,EACf,OAAe,EACf,WAA0B,gBAAgB;IAE1C,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACnC,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,OAAO,eAAe,CACpB,KAAK,EACL,KAAK,CAAC,IAAI,GAAG,cAAc,CAAC,GAAG,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,EAChF,QAAQ,CACT,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;AAClF,CAAC"}

package/dist/testing/arbitraries.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `@ducatjs/money/testing/arbitraries`: fast-check arbitraries for property tests. They cover what
+ * hand-written cases tend to miss: amounts beyond 2^53 (bigint minor units), currencies with
+ * unusual exponents (JPY 0, KWD 3, CLF 4) and scales above the currency's exponent. fast-check is
+ * an optional peer dependency, needed only for this entry.
+ */
+import fc from 'fast-check';
+import { type Money } from '../money.js';
+/** Options for `arbCurrency`. */
+export interface ArbCurrencyOptions {
+    /** Only currencies with one of these exponents (default: the representative mix). */
+    readonly exponents?: readonly number[];
+    /** Draw from every ISO 4217 code instead of the representative mix. */
+    readonly all?: boolean;
+    /** More codes to draw from, such as ones registered with `defineCurrency`. */
+    readonly extra?: readonly string[];
+}
+/**
+ * Currency codes, by default a representative mix of exponents 0, 2, 3 and 4 (JPY, EUR, KWD,
+ * CLF...). `{ all: true }` draws from every ISO 4217 code, `extra` adds codes (custom ones from
+ * `defineCurrency`), and `exponents` narrows whichever pool that is.
+ */
+export declare function arbCurrency(options?: ArbCurrencyOptions): fc.Arbitrary<string>;
+/** Options for `arbMoney`. */
+export interface ArbMoneyOptions<C extends string = string> {
+    /** The currency, or an arbitrary of currencies (default: `arbCurrency()`). */
+    readonly currency?: C | fc.Arbitrary<C>;
+    /** The smallest amount, in major units (default: none, down to -10^30 minor units). */
+    readonly min?: string | number | bigint;
+    /** The largest amount, in major units (default: none, up to 10^30 minor units). */
+    readonly max?: string | number | bigint;
+    /**
+     * The scale, or an arbitrary of scales. By default mostly the currency's exponent, sometimes up
+     * to three more decimals.
+     */
+    readonly scale?: number | fc.Arbitrary<number>;
+}
+/**
+ * Money values for property tests: `arbMoney()`, `arbMoney({ currency: 'EUR', min: '0', max:
+ * '100' })`. With bounds, every value is within them; without, minor units reach ±10^30.
+ */
+export declare function arbMoney<C extends string = string>(options?: ArbMoneyOptions<C>): fc.Arbitrary<Money<C>>;
+//# sourceMappingURL=arbitraries.d.ts.map

package/dist/testing/arbitraries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbitraries.d.ts","sourceRoot":"","sources":["../../src/testing/arbitraries.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5B,OAAO,EAAoB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAK3D,iCAAiC;AACjC,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,uEAAuE;IACvE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAYlF;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACxD,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACxC,uFAAuF;IACvF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACxC,mFAAmF;IACnF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;CAChD;AA0BD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAChD,OAAO,GAAE,eAAe,CAAC,CAAC,CAAM,GAC/B,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CA6CxB"}

package/dist/testing/arbitraries.js

@@ -0,0 +1,98 @@
+/**
+ * `@ducatjs/money/testing/arbitraries`: fast-check arbitraries for property tests. They cover what
+ * hand-written cases tend to miss: amounts beyond 2^53 (bigint minor units), currencies with
+ * unusual exponents (JPY 0, KWD 3, CLF 4) and scales above the currency's exponent. fast-check is
+ * an optional peer dependency, needed only for this entry.
+ */
+import fc from 'fast-check';
+import { currencyExponent, ISO_EXPONENTS } from '../currency.js';
+import { MAX_DECIMAL_SCALE } from '../decimal.js';
+import { fromMinor, money } from '../money.js';
+/** A mix of exponents: the common two-decimal currencies and every unusual one. */
+const DEFAULT_CURRENCIES = ['EUR', 'USD', 'GBP', 'JPY', 'KRW', 'KWD', 'BHD', 'TND', 'CLF'];
+/**
+ * Currency codes, by default a representative mix of exponents 0, 2, 3 and 4 (JPY, EUR, KWD,
+ * CLF...). `{ all: true }` draws from every ISO 4217 code, `extra` adds codes (custom ones from
+ * `defineCurrency`), and `exponents` narrows whichever pool that is.
+ */
+export function arbCurrency(options = {}) {
+    const base = options.all === true ? Object.keys(ISO_EXPONENTS) : DEFAULT_CURRENCIES;
+    const pool = [...base, ...(options.extra ?? [])];
+    const exponents = options.exponents;
+    const codes = exponents === undefined
+        ? pool
+        : pool.filter((code) => exponents.includes(currencyExponent(code)));
+    if (codes.length === 0) {
+        throw new RangeError('No currency has the requested exponents');
+    }
+    return fc.constantFrom(...codes);
+}
+const BIG = 10n ** 30n;
+const SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+/** Minor units weighted toward the interesting places: small, near 2^53, and far beyond it. */
+function arbMinor(min, max) {
+    const clamp = (low, high) => fc.bigInt({ min: low > min ? low : min, max: high < max ? high : max });
+    const parts = [];
+    if (min <= 10000n && max >= -10000n) {
+        parts.push(clamp(-10000n, 10000n));
+    }
+    if (min <= SAFE && max >= -SAFE) {
+        parts.push(clamp(-SAFE, SAFE));
+    }
+    // within 1000 of ±2^53, where number and bigint meet
+    for (const edge of [SAFE, -SAFE]) {
+        if (min <= edge + 1000n && max >= edge - 1000n) {
+            parts.push(clamp(edge - 1000n, edge + 1000n));
+        }
+    }
+    parts.push(fc.bigInt({ min, max }));
+    return fc.oneof(...parts);
+}
+/**
+ * Money values for property tests: `arbMoney()`, `arbMoney({ currency: 'EUR', min: '0', max:
+ * '100' })`. With bounds, every value is within them; without, minor units reach ±10^30.
+ */
+export function arbMoney(options = {}) {
+    const given = options.currency;
+    let currencies;
+    if (given === undefined) {
+        currencies = arbCurrency();
+    }
+    else if (typeof given === 'string') {
+        currencies = fc.constant(given);
+    }
+    else {
+        currencies = given;
+    }
+    return currencies.chain((currency) => {
+        const exponent = currencyExponent(currency);
+        const scaleOption = options.scale;
+        let scales;
+        if (typeof scaleOption === 'number') {
+            scales = fc.constant(scaleOption);
+        }
+        else if (scaleOption === undefined) {
+            scales = fc.oneof({ weight: 3, arbitrary: fc.constant(exponent) }, { weight: 1, arbitrary: fc.integer({ min: exponent + 1, max: exponent + 3 }) });
+        }
+        else {
+            scales = scaleOption;
+        }
+        return scales.chain((scale) => {
+            if (!(Number.isInteger(scale) && scale >= 0 && scale <= MAX_DECIMAL_SCALE)) {
+                throw new RangeError(`Invalid scale ${scale}`);
+            }
+            // Bounds in minor units at this scale; a bound between two units rounds inward.
+            const min = options.min === undefined
+                ? -BIG
+                : BigInt(money(options.min, currency, { scale, rounding: 'ceil' }).toMinor());
+            const max = options.max === undefined
+                ? BIG
+                : BigInt(money(options.max, currency, { scale, rounding: 'floor' }).toMinor());
+            if (min > max) {
+                throw new RangeError(`No ${currency} amount at scale ${scale} between min and max`);
+            }
+            return arbMinor(min, max).map((minor) => fromMinor(minor, currency, scale));
+        });
+    });
+}
+//# sourceMappingURL=arbitraries.js.map

package/dist/testing/arbitraries.js.map

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

package/dist/testing/index.d.ts

@@ -0,0 +1,67 @@
+import { type Money } from '../money.js';
+/** An equality tester, as Vitest and Jest's `expect.addEqualityTesters` take them. */
+export type MoneyEqualityTester = (left: unknown, right: unknown) => boolean | undefined;
+/**
+ * Money compares by value in `toEqual`, `toStrictEqual` and nested structures: same currency and
+ * the same amount, whatever the scale (`1.0` and `1.00`) and whether the minor units are a number
+ * or a bigint. For anything other than two Money values it returns undefined, so the usual
+ * comparison applies.
+ */
+export declare const moneyEquality: MoneyEqualityTester;
+/** A snapshot serializer that prints Money as `12.34 EUR` (unquoted, so it isn't a string). */
+export declare const moneySerializer: {
+    test: (value: unknown) => boolean;
+    serialize: (value: unknown) => string;
+};
+/** What the matchers receive as `this`, the part of Vitest's and Jest's matcher state used here. */
+export interface MoneyMatcherContext {
+    readonly isNot: boolean;
+}
+/** A matcher's result, as Vitest and Jest expect it. */
+export interface MoneyMatcherResult {
+    pass: boolean;
+    message: () => string;
+    actual?: unknown;
+    expected?: unknown;
+}
+/** The money matchers, typed for `declare module` augmentation of `Assertion` / `Matchers`. */
+export interface MoneyMatchers<R = unknown> {
+    /** The value is Money equal to `amount` in `currency`, at any scale: `toBeMoney('12.34', 'EUR')`. */
+    toBeMoney(amount: string | number | bigint, currency: string): R;
+    /** The value is Money in `currency`. */
+    toHaveCurrency(currency: string): R;
+    /** The value is Money greater than `other` (same currency). */
+    toBeGreaterThanMoney(other: Money): R;
+    /** The value is Money greater than or equal to `other` (same currency). */
+    toBeGreaterThanOrEqualMoney(other: Money): R;
+    /** The value is Money less than `other` (same currency). */
+    toBeLessThanMoney(other: Money): R;
+    /** The value is Money less than or equal to `other` (same currency). */
+    toBeLessThanOrEqualMoney(other: Money): R;
+    /** The value is a list of Money that sums exactly to `total`, as allocations must. */
+    toSumTo(total: Money): R;
+}
+/** The matcher implementations, for `expect.extend`. */
+export declare const moneyMatchers: {
+    toBeMoney(this: MoneyMatcherContext, received: unknown, amount: string | number | bigint, currency: string): MoneyMatcherResult;
+    toHaveCurrency(this: MoneyMatcherContext, received: unknown, currency: string): MoneyMatcherResult;
+    toBeGreaterThanMoney: (this: MoneyMatcherContext, received: unknown, other: Money) => MoneyMatcherResult;
+    toBeGreaterThanOrEqualMoney: (this: MoneyMatcherContext, received: unknown, other: Money) => MoneyMatcherResult;
+    toBeLessThanMoney: (this: MoneyMatcherContext, received: unknown, other: Money) => MoneyMatcherResult;
+    toBeLessThanOrEqualMoney: (this: MoneyMatcherContext, received: unknown, other: Money) => MoneyMatcherResult;
+    toSumTo(this: MoneyMatcherContext, received: unknown, total: Money): MoneyMatcherResult;
+};
+/** The parts of Vitest's and Jest's `expect` that `installMoneyMatchers` uses. */
+export interface ExpectWithExtensions {
+    extend(matchers: any): void;
+    addEqualityTesters?(testers: any[]): void;
+    addSnapshotSerializer?(serializer: any): void;
+}
+/**
+ * Installs everything on a test runner's `expect`: the matchers, value equality and the snapshot
+ * serializer. It also gives Money a Node inspect hook, so `console.log(price)` prints
+ * `Money(12.34 EUR)`. Safe to call more than once. A runner that lacks `addEqualityTesters` or
+ * `addSnapshotSerializer` (Bun supports neither) gets the matchers and the inspect hook.
+ */
+export declare function installMoneyMatchers(expect: ExpectWithExtensions): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAA8C,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAErF,sFAAsF;AACtF,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,SAAS,CAAC;AAEzF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,mBAO3B,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,eAAe;kBACZ,OAAO,KAAG,OAAO;uBACZ,OAAO,KAAG,MAAM;CACpC,CAAC;AAEF,oGAAoG;AACpG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,+FAA+F;AAC/F,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,qGAAqG;IACrG,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC;IACjE,wCAAwC;IACxC,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC;IACpC,+DAA+D;IAC/D,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC;IACtC,2EAA2E;IAC3E,2BAA2B,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC;IAC7C,4DAA4D;IAC5D,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC;IACnC,wEAAwE;IACxE,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC;IAC1C,sFAAsF;IACtF,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC;CAC1B;AA8ED,wDAAwD;AACxD,eAAO,MAAM,aAAa;oBAEhB,mBAAmB,YACf,OAAO,UACT,MAAM,GAAG,MAAM,GAAG,MAAM,YACtB,MAAM,GACf,kBAAkB;yBAOb,mBAAmB,YACf,OAAO,YACP,MAAM,GACf,kBAAkB;iCAzBb,mBAAmB,YAAY,OAAO,SAAS,KAAK,KAAK,kBAAkB;wCAA3E,mBAAmB,YAAY,OAAO,SAAS,KAAK,KAAK,kBAAkB;8BAA3E,mBAAmB,YAAY,OAAO,SAAS,KAAK,KAAK,kBAAkB;qCAA3E,mBAAmB,YAAY,OAAO,SAAS,KAAK,KAAK,kBAAkB;kBA6CrE,mBAAmB,YAAY,OAAO,SAAS,KAAK,GAAG,kBAAkB;CAqBxF,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IAEnC,MAAM,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAC;IAE5B,kBAAkB,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE1C,qBAAqB,CAAC,CAAC,UAAU,EAAE,GAAG,GAAG,IAAI,CAAC;CAC/C;AAID;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CA2BvE"}