Nestjs Accountant

A fintech-grade, domain-agnostic, and multi-tenant financial ledger engine for NestJS.

nestjs-accountant is a production-hardened accounting kernel designed to power anything from SaaS platforms and marketplaces to mobility and logistics systems. It enforces strict double-entry accounting, atomic balance updates, and full tenant isolation without embedding any domain-specific business logic.

---

🚀 Key Features

• Domain Agnostic: No "Users", "Drivers", or "Orders". Only generic primitives (referenceType, referenceId, tags, context) to model any vertical.
• Multi-Tenant SaaS Ready: Every query, index, and constraint is scoped to a tenantId for strict isolation.
• Strong Financial Integrity:
  • Double-Entry Enforcement: Sum of Debits MUST equal Sum of Credits for every transaction.
  • Atomic Balances: Row-level Pessimistic Locking ensure thread-safe balance updates.
  • Deadlock Prevention: Deterministic sorted locking of accounts in multi-account transactions.
  • Immutability: Once a transaction is POSTED or REVERSED, it is final and cannot be modified.
• Multi-Currency & Reporting: Store transactions in any currency while tracking a "Base Currency" and exchange rates for global reporting.
• Performance & Precision: Uses BigInt (via string mapping) for all calculations to eliminate floating-point errors.
• Idempotency: Built-in support for idempotencyKey per tenant.

---

📦 Installation

npm install nestjs-accountant

Note: The default adapter uses TypeORM and a PostgreSQL database. However, you can also opt to use the provided Prisma adapter or implement your own.

---

⚙️ Setup

1. Register Entities

The library provides several entities that must be registered in your TypeORM configuration.

import { Account, Balance, Transaction, Entry } from 'nestjs-accountant';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      // ... your config
      entities: [Account, Balance, Transaction, Entry],
      synchronize: true, // or use migrations
    }),
  ],
})
export class AppModule {}

import { AccountantModule, PrismaLedgerAdapter } from 'nestjs-accountant';
import { PrismaClient } from '@prisma/client';

@Module({
  imports: [
    AccountantModule.register({
      // By default, it uses TypeOrmLedgerAdapter.
      // To use Prisma, you can provide an instance or a provider token:
      adapter: new PrismaLedgerAdapter(new PrismaClient()),
    }),
  ],
})
export class AppModule {}

---

📖 Core Concepts

Double-Entry Accounting

Every financial event is recorded as a Transaction containing at least two Entries.

• Debit: Increases ASSET/EXPENSE, decreases LIABILITY/EQUITY/REVENUE.
• Credit: Increases LIABILITY/EQUITY/REVENUE, decreases ASSET/EXPENSE.
• Rule: Sum(Debits) === Sum(Credits)

ALERE Principle (Account Types)

nestjs-accountant uses five core account types:

1. ASSET: (Debit Normal) Things you own (e.g., Bank balance, Cash).
2. LIABILITY: (Credit Normal) Things you owe (e.g., User wallets, Tax payable).
3. EQUITY: (Credit Normal) Ownership interest.
4. REVENUE: (Credit Normal) Income earned (e.g., Platform fees).
5. EXPENSE: (Debit Normal) Costs incurred.

---

🛠️ Usage Guide

1. Account Management

Accounts are the endpoints of your ledger. Use referenceType and referenceId to link them to your domain models (e.g., Users, Merchants).

import { LedgerService, AccountType } from 'nestjs-accountant';

// Create a User Wallet (Liability for the platform)
const wallet = await ledgerService.createAccount({
  tenantId: 'my-tenant',
  accountType: AccountType.LIABILITY,
  referenceType: 'USER',
  referenceId: 'user_123',
  metadata: { name: 'Main Wallet' },
  allowNegative: false, // Enforce no overdraft
});

// Find an account by reference
const account = await ledgerService.findAccountByReference('user_123', 'USER', 'my-tenant');

2. Creating Transactions

Simple Transfer (P2P)

import { Direction } from 'nestjs-accountant';

await ledgerService.createTransaction({
  tenantId: 'my-tenant',
  idempotencyKey: 'transfer_unique_id_1',
  referenceType: 'P2P_TRANSFER',
  referenceId: 'transfer_001',
  entriesData: [
    { 
      accountId: senderId, 
      direction: Direction.DEBIT, 
      amountMinor: '1000', 
      currency: 'USD', 
      description: 'Transfer to User B' 
    },
    { 
      accountId: receiverId, 
      direction: Direction.CREDIT, 
      amountMinor: '1000', 
      currency: 'USD', 
      description: 'Transfer from User A' 
    },
  ],
});

Multi-Split Payment (Marketplace)

A single transaction can involve many accounts, such as splitting an order between a merchant, the platform, and tax authorities.

await ledgerService.createTransaction({
  tenantId: 'my-tenant',
  entriesData: [
    { accountId: customer, direction: Direction.DEBIT, amountMinor: '1000', currency: 'USD', description: 'Total charge' },
    { accountId: merchant, direction: Direction.CREDIT, amountMinor: '800', currency: 'USD', description: 'Net payout' },
    { accountId: platform_fee, direction: Direction.CREDIT, amountMinor: '150', currency: 'USD', description: 'Fee' },
    { accountId: tax_payable, direction: Direction.CREDIT, amountMinor: '50', currency: 'USD', description: 'VAT' },
  ],
});

3. Pending Transactions (Auth & Capture)

Useful for payment gateway flows where funds are authorized but not yet settled.

// 1. Create a pending record (No balance updates yet)
const tx = await ledgerService.createPendingTransaction({
  tenantId, 
  amountMinor: '5000', 
  currency: 'USD', 
  referenceId: 'auth_789'
});

// 2. Later, finalize and update status
await ledgerService.updateTransactionStatus({
  tenantId, 
  transactionId: tx.id, 
  newStatus: TransactionStatus.POSTED
});

4. Reversals

Reversing a transaction creates a mirror-image transaction (swapping debits and credits) and links it to the original.

// This creates a new POSTED transaction that undoes the original
const reversal = await ledgerService.reverseTransaction(originalTxId, 'my-tenant');

---

🌍 Advanced Features

Multi-Currency Reporting

Track a "Base Currency" (e.g., your auditing currency) alongside the transaction currency.

await ledgerService.createTransaction({
  // ... core entries
  baseCurrency: 'USD',
  baseAmountMinor: '4500', 
  exchangeRate: '0.9', // local_amount / base_amount
});

Deadlock Prevention

When processing transactions involving multiple accounts simultaneously, the engine automatically sorts account IDs before acquiring locks. This ensures a deterministic locking order and prevents circular wait deadlocks.

Minor Units & Precision

• BigInt Safety: All amounts are handled as BigInt internally and stored as string in the database to prevent precision loss.
• Minor Units: Always use minor units (e.g., "100" for $1.00).

---

📊 Entity Schema

Entity	Purpose	Key Fields
Account	The ledger account	accountType, referenceType, referenceId, allowNegative, isFrozen
Balance	Cached balance view	amountMinor, currency, accountId
Transaction	Header for entries	status, amountMinor, currency, idempotencyKey, reversalOf
Entry	Individual line items	direction, amountMinor, accountId, exchangeRate

---

⚖️ License

ISC