monetra 2.0.0 → 2.2.0

package/README.md

@@ -1,245 +1,262 @@
+![Monetra](./monetra.png)
+
 # Monetra
 
-**The money library that makes financial correctness impossible to get wrong.**
+A comprehensive TypeScript framework for building financial applications with precision and confidence.
 
-Monetra is a TypeScript-first, zero-dependency money engine built for applications where every cent matters. It eliminates floating-point errors, enforces explicit rounding, and provides built-in audit trails—making it ideal for fintech, e-commerce, accounting, and cryptocurrency applications.
+[![CI](https://github.com/zugobite/monetra/actions/workflows/ci.yml/badge.svg)](https://github.com/zugobite/monetra/actions/workflows/ci.yml)
+[![Test Coverage](https://img.shields.io/badge/Coverage-99.87%25-brightgreen)](coverage/index.html)
+[![Mutation Score](https://img.shields.io/badge/Mutation_Score-92.09%25-brightgreen)](reports/mutation/mutation.html)
+[![Mathematically Verified](https://img.shields.io/badge/Verified-Property--Based_Tests-purple.svg)](tests/property-based.test.ts)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen.svg)]()
 
-[![npm version](https://img.shields.io/npm/v/monetra.svg)](https://www.npmjs.com/package/monetra)
-![License](https://img.shields.io/badge/license-MIT-blue.svg)
-![TypeScript](https://img.shields.io/badge/language-TypeScript-blue.svg)
-![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)
-![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)
+### Package Information
 
-## Why Monetra?
+[![npm version](https://img.shields.io/npm/v/monetra.svg)](https://www.npmjs.com/package/monetra)
+[![npm downloads](https://img.shields.io/npm/dm/monetra.svg)](https://www.npmjs.com/package/monetra)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Stability](https://img.shields.io/badge/stability-stable-brightgreen.svg)](https://github.com/zugobite/monetra)
 
-```javascript
-// ❌ Regular JavaScript
-0.1 + 0.2 === 0.3  // false! (0.30000000000000004)
+---
 
-// ✅ Monetra
-Money.fromDecimal('0.10', 'USD').add('0.20').equals('0.30')  // true
-```
+## Overview
 
-### The Problem
+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.
 
-Most programming languages store decimals as floating-point numbers, leading to tiny precision errors that compound over millions of transactions. These errors cause audit failures, reconciliation nightmares, and lost customer trust.
+**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.
 
-### The Solution
+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.
 
-Monetra stores all values as integers (cents, satoshis, wei) using BigInt, eliminating floating-point errors entirely. When rounding is necessary, you explicitly choose how—no hidden surprises.
+It bridges the gap between simple e-commerce math and complex ledger systems, offering a unified, type-safe environment for building:
 
-## Features
+- **Neobanks & Digital Wallets**
+- **Billing & Invoicing Engines**
+- **Loan & Mortgage Calculators**
+- **Double-Entry Ledgers**
 
-| Feature | Description |
-|---------|-------------|
-| 🔢 **Integer-Based** | All values stored in minor units (BigInt). No floats, ever. |
-| 🎯 **Explicit Rounding** | 6 rounding modes. You choose when and how. |
-| 🌍 **Multi-Currency** | ISO 4217 currencies + custom tokens + crypto (18 decimals) |
-| 📊 **Financial Math** | Loan payments, NPV, IRR, amortization schedules |
-| 📝 **Audit Ledger** | Tamper-evident transaction history with SHA-256 hashing |
-| 🔄 **Currency Conversion** | Rate management with historical lookups |
-| 💼 **Wallet/MoneyBag** | Multi-currency portfolio management |
-| ⚡ **Zero Dependencies** | Nothing to audit, nothing to break |
-| 🌐 **Runs Everywhere** | Node.js, browsers, serverless, edge functions |
+### The Monetra Stack
 
-## Table of Contents
+Monetra is architected in three distinct layers to ensure separation of concerns while maintaining type safety across your entire financial domain.
 
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-- [Usage Examples](#usage-examples)
-- [What's New in v2.0](#whats-new-in-v20)
-- [Documentation](#documentation)
-- [Testing](#testing)
-- [Contributing](#contributing)
-- [Security](#security)
-- [License](#license)
+#### Layer 1: The Core (Precision & Safety)
 
-## Quick Start
+- **`Money`**: Immutable, integer-based monetary value object using `BigInt` to prevent the [`0.1 + 0.2` problem](https://0.30000000000000004.com/).
+- **`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).
 
-### Installation
+#### Layer 2: The Logic (Business Intelligence)
 
-```bash
-npm install monetra
-# or
-yarn add monetra
-# or
-pnpm add monetra
-```
+- **`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).
 
-### Basic Usage
+#### Layer 3: The Audit (Compliance & Verification)
 
-```typescript
-import { money, USD } from "monetra";
+- **`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.
 
-// Create money easily
-const price = money("10.50", "USD"); // $10.50
-const tax = price.percentage(10); // $1.05
+---
 
-// Smart arithmetic
-const total = price.add(tax); // $11.55
-const discounted = total.subtract("2.00"); // $9.55
+## Installation
 
-console.log(discounted.format()); // "$9.55"
+```bash
+pnpm add monetra
 ```
 
-## Core Concepts
+**Requirements:** Node.js 18+ or modern browsers with BigInt support.
 
-### Integer-Only Representation
+---
 
-Monetra stores all values in minor units (e.g., cents) using `BigInt`. This avoids the precision errors common with floating-point math.
+## Why Monetra?
 
-- `$10.50` is stored as `1050n`.
-- `¥100` is stored as `100n`.
+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.
 
-### Immutability
+### Framework Capabilities
 
-Money objects are immutable. Operations like `add` or `multiply` return new instances.
+**Core Money Operations**
 
-```typescript
-const a = Money.fromMajor("10.00", USD);
-const b = a.add(Money.fromMajor("5.00", USD));
+- 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
 
-console.log(a.format()); // "$10.00" (unchanged)
-console.log(b.format()); // "$15.00"
-```
+**Financial Mathematics**
 
-### Explicit Rounding
+- 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
 
-Operations that result in fractional minor units (like multiplication) require an explicit rounding mode.
+**Transaction Ledger System**
 
-```typescript
-const m = Money.fromMajor("10.00", USD);
-// m.multiply(0.333); // Throws RoundingRequiredError
-m.multiply(0.333, { rounding: RoundingMode.HALF_UP }); // OK
-```
+- 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
 
-## Usage Examples
+**Currency Management**
 
-### Allocation (Splitting Funds)
+- 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
 
-Split money without losing a cent. Remainders are distributed deterministically using the largest remainder method.
+**Developer Experience**
 
-```typescript
-const pot = Money.fromMajor("100.00", USD);
-const [part1, part2, part3] = pot.allocate([1, 1, 1]);
+- 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)
 
-// part1: $33.34
-// part2: $33.33
-// part3: $33.33
-// Sum: $100.00
-```
+---
 
-## What's New in v2.0
+## Use Cases
 
-### New Money Methods
+Monetra is built for applications that require financial precision:
 
-```typescript
-// Convenient aliases
-Money.fromCents(1000, 'USD');      // Same as fromMinor
-Money.fromDecimal('10.50', 'USD'); // Same as fromMajor
+- **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
 
-// Clamp between bounds
-const clamped = price.clamp(minPrice, maxPrice);
+---
 
-// Raw decimal string (no locale formatting)
-const decimal = price.toDecimalString(); // "10.50"
+## Quick Start: The Framework in Action
 
-// JSON serialization support
-const json = JSON.stringify(money);
-const restored = JSON.parse(json, Money.reviver);
-```
+### 1. The Core: Safe Money Handling
 
-### TRUNCATE Rounding Mode
+Stop worrying about floating-point errors.
 
 ```typescript
-money.divide(3, { rounding: RoundingMode.TRUNCATE }); // Truncate towards zero
-```
+import { money, Money } from "monetra";
 
-### Accounting Format
+// Safe integer math
+const price = money("19.99", "USD");
+const tax = Money.fromMinor(199, "USD"); // 199 cents
+const total = price.add(tax);
 
-```typescript
-const negative = Money.fromDecimal('-100.00', 'USD');
-negative.format({ accounting: true }); // "($100.00)"
+console.log(total.format()); // "$21.98"
 ```
 
-### Rate Abstraction for Interest Calculations
+### 2. The Logic: Build a Loan Calculator
 
-```typescript
-import { Rate } from 'monetra';
+Implement complex financial products without external formulas.
 
-const annual = Rate.percent(12);
-const monthly = annual.periodic(12);        // 1%
-const effective = annual.toEffective(12);   // ~12.68%
+```typescript
+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()}`);
 ```
 
-### Historical Exchange Rates
+### 3. The Audit: Immutable Ledger
+
+Record the transaction and verify integrity.
 
 ```typescript
-const converter = new Converter('USD', { EUR: 0.92 });
-converter.addHistoricalRate('EUR', 0.85, new Date('2024-01-01'));
-converter.convert(money, 'EUR', { date: new Date('2024-06-01') });
+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
 ```
 
-### Error Codes for Programmatic Handling
+---
 
-```typescript
-try {
-  usd.add(eur);
-} catch (error) {
-  if (error.code === MonetraErrorCode.CURRENCY_MISMATCH) {
-    // Handle programmatically
-  }
-}
-```
+## Documentation
 
-### Browser-Compatible Ledger
+Full documentation is available in the [docs](docs/index.md) directory:
 
-```typescript
-// Async methods for browser environments
-const entry = await ledger.recordAsync(money, metadata);
-const isValid = await ledger.verifyAsync();
-```
+**Getting Started**
 
-📖 **See [Migration Guide](docs/006-MIGRATION-v2.md) for upgrade instructions.**
+- [Core Concepts](docs/core-concepts.md)
+- [Installation & Setup](docs/getting-started.md)
 
-## Documentation
+**The Framework API**
 
-For detailed information, please refer to the documentation in the `docs` folder:
+- [Layer 1: Money & Currency](docs/core/money.md)
+- [Layer 2: Financial Math](docs/logic/financial.md)
+- [Layer 3: Ledger & Audit](docs/audit/ledger.md)
 
-0. [Introduction (Non-Technical)](docs/000-INTRODUCTION.md) - What is Monetra and who should use it
-1. [Core Concepts](docs/001-CORE-CONCEPTS.md) - Fundamental principles and design decisions
-2. [Ledger System](docs/002-LEDGER-SYSTEM.md) - Audit trails and transaction history
-3. [Financial Math](docs/003-FINANCIAL-MATH.md) - Loans, investments, and time-value-of-money
-4. [Tokens & Crypto](docs/004-TOKENS-AND-CRYPTO.md) - Cryptocurrency and custom token support
-5. [API Reference](docs/005-API-REFERENCE.md) - Complete API documentation
-6. [Migration Guide v2.0](docs/006-MIGRATION-v2.md) - Upgrading from v1.x
-7. [Cookbook](docs/007-COOKBOOK.md) - Practical recipes and patterns
+**Guides & Best Practices**
 
-## Testing
+- [Precise Allocation (Splitting)](docs/guides/allocation.md)
+- [Handling Custom Tokens](docs/guides/custom-tokens.md)
+- [Error Handling Strategies](docs/guides/error-handling.md)
+- [Integration Examples (React, Vue, Node)](docs/examples/node.md)
 
-We maintain 100% test coverage to ensure financial correctness.
+---
+
+## Testing & Support
 
 ```bash
-# Run all tests
-npm test
+# Run the test suite
+pnpm test
+
+# Run property-based verification
+pnpm test:property
 
-# Run tests in watch mode
-npm run test:watch
+# Run coverage report
+pnpm test:coverage
 
-# Generate coverage report
-npm run test:coverage
+# Run mutation testing
+pnpm test:mutation
 ```
 
+---
+
 ## Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+Check our [Project Roadmap](https://github.com/users/zugobite/projects/2) to see what we're working on.
 
-We also have a [Code of Conduct](CODE_OF_CONDUCT.md) that all contributors are expected to follow.
+Please review our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
+
+---
 
 ## Security
 
-If you discover a security vulnerability, please review our [Security Policy](SECURITY.md) for instructions on how to report it responsibly.
+Report security vulnerabilities according to our [Security Policy](SECURITY.md).
+
+---
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT - see [LICENSE](LICENSE) for details.

package/dist/currency/Currency.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Represents a currency with its metadata.
+ *
+ * This interface defines the structure for currency objects used throughout the library.
+ * It includes the ISO 4217 code, the number of decimal places (precision),
+ * the currency symbol, and an optional default locale for formatting.
+ */
+export interface Currency {
+    /**
+     * The ISO 4217 currency code (e.g., "USD", "EUR", "ZAR").
+     */
+    code: string;
+    /**
+     * The number of decimal places for the currency.
+     * This defines the precision of the currency (e.g., 2 for USD, 0 for JPY).
+     */
+    decimals: number;
+    /**
+     * The symbol associated with the currency (e.g., "$", "€", "R").
+     */
+    symbol: string;
+    /**
+     * The default locale to use when formatting amounts in this currency (e.g., "en-US").
+     * If not provided, the formatter may fall back to a default or user-provided locale.
+     */
+    locale?: string;
+}

package/dist/currency/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./Currency";
+export * from "./iso4217";
+export * from "./precision";
+export * from "./registry";