@crewhaus/tool-money 0.7.0 → 0.8.1

package/dist/lib/match.js

@@ -7,6 +7,7 @@
  * 4,800 matches 4,750 is being paid to do subtraction, and it will sometimes
  * get it wrong on an invoice nobody re-reads.
  */
+import { addDecimal, addExact, atScale, big, compareDecimal, decimalNumber, decimalOf, roundHalfAwayFromZero, sumExact, toNumber, } from "./exact";
 export const MATCH_STATUSES = [
     "matched",
     "price-variance",
@@ -23,14 +24,86 @@ function normalizeDescription(text) {
         .replace(/\s+/g, " ")
         .trim();
 }
-function withinTolerance(actual, expected, percentBps, absolute) {
-    const delta = Math.abs(actual - expected);
-    if (delta === 0)
+const abs = (v) => (v < 0n ? -v : v);
+/** `make()`, worked out on the first call and kept. */
+function once(make) {
+    const held = {};
+    return () => {
+        if (held.made === undefined)
+            held.made = { value: make() };
+        return held.made.value;
+    };
+}
+/** Every line with a key, grouped by it; a line without one is in no group. */
+function linesBy(lines, keyOf) {
+    const groups = new Map();
+    for (const line of lines) {
+        const key = keyOf(line);
+        if (key === undefined)
+            continue;
+        const group = groups.get(key);
+        if (group === undefined)
+            groups.set(key, { lines: [line], head: 0 });
+        else
+            group.lines.push(line);
+    }
+    return groups;
+}
+/**
+ * The first line of the order carrying `key` that is still unmatched: what
+ * searching the remaining lines in order finds. A matched line never comes
+ * back, so the ones at the head of the group are passed over once and for
+ * good.
+ */
+function firstRemaining(groups, key, remaining) {
+    const group = groups.get(key);
+    if (group === undefined)
+        return undefined;
+    while (group.head < group.lines.length) {
+        const line = group.lines[group.head];
+        if (remaining.has(line.id))
+            return line;
+        group.head += 1;
+    }
+    return undefined;
+}
+/**
+ * Whether `actual` is within tolerance of `expected`, decided exactly.
+ *
+ * Prices are integers whose products with a rate pass 2^53 on ordinary
+ * amounts, and quantities are decimals a double cannot hold (0.33 against
+ * 0.3 at 10% is exactly on the bound, and 0.7.0's float arithmetic put it
+ * just outside). So every figure — the two values, the rate and the absolute
+ * bound — is compared as the exact decimal it was written as.
+ */
+function withinTolerance(actual, expected, percentBps, absolute, what) {
+    if (compareDecimal(actual, expected) === 0)
         return true;
     // Either bound may pass. A percentage alone is useless on a cheap line and
     // an absolute alone is useless on an expensive one.
-    const byPercent = percentBps !== undefined && Math.abs(expected) * percentBps >= delta * 10_000;
-    const byAbsolute = absolute !== undefined && delta <= absolute;
+    const scale = Math.max(actual.scale, expected.scale);
+    const delta = abs(atScale(actual, scale) - atScale(expected, scale));
+    const base = abs(atScale(expected, scale));
+    let byPercent = false;
+    if (percentBps !== undefined && !Number.isNaN(percentBps)) {
+        if (percentBps === Number.POSITIVE_INFINITY)
+            byPercent = true;
+        else {
+            // |expected| × bps / 10 000 >= delta, on one scale: bps is b / 10^s.
+            const bps = decimalOf(percentBps, `${what} percentage tolerance`);
+            byPercent = base * bps.units >= delta * 10000n * 10n ** BigInt(bps.scale);
+        }
+    }
+    let byAbsolute = false;
+    if (absolute !== undefined && !Number.isNaN(absolute)) {
+        if (absolute === Number.POSITIVE_INFINITY)
+            byAbsolute = true;
+        else {
+            // delta / 10^scale <= a / 10^s.
+            const bound = decimalOf(absolute, `${what} absolute tolerance`);
+            byAbsolute = delta * 10n ** BigInt(bound.scale) <= bound.units * 10n ** BigInt(scale);
+        }
+    }
     return byPercent || byAbsolute;
 }
 export function matchInvoiceToPurchaseOrder(invoiceLines, poLines, receiptLines = [], tolerance = {}) {
@@ -45,11 +118,21 @@ export function matchInvoiceToPurchaseOrder(invoiceLines, poLines, receiptLines
             seen.add(line.id);
         }
     }
+    // Receipts against one line are summed exactly: 0.1 + 0.2 received is 0.3,
+    // not a float a hair over it that an invoice for 0.3 is then "within".
     const received = new Map();
     for (const entry of receiptLines) {
-        received.set(entry.poLineId, (received.get(entry.poLineId) ?? 0) + entry.quantity);
+        const quantity = decimalOf(entry.quantity, `receipt for "${entry.poLineId}" quantity`);
+        const before = received.get(entry.poLineId);
+        received.set(entry.poLineId, before === undefined ? quantity : addDecimal(before, quantity));
     }
     const remainingPo = new Map(poLines.map((l) => [l.id, l]));
+    // The order lines by SKU and by normalized description, each built once,
+    // the first time it is needed. Searching every remaining line for each
+    // invoice line, and normalizing every description again, cost the invoice
+    // lines times the order lines.
+    const bySku = once(() => linesBy(poLines, (l) => l.sku));
+    const byDescription = once(() => linesBy(poLines, (l) => l.description === undefined ? undefined : normalizeDescription(l.description)));
     const pairs = [];
     const unmatchedInvoiceLines = [];
     for (const invoice of invoiceLines) {
@@ -59,13 +142,13 @@ export function matchInvoiceToPurchaseOrder(invoiceLines, poLines, receiptLines
         let po = invoice.poLineId === undefined ? undefined : remainingPo.get(invoice.poLineId);
         let matchedBy = "reference";
         if (!po && invoice.sku !== undefined) {
-            po = [...remainingPo.values()].find((l) => l.sku !== undefined && l.sku === invoice.sku);
+            po = firstRemaining(bySku(), invoice.sku, remainingPo);
             if (po)
                 matchedBy = "sku";
         }
         if (!po && invoice.description !== undefined) {
             const wanted = normalizeDescription(invoice.description);
-            po = [...remainingPo.values()].find((l) => l.description !== undefined && normalizeDescription(l.description) === wanted);
+            po = firstRemaining(byDescription(), wanted, remainingPo);
             if (po)
                 matchedBy = "description";
         }
@@ -75,15 +158,23 @@ export function matchInvoiceToPurchaseOrder(invoiceLines, poLines, receiptLines
         }
         remainingPo.delete(po.id);
         const reasons = [];
-        const priceOk = withinTolerance(invoice.unitPriceMinor, po.unitPriceMinor, tolerance.pricePercentBps, tolerance.priceAbsoluteMinor);
-        const quantityOk = withinTolerance(invoice.quantity, po.quantity, tolerance.quantityPercentBps, tolerance.quantityAbsolute);
+        const line = `invoice line "${invoice.id}"`;
+        const invoicePrice = big(invoice.unitPriceMinor, `${line} unitPriceMinor`);
+        const poPrice = big(po.unitPriceMinor, `order line "${po.id}" unitPriceMinor`);
+        const invoiceQuantity = decimalOf(invoice.quantity, `${line} quantity`);
+        const poQuantity = decimalOf(po.quantity, `order line "${po.id}" quantity`);
+        const priceOk = withinTolerance({ units: invoicePrice, scale: 0 }, { units: poPrice, scale: 0 }, tolerance.pricePercentBps, tolerance.priceAbsoluteMinor, `${line} price`);
+        const quantityOk = withinTolerance(invoiceQuantity, poQuantity, tolerance.quantityPercentBps, tolerance.quantityAbsolute, `${line} quantity`);
         if (!priceOk) {
             reasons.push(`unit price ${invoice.unitPriceMinor} against ${po.unitPriceMinor} on the order`);
         }
         if (!quantityOk) {
             reasons.push(`quantity ${invoice.quantity} against ${po.quantity} on the order`);
         }
-        const receivedQuantity = received.has(po.id) ? received.get(po.id) : null;
+        const receivedExact = received.get(po.id);
+        const receivedQuantity = receivedExact === undefined
+            ? null
+            : decimalNumber(receivedExact, `the quantity received against order line "${po.id}"`);
         let status = !priceOk && !quantityOk
             ? "both-variance"
             : !priceOk
@@ -95,18 +186,29 @@ export function matchInvoiceToPurchaseOrder(invoiceLines, poLines, receiptLines
         // failure this control exists to catch, and it is invisible in a two-way
         // match however well price and quantity agree with the order.
         if (receiptLines.length > 0) {
-            if (receivedQuantity === null || receivedQuantity === 0) {
+            if (receivedExact === undefined || receivedExact.units === 0n) {
                 status = "not-received";
                 reasons.push("nothing has been received against this order line");
             }
-            else if (invoice.quantity > receivedQuantity) {
+            else if (compareDecimal(invoiceQuantity, receivedExact) > 0) {
                 status = "over-receipt";
                 reasons.push(`invoiced ${invoice.quantity} but only ${receivedQuantity} received`);
             }
         }
-        const billable = Math.min(invoice.quantity, receivedQuantity ?? invoice.quantity);
-        const exposureMinor = invoice.quantity * invoice.unitPriceMinor -
-            billable * Math.min(invoice.unitPriceMinor, po.unitPriceMinor);
+        // What the variance costs: the invoice's quantity at its price, less what
+        // was billable (no more than arrived) at the lower of the two prices.
+        // Counted exactly — decimal quantities times integer prices, as bigints
+        // on one decimal scale — then rounded to whole minor units, a half away
+        // from zero, and refused past 2^53 rather than reported units off.
+        const billable = receivedExact !== undefined && compareDecimal(receivedExact, invoiceQuantity) < 0
+            ? receivedExact
+            : invoiceQuantity;
+        const scale = Math.max(invoiceQuantity.scale, billable.scale);
+        const lowerPrice = invoicePrice < poPrice ? invoicePrice : poPrice;
+        const exposureMinor = status === "matched"
+            ? 0
+            : toNumber(roundHalfAwayFromZero(atScale(invoiceQuantity, scale) * invoicePrice -
+                atScale(billable, scale) * lowerPrice, 10n ** BigInt(scale)), `${line} exposure`);
         pairs.push({
             invoiceLineId: invoice.id,
             poLineId: po.id,
@@ -114,12 +216,12 @@ export function matchInvoiceToPurchaseOrder(invoiceLines, poLines, receiptLines
             status,
             invoiceUnitPriceMinor: invoice.unitPriceMinor,
             poUnitPriceMinor: po.unitPriceMinor,
-            priceDeltaMinor: invoice.unitPriceMinor - po.unitPriceMinor,
+            priceDeltaMinor: addExact(invoice.unitPriceMinor, -po.unitPriceMinor, `${line} price delta`),
             invoiceQuantity: invoice.quantity,
             poQuantity: po.quantity,
             receivedQuantity,
-            quantityDelta: invoice.quantity - po.quantity,
-            exposureMinor: status === "matched" ? 0 : exposureMinor,
+            quantityDelta: decimalNumber(addDecimal(invoiceQuantity, poQuantity, -1n), `${line} quantity delta`),
+            exposureMinor,
             reasons,
         });
     }
@@ -130,7 +232,7 @@ export function matchInvoiceToPurchaseOrder(invoiceLines, poLines, receiptLines
         unmatchedPoLines: [...remainingPo.keys()],
         ok: exceptions === 0 && unmatchedInvoiceLines.length === 0,
         exceptions,
-        totalExposureMinor: pairs.reduce((s, p) => s + p.exposureMinor, 0),
+        totalExposureMinor: sumExact(pairs.map((p) => p.exposureMinor), "the total exposure"),
         threeWay: receiptLines.length > 0,
     };
 }

package/dist/lib/statement.d.ts

@@ -49,24 +49,51 @@ export type ParseOptions = {
     };
     /** Currency's minor-unit exponent. 2 for most, 0 for JPY. */
     readonly decimals?: number;
+    /**
+     * How many transactions and how many rejected rows to hold. The file is
+     * read to the end either way — `count`, `rejectedCount` and the totals
+     * cover every row — but the lists stop growing, so a caller that shows the
+     * first few hundred rows does not hold a million in memory first. Default:
+     * all of them.
+     */
+    readonly keep?: {
+        readonly transactions?: number;
+        readonly rejected?: number;
+    };
 };
 export type ParseResult = {
     readonly format: StatementFormat;
+    /** The transactions read, in file order — the first `keep.transactions` of them. */
     readonly transactions: ReadonlyArray<Transaction>;
+    /** Every transaction read, held or not. */
     readonly count: number;
-    readonly totalMinor: number;
-    readonly debitMinor: number;
-    readonly creditMinor: number;
+    /**
+     * The sums of every transaction read, exact, or null when one comes to more
+     * than a JSON number holds exactly — `totalsUnavailable` then says which.
+     */
+    readonly totalMinor: number | null;
+    readonly debitMinor: number | null;
+    readonly creditMinor: number | null;
+    readonly totalsUnavailable: string | null;
     readonly dateOrder: DateOrder;
-    /** Rows the file contained that could not be read, with the reason. */
+    /** Rows the file contained that could not be read, with the reason — the first `keep.rejected`. */
     readonly rejected: ReadonlyArray<{
         readonly row: number;
         readonly reason: string;
     }>;
+    /** Every row that could not be read, held or not. */
+    readonly rejectedCount: number;
 };
 /** RFC 4180 fields: quotes, doubled quotes inside them, embedded newlines. */
 export declare function parseCsvRows(text: string): string[][];
-/** Parse a money string to minor units, exactly, without floating point. */
+/**
+ * Parse a money string to minor units, exactly, without floating point.
+ *
+ * Returns null for text that is not an amount. An amount past 2^53 − 1 minor
+ * units is refused with an {@link InexactAmountError}: a JSON number past
+ * that has already been rounded, and 90,071,992,547,409.93 read as
+ * 9007199254740992 cents is a figure one cent out that nothing flags.
+ */
 export declare function parseMoneyMinor(raw: string, decimals: number, decimalComma: boolean): number | null;
 /**
  * Parse a date, refusing what cannot be read unambiguously.
@@ -77,4 +104,16 @@ export declare function parseMoneyMinor(raw: string, decimals: number, decimalCo
 export declare function parseDate(raw: string, order: DateOrder): string | null;
 /** True when every slashed date in the file reads the same either way. */
 export declare function datesAreUnambiguous(values: ReadonlyArray<string>): boolean;
+/**
+ * The `<STMTTRN>` blocks of an OFX file, in one forward pass over its tags.
+ *
+ * OFX 1.x is SGML, where an end tag may be left out, so a block that is
+ * never closed ends where the next one starts, at the transaction list's
+ * own tags, or at the end of the file — and is read like any other rather
+ * than dropped. (A lazy `<STMTTRN>…</STMTTRN>` match instead rescanned to
+ * the end of the file from every unclosed tag, which was quadratic, and
+ * swallowed the next transaction into an unclosed one.) A stray end tag is
+ * ignored.
+ */
+export declare function ofxTransactionBlocks(text: string): Generator<string>;
 export declare function parseStatement(text: string, options?: ParseOptions): ParseResult;