@trajectonomics/ledger 0.0.0-stage → 0.1.0-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,285 @@
+/**
+ * Nominal tag. The private member makes the type unforgeable: TypeScript omits private members
+ * from object spreads and rejects object literals, so only an explicit cast can fake a brand.
+ */
+declare class Nominal<Tag extends string> {
+  private readonly tag;
+}
+/** A `T` carrying a nominal tag so unrelated values cannot be mixed up. */
+type Brand<T, Tag extends string> = T & Nominal<Tag>;
+/** An ISO 4217 alphabetic currency code, e.g. `"THB"`. */
+type Currency = Brand<string, "Currency">;
+/**
+ * Validate an ISO 4217 code against the runtime's own currency data
+ * (`Intl.supportedValuesOf("currency")`), so no code table ships in this package.
+ * The accepted set therefore follows the runtime's ICU version.
+ */
+export declare const parseCurrency: (value: unknown, field?: string) => Currency;
+/** Caller-supplied account identifier. This package never generates ids. */
+type AccountId = Brand<string, "AccountId">;
+/** Caller-supplied transaction identifier. This package never generates ids. */
+type TransactionId = Brand<string, "TransactionId">;
+/** Tag a string as an {@link AccountId}, e.g. to look an account up in a chart. */
+export declare const accountId: (value: string) => AccountId;
+/** Tag a string as a {@link TransactionId}. */
+export declare const transactionId: (value: string) => TransactionId;
+/** The five canonical account types. Opening balances use `equity`; there is no sixth type. */
+type AccountType = "asset" | "liability" | "equity" | "income" | "expense";
+/** Side on which an account type normally grows. Debit is `+`, credit is `-`. */
+type NormalBalance = "debit" | "credit";
+/** An account as supplied by a caller, before validation. */
+interface AccountInput {
+  readonly id: string;
+  readonly type: AccountType;
+  readonly currency: string;
+  /** Legal/accounting entity that owns the account. Defaults to `"default"`. */
+  readonly entityId?: string;
+  /** Header/summary account this account rolls up into. */
+  readonly parentId?: string;
+}
+/** A validated account. Only {@link createChartOfAccounts} produces these. */
+interface Account {
+  readonly id: AccountId;
+  readonly type: AccountType;
+  readonly currency: Currency;
+  readonly entityId: string;
+  readonly parentId?: AccountId;
+}
+/** `asset` and `expense` are debit-normal; `liability`, `equity` and `income` credit-normal. */
+export declare const normalBalance: (type: AccountType) => NormalBalance;
+/**
+ * A validated, hierarchy-checked set of accounts, read-only at runtime. Only
+ * {@link createChartOfAccounts} constructs one (this module's constructor is not exported from
+ * the package), so holding one proves parents exist, share entity and type, and form no cycle.
+ * Its state lives in `#private` fields, so it cannot be mutated even via `Map.prototype`.
+ */
+declare class ChartOfAccounts implements ReadonlyMap<AccountId, Account> {
+  #private;
+  constructor(accounts: ReadonlyMap<AccountId, Account>);
+  get size(): number;
+  get(id: AccountId): Account | undefined;
+  has(id: AccountId): boolean;
+  /** True for an account in this chart that no other account names as its parent. */
+  isLeaf(id: AccountId): boolean;
+  forEach(callbackfn: (value: Account, key: AccountId, map: ReadonlyMap<AccountId, Account>) => void, thisArg?: unknown): void;
+  entries(): MapIterator<[AccountId, Account]>;
+  keys(): MapIterator<AccountId>;
+  values(): MapIterator<Account>;
+  [Symbol.iterator](): MapIterator<[AccountId, Account]>;
+}
+/** A real calendar date formatted `YYYY-MM-DD`. No time, no timezone. */
+type ISODate = Brand<string, "ISODate">;
+export declare const parseISODate: (value: unknown, field?: string) => ISODate;
+/** A posting as supplied by a caller. `amount` is signed minor units: debit `+`, credit `-`. */
+interface PostingInput {
+  readonly accountId: string;
+  readonly amount: number;
+  readonly currency: string;
+  /** Cost centre / project / class tags. Keys and values must be non-empty. */
+  readonly dimensions?: Readonly<Record<string, string>>;
+}
+/** A validated posting. */
+interface Posting {
+  readonly accountId: AccountId;
+  readonly amount: number;
+  readonly currency: Currency;
+  readonly dimensions?: Readonly<Record<string, string>>;
+}
+/** A transaction as supplied by a caller. The caller supplies `id`; nothing here generates one. */
+interface TransactionInput {
+  readonly id: string;
+  readonly date: string;
+  readonly postings: readonly PostingInput[];
+  /** The transaction this one reverses or amends (append-only audit chain). */
+  readonly linkedTo?: string;
+}
+/** A balanced transaction. Only {@link validateTransaction} produces one. */
+type Transaction = Brand<{
+  readonly id: TransactionId;
+  readonly date: ISODate;
+  readonly postings: readonly Posting[];
+  readonly linkedTo?: TransactionId;
+}, "Transaction">;
+/** Validate a transaction against a chart. Throws {@link LedgerValidationError}. */
+export declare const validateTransaction: (input: TransactionInput, chart: ChartOfAccounts) => Transaction;
+/**
+ * Build an Amendment: `[reversal, replacement]`, both linked to the original. The replacement's
+ * own `linkedTo` is overwritten with the original's id.
+ */
+export declare const amend: (tx: Transaction, input: {
+  readonly reversal: {
+    readonly id: string;
+    readonly date: string;
+  };
+  readonly replacement: TransactionInput;
+}, chart: ChartOfAccounts) => readonly [Transaction, Transaction];
+/** One Leaf Account's raw signed Balance (Debit `+`, Credit `-`) in its own Currency. */
+interface BalanceRow {
+  readonly entityId: string;
+  readonly accountId: AccountId;
+  readonly currency: Currency;
+  readonly amount: number;
+}
+/**
+ * Every Leaf Account's Balance up to and including `asOf`, zeros included, sorted. Header
+ * Accounts never appear, so summing the rows never double counts.
+ *
+ * TODO(#14): Header Account roll-ups live in a separate query, never in these rows.
+ */
+export declare const balances: (transactions: readonly Transaction[], asOf: string, chart: ChartOfAccounts) => readonly BalanceRow[];
+/**
+ * One Leaf Account's Balance up to and including `asOf`: the row `balances` gives for it.
+ * Throws `UNKNOWN_ACCOUNT` for an id outside the chart and `NON_LEAF_ACCOUNT` for a Header.
+ *
+ * TODO(#14): a Header's roll-up Balance is a separate query, so a Header id is rejected here.
+ */
+export declare const balance: (transactions: readonly Transaction[], accountId: string, asOf: string, chart: ChartOfAccounts) => BalanceRow;
+/** Validate accounts and build the chart. Throws {@link LedgerValidationError}. */
+export declare const createChartOfAccounts: (inputs: Iterable<AccountInput>) => ChartOfAccounts;
+/** One leg of a Compound Entry: an Account, its own magnitude, and optional Dimensions. */
+interface CompoundLeg {
+  readonly accountId: string;
+  readonly amount: number;
+  readonly dimensions?: Readonly<Record<string, string>>;
+}
+/**
+ * Build a Compound Entry: many legs on either side, each with its own magnitude.
+ * The two sides must total the same amount.
+ */
+export declare const compound: (input: {
+  readonly id: string;
+  readonly date: string;
+  readonly debit: readonly CompoundLeg[];
+  readonly credit: readonly CompoundLeg[];
+}, chart: ChartOfAccounts) => Transaction;
+/**
+ * Every way a ledger input can be rejected. Each code names exactly one rule.
+ *
+ * TODO(#12): adding a code is source-breaking for a consumer that switches exhaustively over this
+ * union. How that growth is versioned and communicated is not decided yet.
+ */
+type LedgerErrorCode = "SINGLE_POSTING" | "INVALID_AMOUNT" | "ZERO_AMOUNT_POSTING" | "UNKNOWN_ACCOUNT" | "NON_LEAF_ACCOUNT" | "CURRENCY_MISMATCH" | "UNBALANCED_TRANSACTION" | "INVALID_DATE" | "INVALID_CURRENCY" | "INVALID_DIMENSION" | "INVALID_ACCOUNT_HIERARCHY" | "NEGATIVE_AMOUNT" | "DUPLICATE_TRANSACTION_ID" | "REVERSAL_BEFORE_ORIGINAL" | "NON_EQUITY_CONTRA" | "INVALID_PERIOD" | "AMOUNT_OVERFLOW";
+/** Thrown by every smart constructor and validator in this package. */
+export declare class LedgerValidationError extends Error {
+  readonly code: LedgerErrorCode;
+  /** Path of the offending input, e.g. `postings[1].accountId`. */
+  readonly field: string;
+  readonly value: unknown;
+  readonly reason: string;
+  constructor(code: LedgerErrorCode, field: string, value: unknown, reason: string);
+}
+type LegObject = {
+  readonly accountId: string;
+  readonly dimensions?: Readonly<Record<string, string>>;
+};
+/** One side of a builder entry: a bare account id, or an account id with Dimensions. */
+type LegInput = string | LegObject;
+/**
+ * Convert a major-unit amount (`12.34`) to signed integer minor units (`1234`).
+ * Rounds half away from zero; `toPrecision` strips binary-float noise first.
+ */
+export declare const toMinorUnits: (majorAmount: number, currency: string) => number;
+/** Convert signed integer minor units (`1234`) to a major-unit amount (`12.34`). */
+export declare const fromMinorUnits: (minorUnits: number, currency: string) => number;
+/** A named total for one `(Entity, Currency)` pair. */
+interface Total {
+  readonly entityId: string;
+  readonly currency: Currency;
+  readonly amount: number;
+}
+/** Net Worth: the asset and liability Balance rows behind it, and one total per `(Entity, Currency)`. */
+interface NetWorth {
+  readonly rows: readonly BalanceRow[];
+  readonly totals: readonly Total[];
+}
+/**
+ * Assets minus Liabilities up to and including `asOf`, per `(Entity, Currency)`, positive when
+ * assets exceed liabilities. Rows stay raw signed; Equity is not part of it. Raw liabilities are
+ * negative, so the natural-sign total is the plain sum of the rows.
+ */
+export declare const netWorth: (transactions: readonly Transaction[], asOf: string, chart: ChartOfAccounts) => NetWorth;
+/**
+ * Build an Opening Balance: `amount` posts on `account`, the opposite Posting on the equity
+ * `contra`. `amount` is signed (an overdrawn Asset opens negative); direction is never inferred.
+ */
+export declare const openingBalance: (input: {
+  readonly id: string;
+  readonly date: string;
+  readonly account: LegInput;
+  readonly contra: LegInput;
+  readonly amount: number;
+}, chart: ChartOfAccounts) => Transaction;
+/** A P&L row for one Dimension value; `null` collects Postings lacking the grouped key. */
+interface GroupedRow extends BalanceRow {
+  readonly dimensionValue: string | null;
+}
+/** P&L: raw rows for Income and Expense Leaf Accounts and income-minus-expenses totals. */
+interface ProfitAndLoss<Row extends BalanceRow = BalanceRow> {
+  readonly rows: readonly Row[];
+  readonly totals: readonly Total[];
+}
+/**
+ * The period and optional Dimension handling of a P&L query. An absent `from` means "from the
+ * start of the ledger". `where` is exact-match, ANDed; a missing key never matches.
+ */
+interface ProfitAndLossOptions {
+  readonly from?: string;
+  readonly to: string;
+  readonly groupBy?: string;
+  readonly where?: Readonly<Record<string, string>>;
+}
+/**
+ * Income minus Expenses over an inclusive period, per `(Entity, Currency)`, positive when income
+ * exceeds expenses. Rows stay raw signed, so the total is the negated sum of the rows. With
+ * `groupBy`, rows split by that Dimension's value and only groups with Postings appear. Totals hold
+ * one entry, zero if nothing posted, for every Income and Expense Leaf Account's pair.
+ */
+export declare function profitAndLoss(transactions: readonly Transaction[], options: ProfitAndLossOptions & {
+  readonly groupBy: string;
+}, chart: ChartOfAccounts): ProfitAndLoss<GroupedRow>;
+/** P&L without grouping: one row per Income and Expense Leaf Account; totals seeded per Leaf pair. */
+export declare function profitAndLoss(transactions: readonly Transaction[], options: ProfitAndLossOptions & {
+  readonly groupBy?: undefined;
+}, chart: ChartOfAccounts): ProfitAndLoss;
+/** P&L when `groupBy` is only known at runtime: rows are plain or grouped, totals seeded alike. */
+export declare function profitAndLoss(transactions: readonly Transaction[], options: ProfitAndLossOptions, chart: ChartOfAccounts): ProfitAndLoss<BalanceRow | GroupedRow>;
+/** Build a Reversal: the original's Postings in order, every sign flipped, linked to it. */
+export declare const reverse: (tx: Transaction, input: {
+  readonly id: string;
+  readonly date: string;
+}, chart: ChartOfAccounts) => Transaction;
+/** Build a Simple Entry: `+amount` on `debit`, `-amount` on `credit`. `amount` is a magnitude. */
+export declare const simple: (input: {
+  readonly id: string;
+  readonly date: string;
+  readonly debit: LegInput;
+  readonly credit: LegInput;
+  readonly amount: number;
+}, chart: ChartOfAccounts) => Transaction;
+/** One Leaf Account's net Balance as a magnitude in its Debit or Credit column. */
+interface TrialBalanceRow {
+  readonly entityId: string;
+  readonly accountId: AccountId;
+  readonly currency: Currency;
+  readonly debit: number;
+  readonly credit: number;
+}
+/** Column totals for one `(Entity, Currency)` pair. They always match. */
+interface TrialBalanceTotal {
+  readonly entityId: string;
+  readonly currency: Currency;
+  readonly debit: number;
+  readonly credit: number;
+}
+/** A Trial Balance: one row per Leaf Account and column totals per `(Entity, Currency)`. */
+interface TrialBalance {
+  readonly rows: readonly TrialBalanceRow[];
+  readonly totals: readonly TrialBalanceTotal[];
+}
+/**
+ * Every Leaf Account's net Balance at `asOf`, zeros included: positive in `debit`, negative in
+ * `credit` as a magnitude (the one exception to raw signed rows).
+ */
+export declare const trialBalance: (transactions: readonly Transaction[], asOf: string, chart: ChartOfAccounts) => TrialBalance;
+export type { Account, AccountId, AccountInput, AccountType, BalanceRow, ChartOfAccounts, CompoundLeg, Currency, GroupedRow, ISODate, LedgerErrorCode, LegInput, NetWorth, NormalBalance, Posting, PostingInput, ProfitAndLoss, ProfitAndLossOptions, Total, Transaction, TransactionId, TransactionInput, TrialBalance, TrialBalanceRow, TrialBalanceTotal };
+//# sourceMappingURL=index.d.mts.map