@ekwo-ai/trial-balance 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karuna Co OÜ, trading as Ekwo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# `@ekwo-ai/trial-balance`
+
+Reads a **trial balance written as CSV** — one row per account, a debit and a
+credit, or one signed balance — into plain objects, in TypeScript, with no
+dependencies.
+
+It is the one thing every accounting package prints and every spreadsheet
+saves, which makes it the way in for books that come from anywhere: the
+balances of the day the new books open on.
+
+```ts
+import { readTrialBalance } from '@ekwo-ai/trial-balance';
+
+const books = readTrialBalance(bytesOrString);
+
+books.opening;    // [{ account: '512000', debit: '8400.00', credit: '0.00', contact: null, … }, …]
+books.accounts;   // [{ code: '512000', name: 'Bank', type: null }, …]
+books.contacts;   // the parties a receivable or a payable row names
+books.violations; // [{ rule: 'unbalanced', message: '…', row: null }] when it does not balance
+```
+
+## The file
+
+A header row, then one row per account. The columns are found by their name,
+without regard to case, and without the `*` some exports put on a required
+column:
+
+| Column | Names accepted | |
+|---|---|---|
+| account | `account`, `account code`, `code` | required |
+| name | `name`, `account name` | optional |
+| debit, credit | `debit`, `credit` | both, or… |
+| balance | `balance` | …one signed balance, positive in debit |
+| contact | `contact`, `party` | optional: the customer or supplier of a receivable or payable row |
+| contact name | `contact name`, `party name` | optional |
+| label | `label`, `description` | optional |
+
+- A row with a debit **and** a credit is **netted**: a trial balance prints the
+  totals of each side, and 100 in debit with 30 in credit opens at 70 in
+  debit. A row that nets to zero opens nothing and is left out.
+- The **separator** is read from the header: the first of `,`, `;` and a tab it
+  holds outside quotes. Fields may be quoted as RFC 4180 says.
+- The **decimal mark** is a point. A comma is read as one only in a file
+  separated by something else, where it cannot be a separator of thousands. No
+  thousands separator, no currency sign, no exponent: each is refused rather
+  than read one way or the other.
+- The **encoding** is UTF-8, fatally. A file saved in Latin-1 is said to be so
+  (`{ encoding: 'iso-8859-1' }`); it is never guessed, because every sequence
+  of bytes is valid Latin-1.
+
+## What it returns
+
+The shape declared in [`src/types.ts`](./src/types.ts) — accounts, contacts,
+entries, an opening balance, violations — which is, field for field, the shape
+every reader of an accounting export in this repository declares for itself.
+A trial balance fills `opening` and leaves `entries` empty. It says no
+currency and no date: the file has neither, and whatever takes the balance is
+told the day it opens on.
+
+What does not balance comes back in `violations`, and the rows come back as
+written. What is not a trial balance at all — no account column, a debit
+column beside a balance column, an amount that is not one — is thrown as a
+`BooksFileError` with a `code`.
+
+It knows no chart of accounts. The codes are the ones the file wrote; which
+account of another chart each becomes is the importer's business. In
+[Ekwo OS](https://github.com/Ekwo-ai/ekwo-os) that is `ekwo import
+trial-balance <file> --opening-date <first day of the year>`.
+
+MIT.

package/dist/csv.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The comma-separated values a spreadsheet saves, as RFC 4180 describes them:
+ * fields between double quotes may hold the separator, a line break and a
+ * doubled quote. Nothing else about the file is assumed.
+ *
+ * The separator is **read from the header**, which this format requires: the
+ * first of `,`, `;` and a tab that the header row contains outside quotes. A
+ * spreadsheet saves with a comma or a semicolon depending on the language of
+ * the machine, and the header is the one row whose content is known, so this
+ * is reading the file rather than guessing at it.
+ */
+import type { Encoding } from './types.js';
+export type Separator = ',' | ';' | '\t';
+/** Bytes to text, in the encoding the caller said, refusing what is not that. */
+export declare function decode(input: string | Uint8Array, encoding: Encoding, maxBytes: number): string;
+/** The separator of a header line: the first of the three found outside quotes. */
+export declare function separatorOf(headerLine: string): Separator;
+/** Every row of the file, each an array of fields, with the row number it starts on. */
+export declare function parseCsv(text: string, separator: Separator): {
+    row: number;
+    fields: string[];
+}[];
+/** A header cell as it is compared: trimmed, lower case, without the `*` some exports put on a required column. */
+export declare function headerKey(cell: string): string;
+//# sourceMappingURL=csv.d.ts.map

package/dist/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../src/csv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC;AAEzC,iFAAiF;AACjF,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA0B/F;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAQzD;AAED,wFAAwF;AACxF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,CAqDhG;AAED,mHAAmH;AACnH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/csv.js

@@ -0,0 +1,125 @@
+/**
+ * The comma-separated values a spreadsheet saves, as RFC 4180 describes them:
+ * fields between double quotes may hold the separator, a line break and a
+ * doubled quote. Nothing else about the file is assumed.
+ *
+ * The separator is **read from the header**, which this format requires: the
+ * first of `,`, `;` and a tab that the header row contains outside quotes. A
+ * spreadsheet saves with a comma or a semicolon depending on the language of
+ * the machine, and the header is the one row whose content is known, so this
+ * is reading the file rather than guessing at it.
+ */
+import { BooksFileError } from './errors.js';
+const BYTE_ORDER_MARK = 0xfeff;
+/** Bytes to text, in the encoding the caller said, refusing what is not that. */
+export function decode(input, encoding, maxBytes) {
+    let text;
+    if (typeof input === 'string') {
+        if (input.length > maxBytes)
+            throw new BooksFileError('too_large', `the file is longer than ${maxBytes} bytes`);
+        text = input;
+    }
+    else {
+        if (input.byteLength > maxBytes) {
+            throw new BooksFileError('too_large', `the file is ${input.byteLength} bytes, over the limit of ${maxBytes}`);
+        }
+        if (encoding === 'iso-8859-1') {
+            const parts = [];
+            for (let i = 0; i < input.length; i += 8192)
+                parts.push(String.fromCharCode(...input.subarray(i, i + 8192)));
+            text = parts.join('');
+        }
+        else {
+            try {
+                text = new TextDecoder('utf-8', { fatal: true }).decode(input);
+            }
+            catch {
+                throw new BooksFileError('unsupported_encoding', "the bytes are not UTF-8; if the file was saved in Latin-1, say so with { encoding: 'iso-8859-1' } — it is not guessed, because every sequence of bytes is valid Latin-1");
+            }
+        }
+    }
+    if (text.charCodeAt(0) === BYTE_ORDER_MARK)
+        text = text.slice(1);
+    return text;
+}
+/** The separator of a header line: the first of the three found outside quotes. */
+export function separatorOf(headerLine) {
+    let quoted = false;
+    for (const char of headerLine) {
+        if (char === '"')
+            quoted = !quoted;
+        else if (!quoted && (char === ',' || char === ';' || char === '\t'))
+            return char;
+    }
+    // A header of one column has no separator; any will do, and a comma is it.
+    return ',';
+}
+/** Every row of the file, each an array of fields, with the row number it starts on. */
+export function parseCsv(text, separator) {
+    const rows = [];
+    let fields = [];
+    let field = '';
+    let quoted = false;
+    let line = 1;
+    let startedOn = 1;
+    let fieldStarted = false;
+    const endRow = () => {
+        fields.push(field);
+        // A blank line is no row; a row of empty fields is kept and read.
+        if (!(fields.length === 1 && fields[0] === ''))
+            rows.push({ row: startedOn, fields });
+        fields = [];
+        field = '';
+        fieldStarted = false;
+    };
+    for (let i = 0; i < text.length; i += 1) {
+        const char = text[i];
+        if (quoted) {
+            if (char === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i += 1;
+                }
+                else
+                    quoted = false;
+            }
+            else {
+                if (char === '\n')
+                    line += 1;
+                field += char;
+            }
+            continue;
+        }
+        if (char === '"' && !fieldStarted) {
+            quoted = true;
+            fieldStarted = true;
+        }
+        else if (char === separator) {
+            fields.push(field);
+            field = '';
+            fieldStarted = false;
+        }
+        else if (char === '\r' && text[i + 1] === '\n') {
+            // The \n that follows ends the row.
+        }
+        else if (char === '\n' || char === '\r') {
+            endRow();
+            line += 1;
+            startedOn = line;
+        }
+        else {
+            field += char;
+            fieldStarted = true;
+        }
+    }
+    if (quoted)
+        throw new BooksFileError('malformed_csv', 'a quoted field is never closed', startedOn);
+    if (field !== '' || fields.length > 0)
+        endRow();
+    return rows;
+}
+/** A header cell as it is compared: trimmed, lower case, without the `*` some exports put on a required column. */
+export function headerKey(cell) {
+    return cell.trim().replace(/^\*/, '').trim().toLowerCase();
+}
+//# sourceMappingURL=csv.js.map

package/dist/csv.js.map

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

package/dist/decimal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Amounts as the file wrote them, added without a float.
+ *
+ * An amount is held as a `bigint` of millionths: enough for any currency and
+ * any rate a spreadsheet prints, and exact. What leaves is a string with two
+ * decimals, and more when the file wrote more that are not zero — dropping a
+ * written zero is not rounding, dropping anything else would be, and is never
+ * done here.
+ */
+/**
+ * The decimal marks a number may be written with. The comma is accepted only
+ * where it cannot be a separator of thousands — in a file whose fields are
+ * separated by something else — and a number never carries both marks.
+ */
+export type DecimalMark = '.' | ',';
+/**
+ * A written amount as millionths, or null when it is not a number this reader
+ * accepts: digits, one decimal mark, an optional leading minus or a pair of
+ * brackets for a negative. No thousands separator, no currency symbol, no
+ * exponent — each of those is refused rather than read one way or another.
+ */
+export declare function parseDecimal(text: string, marks: readonly DecimalMark[]): bigint | null;
+/** Millionths as a decimal string: signed, two decimals, more when they are written. */
+export declare function formatDecimal(value: bigint): string;
+//# sourceMappingURL=decimal.d.ts.map

package/dist/decimal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimal.d.ts","sourceRoot":"","sources":["../src/decimal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,GAAG,GAAG,GAAG,CAAC;AAEpC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,GAAG,IAAI,CAuBvF;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnD"}

package/dist/decimal.js

@@ -0,0 +1,55 @@
+/**
+ * Amounts as the file wrote them, added without a float.
+ *
+ * An amount is held as a `bigint` of millionths: enough for any currency and
+ * any rate a spreadsheet prints, and exact. What leaves is a string with two
+ * decimals, and more when the file wrote more that are not zero — dropping a
+ * written zero is not rounding, dropping anything else would be, and is never
+ * done here.
+ */
+const SCALE = 6;
+const UNIT = 10n ** BigInt(SCALE);
+/**
+ * A written amount as millionths, or null when it is not a number this reader
+ * accepts: digits, one decimal mark, an optional leading minus or a pair of
+ * brackets for a negative. No thousands separator, no currency symbol, no
+ * exponent — each of those is refused rather than read one way or another.
+ */
+export function parseDecimal(text, marks) {
+    let value = text.trim();
+    if (value === '')
+        return null;
+    let negative = false;
+    if (value.startsWith('(') && value.endsWith(')')) {
+        negative = true;
+        value = value.slice(1, -1).trim();
+    }
+    if (value.startsWith('-')) {
+        if (negative)
+            return null;
+        negative = true;
+        value = value.slice(1);
+    }
+    else if (value.startsWith('+')) {
+        value = value.slice(1);
+    }
+    const pattern = marks.includes(',') ? /^([0-9]+)(?:[.,]([0-9]*))?$|^[.,]([0-9]+)$/ : /^([0-9]+)(?:\.([0-9]*))?$|^\.([0-9]+)$/;
+    const match = pattern.exec(value);
+    if (match === null)
+        return null;
+    const whole = match[1] ?? '0';
+    const fraction = match[2] ?? match[3] ?? '';
+    if (fraction.length > SCALE)
+        return null;
+    const units = BigInt(whole) * UNIT + BigInt(fraction.padEnd(SCALE, '0') || '0');
+    return negative ? -units : units;
+}
+/** Millionths as a decimal string: signed, two decimals, more when they are written. */
+export function formatDecimal(value) {
+    const negative = value < 0n;
+    const digits = (negative ? -value : value).toString().padStart(SCALE + 1, '0');
+    const whole = digits.slice(0, -SCALE);
+    const fraction = digits.slice(-SCALE).replace(/0+$/, '').padEnd(2, '0');
+    return `${negative ? '-' : ''}${whole}.${fraction}`;
+}
+//# sourceMappingURL=decimal.js.map

package/dist/decimal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimal.js","sourceRoot":"","sources":["../src/decimal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,KAAK,GAAG,CAAC,CAAC;AAChB,MAAM,IAAI,GAAG,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;AASlC;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,KAA6B;IACtE,IAAI,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IACxB,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,QAAQ,GAAG,IAAI,CAAC;QAChB,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpC,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,IAAI,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1B,QAAQ,GAAG,IAAI,CAAC;QAChB,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;SAAM,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,4CAA4C,CAAC,CAAC,CAAC,wCAAwC,CAAC;IAC9H,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;IAC9B,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5C,IAAI,QAAQ,CAAC,MAAM,GAAG,KAAK;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;IAChF,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AACnC,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,QAAQ,GAAG,KAAK,GAAG,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/E,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACxE,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,QAAQ,EAAE,CAAC;AACtD,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What makes a file unreadable, as opposed to books that read and do not add
+ * up. The second comes back in `violations`; the first is thrown, because a
+ * file with no header the reader recognises has no row to hang a violation on.
+ */
+export type BooksFileErrorCode = 
+/** Larger than `maxBytes`. Refused before a single character is read. */
+'too_large'
+/** Bytes that are not the encoding announced. */
+ | 'unsupported_encoding'
+/** Nothing in the file, or a header and nothing under it. */
+ | 'empty_file'
+/** A header that lacks a column the format needs, or names one twice. */
+ | 'missing_column'
+/** A quote that is never closed. */
+ | 'malformed_csv'
+/** A value the format does not allow where it is: a date, an amount. */
+ | 'invalid_value';
+export declare class BooksFileError extends Error {
+    readonly code: BooksFileErrorCode;
+    /** The row the reader stopped on, from 1, when there is one. */
+    readonly row: number | null;
+    constructor(code: BooksFileErrorCode, message: string, row?: number | null);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,kBAAkB;AAC5B,yEAAyE;AACvE,WAAW;AACb,iDAAiD;GAC/C,sBAAsB;AACxB,6DAA6D;GAC3D,YAAY;AACd,yEAAyE;GACvE,gBAAgB;AAClB,oCAAoC;GAClC,eAAe;AACjB,wEAAwE;GACtE,eAAe,CAAC;AAEpB,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEhB,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,GAAG,IAAW;CAMjF"}

package/dist/errors.js

@@ -0,0 +1,12 @@
+export class BooksFileError extends Error {
+    code;
+    /** The row the reader stopped on, from 1, when there is one. */
+    row;
+    constructor(code, message, row = null) {
+        super(row === null ? message : `row ${row}: ${message}`);
+        this.name = 'BooksFileError';
+        this.code = code;
+        this.row = row;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAmBA,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAqB;IAClC,gEAAgE;IACvD,GAAG,CAAgB;IAE5B,YAAY,IAAwB,EAAE,OAAe,EAAE,MAAqB,IAAI;QAC9E,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A trial balance, written as CSV: one row per account, a debit and a credit,
+ * or a signed balance. It is the one thing every accounting package can print
+ * and every spreadsheet can save, which is why it is the way in for books that
+ * come from anywhere: the balances of the day the new books open on.
+ *
+ * It depends on nothing, reads no database and knows no chart of accounts: the
+ * codes are the ones the file wrote, and saying which account of another chart
+ * each of them becomes is the importer's business, not this reader's.
+ */
+import type { ImportedBooks, ReadOptions } from './types.js';
+export * from './types.js';
+export { BooksFileError, type BooksFileErrorCode } from './errors.js';
+/**
+ * The columns this reader knows, each under the names it accepts in a header.
+ * Compared without regard to case, and without the `*` some exports put on a
+ * column that is required.
+ */
+export declare const TRIAL_BALANCE_COLUMNS: {
+    readonly account: readonly ["account", "account code", "code"];
+    readonly name: readonly ["name", "account name"];
+    readonly debit: readonly ["debit"];
+    readonly credit: readonly ["credit"];
+    readonly balance: readonly ["balance"];
+    readonly contact: readonly ["contact", "party"];
+    readonly contactName: readonly ["contact name", "party name"];
+    readonly label: readonly ["label", "description"];
+};
+/**
+ * Reads the file. A row carries its account and either a debit and a credit —
+ * the totals a trial balance prints, which are netted: 100 in debit and 30 in
+ * credit open at 70 in debit — or one signed `balance`, positive in debit.
+ * A row that nets to zero opens nothing and is left out.
+ *
+ * A comma is read as the decimal mark only in a file whose fields are
+ * separated by something else, where it cannot be a separator of thousands.
+ */
+export declare function readTrialBalance(input: string | Uint8Array, options?: ReadOptions): ImportedBooks;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAmB,aAAa,EAAiC,WAAW,EAAa,MAAM,YAAY,CAAC;AAExH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAItE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;CASxB,CAAC;AAIX;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAwGrG"}

package/dist/index.js

@@ -0,0 +1,151 @@
+/**
+ * A trial balance, written as CSV: one row per account, a debit and a credit,
+ * or a signed balance. It is the one thing every accounting package can print
+ * and every spreadsheet can save, which is why it is the way in for books that
+ * come from anywhere: the balances of the day the new books open on.
+ *
+ * It depends on nothing, reads no database and knows no chart of accounts: the
+ * codes are the ones the file wrote, and saying which account of another chart
+ * each of them becomes is the importer's business, not this reader's.
+ */
+import { decode, headerKey, parseCsv, separatorOf } from './csv.js';
+import { formatDecimal, parseDecimal } from './decimal.js';
+import { BooksFileError } from './errors.js';
+export * from './types.js';
+export { BooksFileError } from './errors.js';
+const DEFAULTS = { encoding: 'utf-8', maxBytes: 64 * 1024 * 1024 };
+/**
+ * The columns this reader knows, each under the names it accepts in a header.
+ * Compared without regard to case, and without the `*` some exports put on a
+ * column that is required.
+ */
+export const TRIAL_BALANCE_COLUMNS = {
+    account: ['account', 'account code', 'code'],
+    name: ['name', 'account name'],
+    debit: ['debit'],
+    credit: ['credit'],
+    balance: ['balance'],
+    contact: ['contact', 'party'],
+    contactName: ['contact name', 'party name'],
+    label: ['label', 'description'],
+};
+/**
+ * Reads the file. A row carries its account and either a debit and a credit —
+ * the totals a trial balance prints, which are netted: 100 in debit and 30 in
+ * credit open at 70 in debit — or one signed `balance`, positive in debit.
+ * A row that nets to zero opens nothing and is left out.
+ *
+ * A comma is read as the decimal mark only in a file whose fields are
+ * separated by something else, where it cannot be a separator of thousands.
+ */
+export function readTrialBalance(input, options = {}) {
+    const text = decode(input, options.encoding ?? DEFAULTS.encoding, options.maxBytes ?? DEFAULTS.maxBytes);
+    const firstLine = text.split(/\r?\n/, 1)[0] ?? '';
+    const separator = separatorOf(firstLine);
+    const rows = parseCsv(text, separator);
+    const header = rows.shift();
+    if (header === undefined)
+        throw new BooksFileError('empty_file', 'the file is empty');
+    const at = locate(header.fields);
+    if (at.account === undefined) {
+        throw new BooksFileError('missing_column', `the header names no account column; it needs one of: ${TRIAL_BALANCE_COLUMNS.account.join(', ')}`, header.row);
+    }
+    const signed = at.balance !== undefined;
+    if (!signed && (at.debit === undefined || at.credit === undefined)) {
+        throw new BooksFileError('missing_column', 'the header needs a debit and a credit column, or one signed balance column', header.row);
+    }
+    if (signed && (at.debit !== undefined || at.credit !== undefined)) {
+        throw new BooksFileError('missing_column', 'the header has a balance column beside a debit or a credit one; keep one of the two ways, so that no amount is read twice', header.row);
+    }
+    if (rows.length === 0)
+        throw new BooksFileError('empty_file', 'the file has a header and no row under it', header.row);
+    const marks = separator === ',' ? ['.'] : ['.', ','];
+    const cell = (fields, column) => {
+        const index = at[column];
+        return index === undefined ? '' : (fields[index] ?? '').trim();
+    };
+    const amount = (fields, column, row) => {
+        const raw = cell(fields, column);
+        if (raw === '')
+            return 0n;
+        const value = parseDecimal(raw, marks);
+        if (value === null) {
+            throw new BooksFileError('invalid_value', `"${raw}" in the ${column} column is not an amount this reader accepts: digits and one decimal mark${separator === ',' ? ' (a point, in a comma-separated file)' : ''}, no thousands separator, no currency sign`, row);
+        }
+        return value;
+    };
+    const accounts = new Map();
+    const contacts = new Map();
+    const opening = [];
+    const violations = [];
+    let debits = 0n;
+    let credits = 0n;
+    for (const { row, fields } of rows) {
+        const account = cell(fields, 'account');
+        if (account === '') {
+            violations.push({ rule: 'account_missing', message: 'a row names no account and was left out', row });
+            continue;
+        }
+        const name = cell(fields, 'name');
+        if (!accounts.has(account))
+            accounts.set(account, { code: account, name: name === '' ? null : name, type: null });
+        const net = signed ? amount(fields, 'balance', row) : amount(fields, 'debit', row) - amount(fields, 'credit', row);
+        if (net === 0n)
+            continue;
+        const contact = cell(fields, 'contact');
+        if (contact !== '' && !contacts.has(contact)) {
+            const contactName = cell(fields, 'contactName');
+            contacts.set(contact, {
+                code: contact,
+                name: contactName === '' ? contact : contactName,
+                vatNumber: null,
+                registrationNumber: null,
+                email: null,
+                country: null,
+            });
+        }
+        const label = cell(fields, 'label');
+        opening.push({
+            account,
+            contact: contact === '' ? null : contact,
+            label: label === '' ? null : label,
+            debit: formatDecimal(net > 0n ? net : 0n),
+            credit: formatDecimal(net < 0n ? -net : 0n),
+            currency: null,
+            amountCurrency: null,
+            dueDate: null,
+            matching: null,
+        });
+        if (net > 0n)
+            debits += net;
+        else
+            credits -= net;
+    }
+    if (debits !== credits) {
+        violations.push({
+            rule: 'unbalanced',
+            message: `the balance has debit ${formatDecimal(debits)} and credit ${formatDecimal(credits)}; an opening entry has to balance`,
+            row: null,
+        });
+    }
+    return {
+        format: 'trial-balance',
+        currency: null,
+        accounts: [...accounts.values()],
+        contacts: [...contacts.values()],
+        entries: [],
+        opening,
+        violations,
+    };
+}
+function locate(header) {
+    const keys = header.map(headerKey);
+    const at = {};
+    for (const [column, names] of Object.entries(TRIAL_BALANCE_COLUMNS)) {
+        const found = keys.findIndex((key) => names.includes(key));
+        if (found !== -1)
+            at[column] = found;
+    }
+    return at;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * What a set of books is once it has been read out of the software that kept
+ * them: accounts, parties, entries and an opening balance. The shape is
+ * declared here and imported from nowhere — it names no table and no ledger.
+ *
+ * It is, field for field, the shape every reader of an accounting export in
+ * this repository declares for itself (`@ekwo-ai/fec`, and the readers beside
+ * this one), so whatever takes one takes the others. It is not a shared
+ * abstraction: none imports another, and a reader that has nothing to say for
+ * a part of it returns that part empty.
+ *
+ * Every amount is a **decimal string**, never negative: a line carries a debit
+ * or a credit, and the side is the sign. No figure passes through a `number`.
+ */
+/** ISO 8601 calendar date, `YYYY-MM-DD`. */
+export type IsoDate = string;
+/** A fixed-point number, `1234.50`, never negative. */
+export type Decimal = string;
+/** One account of the chart the books were kept on, in the words of that software. */
+export interface ImportedAccount {
+    code: string;
+    name: string | null;
+    /** What the source calls its kind, verbatim. Null when it says nothing. */
+    type: string | null;
+}
+/** A customer, a supplier or anybody else a line names. */
+export interface ImportedContact {
+    /** How the source identifies the party on a line: its code, or its name where it has no code. */
+    code: string;
+    name: string;
+    vatNumber: string | null;
+    registrationNumber: string | null;
+    email: string | null;
+    /** ISO 3166-1 alpha-2, when the source writes one. Never inferred. */
+    country: string | null;
+}
+export interface ImportedLine {
+    /** The account code in the source's chart. */
+    account: string;
+    /** The `code` of an {@link ImportedContact}, or null. */
+    contact: string | null;
+    label: string | null;
+    debit: Decimal;
+    credit: Decimal;
+    /** A foreign currency the line was in, when the source says so. */
+    currency: string | null;
+    /** The amount in that currency, never negative. */
+    amountCurrency: Decimal | null;
+    dueDate: IsoDate | null;
+    /** The reconciliation mark the source put on the line, as written. */
+    matching: string | null;
+}
+export interface ImportedEntry {
+    /** The journal code in the source, or null when it has none. */
+    journal: string | null;
+    journalName: string | null;
+    /** The entry's number in the source. */
+    number: string | null;
+    date: IsoDate;
+    reference: string | null;
+    description: string | null;
+    lines: ImportedLine[];
+    /** The row of the file the entry starts on, from 1, for a message. */
+    row: number | null;
+}
+export interface Violation {
+    rule: string;
+    message: string;
+    /** The row of the file, from 1, or null for a rule about the whole file. */
+    row: number | null;
+}
+export interface ImportedBooks {
+    /** Which reader: `trial-balance` here. */
+    format: string;
+    /** The currency the file says its amounts are in. Null when it says none: never guessed. */
+    currency: string | null;
+    accounts: ImportedAccount[];
+    contacts: ImportedContact[];
+    entries: ImportedEntry[];
+    /** A trial balance: one line per account, to become the opening entry of a year. */
+    opening: ImportedLine[];
+    violations: Violation[];
+}
+export type Encoding = 'utf-8' | 'iso-8859-1';
+export interface ReadOptions {
+    /**
+     * How bytes are decoded. Default `utf-8`, fatally: bytes that are not UTF-8
+     * are refused by name, never read as something else. A spreadsheet that
+     * saves in Latin-1 is said to be so, because every sequence of bytes is
+     * valid Latin-1 and a guess would always succeed.
+     */
+    encoding?: Encoding;
+    /** Refused beyond this many bytes, before anything is read. Default 64 MiB. */
+    maxBytes?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,4CAA4C;AAC5C,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,uDAAuD;AACvD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mDAAmD;IACnD,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,wCAAwC;IACxC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,sEAAsE;IACtE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,oFAAoF;IACpF,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;AAE9C,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * What a set of books is once it has been read out of the software that kept
+ * them: accounts, parties, entries and an opening balance. The shape is
+ * declared here and imported from nowhere — it names no table and no ledger.
+ *
+ * It is, field for field, the shape every reader of an accounting export in
+ * this repository declares for itself (`@ekwo-ai/fec`, and the readers beside
+ * this one), so whatever takes one takes the others. It is not a shared
+ * abstraction: none imports another, and a reader that has nothing to say for
+ * a part of it returns that part empty.
+ *
+ * Every amount is a **decimal string**, never negative: a line carries a debit
+ * or a credit, and the side is the sign. No figure passes through a `number`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ekwo-ai/trial-balance",
+  "version": "0.6.0",
+  "description": "Reads a trial balance written as CSV — account, debit, credit — into the plain shape an opening balance is made of, in TypeScript: amounts as decimal strings, and what does not add up. Zero dependencies.",
+  "keywords": [
+    "trial-balance",
+    "opening-balance",
+    "csv",
+    "accounting",
+    "bookkeeping",
+    "migration",
+    "import",
+    "parser"
+  ],
+  "license": "MIT",
+  "author": "Ekwo AI",
+  "homepage": "https://github.com/Ekwo-ai/ekwo-os/tree/main/packages/formats/trial-balance#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ekwo-ai/ekwo-os.git",
+    "directory": "packages/formats/trial-balance"
+  },
+  "bugs": {
+    "url": "https://github.com/Ekwo-ai/ekwo-os/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  }
+}