@happyvertical/smrt-ledgers

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.7万

Double-entry accounting ledger for the SMRT framework

原始使用文档
文档目录13 节
  1. Exact ledgers and counterparties
  2. Installation
  3. Usage
  4. Double-Entry Accounting
  5. Journal Lifecycle
  6. API
  7. Models
  8. Collections
  9. Migration
  10. Types
  11. Upgrading from 0.51.x: the ledger_accounts table (#3098)
  12. Dependencies
  13. Contributor guide

@happyvertical/smrt-ledgers

Double-entry accounting ledger for the s-m-r-t framework. Hierarchical chart of accounts, journal lifecycle with immutability after posting, and balance enforcement with epsilon tolerance.

Exact ledgers and counterparties

Create a Ledger with balanceMode: 'exact-integer' and an ISO currency when the accounting scope stores minor units. Accounts and journals assigned to that ledger must share its tenant and currency; posting rejects fractional or unsafe amounts and requires exactly equal debit and credit totals. Existing journals without a ledger retain the compatible tolerant decimal rule. Direct entry writes also require an accessible same-owner journal and matching account/journal ledger scope; legacy journals cannot write movements on scoped accounts. An existing account cannot change ledger scope, including adoption from an unassigned account; create a fresh scoped account instead. Scoped-account creation validates the referenced ledger owner. createChild() inherits the persisted scoped parent ledger and owner and rejects conflicting overrides.

JournalEntry carries opaque counterpartyKind / counterpartyId values, plus an optional dueDate. JournalEntryCollection.getCounterpartyBalances() reports posted AR/AP movements for caller-selected accounts. Aging is an open-item report: the original line needs a source reference and due date, and the later settlement uses settlesSourceRef; do not infer aging from a net counterparty balance.

Use postReceivable, postPayable, or postSettlement for exact ledger events. They take a tenant-scoped idempotency key and create journal plus lines under the framework's atomic retry claim. A replay with changed content is refused. Idempotency is permanent, not bounded by the retry claim's retention window: after the claim is pruned, a retry resolves the existing journal by (tenantId, ledgerId, key) and returns it when the request digest matches, or refuses a changed replay. Refunds and disputes must post a separate compensating entry with a new key; posted ledger journals and their lines cannot be edited, deleted, or voided. Reverse the debit/credit accounts and set settlesSourceRef to the original open item when reducing it. Partial reversals use the partial integer amount; full reversals use the remaining amount. Commerce/sales owns deciding that amount and retaining the external payment/refund event, including disputes after payout; ledgers never initiates a money transfer. Retry the same key after a crash between external payout completion and ledger posting. A failed ledger transaction rolls back the journal, lines and retry receipt together. Manual draft edits and posting claim the parent journal revision in their transaction; a concurrent loser fails closed and must reload before retrying.

Keys are unique within (tenantId, ledgerId) and bind all accounting inputs, including an explicitly provided date. Omitted dates use the first successful posting time. Caller references must uniquely identify each open item within the selected account set. Use normalBalance: 'credit' for AP aging/balances (AR is debit-normal by default). Balance reports use from/to; aging uses from/asOf. Choose a from that includes the original obligation. An out-of-order settlement is included once its source exists; future-dated movements are excluded from historical reports. Negative balances/credits remain visible in balances, not aging buckets.

Ledger currency, owner and balance mode are immutable. Amounts are safe integer minor units with zero epsilon; helpers never round, allocate residuals or convert currency. Sales owns deterministic allocation rounding and residual assignment; commerce owns original gross/tax/fee amounts. Each boundary must pass reconciled integers, e.g. a CAD 100.00 worker co-op invoice posts 10000 debit to receivables and 10000 credit to project revenue. A CAD 40.00 settlement reverses 4000 of that receivable, leaving 6000. Legacy unassigned journals retain their existing void and decimal behavior.

The transactional posting and subledger suites cover SQLite and PostgreSQL. DuckDB cannot provision this package's existing JournalEntry cascading foreign keys: the framework explicitly rejects DuckDB's unsupported ON UPDATE CASCADE. It is not a supported exact-ledger runtime; no relationship is weakened to make that dialect appear compatible.

Installation

pnpm add @happyvertical/smrt-ledgers

Usage

import {
  Account, AccountCollection,
  Journal, JournalCollection,
  JournalEntry, JournalEntryCollection
} from '@happyvertical/smrt-ledgers';

// Set up chart of accounts
const accounts = await AccountCollection.create({ db });
const cash = await accounts.create({
  number: '1000',
  name: 'Cash',
  type: 'asset',
});
await cash.save();

const revenue = await accounts.create({
  number: '4000',
  name: 'Sales Revenue',
  type: 'revenue',
});
await revenue.save();

// Create a sub-account under Cash
const checking = await cash.createChild({
  number: '1010',
  name: 'Checking Account',
});

// Create a balanced journal with entries
const journals = await JournalCollection.create({ db });
const journal = await journals.createWithEntries({
  description: 'Cash sale',
  sourceModule: 'manual',
  entries: [
    { accountId: cash.id, debit: 100.00 },
    { accountId: revenue.id, credit: 100.00 },
  ],
});

// Post the journal (validates balance, then immutable)
await journal.post();

// Query balances
const cashBalance = await cash.getBalance();

// Get trial balance across all active accounts
const entries = await JournalEntryCollection.create({ db });
const trialBalance = await entries.getTrialBalance();

// Void a journal (cannot edit after posting, only void)
await journal.void('Duplicate entry');

Double-Entry Accounting

Every journal must balance before it can be posted. The balance check uses BALANCE_EPSILON = 0.001 to handle floating-point rounding:

Math.abs(totalDebits - totalCredits) < 0.001

Account types follow standard accounting rules:

  • Debit-normal (Asset, Expense): balance = debits - credits
  • Credit-normal (Liability, Equity, Revenue): balance = credits - debits

Journal Lifecycle

Journals follow a strict draft -> posted -> voided lifecycle:

  • Draft: editable, entries can be added via journal.addEntry()
  • Posted: immutable, balance validated, postedAt timestamp set
  • Voided: marked with voidReason and voidedAt, cannot be edited or re-posted

Each JournalEntry must have either a debit or a credit (not both, not zero). Amounts must be non-negative. Multi-currency is supported via exchangeRate on each entry.

API

Models

ExportDescription
AccountChart of accounts entry with type, number, hierarchical parent, and balance queries
JournalTransaction journal with status lifecycle, auto-numbered (JNL-*), sourceModule/sourceRef for cross-package attribution
JournalEntryIndividual debit or credit line within a journal, with currency and exchange rate

Collections

ExportKey Methods
AccountCollectionfindChildren(), findActive()
JournalCollectioncreateWithEntries(), findByNumber(), findByDateRange(), findBySource(), findByStatus(), findDrafts(), findPosted()
JournalEntryCollectionfindByJournal(), findByAccount(), getAccountBalance(), getTrialBalance(), getAccountLedger(), getTotalsForDateRange()

Migration

ExportDescription
planLedgerAccountsTableMove(db)Count the ledger rows a pre-#3098 accounts table still holds, without writing
migrateLedgerAccountsTable(db, options?)Move them into ledger_accounts (see Upgrading)
LedgerAccountsTableMoveErrorThrown when the move refuses (uncertain rows, id clash, missing table, non-PostgreSQL)

Types

ExportDescription
AccountType'asset', 'liability', 'equity', 'revenue', 'expense'
JournalStatus'draft', 'posted', 'voided'
AccountOptionsOptions for creating an Account
JournalOptionsOptions for creating a Journal
JournalEntryOptionsOptions for creating a JournalEntry
JournalEntryDataEntry data for addEntry() / createWithEntries()
CreateJournalDataFull journal + entries creation payload
TrialBalanceRowRow in trial balance report (accountId, number, name, type, debit/credit balances)
AccountTreeTree of account nodes (roots array)
AccountTreeNodeSingle node in account tree (account + children)

Upgrading from 0.51.x: the ledger_accounts table (#3098)

Account is stored in ledger_accounts. Earlier releases derived the table name accounts, which @happyvertical/smrt-messages also uses for its unrelated messaging Account; an app with both packages got one union table whose rows each package read as its own. An existing database moves its ledger accounts once, in a PostgreSQL maintenance window:

  1. smrt db:migrate-ledger-accounts --dry-run, then without --dry-run — creates ledger_accounts when it is missing (db:migrate cannot go first: it is all or nothing, and the journal_entries.account_id foreign key that still points at accounts stops it), copies every ledger row (ids, hierarchy and metadata unchanged) into ledger_accounts, detaches the ledger foreign keys from accounts, and deletes the moved rows, in one locked transaction. Messaging rows (those with an STI discriminator) stay. Before writing anything it refuses a row whose owner is uncertain, ids already present in ledger_accounts, and any foreign key into accounts that no registered model declares (it would otherwise dangle, or cascade); a rerun is a no-op. The same step is migrateLedgerAccountsTable(db) / planLedgerAccountsTableMove(db) from this package — call it with the application's models registered, as the CLI does.
  2. smrt db:migrate — adds the foreign keys against ledger_accounts.

Afterwards accounts is either empty (ledgers only — drop it when nothing else uses it) or holds only messaging accounts plus the unused ledger columns number, type, parent_id, description, active and metadata, which can be dropped once verified. A database that never ran ledgers needs nothing.

The move supports PostgreSQL. On SQLite, a database whose accounts table holds only ledger accounts is upgraded with ALTER TABLE accounts RENAME TO ledger_accounts before step 1; a SQLite database that also holds messaging accounts must be rebuilt.

Code that referenced the ledger model by the bare name 'Account' should use the constructor or the qualified name @happyvertical/smrt-ledgers:Account; the exported Account and AccountCollection are unchanged.

Dependencies

  • @happyvertical/smrt-core -- ORM and code generation
  • @happyvertical/smrt-tenancy -- multi-tenant scoping

Contributor guide

See AGENTS.md for package architecture, invariants, validation, and contributor guidance.

Accounting identities are insert-only on their first save: an explicit slug/context collision cannot replace an existing ledger, account, journal, or line. Load the existing object to update it through its lifecycle guards. This also applies to legacy unassigned objects; natural-key replacement is not a supported update path. Legacy tenant journals may still use shared global accounts that have no ledger; scoped journals require accounts owned by their ledger.

A journal chooses its ledger scope at creation. Persisted draft journals cannot move between ledgers or change between unassigned and scoped, even when empty. Create a new journal for another scope; this prevents an in-flight legacy line from entering an exact ledger after its validation. Ordinary same-scope draft edits and legacy decimal journals retain their existing behavior.

版本与发布记录

@happyvertical/smrt-ledgers 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-ledgers 的常见问题

@happyvertical/smrt-ledgers 是什么?

Double-entry accounting ledger for the SMRT framework

如何安装 @happyvertical/smrt-ledgers?

在项目目录运行 npm install @happyvertical/smrt-ledgers,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-ledgers 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-ledgers 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-ledgers 可以商用吗?

@happyvertical/smrt-ledgers 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-ledgers 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-ledgers 在 2026/10/17 – 2026/11/15 这 30 天内被下载 17,163 次,日均约 572 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-ledgers 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 365 个版本,其中过去 12 个月发布了 365 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。