tallyd 0.0.0-stage → 0.1.0

package/dist/ledger/close.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Closing the books at a date.
+ *
+ * A year end has a step nothing in this library has needed until now: the
+ * income and expense accounts are emptied into reserves, so that they start the
+ * next year at nil and the balance sheet carries what was earned. It is
+ * mechanical, and for a company keeping its own books it is a housekeeping
+ * task. It becomes interesting in a group.
+ *
+ * A consolidation reads an entity's result as the balance on its income
+ * accounts at the reporting date. That is right for books closed at each year
+ * end, where the balance is exactly the year's result, and wrong in two
+ * situations that are not unusual. A company acquired in March has twelve
+ * months on its income accounts and only nine of them belong to the group. A
+ * company that has never closed its books has every year since it was formed
+ * on them. In both cases the fix is the same: close the books at the date the
+ * period of interest begins, and what is left on the income accounts is the
+ * period's result and nothing else.
+ *
+ * Two things about how it is done here.
+ *
+ * It is an entry, not an adjustment. The same rule the rest of the library
+ * follows: if a figure changed, there is a balanced journal entry with a
+ * narration that changed it, and a reader can find it. A closing pass that
+ * quietly rewrote balances would be the one operation in the system that could
+ * not be audited.
+ *
+ * And it returns a new ledger rather than mutating one. An entity's books are
+ * not the group's to rewrite: the group needs a view of them closed at a date
+ * for its own purposes, and the file on disk is unchanged. The append-only
+ * ledger makes that free.
+ */
+import { Money } from "../money/money.js";
+import type { Currency } from "../money/currency.js";
+import type { CalendarDate } from "./date.js";
+import { JournalEntry } from "./entry.js";
+import { Ledger } from "./ledger.js";
+export declare class CloseError extends Error {
+    constructor(message: string);
+}
+export interface CloseOptions {
+    /** Where the result goes. Retained earnings by default. */
+    reserves?: string;
+    /** The entry's id. One is derived from the date when this is not given. */
+    id?: string;
+    narration?: string;
+    /** Which currency's balances to close. Defaults to the ledger's first. */
+    currency?: Currency | string;
+    tags?: readonly string[];
+}
+/**
+ * The entry that closes the income and expense accounts as at a date.
+ *
+ * Null when there is nothing to close, which is the ordinary case for a ledger
+ * already closed at that date and for one that has not traded yet. A caller
+ * that wants an entry either way would be asking for an unbalanced one.
+ */
+export declare function closingEntry(ledger: Ledger, asAt: CalendarDate | string, options?: CloseOptions): JournalEntry | null;
+/**
+ * The same books, with the result to a date taken to reserves.
+ *
+ * The original ledger is untouched. Where there is nothing to close the same
+ * ledger comes back, so this is safe to call on books that are already closed
+ * and cheap to call when it turns out not to be needed.
+ */
+export declare function withResultClosed(ledger: Ledger, asAt: CalendarDate | string, options?: CloseOptions): Ledger;
+/**
+ * What an entity earned over a window, read off books closed at its start.
+ *
+ * This is the figure a consolidation wants when an entity was controlled for
+ * part of the period: the income and expense balances at the reporting date,
+ * on books closed the day the window opens. Returned as a credit-positive
+ * figure, the way a result reads.
+ */
+export declare function resultOver(ledger: Ledger, from: CalendarDate | string, to: CalendarDate | string, options?: CloseOptions): Money;

package/dist/ledger/close.js

@@ -0,0 +1,142 @@
+/**
+ * Closing the books at a date.
+ *
+ * A year end has a step nothing in this library has needed until now: the
+ * income and expense accounts are emptied into reserves, so that they start the
+ * next year at nil and the balance sheet carries what was earned. It is
+ * mechanical, and for a company keeping its own books it is a housekeeping
+ * task. It becomes interesting in a group.
+ *
+ * A consolidation reads an entity's result as the balance on its income
+ * accounts at the reporting date. That is right for books closed at each year
+ * end, where the balance is exactly the year's result, and wrong in two
+ * situations that are not unusual. A company acquired in March has twelve
+ * months on its income accounts and only nine of them belong to the group. A
+ * company that has never closed its books has every year since it was formed
+ * on them. In both cases the fix is the same: close the books at the date the
+ * period of interest begins, and what is left on the income accounts is the
+ * period's result and nothing else.
+ *
+ * Two things about how it is done here.
+ *
+ * It is an entry, not an adjustment. The same rule the rest of the library
+ * follows: if a figure changed, there is a balanced journal entry with a
+ * narration that changed it, and a reader can find it. A closing pass that
+ * quietly rewrote balances would be the one operation in the system that could
+ * not be audited.
+ *
+ * And it returns a new ledger rather than mutating one. An entity's books are
+ * not the group's to rewrite: the group needs a view of them closed at a date
+ * for its own purposes, and the file on disk is unchanged. The append-only
+ * ledger makes that free.
+ */
+import { Money } from "../money/money.js";
+import { date as parseDate } from "./date.js";
+import { JournalEntry } from "./entry.js";
+import { Ledger } from "./ledger.js";
+import { trialBalance } from "./trialBalance.js";
+export class CloseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CloseError";
+    }
+}
+/**
+ * The entry that closes the income and expense accounts as at a date.
+ *
+ * Null when there is nothing to close, which is the ordinary case for a ledger
+ * already closed at that date and for one that has not traded yet. A caller
+ * that wants an entry either way would be asking for an unbalanced one.
+ */
+export function closingEntry(ledger, asAt, options = {}) {
+    const when = parseDate(String(asAt));
+    const currencyCode = options.currency === undefined
+        ? (ledger.currenciesUsed()[0] ?? ledger.chart?.defaultCurrency.code ?? "GBP")
+        : typeof options.currency === "string"
+            ? options.currency.toUpperCase()
+            : options.currency.code;
+    const reserves = options.reserves ?? "3200";
+    const balances = trialBalance(ledger, { currency: currencyCode, asAt: when });
+    const postings = [];
+    let total = Money.zero(currencyCode);
+    for (const row of balances.rows) {
+        if (row.type !== "income" && row.type !== "expense")
+            continue;
+        if (row.account === reserves)
+            continue;
+        if (row.signed.isZero)
+            continue;
+        postings.push({
+            account: row.account,
+            amount: row.signed.negated(),
+            memo: `closed at ${when}`,
+        });
+        total = total.plus(row.signed);
+    }
+    if (postings.length === 0)
+        return null;
+    if (total.isZero) {
+        // Income and expenses that cancel exactly. There is still something to
+        // close — both sides have to come off — but no result to carry across, so
+        // the reserves line would be for zero and entries reject zero postings.
+        return JournalEntry.create({
+            id: options.id ?? `CLOSE-${when}`,
+            date: String(when),
+            narration: options.narration ?? `Result to ${when} closed to reserves`,
+            postings,
+            tags: options.tags ?? ["close"],
+        }, ledger.chart);
+    }
+    postings.push({
+        account: reserves,
+        amount: total,
+        memo: `result to ${when}`,
+    });
+    return JournalEntry.create({
+        id: options.id ?? `CLOSE-${when}`,
+        date: String(when),
+        narration: options.narration ?? `Result to ${when} closed to reserves`,
+        postings,
+        tags: options.tags ?? ["close"],
+    }, ledger.chart);
+}
+/**
+ * The same books, with the result to a date taken to reserves.
+ *
+ * The original ledger is untouched. Where there is nothing to close the same
+ * ledger comes back, so this is safe to call on books that are already closed
+ * and cheap to call when it turns out not to be needed.
+ */
+export function withResultClosed(ledger, asAt, options = {}) {
+    const entry = closingEntry(ledger, asAt, options);
+    if (entry === null)
+        return ledger;
+    if (ledger.has(entry.id)) {
+        // The ledger would reject the duplicate id anyway. Saying which operation
+        // collided is more use than a bare id clash from somewhere further down.
+        throw new CloseError(`These books already carry an entry ${entry.id}, so they have been closed at ` +
+            `${asAt} once already. Pass a different id if that is not what happened.`);
+    }
+    return ledger.post(entry);
+}
+/**
+ * What an entity earned over a window, read off books closed at its start.
+ *
+ * This is the figure a consolidation wants when an entity was controlled for
+ * part of the period: the income and expense balances at the reporting date,
+ * on books closed the day the window opens. Returned as a credit-positive
+ * figure, the way a result reads.
+ */
+export function resultOver(ledger, from, to, options = {}) {
+    const closed = withResultClosed(ledger, from, options);
+    const currencyCode = options.currency === undefined
+        ? (ledger.currenciesUsed()[0] ?? ledger.chart?.defaultCurrency.code ?? "GBP")
+        : typeof options.currency === "string"
+            ? options.currency.toUpperCase()
+            : options.currency.code;
+    const balances = trialBalance(closed, { currency: currencyCode, asAt: parseDate(String(to)) });
+    return balances.rows
+        .filter((row) => row.type === "income" || row.type === "expense")
+        .reduce((running, row) => running.plus(row.signed), Money.zero(currencyCode))
+        .negated();
+}

package/dist/ledger/date.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Calendar dates as `YYYY-MM-DD` strings.
+ *
+ * A posting happens on a date, not at an instant. Using `Date` here would drag
+ * in a timezone, and a statement line dated 1 March in London would sort before
+ * a ledger entry dated 1 March in New York. So: no clocks, no zones, just the
+ * proleptic Gregorian calendar and integer day arithmetic.
+ */
+export type CalendarDate = string & {
+    readonly __brand: "CalendarDate";
+};
+export declare class InvalidDateError extends Error {
+    constructor(value: string);
+}
+export declare function daysInMonth(year: number, month: number): number;
+/** Validate and brand a `YYYY-MM-DD` string. */
+export declare function date(value: string): CalendarDate;
+export declare function isValidDate(value: string): boolean;
+export declare function parts(d: CalendarDate): {
+    year: number;
+    month: number;
+    day: number;
+};
+/**
+ * Days since 1970-01-01, computed arithmetically (Howard Hinnant's civil-days
+ * algorithm) so there is no dependence on the host `Date` implementation.
+ */
+export declare function toEpochDay(d: CalendarDate): number;
+export declare function fromEpochDay(epochDay: number): CalendarDate;
+/** Signed whole days from `a` to `b`. */
+export declare function daysBetween(a: CalendarDate, b: CalendarDate): number;
+export declare function addDays(d: CalendarDate, days: number): CalendarDate;
+export declare function compareDates(a: CalendarDate, b: CalendarDate): -1 | 0 | 1;
+export declare function minDate(a: CalendarDate, b: CalendarDate): CalendarDate;
+export declare function maxDate(a: CalendarDate, b: CalendarDate): CalendarDate;
+/** 0 = Sunday through 6 = Saturday. */
+export declare function dayOfWeek(d: CalendarDate): number;
+export declare function isWeekend(d: CalendarDate): boolean;
+/** First and last day of the month containing `d`. */
+export declare function startOfMonth(d: CalendarDate): CalendarDate;
+export declare function endOfMonth(d: CalendarDate): CalendarDate;
+/** An inclusive date range. */
+export interface DateRange {
+    readonly from: CalendarDate;
+    readonly to: CalendarDate;
+}
+export declare function dateRange(from: string, to: string): DateRange;
+export declare function withinRange(d: CalendarDate, range: DateRange): boolean;

package/dist/ledger/date.js

@@ -0,0 +1,141 @@
+/**
+ * Calendar dates as `YYYY-MM-DD` strings.
+ *
+ * A posting happens on a date, not at an instant. Using `Date` here would drag
+ * in a timezone, and a statement line dated 1 March in London would sort before
+ * a ledger entry dated 1 March in New York. So: no clocks, no zones, just the
+ * proleptic Gregorian calendar and integer day arithmetic.
+ */
+const PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+export class InvalidDateError extends Error {
+    constructor(value) {
+        super(`Not a valid calendar date: ${JSON.stringify(value)}`);
+        this.name = "InvalidDateError";
+    }
+}
+function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+export function daysInMonth(year, month) {
+    switch (month) {
+        case 1:
+        case 3:
+        case 5:
+        case 7:
+        case 8:
+        case 10:
+        case 12:
+            return 31;
+        case 4:
+        case 6:
+        case 9:
+        case 11:
+            return 30;
+        case 2:
+            return isLeapYear(year) ? 29 : 28;
+        default:
+            throw new RangeError(`Month out of range: ${month}`);
+    }
+}
+/** Validate and brand a `YYYY-MM-DD` string. */
+export function date(value) {
+    const match = PATTERN.exec(value);
+    if (match === null)
+        throw new InvalidDateError(value);
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    if (month < 1 || month > 12)
+        throw new InvalidDateError(value);
+    if (day < 1 || day > daysInMonth(year, month))
+        throw new InvalidDateError(value);
+    return value;
+}
+export function isValidDate(value) {
+    try {
+        date(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function parts(d) {
+    const match = PATTERN.exec(d);
+    return {
+        year: Number(match[1]),
+        month: Number(match[2]),
+        day: Number(match[3]),
+    };
+}
+/**
+ * Days since 1970-01-01, computed arithmetically (Howard Hinnant's civil-days
+ * algorithm) so there is no dependence on the host `Date` implementation.
+ */
+export function toEpochDay(d) {
+    const { year, month, day } = parts(d);
+    const y = month <= 2 ? year - 1 : year;
+    const era = Math.floor(y / 400);
+    const yoe = y - era * 400;
+    const mp = (month + 9) % 12;
+    const doy = Math.floor((153 * mp + 2) / 5) + day - 1;
+    const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy;
+    return era * 146097 + doe - 719468;
+}
+export function fromEpochDay(epochDay) {
+    const z = epochDay + 719468;
+    const era = Math.floor(z / 146097);
+    const doe = z - era * 146097;
+    const yoe = Math.floor((doe - Math.floor(doe / 1460) + Math.floor(doe / 36524) - Math.floor(doe / 146096)) / 365);
+    const y = yoe + era * 400;
+    const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100));
+    const mp = Math.floor((5 * doy + 2) / 153);
+    const day = doy - Math.floor((153 * mp + 2) / 5) + 1;
+    const month = mp < 10 ? mp + 3 : mp - 9;
+    const year = month <= 2 ? y + 1 : y;
+    return `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+/** Signed whole days from `a` to `b`. */
+export function daysBetween(a, b) {
+    return toEpochDay(b) - toEpochDay(a);
+}
+export function addDays(d, days) {
+    return fromEpochDay(toEpochDay(d) + days);
+}
+export function compareDates(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export function minDate(a, b) {
+    return a <= b ? a : b;
+}
+export function maxDate(a, b) {
+    return a >= b ? a : b;
+}
+/** 0 = Sunday through 6 = Saturday. */
+export function dayOfWeek(d) {
+    return (((toEpochDay(d) + 4) % 7) + 7) % 7;
+}
+export function isWeekend(d) {
+    const dow = dayOfWeek(d);
+    return dow === 0 || dow === 6;
+}
+/** First and last day of the month containing `d`. */
+export function startOfMonth(d) {
+    const { year, month } = parts(d);
+    return `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}-01`;
+}
+export function endOfMonth(d) {
+    const { year, month } = parts(d);
+    const last = daysInMonth(year, month);
+    return `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}-${String(last).padStart(2, "0")}`;
+}
+export function dateRange(from, to) {
+    const f = date(from);
+    const t = date(to);
+    if (f > t)
+        throw new RangeError(`Date range is inverted: ${from}..${to}`);
+    return Object.freeze({ from: f, to: t });
+}
+export function withinRange(d, range) {
+    return d >= range.from && d <= range.to;
+}

package/dist/ledger/entry.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Journal entries and the balancing invariant.
+ *
+ * The central rule of this file: an unbalanced `JournalEntry` cannot be
+ * constructed. The check lives in the factory, the constructor is private, and
+ * every field is frozen — so no code downstream of this module has to remember
+ * to validate anything, and no code can un-balance an entry after the fact.
+ *
+ * Sign convention: a posting's amount is positive for a debit and negative for
+ * a credit. One signed number is easier to sum than a (side, magnitude) pair,
+ * and "the postings sum to zero" is then literally the invariant.
+ */
+import { Money } from "../money/money.js";
+import type { Currency } from "../money/currency.js";
+import type { ChartOfAccounts } from "../accounts/chart.js";
+import { type CalendarDate } from "./date.js";
+export declare class UnbalancedEntryError extends Error {
+    readonly residuals: readonly Money[];
+    readonly narration: string;
+    constructor(residuals: readonly Money[], narration: string);
+}
+export declare class InvalidEntryError extends Error {
+    constructor(message: string);
+}
+export interface PostingInput {
+    account: string;
+    amount: Money;
+    memo?: string;
+    /**
+     * The open item this line belongs to, when that is narrower than the entry's
+     * own reference. See `Posting.reference`.
+     */
+    reference?: string;
+    /**
+     * What actually moved, when that was not in the currency the books are kept
+     * in. See `Posting.foreign`.
+     */
+    foreign?: Money;
+}
+export interface Posting {
+    readonly account: string;
+    /** Positive is a debit, negative is a credit. */
+    readonly amount: Money;
+    readonly memo: string;
+    /** Index within the entry, stable and used for deterministic ordering. */
+    readonly index: number;
+    /**
+     * The open item this line belongs to, when the entry as a whole is about
+     * more than one of them.
+     *
+     * A revaluation adjusts several invoices in a single entry, and each of its
+     * postings belongs to a different one. Without this, the adjustment is
+     * attributable to the account but not to the item, and settling one invoice
+     * out of several would measure against what that invoice was originally
+     * booked at rather than what it is now carried at — booking the same rate
+     * movement once as unrealised and again as realised.
+     *
+     * Null means "whatever the entry says", which is the ordinary case.
+     */
+    readonly reference: string | null;
+    /**
+     * The transaction-currency amount, when the posting was denominated in
+     * something other than the functional currency.
+     *
+     * `amount` is always the figure the books are kept in and always the one the
+     * entry has to balance in — the invariant does not become "balances in every
+     * currency at once", because it never was true of a real transaction. A euro
+     * invoice is one economic event with two numbers attached: 1,000 EUR of
+     * receivable, booked at 847.30 GBP. The second is what the trial balance
+     * adds up; the first is what the customer owes and what a revaluation at the
+     * close has to look at.
+     *
+     * Signs agree with `amount`. A debit of 847.30 GBP carrying a credit of
+     * 1,000 EUR would be describing two different transactions.
+     */
+    readonly foreign: Money | null;
+}
+export interface JournalEntryInput {
+    id: string;
+    date: string;
+    narration: string;
+    postings: readonly PostingInput[];
+    /** External reference: invoice number, statement line id, cheque number. */
+    reference?: string;
+    tags?: readonly string[];
+    /** Set when this entry reverses another. */
+    reverses?: string;
+}
+export declare class JournalEntry {
+    readonly id: string;
+    readonly date: CalendarDate;
+    readonly narration: string;
+    readonly postings: readonly Posting[];
+    readonly reference: string | null;
+    readonly tags: readonly string[];
+    readonly reverses: string | null;
+    private constructor();
+    /**
+     * Build a validated entry. Throws unless:
+     * - there are at least two postings,
+     * - no posting is for zero,
+     * - the postings sum to zero *within each currency*,
+     * - and, when a chart is supplied, every account exists and is postable.
+     */
+    static create(input: JournalEntryInput, chart?: ChartOfAccounts): JournalEntry;
+    /** Convenience for the overwhelmingly common two-line entry. */
+    static simple(input: {
+        id: string;
+        date: string;
+        narration: string;
+        debit: string;
+        credit: string;
+        amount: Money;
+        reference?: string;
+        tags?: readonly string[];
+    }, chart?: ChartOfAccounts): JournalEntry;
+    get debits(): readonly Posting[];
+    get credits(): readonly Posting[];
+    get accounts(): readonly string[];
+    get currencies(): readonly Currency[];
+    get isMultiCurrency(): boolean;
+    /** Postings that record something that happened in another currency. */
+    get foreignPostings(): readonly Posting[];
+    get hasForeignAmounts(): boolean;
+    /** The transaction currencies this entry touches, deduplicated. */
+    get foreignCurrencies(): readonly Currency[];
+    /** Net foreign-currency effect on one account within this entry. */
+    foreignAmountFor(account: string, currency: Currency | string): Money;
+    /** Total of the debit side in the given currency — the entry's "size". */
+    total(currency?: Currency | string): Money;
+    /** The open item a posting belongs to: its own, or the entry's. */
+    referenceFor(posting: Posting): string | null;
+    touches(account: string): boolean;
+    /** Net effect on one account, summed across its postings in this entry. */
+    amountFor(account: string, currency?: Currency | string): Money;
+    /** A mirror-image entry that undoes this one. */
+    reversal(input: {
+        id: string;
+        date: string;
+        narration?: string;
+    }): JournalEntry;
+    toString(): string;
+    toJSON(): unknown;
+}
+/**
+ * Per-currency sums that are not zero. An empty result means the set balances.
+ * Exported because the ledger uses it to re-check invariants in bulk.
+ */
+export declare function residualsByCurrency(amounts: readonly Money[]): Money[];
+export declare function isBalanced(amounts: readonly Money[]): boolean;