@finengine/core

Core money primitives and ledger validation helpers for FinEngine. This package is designed to make finance logic explicit and teachable, especially for BDT-denominated flows, MFS settlement examples, and spreadsheet-to-code transitions.

Precision model

The current starter package uses JavaScript number arithmetic with explicit rounding at public API boundaries. That keeps examples deterministic for BDT-facing demos and documentation. For regulated production ledgers, teams should still consider integer minor-unit storage or a decimal strategy in the surrounding application architecture.

TypeScript shapes

interface Money {
  amount: number;
  currency: 'BDT' | 'USD';
}

interface LedgerEntry {
  reference: string;
  currency: 'BDT' | 'USD';
  lines: Array<{
    account: string;
    side: 'debit' | 'credit';
    amount: number;
  }>;
}

interface ValidationResult {
  valid: boolean;
  totalDebit: number;
  totalCredit: number;
  errors: string[];
}

API

createMoney(amount, currency?)

Creates a rounded money object.

formatMoney(amount, currency?, locale?)

Formats an amount using Intl.NumberFormat.

validateLedgerEntry(entry)

Checks that debit and credit totals balance and that each line is structurally valid.

sumEntries(entries)

Sums debit totals across entries.

Executed example

import { formatMoney, validateLedgerEntry, sumEntries } from '@finengine/core'

const entry = {
  reference: 'MFS-SETTLEMENT-01',
  currency: 'BDT',
  lines: [
    { account: '1010-Cash', side: 'debit', amount: 5000 },
    { account: '2100-Customer-Balance', side: 'credit', amount: 5000 }
  ]
}

formatMoney(125000)
// BDT 125,000.00

validateLedgerEntry(entry)
// { valid: true, totalDebit: 5000, totalCredit: 5000, errors: [] }

sumEntries([entry])
// { amount: 5000, currency: 'BDT' }