@lacspace/ledger 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data 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 conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+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.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,86 @@
+<div align="center">
+
+# @lacspace/ledger
+
+**A tiny double-entry ledger / wallet — balanced transactions, per-account balances and a trial balance that always sums to zero.**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/ledger?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/ledger)
+[![install size](https://packagephobia.com/badge?p=@lacspace/ledger)](https://packagephobia.com/result?p=@lacspace/ledger)
+[![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/ledger?label=minzip)](https://bundlephobia.com/package/@lacspace/ledger)
+[![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/ledger)
+[![license](https://img.shields.io/npm/l/@lacspace/ledger?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> Wallets and internal balances are usually a single mutable number that silently drifts. This is **double-entry** in a few bytes: every transaction is a set of signed lines that sum to **zero**, so the books can't go out of balance. Integer minor units, immutable operations, crypto-random ids.
+
+- ⚖️ **Always balanced** — a transaction's lines must sum to `0`, or it throws
+- 💯 **Integer minor units** — cents / paisa, never floats
+- 🧊 **Immutable** — every op returns a new ledger
+- 📒 `balance`, `statement` and a `trialBalance` that totals zero
+- ⚡ Isomorphic (Web Crypto ids) · zero dependencies · fully typed
+
+## Install
+
+```bash
+npm install @lacspace/ledger      # or pnpm add / yarn add / bun add
+```
+
+## Usage
+
+```ts
+import { createLedger, post, postMany, balance, statement, trialBalance } from "@lacspace/ledger";
+
+let book = createLedger();
+
+// Simple two-line posting: +amount to `debit`, -amount to `credit`
+book = post(book, { debit: "cash", credit: "sales", amount: 10000, ref: "INV-1" });
+
+// Multi-line posting — throws unless the signed amounts sum to 0
+book = postMany(book, [
+  { account: "cash",  amount: 9700 },
+  { account: "fees",  amount: 300 },
+  { account: "sales", amount: -10000 },
+], { memo: "sale less processor fee" });
+
+balance(book, "cash");       // 19700
+statement(book, "cash");     // [{ at, amount, ref?, memo? }, …]
+trialBalance(book);          // [{ account, balance }, …] — always sums to 0
+```
+
+## Sign convention
+
+An account's balance is the **sum of its signed line amounts**. A **debit is positive**, a **credit is negative**. So `post({ debit, credit, amount })` books `+amount` to `debit` and `-amount` to `credit`. Under this rule an asset/expense account rises when debited; a liability/income/equity account rises when credited (its balance goes further negative).
+
+## API
+
+| Function | Description |
+| --- | --- |
+| `createLedger()` | a new empty ledger |
+| `post(ledger, { debit, credit, amount, ref?, memo? })` | two-line balanced entry (`amount` positive) |
+| `postMany(ledger, lines[], meta?)` | arbitrary entry — **throws** if lines don't sum to 0 |
+| `balance(ledger, account)` | sum of that account's signed lines |
+| `statement(ledger, account)` | rows `{ at, amount, ref?, memo? }` for entries touching the account |
+| `trialBalance(ledger)` | `{ account, balance }[]`, sorted, always sums to 0 |
+
+## Licensing
+
+This package is **free** under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — permissive freedoms. Use it in personal and commercial projects at no cost; just keep the notice.
+
+Not every Lacspace package is free. We also offer **Commercial** (paid), **Client-specific**, and **Private** (proprietary) packages under separate terms. See the full **[Lacspace Licence Centre](https://lacspace.com/licenses)**.
+
+<!-- LACSPACE-DEV-PLATFORM -->
+
+---
+
+## The Lacspace Developer Platform
+
+`@lacspace/ledger` is part of **63+ zero-dependency, isomorphic TypeScript packages**. Explore the ecosystem:
+
+- 🗂️ **All packages** — https://developer.lacspace.com/packages
+- 🧭 **Developer handbook** — https://developer.lacspace.com/handbook
+- 🧪 **Live playground** — https://developer.lacspace.com/playground
+- 🖥️ **Finished app templates** — https://templates.lacspace.com
+- 🚀 **Scaffold a full app** — `npm create lacspace-app@latest`
+
+Free under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — a permissive, free-to-use licence.

package/dist/index.cjs

@@ -0,0 +1,108 @@
+'use strict';
+
+// src/index.ts
+var HEX = [];
+for (let i = 0; i < 256; i++) HEX.push((i + 256).toString(16).slice(1));
+function genId() {
+  const c = globalThis.crypto;
+  if (!c || typeof c.getRandomValues !== "function") {
+    throw new Error("Web Crypto getRandomValues is unavailable in this environment.");
+  }
+  const b = new Uint8Array(16);
+  c.getRandomValues(b);
+  let out = "";
+  for (let i = 0; i < 16; i++) out += HEX[b[i]];
+  return out;
+}
+function assertInteger(amount, label) {
+  if (!Number.isInteger(amount)) {
+    throw new TypeError(`${label} must be an integer number of minor units, got ${amount}`);
+  }
+}
+function createLedger() {
+  return { entries: [] };
+}
+function append(ledger, lines, meta) {
+  const entry = {
+    id: genId(),
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    lines,
+    ...meta?.ref !== void 0 ? { ref: meta.ref } : {},
+    ...meta?.memo !== void 0 ? { memo: meta.memo } : {}
+  };
+  return { entries: [...ledger.entries, entry] };
+}
+function post(ledger, tx) {
+  assertInteger(tx.amount, "amount");
+  if (tx.amount <= 0) {
+    throw new RangeError(`post() amount must be positive, got ${tx.amount}`);
+  }
+  const lines = [
+    { account: tx.debit, amount: tx.amount },
+    { account: tx.credit, amount: -tx.amount }
+  ];
+  return append(ledger, lines, { ref: tx.ref, memo: tx.memo });
+}
+function postMany(ledger, lines, meta) {
+  if (!Array.isArray(lines) || lines.length === 0) {
+    throw new RangeError("postMany() requires at least one line");
+  }
+  let sum = 0;
+  for (const line of lines) {
+    assertInteger(line.amount, "line amount");
+    sum += line.amount;
+  }
+  if (sum !== 0) {
+    throw new RangeError(`unbalanced transaction: lines sum to ${sum}, expected 0`);
+  }
+  return append(ledger, lines.map((l) => ({ account: l.account, amount: l.amount })), meta);
+}
+function balance(ledger, account) {
+  let total = 0;
+  for (const entry of ledger.entries) {
+    for (const line of entry.lines) {
+      if (line.account === account) total += line.amount;
+    }
+  }
+  return total;
+}
+function statement(ledger, account) {
+  const rows = [];
+  for (const entry of ledger.entries) {
+    let net = 0;
+    let touched = false;
+    for (const line of entry.lines) {
+      if (line.account === account) {
+        net += line.amount;
+        touched = true;
+      }
+    }
+    if (touched) {
+      rows.push({
+        at: entry.at,
+        amount: net,
+        ...entry.ref !== void 0 ? { ref: entry.ref } : {},
+        ...entry.memo !== void 0 ? { memo: entry.memo } : {}
+      });
+    }
+  }
+  return rows;
+}
+function trialBalance(ledger) {
+  const totals = /* @__PURE__ */ new Map();
+  for (const entry of ledger.entries) {
+    for (const line of entry.lines) {
+      totals.set(line.account, (totals.get(line.account) ?? 0) + line.amount);
+    }
+  }
+  return [...totals.entries()].map(([account, bal]) => ({ account, balance: bal })).sort((a, b) => a.account < b.account ? -1 : a.account > b.account ? 1 : 0);
+}
+
+exports.balance = balance;
+exports.createLedger = createLedger;
+exports.post = post;
+exports.postMany = postMany;
+exports.statement = statement;
+exports.trialBalance = trialBalance;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @lacspace/ledger\n *\n * A tiny **double-entry** ledger / wallet. Every transaction is a set of lines\n * whose signed amounts sum to **zero**, so the books can never drift: balances\n * are just sums, and the trial balance always totals zero.\n *\n * Sign convention: an account's balance is the sum of its signed line amounts.\n * A debit is a **positive** amount, a credit is a **negative** one — so\n * `post({ debit, credit, amount })` books `+amount` to `debit` and `-amount` to\n * `credit`. Under this convention an asset/expense account rises when debited\n * and a liability/income/equity account rises when credited (its balance goes\n * more negative). Amounts are **integer minor units** (cents, paisa, …).\n *\n * ```ts\n * import { createLedger, post, balance, trialBalance } from \"@lacspace/ledger\";\n *\n * let book = createLedger();\n * book = post(book, { debit: \"cash\", credit: \"sales\", amount: 10000 });\n * balance(book, \"cash\");   //  10000\n * balance(book, \"sales\");  // -10000\n * trialBalance(book);      // sums to 0\n * ```\n *\n * Immutable — every operation returns a new {@link Ledger}. Zero dependencies,\n * isomorphic (ids use Web Crypto `getRandomValues`).\n */\n\n/** A single posting line: a signed amount against an account (minor units). */\nexport interface LedgerLine {\n  account: string;\n  /** Signed amount in minor units. A transaction's lines MUST sum to 0. */\n  amount: number;\n}\n\n/** One posted transaction. Its `lines` always sum to zero. */\nexport interface LedgerEntry {\n  /** Unique id (crypto-random). */\n  id: string;\n  /** ISO-8601 timestamp of when it was posted. */\n  at: string;\n  lines: LedgerLine[];\n  /** Optional external reference (invoice #, txn id, …). */\n  ref?: string;\n  /** Optional human-readable note. */\n  memo?: string;\n}\n\n/** An immutable ledger — an ordered list of balanced entries. */\nexport interface Ledger {\n  entries: LedgerEntry[];\n}\n\n/** A single row of a {@link statement}. */\nexport interface StatementRow {\n  at: string;\n  /** Net signed amount this entry moved on the account (minor units). */\n  amount: number;\n  ref?: string;\n  memo?: string;\n}\n\n/** A single row of a {@link trialBalance}. */\nexport interface TrialBalanceRow {\n  account: string;\n  balance: number;\n}\n\nconst HEX: string[] = [];\nfor (let i = 0; i < 256; i++) HEX.push((i + 0x100).toString(16).slice(1));\n\n/** Crypto-random 16-byte hex id. Isomorphic via Web Crypto. */\nfunction genId(): string {\n  const c = (globalThis as { crypto?: Crypto }).crypto;\n  if (!c || typeof c.getRandomValues !== \"function\") {\n    throw new Error(\"Web Crypto getRandomValues is unavailable in this environment.\");\n  }\n  const b = new Uint8Array(16);\n  c.getRandomValues(b);\n  let out = \"\";\n  for (let i = 0; i < 16; i++) out += HEX[b[i]!]!;\n  return out;\n}\n\nfunction assertInteger(amount: number, label: string): void {\n  if (!Number.isInteger(amount)) {\n    throw new TypeError(`${label} must be an integer number of minor units, got ${amount}`);\n  }\n}\n\n/** Create a new, empty ledger. */\nexport function createLedger(): Ledger {\n  return { entries: [] };\n}\n\n/** Append a pre-built, already-balanced entry (immutable). */\nfunction append(\n  ledger: Ledger,\n  lines: LedgerLine[],\n  meta?: { ref?: string; memo?: string }\n): Ledger {\n  const entry: LedgerEntry = {\n    id: genId(),\n    at: new Date().toISOString(),\n    lines,\n    ...(meta?.ref !== undefined ? { ref: meta.ref } : {}),\n    ...(meta?.memo !== undefined ? { memo: meta.memo } : {}),\n  };\n  return { entries: [...ledger.entries, entry] };\n}\n\n/**\n * Post a simple two-line transaction: `+amount` to `debit`, `-amount` to\n * `credit`. `amount` must be a positive integer (minor units). Returns a new\n * ledger — the input is never mutated.\n */\nexport function post(\n  ledger: Ledger,\n  tx: { debit: string; credit: string; amount: number; ref?: string; memo?: string }\n): Ledger {\n  assertInteger(tx.amount, \"amount\");\n  if (tx.amount <= 0) {\n    throw new RangeError(`post() amount must be positive, got ${tx.amount}`);\n  }\n  const lines: LedgerLine[] = [\n    { account: tx.debit, amount: tx.amount },\n    { account: tx.credit, amount: -tx.amount },\n  ];\n  return append(ledger, lines, { ref: tx.ref, memo: tx.memo });\n}\n\n/**\n * Post an arbitrary multi-line transaction. **Throws** if the signed line\n * amounts don't sum to exactly zero (or any amount isn't an integer).\n */\nexport function postMany(\n  ledger: Ledger,\n  lines: LedgerLine[],\n  meta?: { ref?: string; memo?: string }\n): Ledger {\n  if (!Array.isArray(lines) || lines.length === 0) {\n    throw new RangeError(\"postMany() requires at least one line\");\n  }\n  let sum = 0;\n  for (const line of lines) {\n    assertInteger(line.amount, \"line amount\");\n    sum += line.amount;\n  }\n  if (sum !== 0) {\n    throw new RangeError(`unbalanced transaction: lines sum to ${sum}, expected 0`);\n  }\n  return append(ledger, lines.map((l) => ({ account: l.account, amount: l.amount })), meta);\n}\n\n/** Balance of an account: the sum of all its signed line amounts. */\nexport function balance(ledger: Ledger, account: string): number {\n  let total = 0;\n  for (const entry of ledger.entries) {\n    for (const line of entry.lines) {\n      if (line.account === account) total += line.amount;\n    }\n  }\n  return total;\n}\n\n/**\n * Statement for one account: one row per entry that touches it, in order, with\n * the net signed amount that entry moved on the account.\n */\nexport function statement(ledger: Ledger, account: string): StatementRow[] {\n  const rows: StatementRow[] = [];\n  for (const entry of ledger.entries) {\n    let net = 0;\n    let touched = false;\n    for (const line of entry.lines) {\n      if (line.account === account) {\n        net += line.amount;\n        touched = true;\n      }\n    }\n    if (touched) {\n      rows.push({\n        at: entry.at,\n        amount: net,\n        ...(entry.ref !== undefined ? { ref: entry.ref } : {}),\n        ...(entry.memo !== undefined ? { memo: entry.memo } : {}),\n      });\n    }\n  }\n  return rows;\n}\n\n/**\n * Trial balance: every account with its balance, sorted by account name. Since\n * every entry is balanced, the balances always sum to exactly zero.\n */\nexport function trialBalance(ledger: Ledger): TrialBalanceRow[] {\n  const totals = new Map<string, number>();\n  for (const entry of ledger.entries) {\n    for (const line of entry.lines) {\n      totals.set(line.account, (totals.get(line.account) ?? 0) + line.amount);\n    }\n  }\n  return [...totals.entries()]\n    .map(([account, bal]) => ({ account, balance: bal }))\n    .sort((a, b) => (a.account < b.account ? -1 : a.account > b.account ? 1 : 0));\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,98 @@
+/**
+ * @lacspace/ledger
+ *
+ * A tiny **double-entry** ledger / wallet. Every transaction is a set of lines
+ * whose signed amounts sum to **zero**, so the books can never drift: balances
+ * are just sums, and the trial balance always totals zero.
+ *
+ * Sign convention: an account's balance is the sum of its signed line amounts.
+ * A debit is a **positive** amount, a credit is a **negative** one — so
+ * `post({ debit, credit, amount })` books `+amount` to `debit` and `-amount` to
+ * `credit`. Under this convention an asset/expense account rises when debited
+ * and a liability/income/equity account rises when credited (its balance goes
+ * more negative). Amounts are **integer minor units** (cents, paisa, …).
+ *
+ * ```ts
+ * import { createLedger, post, balance, trialBalance } from "@lacspace/ledger";
+ *
+ * let book = createLedger();
+ * book = post(book, { debit: "cash", credit: "sales", amount: 10000 });
+ * balance(book, "cash");   //  10000
+ * balance(book, "sales");  // -10000
+ * trialBalance(book);      // sums to 0
+ * ```
+ *
+ * Immutable — every operation returns a new {@link Ledger}. Zero dependencies,
+ * isomorphic (ids use Web Crypto `getRandomValues`).
+ */
+/** A single posting line: a signed amount against an account (minor units). */
+interface LedgerLine {
+    account: string;
+    /** Signed amount in minor units. A transaction's lines MUST sum to 0. */
+    amount: number;
+}
+/** One posted transaction. Its `lines` always sum to zero. */
+interface LedgerEntry {
+    /** Unique id (crypto-random). */
+    id: string;
+    /** ISO-8601 timestamp of when it was posted. */
+    at: string;
+    lines: LedgerLine[];
+    /** Optional external reference (invoice #, txn id, …). */
+    ref?: string;
+    /** Optional human-readable note. */
+    memo?: string;
+}
+/** An immutable ledger — an ordered list of balanced entries. */
+interface Ledger {
+    entries: LedgerEntry[];
+}
+/** A single row of a {@link statement}. */
+interface StatementRow {
+    at: string;
+    /** Net signed amount this entry moved on the account (minor units). */
+    amount: number;
+    ref?: string;
+    memo?: string;
+}
+/** A single row of a {@link trialBalance}. */
+interface TrialBalanceRow {
+    account: string;
+    balance: number;
+}
+/** Create a new, empty ledger. */
+declare function createLedger(): Ledger;
+/**
+ * Post a simple two-line transaction: `+amount` to `debit`, `-amount` to
+ * `credit`. `amount` must be a positive integer (minor units). Returns a new
+ * ledger — the input is never mutated.
+ */
+declare function post(ledger: Ledger, tx: {
+    debit: string;
+    credit: string;
+    amount: number;
+    ref?: string;
+    memo?: string;
+}): Ledger;
+/**
+ * Post an arbitrary multi-line transaction. **Throws** if the signed line
+ * amounts don't sum to exactly zero (or any amount isn't an integer).
+ */
+declare function postMany(ledger: Ledger, lines: LedgerLine[], meta?: {
+    ref?: string;
+    memo?: string;
+}): Ledger;
+/** Balance of an account: the sum of all its signed line amounts. */
+declare function balance(ledger: Ledger, account: string): number;
+/**
+ * Statement for one account: one row per entry that touches it, in order, with
+ * the net signed amount that entry moved on the account.
+ */
+declare function statement(ledger: Ledger, account: string): StatementRow[];
+/**
+ * Trial balance: every account with its balance, sorted by account name. Since
+ * every entry is balanced, the balances always sum to exactly zero.
+ */
+declare function trialBalance(ledger: Ledger): TrialBalanceRow[];
+
+export { type Ledger, type LedgerEntry, type LedgerLine, type StatementRow, type TrialBalanceRow, balance, createLedger, post, postMany, statement, trialBalance };

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @lacspace/ledger
+ *
+ * A tiny **double-entry** ledger / wallet. Every transaction is a set of lines
+ * whose signed amounts sum to **zero**, so the books can never drift: balances
+ * are just sums, and the trial balance always totals zero.
+ *
+ * Sign convention: an account's balance is the sum of its signed line amounts.
+ * A debit is a **positive** amount, a credit is a **negative** one — so
+ * `post({ debit, credit, amount })` books `+amount` to `debit` and `-amount` to
+ * `credit`. Under this convention an asset/expense account rises when debited
+ * and a liability/income/equity account rises when credited (its balance goes
+ * more negative). Amounts are **integer minor units** (cents, paisa, …).
+ *
+ * ```ts
+ * import { createLedger, post, balance, trialBalance } from "@lacspace/ledger";
+ *
+ * let book = createLedger();
+ * book = post(book, { debit: "cash", credit: "sales", amount: 10000 });
+ * balance(book, "cash");   //  10000
+ * balance(book, "sales");  // -10000
+ * trialBalance(book);      // sums to 0
+ * ```
+ *
+ * Immutable — every operation returns a new {@link Ledger}. Zero dependencies,
+ * isomorphic (ids use Web Crypto `getRandomValues`).
+ */
+/** A single posting line: a signed amount against an account (minor units). */
+interface LedgerLine {
+    account: string;
+    /** Signed amount in minor units. A transaction's lines MUST sum to 0. */
+    amount: number;
+}
+/** One posted transaction. Its `lines` always sum to zero. */
+interface LedgerEntry {
+    /** Unique id (crypto-random). */
+    id: string;
+    /** ISO-8601 timestamp of when it was posted. */
+    at: string;
+    lines: LedgerLine[];
+    /** Optional external reference (invoice #, txn id, …). */
+    ref?: string;
+    /** Optional human-readable note. */
+    memo?: string;
+}
+/** An immutable ledger — an ordered list of balanced entries. */
+interface Ledger {
+    entries: LedgerEntry[];
+}
+/** A single row of a {@link statement}. */
+interface StatementRow {
+    at: string;
+    /** Net signed amount this entry moved on the account (minor units). */
+    amount: number;
+    ref?: string;
+    memo?: string;
+}
+/** A single row of a {@link trialBalance}. */
+interface TrialBalanceRow {
+    account: string;
+    balance: number;
+}
+/** Create a new, empty ledger. */
+declare function createLedger(): Ledger;
+/**
+ * Post a simple two-line transaction: `+amount` to `debit`, `-amount` to
+ * `credit`. `amount` must be a positive integer (minor units). Returns a new
+ * ledger — the input is never mutated.
+ */
+declare function post(ledger: Ledger, tx: {
+    debit: string;
+    credit: string;
+    amount: number;
+    ref?: string;
+    memo?: string;
+}): Ledger;
+/**
+ * Post an arbitrary multi-line transaction. **Throws** if the signed line
+ * amounts don't sum to exactly zero (or any amount isn't an integer).
+ */
+declare function postMany(ledger: Ledger, lines: LedgerLine[], meta?: {
+    ref?: string;
+    memo?: string;
+}): Ledger;
+/** Balance of an account: the sum of all its signed line amounts. */
+declare function balance(ledger: Ledger, account: string): number;
+/**
+ * Statement for one account: one row per entry that touches it, in order, with
+ * the net signed amount that entry moved on the account.
+ */
+declare function statement(ledger: Ledger, account: string): StatementRow[];
+/**
+ * Trial balance: every account with its balance, sorted by account name. Since
+ * every entry is balanced, the balances always sum to exactly zero.
+ */
+declare function trialBalance(ledger: Ledger): TrialBalanceRow[];
+
+export { type Ledger, type LedgerEntry, type LedgerLine, type StatementRow, type TrialBalanceRow, balance, createLedger, post, postMany, statement, trialBalance };

package/dist/index.js

@@ -0,0 +1,101 @@
+// src/index.ts
+var HEX = [];
+for (let i = 0; i < 256; i++) HEX.push((i + 256).toString(16).slice(1));
+function genId() {
+  const c = globalThis.crypto;
+  if (!c || typeof c.getRandomValues !== "function") {
+    throw new Error("Web Crypto getRandomValues is unavailable in this environment.");
+  }
+  const b = new Uint8Array(16);
+  c.getRandomValues(b);
+  let out = "";
+  for (let i = 0; i < 16; i++) out += HEX[b[i]];
+  return out;
+}
+function assertInteger(amount, label) {
+  if (!Number.isInteger(amount)) {
+    throw new TypeError(`${label} must be an integer number of minor units, got ${amount}`);
+  }
+}
+function createLedger() {
+  return { entries: [] };
+}
+function append(ledger, lines, meta) {
+  const entry = {
+    id: genId(),
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    lines,
+    ...meta?.ref !== void 0 ? { ref: meta.ref } : {},
+    ...meta?.memo !== void 0 ? { memo: meta.memo } : {}
+  };
+  return { entries: [...ledger.entries, entry] };
+}
+function post(ledger, tx) {
+  assertInteger(tx.amount, "amount");
+  if (tx.amount <= 0) {
+    throw new RangeError(`post() amount must be positive, got ${tx.amount}`);
+  }
+  const lines = [
+    { account: tx.debit, amount: tx.amount },
+    { account: tx.credit, amount: -tx.amount }
+  ];
+  return append(ledger, lines, { ref: tx.ref, memo: tx.memo });
+}
+function postMany(ledger, lines, meta) {
+  if (!Array.isArray(lines) || lines.length === 0) {
+    throw new RangeError("postMany() requires at least one line");
+  }
+  let sum = 0;
+  for (const line of lines) {
+    assertInteger(line.amount, "line amount");
+    sum += line.amount;
+  }
+  if (sum !== 0) {
+    throw new RangeError(`unbalanced transaction: lines sum to ${sum}, expected 0`);
+  }
+  return append(ledger, lines.map((l) => ({ account: l.account, amount: l.amount })), meta);
+}
+function balance(ledger, account) {
+  let total = 0;
+  for (const entry of ledger.entries) {
+    for (const line of entry.lines) {
+      if (line.account === account) total += line.amount;
+    }
+  }
+  return total;
+}
+function statement(ledger, account) {
+  const rows = [];
+  for (const entry of ledger.entries) {
+    let net = 0;
+    let touched = false;
+    for (const line of entry.lines) {
+      if (line.account === account) {
+        net += line.amount;
+        touched = true;
+      }
+    }
+    if (touched) {
+      rows.push({
+        at: entry.at,
+        amount: net,
+        ...entry.ref !== void 0 ? { ref: entry.ref } : {},
+        ...entry.memo !== void 0 ? { memo: entry.memo } : {}
+      });
+    }
+  }
+  return rows;
+}
+function trialBalance(ledger) {
+  const totals = /* @__PURE__ */ new Map();
+  for (const entry of ledger.entries) {
+    for (const line of entry.lines) {
+      totals.set(line.account, (totals.get(line.account) ?? 0) + line.amount);
+    }
+  }
+  return [...totals.entries()].map(([account, bal]) => ({ account, balance: bal })).sort((a, b) => a.account < b.account ? -1 : a.account > b.account ? 1 : 0);
+}
+
+export { balance, createLedger, post, postMany, statement, trialBalance };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AAoEA,IAAM,MAAgB,EAAC;AACvB,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,GAAA,EAAK,KAAK,GAAA,CAAI,IAAA,CAAA,CAAM,CAAA,GAAI,GAAA,EAAO,QAAA,CAAS,EAAE,CAAA,CAAE,KAAA,CAAM,CAAC,CAAC,CAAA;AAGxE,SAAS,KAAA,GAAgB;AACvB,EAAA,MAAM,IAAK,UAAA,CAAmC,MAAA;AAC9C,EAAA,IAAI,CAAC,CAAA,IAAK,OAAO,CAAA,CAAE,oBAAoB,UAAA,EAAY;AACjD,IAAA,MAAM,IAAI,MAAM,gEAAgE,CAAA;AAAA,EAClF;AACA,EAAA,MAAM,CAAA,GAAI,IAAI,UAAA,CAAW,EAAE,CAAA;AAC3B,EAAA,CAAA,CAAE,gBAAgB,CAAC,CAAA;AACnB,EAAA,IAAI,GAAA,GAAM,EAAA;AACV,EAAA,KAAA,IAAS,CAAA,GAAI,GAAG,CAAA,GAAI,EAAA,EAAI,KAAK,GAAA,IAAO,GAAA,CAAI,CAAA,CAAE,CAAC,CAAE,CAAA;AAC7C,EAAA,OAAO,GAAA;AACT;AAEA,SAAS,aAAA,CAAc,QAAgB,KAAA,EAAqB;AAC1D,EAAA,IAAI,CAAC,MAAA,CAAO,SAAA,CAAU,MAAM,CAAA,EAAG;AAC7B,IAAA,MAAM,IAAI,SAAA,CAAU,CAAA,EAAG,KAAK,CAAA,+CAAA,EAAkD,MAAM,CAAA,CAAE,CAAA;AAAA,EACxF;AACF;AAGO,SAAS,YAAA,GAAuB;AACrC,EAAA,OAAO,EAAE,OAAA,EAAS,EAAC,EAAE;AACvB;AAGA,SAAS,MAAA,CACP,MAAA,EACA,KAAA,EACA,IAAA,EACQ;AACR,EAAA,MAAM,KAAA,GAAqB;AAAA,IACzB,IAAI,KAAA,EAAM;AAAA,IACV,EAAA,EAAA,iBAAI,IAAI,IAAA,EAAK,EAAE,WAAA,EAAY;AAAA,IAC3B,KAAA;AAAA,IACA,GAAI,MAAM,GAAA,KAAQ,MAAA,GAAY,EAAE,GAAA,EAAK,IAAA,CAAK,GAAA,EAAI,GAAI,EAAC;AAAA,IACnD,GAAI,MAAM,IAAA,KAAS,MAAA,GAAY,EAAE,IAAA,EAAM,IAAA,CAAK,IAAA,EAAK,GAAI;AAAC,GACxD;AACA,EAAA,OAAO,EAAE,OAAA,EAAS,CAAC,GAAG,MAAA,CAAO,OAAA,EAAS,KAAK,CAAA,EAAE;AAC/C;AAOO,SAAS,IAAA,CACd,QACA,EAAA,EACQ;AACR,EAAA,aAAA,CAAc,EAAA,CAAG,QAAQ,QAAQ,CAAA;AACjC,EAAA,IAAI,EAAA,CAAG,UAAU,CAAA,EAAG;AAClB,IAAA,MAAM,IAAI,UAAA,CAAW,CAAA,oCAAA,EAAuC,EAAA,CAAG,MAAM,CAAA,CAAE,CAAA;AAAA,EACzE;AACA,EAAA,MAAM,KAAA,GAAsB;AAAA,IAC1B,EAAE,OAAA,EAAS,EAAA,CAAG,KAAA,EAAO,MAAA,EAAQ,GAAG,MAAA,EAAO;AAAA,IACvC,EAAE,OAAA,EAAS,EAAA,CAAG,QAAQ,MAAA,EAAQ,CAAC,GAAG,MAAA;AAAO,GAC3C;AACA,EAAA,OAAO,MAAA,CAAO,MAAA,EAAQ,KAAA,EAAO,EAAE,GAAA,EAAK,GAAG,GAAA,EAAK,IAAA,EAAM,EAAA,CAAG,IAAA,EAAM,CAAA;AAC7D;AAMO,SAAS,QAAA,CACd,MAAA,EACA,KAAA,EACA,IAAA,EACQ;AACR,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,IAAK,KAAA,CAAM,WAAW,CAAA,EAAG;AAC/C,IAAA,MAAM,IAAI,WAAW,uCAAuC,CAAA;AAAA,EAC9D;AACA,EAAA,IAAI,GAAA,GAAM,CAAA;AACV,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,aAAA,CAAc,IAAA,CAAK,QAAQ,aAAa,CAAA;AACxC,IAAA,GAAA,IAAO,IAAA,CAAK,MAAA;AAAA,EACd;AACA,EAAA,IAAI,QAAQ,CAAA,EAAG;AACb,IAAA,MAAM,IAAI,UAAA,CAAW,CAAA,qCAAA,EAAwC,GAAG,CAAA,YAAA,CAAc,CAAA;AAAA,EAChF;AACA,EAAA,OAAO,MAAA,CAAO,MAAA,EAAQ,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA,MAAO,EAAE,OAAA,EAAS,CAAA,CAAE,SAAS,MAAA,EAAQ,CAAA,CAAE,MAAA,EAAO,CAAE,GAAG,IAAI,CAAA;AAC1F;AAGO,SAAS,OAAA,CAAQ,QAAgB,OAAA,EAAyB;AAC/D,EAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,EAAA,KAAA,MAAW,KAAA,IAAS,OAAO,OAAA,EAAS;AAClC,IAAA,KAAA,MAAW,IAAA,IAAQ,MAAM,KAAA,EAAO;AAC9B,MAAA,IAAI,IAAA,CAAK,OAAA,KAAY,OAAA,EAAS,KAAA,IAAS,IAAA,CAAK,MAAA;AAAA,IAC9C;AAAA,EACF;AACA,EAAA,OAAO,KAAA;AACT;AAMO,SAAS,SAAA,CAAU,QAAgB,OAAA,EAAiC;AACzE,EAAA,MAAM,OAAuB,EAAC;AAC9B,EAAA,KAAA,MAAW,KAAA,IAAS,OAAO,OAAA,EAAS;AAClC,IAAA,IAAI,GAAA,GAAM,CAAA;AACV,IAAA,IAAI,OAAA,GAAU,KAAA;AACd,IAAA,KAAA,MAAW,IAAA,IAAQ,MAAM,KAAA,EAAO;AAC9B,MAAA,IAAI,IAAA,CAAK,YAAY,OAAA,EAAS;AAC5B,QAAA,GAAA,IAAO,IAAA,CAAK,MAAA;AACZ,QAAA,OAAA,GAAU,IAAA;AAAA,MACZ;AAAA,IACF;AACA,IAAA,IAAI,OAAA,EAAS;AACX,MAAA,IAAA,CAAK,IAAA,CAAK;AAAA,QACR,IAAI,KAAA,CAAM,EAAA;AAAA,QACV,MAAA,EAAQ,GAAA;AAAA,QACR,GAAI,MAAM,GAAA,KAAQ,MAAA,GAAY,EAAE,GAAA,EAAK,KAAA,CAAM,GAAA,EAAI,GAAI,EAAC;AAAA,QACpD,GAAI,MAAM,IAAA,KAAS,MAAA,GAAY,EAAE,IAAA,EAAM,KAAA,CAAM,IAAA,EAAK,GAAI;AAAC,OACxD,CAAA;AAAA,IACH;AAAA,EACF;AACA,EAAA,OAAO,IAAA;AACT;AAMO,SAAS,aAAa,MAAA,EAAmC;AAC9D,EAAA,MAAM,MAAA,uBAAa,GAAA,EAAoB;AACvC,EAAA,KAAA,MAAW,KAAA,IAAS,OAAO,OAAA,EAAS;AAClC,IAAA,KAAA,MAAW,IAAA,IAAQ,MAAM,KAAA,EAAO;AAC9B,MAAA,MAAA,CAAO,GAAA,CAAI,IAAA,CAAK,OAAA,EAAA,CAAU,MAAA,CAAO,GAAA,CAAI,KAAK,OAAO,CAAA,IAAK,CAAA,IAAK,IAAA,CAAK,MAAM,CAAA;AAAA,IACxE;AAAA,EACF;AACA,EAAA,OAAO,CAAC,GAAG,MAAA,CAAO,OAAA,EAAS,CAAA,CACxB,GAAA,CAAI,CAAC,CAAC,OAAA,EAAS,GAAG,CAAA,MAAO,EAAE,SAAS,OAAA,EAAS,GAAA,EAAI,CAAE,CAAA,CACnD,IAAA,CAAK,CAAC,CAAA,EAAG,CAAA,KAAO,EAAE,OAAA,GAAU,CAAA,CAAE,OAAA,GAAU,EAAA,GAAK,CAAA,CAAE,OAAA,GAAU,CAAA,CAAE,OAAA,GAAU,IAAI,CAAE,CAAA;AAChF","file":"index.js","sourcesContent":["/**\n * @lacspace/ledger\n *\n * A tiny **double-entry** ledger / wallet. Every transaction is a set of lines\n * whose signed amounts sum to **zero**, so the books can never drift: balances\n * are just sums, and the trial balance always totals zero.\n *\n * Sign convention: an account's balance is the sum of its signed line amounts.\n * A debit is a **positive** amount, a credit is a **negative** one — so\n * `post({ debit, credit, amount })` books `+amount` to `debit` and `-amount` to\n * `credit`. Under this convention an asset/expense account rises when debited\n * and a liability/income/equity account rises when credited (its balance goes\n * more negative). Amounts are **integer minor units** (cents, paisa, …).\n *\n * ```ts\n * import { createLedger, post, balance, trialBalance } from \"@lacspace/ledger\";\n *\n * let book = createLedger();\n * book = post(book, { debit: \"cash\", credit: \"sales\", amount: 10000 });\n * balance(book, \"cash\");   //  10000\n * balance(book, \"sales\");  // -10000\n * trialBalance(book);      // sums to 0\n * ```\n *\n * Immutable — every operation returns a new {@link Ledger}. Zero dependencies,\n * isomorphic (ids use Web Crypto `getRandomValues`).\n */\n\n/** A single posting line: a signed amount against an account (minor units). */\nexport interface LedgerLine {\n  account: string;\n  /** Signed amount in minor units. A transaction's lines MUST sum to 0. */\n  amount: number;\n}\n\n/** One posted transaction. Its `lines` always sum to zero. */\nexport interface LedgerEntry {\n  /** Unique id (crypto-random). */\n  id: string;\n  /** ISO-8601 timestamp of when it was posted. */\n  at: string;\n  lines: LedgerLine[];\n  /** Optional external reference (invoice #, txn id, …). */\n  ref?: string;\n  /** Optional human-readable note. */\n  memo?: string;\n}\n\n/** An immutable ledger — an ordered list of balanced entries. */\nexport interface Ledger {\n  entries: LedgerEntry[];\n}\n\n/** A single row of a {@link statement}. */\nexport interface StatementRow {\n  at: string;\n  /** Net signed amount this entry moved on the account (minor units). */\n  amount: number;\n  ref?: string;\n  memo?: string;\n}\n\n/** A single row of a {@link trialBalance}. */\nexport interface TrialBalanceRow {\n  account: string;\n  balance: number;\n}\n\nconst HEX: string[] = [];\nfor (let i = 0; i < 256; i++) HEX.push((i + 0x100).toString(16).slice(1));\n\n/** Crypto-random 16-byte hex id. Isomorphic via Web Crypto. */\nfunction genId(): string {\n  const c = (globalThis as { crypto?: Crypto }).crypto;\n  if (!c || typeof c.getRandomValues !== \"function\") {\n    throw new Error(\"Web Crypto getRandomValues is unavailable in this environment.\");\n  }\n  const b = new Uint8Array(16);\n  c.getRandomValues(b);\n  let out = \"\";\n  for (let i = 0; i < 16; i++) out += HEX[b[i]!]!;\n  return out;\n}\n\nfunction assertInteger(amount: number, label: string): void {\n  if (!Number.isInteger(amount)) {\n    throw new TypeError(`${label} must be an integer number of minor units, got ${amount}`);\n  }\n}\n\n/** Create a new, empty ledger. */\nexport function createLedger(): Ledger {\n  return { entries: [] };\n}\n\n/** Append a pre-built, already-balanced entry (immutable). */\nfunction append(\n  ledger: Ledger,\n  lines: LedgerLine[],\n  meta?: { ref?: string; memo?: string }\n): Ledger {\n  const entry: LedgerEntry = {\n    id: genId(),\n    at: new Date().toISOString(),\n    lines,\n    ...(meta?.ref !== undefined ? { ref: meta.ref } : {}),\n    ...(meta?.memo !== undefined ? { memo: meta.memo } : {}),\n  };\n  return { entries: [...ledger.entries, entry] };\n}\n\n/**\n * Post a simple two-line transaction: `+amount` to `debit`, `-amount` to\n * `credit`. `amount` must be a positive integer (minor units). Returns a new\n * ledger — the input is never mutated.\n */\nexport function post(\n  ledger: Ledger,\n  tx: { debit: string; credit: string; amount: number; ref?: string; memo?: string }\n): Ledger {\n  assertInteger(tx.amount, \"amount\");\n  if (tx.amount <= 0) {\n    throw new RangeError(`post() amount must be positive, got ${tx.amount}`);\n  }\n  const lines: LedgerLine[] = [\n    { account: tx.debit, amount: tx.amount },\n    { account: tx.credit, amount: -tx.amount },\n  ];\n  return append(ledger, lines, { ref: tx.ref, memo: tx.memo });\n}\n\n/**\n * Post an arbitrary multi-line transaction. **Throws** if the signed line\n * amounts don't sum to exactly zero (or any amount isn't an integer).\n */\nexport function postMany(\n  ledger: Ledger,\n  lines: LedgerLine[],\n  meta?: { ref?: string; memo?: string }\n): Ledger {\n  if (!Array.isArray(lines) || lines.length === 0) {\n    throw new RangeError(\"postMany() requires at least one line\");\n  }\n  let sum = 0;\n  for (const line of lines) {\n    assertInteger(line.amount, \"line amount\");\n    sum += line.amount;\n  }\n  if (sum !== 0) {\n    throw new RangeError(`unbalanced transaction: lines sum to ${sum}, expected 0`);\n  }\n  return append(ledger, lines.map((l) => ({ account: l.account, amount: l.amount })), meta);\n}\n\n/** Balance of an account: the sum of all its signed line amounts. */\nexport function balance(ledger: Ledger, account: string): number {\n  let total = 0;\n  for (const entry of ledger.entries) {\n    for (const line of entry.lines) {\n      if (line.account === account) total += line.amount;\n    }\n  }\n  return total;\n}\n\n/**\n * Statement for one account: one row per entry that touches it, in order, with\n * the net signed amount that entry moved on the account.\n */\nexport function statement(ledger: Ledger, account: string): StatementRow[] {\n  const rows: StatementRow[] = [];\n  for (const entry of ledger.entries) {\n    let net = 0;\n    let touched = false;\n    for (const line of entry.lines) {\n      if (line.account === account) {\n        net += line.amount;\n        touched = true;\n      }\n    }\n    if (touched) {\n      rows.push({\n        at: entry.at,\n        amount: net,\n        ...(entry.ref !== undefined ? { ref: entry.ref } : {}),\n        ...(entry.memo !== undefined ? { memo: entry.memo } : {}),\n      });\n    }\n  }\n  return rows;\n}\n\n/**\n * Trial balance: every account with its balance, sorted by account name. Since\n * every entry is balanced, the balances always sum to exactly zero.\n */\nexport function trialBalance(ledger: Ledger): TrialBalanceRow[] {\n  const totals = new Map<string, number>();\n  for (const entry of ledger.entries) {\n    for (const line of entry.lines) {\n      totals.set(line.account, (totals.get(line.account) ?? 0) + line.amount);\n    }\n  }\n  return [...totals.entries()]\n    .map(([account, bal]) => ({ account, balance: bal }))\n    .sort((a, b) => (a.account < b.account ? -1 : a.account > b.account ? 1 : 0));\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lacspace/ledger",
+  "version": "1.0.0",
+  "description": "A tiny double-entry ledger & wallet — balanced transactions, per-account balances and a trial balance that always sums to zero. Integer minor units, immutable ops, crypto-random ids. Isomorphic.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ledger",
+    "double-entry",
+    "accounting",
+    "wallet",
+    "bookkeeping",
+    "trial-balance",
+    "transactions",
+    "balances",
+    "minor-units",
+    "immutable",
+    "isomorphic",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://developer.lacspace.com/packages/ledger",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "ledger"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}