Monetra

A comprehensive TypeScript framework for building financial applications with precision and confidence.

Package Information

Overview

Monetra is a zero-dependency TypeScript framework that provides everything you need to build financially accurate applications. From precise money handling to transaction ledgers, from loan calculations to currency conversion - Monetra offers a complete, integrated solution.

Built for financial correctness: By storing amounts in minor units (cents, satoshis, wei) as BigInt, Monetra eliminates floating-point precision errors that plague traditional approaches.

While other libraries rely on floating-point math or simple wrappers, Monetra provides a full stack architecture for the lifecycle of value: from safe storage and precise allocation to complex financial modeling and immutable audit logging.

It bridges the gap between simple e-commerce math and complex ledger systems, offering a unified, type-safe environment for building:

• Neobanks & Digital Wallets
• Billing & Invoicing Engines
• Loan & Mortgage Calculators
• Double-Entry Ledgers

The Monetra Stack

Monetra is architected in three distinct layers to ensure separation of concerns while maintaining type safety across your entire financial domain.

Layer 1: The Core (Precision & Safety)

• Money: Immutable, integer-based monetary value object using BigInt to prevent the 0.1 + 0.2 problem.
• Currency: ISO 4217 compliance out of the box, with support for custom tokens (crypto/loyalty points).
• Allocation: GAAP-compliant splitting algorithms (Distribute value without losing cents).

Layer 2: The Logic (Business Intelligence)

• Financial: Standardized implementation of TVM (Time Value of Money) formulas like PMT, NPV, IRR, and Loan Amortization.
• Interest: Exact calculation of Compound vs. Simple interest with day-count conventions.
• Depreciation: Asset lifecycle management (Straight-line, Declining balance).

Layer 3: The Audit (Compliance & Verification)

• Ledger: Append-only, double-entry accounting system.
• Verification: Cryptographic hashing of transaction chains to detect data tampering.
• Enforcement: Strict rules for credit/debit operations to ensure books always balance.

Installation

pnpm add monetra

Requirements: Node.js 18+ or modern browsers with BigInt support.

Why Monetra?

Monetra is more than a money library - it's a complete financial framework designed to handle the full spectrum of monetary operations in modern applications.

Framework Capabilities

Core Money Operations

• Integer-based storage (BigInt) eliminates floating-point errors
• ISO 4217 currency support with automatic precision handling
• Custom token definitions for cryptocurrencies (up to 18 decimals)
• Explicit rounding strategies (6 modes: HALF_UP, HALF_DOWN, HALF_EVEN, FLOOR, CEIL, TRUNCATE)
• Immutable API-all operations return new instances

Financial Mathematics

• Compound interest calculations with flexible compounding periods
• Loan amortization schedules and payment calculations
• Present/future value computations
• Net Present Value (NPV) and Internal Rate of Return (IRR)
• Depreciation methods (straight-line, declining balance)
• Bond yield calculations and leverage metrics

Transaction Ledger System

• Append-only transaction log with hash chain verification
• Double-entry bookkeeping support
• Auditable history with cryptographic integrity
• Account balance tracking and reconciliation
• Async transaction processing with event handling

Currency Management

• Multi-currency support with type-safe operations
• Currency conversion with rate management
• Historical exchange rate lookups
• MoneyBag for aggregating different currencies
• Mix-currency operation protection

Developer Experience

• Zero runtime dependencies - no supply chain risks
• Full TypeScript support with strict types
• Comprehensive error handling with custom error classes
• Extensive test coverage (>95%) and mutation testing
• Tree-shakeable modular exports
• Framework integrations (React, Vue, Node.js)

Use Cases

Monetra is built for applications that require financial precision:

• E-commerce platforms - Shopping carts, pricing, tax calculations
• Banking & FinTech - Account management, transactions, interest calculations
• Accounting software - Ledgers, reconciliation, financial reporting
• Cryptocurrency apps - Wallet balances, token transfers, DeFi calculations
• SaaS billing - Subscription management, invoicing, revenue recognition
• Investment platforms - Portfolio tracking, return calculations, tax reporting

Quick Start: The Framework in Action

1. The Core: Safe Money Handling

Stop worrying about floating-point errors.

import { money, Money } from "monetra";

// Safe integer math
const price = money("19.99", "USD");
const tax = Money.fromMinor(199, "USD"); // 199 cents
const total = price.add(tax);

console.log(total.format()); // "$21.98"

2. The Logic: Build a Loan Calculator

Implement complex financial products without external formulas.

import { money, pmt, loan } from "monetra";

// Calculate monthly mortgage payment
const payment = pmt({
  principal: money("250000", "USD"), // $250k Loan
  annualRate: 0.055, // 5.5% APR
  years: 30,
});
// result: "$1,419.47"

// Generate the full amortization schedule
const schedule = loan({
  principal: money("250000", "USD"),
  rate: 0.055,
  periods: 360, // 30 years * 12 months
});

console.log(`Total Interest: ${schedule.totalInterest.format()}`);

3. The Audit: Immutable Ledger

Record the transaction and verify integrity.

import { Ledger, money } from "monetra";

// Initialize a ledger for USD
const bankLedger = new Ledger("USD");

// Record a transaction
bankLedger.record({
  description: "Mortgage Payment - Jan",
  entries: [
    { account: "user_wallet", credit: money("1419.47", "USD") },
    { account: "bank_receivables", debit: money("1419.47", "USD") },
  ],
});

// Verify the cryptographic chain
const isClean = bankLedger.verify(); // true

Documentation

Full documentation is available in the docs directory:

Getting Started

• Core Concepts
• Installation & Setup

The Framework API

• Layer 1: Money & Currency
• Layer 2: Financial Math
• Layer 3: Ledger & Audit

Guides & Best Practices

• Precise Allocation (Splitting)
• Handling Custom Tokens
• Error Handling Strategies
• Integration Examples (React, Vue, Node)

Testing & Support

# Run the test suite
pnpm test

# Run property-based verification
pnpm test:property

# Run coverage report
pnpm test:coverage

# Run mutation testing
pnpm test:mutation

Contributing

See CONTRIBUTING.md for guidelines.

Check our Project Roadmap to see what we're working on.

Please review our Code of Conduct before contributing.

Security

Report security vulnerabilities according to our Security Policy.

License

MIT - see LICENSE for details.