tallyd 0.0.0-stage → 0.1.0

package/dist/accounts/chart.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The chart of accounts: an immutable, validated account tree.
+ *
+ * Validation happens once, at construction. Downstream code that holds a
+ * `ChartOfAccounts` can assume every parent exists, no cycle is present, child
+ * types agree with their parent, and any account it is handed is postable —
+ * because the alternative would have thrown before the object existed.
+ */
+import type { Currency } from "../money/currency.js";
+import { type AccountType, type NormalBalance } from "./types.js";
+export interface AccountDefinition {
+    /** Stable identifier, conventionally numeric ("1000") but any string works. */
+    code: string;
+    name: string;
+    type: AccountType;
+    /** Code of the parent account. Omit for a root. */
+    parent?: string;
+    /** Currency for this account. Defaults to the chart's currency. */
+    currency?: Currency | string;
+    /**
+     * A placeholder groups children but cannot itself be posted to — the usual
+     * treatment for "Current Assets" as opposed to "Barclays Current Account".
+     */
+    placeholder?: boolean;
+    /** A closed account keeps its history but rejects new postings. */
+    closed?: boolean;
+    description?: string;
+}
+export interface Account {
+    readonly code: string;
+    readonly name: string;
+    readonly type: AccountType;
+    readonly parent: string | null;
+    readonly currency: Currency;
+    readonly placeholder: boolean;
+    readonly closed: boolean;
+    readonly description: string;
+    readonly normalBalance: NormalBalance;
+    /** Depth from the root; roots are 0. */
+    readonly depth: number;
+    /** Colon-joined names from the root, e.g. "Assets:Current:Barclays". */
+    readonly path: string;
+    readonly children: readonly string[];
+}
+export declare class ChartError extends Error {
+    constructor(message: string);
+}
+export declare class UnknownAccountError extends ChartError {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare class AccountNotPostableError extends ChartError {
+    readonly code: string;
+    constructor(code: string, reason: string);
+}
+export declare class ChartOfAccounts {
+    private readonly accounts;
+    readonly defaultCurrency: Currency;
+    readonly roots: readonly string[];
+    private constructor();
+    static build(definitions: readonly AccountDefinition[], options?: {
+        currency?: Currency | string;
+    }): ChartOfAccounts;
+    has(code: string): boolean;
+    /** Look up an account, throwing if it does not exist. */
+    get(code: string): Account;
+    find(code: string): Account | undefined;
+    get size(): number;
+    /** Every account, in depth-first order from each sorted root. */
+    list(): readonly Account[];
+    ofType(type: AccountType): readonly Account[];
+    /** Accounts with no children — the ones that normally receive postings. */
+    leaves(): readonly Account[];
+    children(code: string): readonly Account[];
+    /** All descendants of `code`, excluding `code` itself. */
+    descendants(code: string): readonly Account[];
+    /** `code` and all its descendants — the set a rolled-up balance covers. */
+    subtree(code: string): readonly Account[];
+    /** Ancestors from the immediate parent up to the root. */
+    ancestors(code: string): readonly Account[];
+    isDescendantOf(code: string, ancestor: string): boolean;
+    /** Resolve by colon-delimited path, e.g. "Assets:Current:Barclays". */
+    findByPath(path: string): Account | undefined;
+    /**
+     * Assert that an account can receive a posting, returning it. Placeholders
+     * and closed accounts are rejected here rather than at posting time so the
+     * error names the account and the reason.
+     */
+    assertPostable(code: string): Account;
+    isPostable(code: string): boolean;
+    /** A new chart with extra accounts, re-validated from scratch. */
+    extend(definitions: readonly AccountDefinition[]): ChartOfAccounts;
+    toDefinitions(): AccountDefinition[];
+    /** Indented text rendering, handy in the CLI and in test failure output. */
+    render(): string;
+}

package/dist/accounts/chart.js

@@ -0,0 +1,244 @@
+/**
+ * The chart of accounts: an immutable, validated account tree.
+ *
+ * Validation happens once, at construction. Downstream code that holds a
+ * `ChartOfAccounts` can assume every parent exists, no cycle is present, child
+ * types agree with their parent, and any account it is handed is postable —
+ * because the alternative would have thrown before the object existed.
+ */
+import { currency as lookupCurrency } from "../money/currency.js";
+import { isAccountType, normalBalanceOf } from "./types.js";
+export class ChartError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ChartError";
+    }
+}
+export class UnknownAccountError extends ChartError {
+    code;
+    constructor(code) {
+        super(`No such account: ${code}`);
+        this.code = code;
+        this.name = "UnknownAccountError";
+    }
+}
+export class AccountNotPostableError extends ChartError {
+    code;
+    constructor(code, reason) {
+        super(`Account ${code} is not postable: ${reason}`);
+        this.code = code;
+        this.name = "AccountNotPostableError";
+    }
+}
+export class ChartOfAccounts {
+    accounts;
+    defaultCurrency;
+    roots;
+    constructor(accounts, defaultCurrency, roots) {
+        this.accounts = accounts;
+        this.defaultCurrency = defaultCurrency;
+        this.roots = Object.freeze([...roots]);
+        Object.freeze(this);
+    }
+    static build(definitions, options = {}) {
+        const defaultCurrency = typeof options.currency === "string"
+            ? lookupCurrency(options.currency)
+            : (options.currency ?? lookupCurrency("GBP"));
+        // Pass 1 — shape and uniqueness.
+        const byCode = new Map();
+        for (const def of definitions) {
+            if (def.code.trim() === "")
+                throw new ChartError("Account code must not be blank");
+            if (def.name.trim() === "") {
+                throw new ChartError(`Account ${def.code} must have a name`);
+            }
+            if (!isAccountType(def.type)) {
+                throw new ChartError(`Account ${def.code} has unknown type: ${String(def.type)}`);
+            }
+            if (byCode.has(def.code))
+                throw new ChartError(`Duplicate account code: ${def.code}`);
+            byCode.set(def.code, def);
+        }
+        // Pass 2 — parent links, cycles and type agreement.
+        const childrenOf = new Map();
+        for (const def of definitions)
+            childrenOf.set(def.code, []);
+        for (const def of definitions) {
+            if (def.parent === undefined)
+                continue;
+            const parent = byCode.get(def.parent);
+            if (parent === undefined) {
+                throw new ChartError(`Account ${def.code} names a missing parent: ${def.parent}`);
+            }
+            if (parent.type !== def.type) {
+                throw new ChartError(`Account ${def.code} is ${def.type} but its parent ${parent.code} is ${parent.type}`);
+            }
+            childrenOf.get(def.parent).push(def.code);
+        }
+        for (const def of definitions) {
+            const seen = new Set([def.code]);
+            let cursor = def.parent;
+            while (cursor !== undefined) {
+                if (seen.has(cursor)) {
+                    throw new ChartError(`Account hierarchy contains a cycle at ${cursor}`);
+                }
+                seen.add(cursor);
+                cursor = byCode.get(cursor)?.parent;
+            }
+        }
+        // Pass 3 — materialise, computing depth and path top-down.
+        const accounts = new Map();
+        const roots = definitions.filter((d) => d.parent === undefined).map((d) => d.code);
+        const visit = (code, depth, prefix) => {
+            const def = byCode.get(code);
+            const children = childrenOf.get(code).slice().sort();
+            const path = prefix === "" ? def.name : `${prefix}:${def.name}`;
+            const accountCurrency = def.currency === undefined
+                ? defaultCurrency
+                : typeof def.currency === "string"
+                    ? lookupCurrency(def.currency)
+                    : def.currency;
+            accounts.set(code, Object.freeze({
+                code,
+                name: def.name,
+                type: def.type,
+                parent: def.parent ?? null,
+                currency: accountCurrency,
+                placeholder: def.placeholder ?? children.length > 0,
+                closed: def.closed ?? false,
+                description: def.description ?? "",
+                normalBalance: normalBalanceOf(def.type),
+                depth,
+                path,
+                children: Object.freeze(children),
+            }));
+            for (const child of children)
+                visit(child, depth + 1, path);
+        };
+        for (const root of roots)
+            visit(root, 0, "");
+        return new ChartOfAccounts(accounts, defaultCurrency, roots.slice().sort());
+    }
+    // ------------------------------------------------------------------ lookups
+    has(code) {
+        return this.accounts.has(code);
+    }
+    /** Look up an account, throwing if it does not exist. */
+    get(code) {
+        const account = this.accounts.get(code);
+        if (account === undefined)
+            throw new UnknownAccountError(code);
+        return account;
+    }
+    find(code) {
+        return this.accounts.get(code);
+    }
+    get size() {
+        return this.accounts.size;
+    }
+    /** Every account, in depth-first order from each sorted root. */
+    list() {
+        const out = [];
+        const walk = (code) => {
+            const account = this.get(code);
+            out.push(account);
+            for (const child of account.children)
+                walk(child);
+        };
+        for (const root of this.roots)
+            walk(root);
+        return out;
+    }
+    ofType(type) {
+        return this.list().filter((a) => a.type === type);
+    }
+    /** Accounts with no children — the ones that normally receive postings. */
+    leaves() {
+        return this.list().filter((a) => a.children.length === 0);
+    }
+    children(code) {
+        return this.get(code).children.map((c) => this.get(c));
+    }
+    /** All descendants of `code`, excluding `code` itself. */
+    descendants(code) {
+        const out = [];
+        const walk = (current) => {
+            for (const child of this.get(current).children) {
+                out.push(this.get(child));
+                walk(child);
+            }
+        };
+        walk(code);
+        return out;
+    }
+    /** `code` and all its descendants — the set a rolled-up balance covers. */
+    subtree(code) {
+        return [this.get(code), ...this.descendants(code)];
+    }
+    /** Ancestors from the immediate parent up to the root. */
+    ancestors(code) {
+        const out = [];
+        let cursor = this.get(code).parent;
+        while (cursor !== null) {
+            const account = this.get(cursor);
+            out.push(account);
+            cursor = account.parent;
+        }
+        return out;
+    }
+    isDescendantOf(code, ancestor) {
+        return this.ancestors(code).some((a) => a.code === ancestor);
+    }
+    /** Resolve by colon-delimited path, e.g. "Assets:Current:Barclays". */
+    findByPath(path) {
+        return this.list().find((a) => a.path === path);
+    }
+    // ----------------------------------------------------------------- postings
+    /**
+     * Assert that an account can receive a posting, returning it. Placeholders
+     * and closed accounts are rejected here rather than at posting time so the
+     * error names the account and the reason.
+     */
+    assertPostable(code) {
+        const account = this.get(code);
+        if (account.placeholder) {
+            throw new AccountNotPostableError(code, "it is a placeholder for its children");
+        }
+        if (account.closed)
+            throw new AccountNotPostableError(code, "it is closed");
+        return account;
+    }
+    isPostable(code) {
+        const account = this.find(code);
+        return account !== undefined && !account.placeholder && !account.closed;
+    }
+    // ------------------------------------------------------------------ derived
+    /** A new chart with extra accounts, re-validated from scratch. */
+    extend(definitions) {
+        return ChartOfAccounts.build([...this.toDefinitions(), ...definitions], {
+            currency: this.defaultCurrency,
+        });
+    }
+    toDefinitions() {
+        return this.list().map((a) => {
+            const def = {
+                code: a.code,
+                name: a.name,
+                type: a.type,
+                currency: a.currency,
+                placeholder: a.placeholder,
+                closed: a.closed,
+                description: a.description,
+            };
+            if (a.parent !== null)
+                def.parent = a.parent;
+            return def;
+        });
+    }
+    /** Indented text rendering, handy in the CLI and in test failure output. */
+    render() {
+        return this.list()
+            .map((a) => `${"  ".repeat(a.depth)}${a.code}  ${a.name}${a.placeholder ? " ·" : ""}`)
+            .join("\n");
+    }
+}

package/dist/accounts/index.d.ts

@@ -0,0 +1,3 @@
+export { type AccountType, type NormalBalance, ACCOUNT_TYPES, normalBalanceOf, debitSign, isBalanceSheet, isTemporary, isAccountType, } from "./types.js";
+export { type Account, type AccountDefinition, ChartOfAccounts, ChartError, UnknownAccountError, AccountNotPostableError, } from "./chart.js";
+export { STANDARD_ACCOUNTS, standardChart } from "./standard.js";

package/dist/accounts/index.js

@@ -0,0 +1,3 @@
+export { ACCOUNT_TYPES, normalBalanceOf, debitSign, isBalanceSheet, isTemporary, isAccountType, } from "./types.js";
+export { ChartOfAccounts, ChartError, UnknownAccountError, AccountNotPostableError, } from "./chart.js";
+export { STANDARD_ACCOUNTS, standardChart } from "./standard.js";

package/dist/accounts/standard.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A small-business chart of accounts, used as the default in the CLI and as
+ * fixture data in tests.
+ *
+ * The codes follow the usual 1000/2000/3000/4000/5000 blocks so the ordering
+ * of a trial balance printed by code matches the order of a balance sheet.
+ */
+import type { AccountDefinition } from "./chart.js";
+import { ChartOfAccounts } from "./chart.js";
+import type { Currency } from "../money/currency.js";
+export declare const STANDARD_ACCOUNTS: readonly AccountDefinition[];
+export declare function standardChart(currency?: Currency | string): ChartOfAccounts;

package/dist/accounts/standard.js

@@ -0,0 +1,95 @@
+/**
+ * A small-business chart of accounts, used as the default in the CLI and as
+ * fixture data in tests.
+ *
+ * The codes follow the usual 1000/2000/3000/4000/5000 blocks so the ordering
+ * of a trial balance printed by code matches the order of a balance sheet.
+ */
+import { ChartOfAccounts } from "./chart.js";
+export const STANDARD_ACCOUNTS = [
+    // 1000 — assets
+    { code: "1000", name: "Assets", type: "asset", placeholder: true },
+    { code: "1100", name: "Current Assets", type: "asset", parent: "1000", placeholder: true },
+    {
+        code: "1110",
+        name: "Bank",
+        type: "asset",
+        parent: "1100",
+        description: "Operating current account, reconciled against statements",
+    },
+    { code: "1120", name: "Petty Cash", type: "asset", parent: "1100" },
+    {
+        code: "1130",
+        name: "Accounts Receivable",
+        type: "asset",
+        parent: "1100",
+        description: "Invoiced but unpaid",
+    },
+    {
+        code: "1140",
+        name: "Undeposited Funds",
+        type: "asset",
+        parent: "1100",
+        description: "Captured by the processor, not yet settled to the bank",
+    },
+    { code: "1150", name: "Prepaid Expenses", type: "asset", parent: "1100" },
+    { code: "1200", name: "Fixed Assets", type: "asset", parent: "1000", placeholder: true },
+    { code: "1210", name: "Equipment", type: "asset", parent: "1200" },
+    {
+        code: "1220",
+        name: "Accumulated Depreciation",
+        type: "asset",
+        parent: "1200",
+        description: "Contra-asset; carries a credit balance",
+    },
+    // 2000 — liabilities
+    { code: "2000", name: "Liabilities", type: "liability", placeholder: true },
+    { code: "2100", name: "Accounts Payable", type: "liability", parent: "2000" },
+    { code: "2200", name: "VAT Payable", type: "liability", parent: "2000" },
+    { code: "2300", name: "Payroll Liabilities", type: "liability", parent: "2000" },
+    { code: "2400", name: "Credit Card", type: "liability", parent: "2000" },
+    // 3000 — equity
+    { code: "3000", name: "Equity", type: "equity", placeholder: true },
+    { code: "3100", name: "Share Capital", type: "equity", parent: "3000" },
+    { code: "3200", name: "Retained Earnings", type: "equity", parent: "3000" },
+    { code: "3300", name: "Drawings", type: "equity", parent: "3000" },
+    // 4000 — income
+    { code: "4000", name: "Income", type: "income", placeholder: true },
+    { code: "4100", name: "Sales", type: "income", parent: "4000" },
+    { code: "4200", name: "Consulting", type: "income", parent: "4000" },
+    { code: "4300", name: "Interest Income", type: "income", parent: "4000" },
+    {
+        code: "4400",
+        name: "Foreign Exchange Gain",
+        type: "income",
+        parent: "4000",
+        description: "Where a balance retranslated or settled in your favour lands",
+    },
+    // 5000 — expenses
+    { code: "5000", name: "Expenses", type: "expense", placeholder: true },
+    { code: "5100", name: "Cost of Sales", type: "expense", parent: "5000" },
+    { code: "5200", name: "Salaries", type: "expense", parent: "5000" },
+    { code: "5300", name: "Rent", type: "expense", parent: "5000" },
+    { code: "5400", name: "Software", type: "expense", parent: "5000" },
+    {
+        code: "5500",
+        name: "Payment Processing Fees",
+        type: "expense",
+        parent: "5000",
+        description: "The gap that makes a deposit fail to match its invoice",
+    },
+    { code: "5600", name: "Travel", type: "expense", parent: "5000" },
+    { code: "5700", name: "Professional Fees", type: "expense", parent: "5000" },
+    { code: "5800", name: "Bank Charges", type: "expense", parent: "5000" },
+    { code: "5900", name: "Depreciation", type: "expense", parent: "5000" },
+    {
+        code: "5950",
+        name: "Foreign Exchange Loss",
+        type: "expense",
+        parent: "5000",
+        description: "The other side of 4400, kept separate so the P&L shows both",
+    },
+];
+export function standardChart(currency = "GBP") {
+    return ChartOfAccounts.build(STANDARD_ACCOUNTS, { currency });
+}

package/dist/accounts/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Account classification and normal balances.
+ *
+ * The five statement classes determine which side of a posting increases an
+ * account. Getting this wrong is the single most common source of a report
+ * that balances arithmetically but reads backwards, so the mapping lives in
+ * one table and everything else derives from it.
+ */
+export type AccountType = "asset" | "liability" | "equity" | "income" | "expense";
+export declare const ACCOUNT_TYPES: readonly AccountType[];
+/** The side on which an account's balance normally sits. */
+export type NormalBalance = "debit" | "credit";
+export declare function normalBalanceOf(type: AccountType): NormalBalance;
+/** +1 when a debit increases this type, -1 when a debit decreases it. */
+export declare function debitSign(type: AccountType): 1 | -1;
+/** Accounts that appear on the balance sheet rather than the P&L. */
+export declare function isBalanceSheet(type: AccountType): boolean;
+/** Accounts closed out to retained earnings at period end. */
+export declare function isTemporary(type: AccountType): boolean;
+export declare function isAccountType(value: string): value is AccountType;

package/dist/accounts/types.js

@@ -0,0 +1,40 @@
+/**
+ * Account classification and normal balances.
+ *
+ * The five statement classes determine which side of a posting increases an
+ * account. Getting this wrong is the single most common source of a report
+ * that balances arithmetically but reads backwards, so the mapping lives in
+ * one table and everything else derives from it.
+ */
+export const ACCOUNT_TYPES = [
+    "asset",
+    "liability",
+    "equity",
+    "income",
+    "expense",
+];
+const NORMAL_BALANCE = {
+    asset: "debit",
+    expense: "debit",
+    liability: "credit",
+    equity: "credit",
+    income: "credit",
+};
+export function normalBalanceOf(type) {
+    return NORMAL_BALANCE[type];
+}
+/** +1 when a debit increases this type, -1 when a debit decreases it. */
+export function debitSign(type) {
+    return NORMAL_BALANCE[type] === "debit" ? 1 : -1;
+}
+/** Accounts that appear on the balance sheet rather than the P&L. */
+export function isBalanceSheet(type) {
+    return type === "asset" || type === "liability" || type === "equity";
+}
+/** Accounts closed out to retained earnings at period end. */
+export function isTemporary(type) {
+    return type === "income" || type === "expense";
+}
+export function isAccountType(value) {
+    return ACCOUNT_TYPES.includes(value);
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Argument parsing, written rather than installed.
+ *
+ * A dependency would do this, and for a tool this size the dependency is the
+ * larger risk: everything a ledger CLI needs — long flags, `--flag=value` and
+ * `--flag value`, short aliases, repeated values, `--` to stop parsing — is a
+ * page of code that can be tested against the awkward cases instead of
+ * trusted.
+ *
+ * The awkward cases are the point. `--account -1100` should be a value, not a
+ * missing flag followed by a stray negative number. `--as-at=2026-08-31` and
+ * `--as-at 2026-08-31` must mean the same thing. An unknown flag must be an
+ * error rather than silently ignored, because a typo in `--as-at` that reports
+ * the wrong period without complaining is exactly the failure a report tool
+ * cannot afford.
+ */
+export type FlagKind = "string" | "boolean" | "list";
+export interface FlagSpec {
+    readonly kind: FlagKind;
+    /** Single-character alias, without the dash. */
+    readonly short?: string;
+    readonly describe: string;
+    readonly placeholder?: string;
+}
+export type FlagSpecs = Readonly<Record<string, FlagSpec>>;
+export interface ParsedArgs {
+    readonly positional: readonly string[];
+    readonly flags: Readonly<Record<string, string | boolean | readonly string[]>>;
+}
+export declare class ArgumentError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse `argv` against a flag table.
+ *
+ * Everything after a bare `--` is positional, however it looks. Anything not
+ * recognised is an error rather than a shrug.
+ */
+export declare function parseArgs(argv: readonly string[], specs: FlagSpecs): ParsedArgs;
+export declare function stringFlag(parsed: ParsedArgs, name: string): string | undefined;
+export declare function requiredFlag(parsed: ParsedArgs, name: string): string;
+export declare function booleanFlag(parsed: ParsedArgs, name: string): boolean;
+export declare function listFlag(parsed: ParsedArgs, name: string): readonly string[];
+/** Render a flag table as aligned help text. */
+export declare function renderFlags(specs: FlagSpecs, indent?: string): string;