@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.

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

Export	Description
Account	Chart of accounts entry with type, number, hierarchical parent, and balance queries
Journal	Transaction journal with status lifecycle, auto-numbered (JNL-*), sourceModule/sourceRef for cross-package attribution
JournalEntry	Individual debit or credit line within a journal, with currency and exchange rate

Collections

Export	Key Methods
AccountCollection	findChildren(), findActive()
JournalCollection	createWithEntries(), findByNumber(), findByDateRange(), findBySource(), findByStatus(), findDrafts(), findPosted()
JournalEntryCollection	findByJournal(), findByAccount(), getAccountBalance(), getTrialBalance(), getAccountLedger(), getTotalsForDateRange()

Types

Export	Description
AccountType	'asset', 'liability', 'equity', 'revenue', 'expense'
JournalStatus	'draft', 'posted', 'voided'
AccountOptions	Options for creating an Account
JournalOptions	Options for creating a Journal
JournalEntryOptions	Options for creating a JournalEntry
JournalEntryData	Entry data for addEntry() / createWithEntries()
CreateJournalData	Full journal + entries creation payload
TrialBalanceRow	Row in trial balance report (accountId, number, name, type, debit/credit balances)
AccountTree	Tree of account nodes (roots array)
AccountTreeNode	Single node in account tree (account + children)

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.