Monetra Core is the heart of the Monetra ecosystem. It is the stripped-down, high-performance engine designed solely for financial correctness.
While the full Monetra framework provides ledgers, audit trails, and complex financial instruments, Monetra Core does one thing and does it perfectly: safe financial arithmetic.
It exists for developers who need the reliability of precise money handling but want to build their own abstractions on top of it. It is the primitive layer - the "physics engine" for your financial application.
The Mission: Zero Ambiguity
In financial software, ambiguity is a bug. 10 / 3 is not 3.33. It is an operation that yields a quotient and a remainder, and your code must decide what to do with that remainder.
Monetra Core forces these decisions to be explicit. It provides the essential types and operations to ensure that:
- Money is never treated as a float.
- Currencies are never mixed implicitly.
- Rounding is never accidental.
What is Inside "Core"?
Monetra Core is designed to be lightweight and zero-dependency. It includes only the non-negotiable primitives for financial engineering.
1. The Money Type
A pure, immutable representation of monetary value. It stores the amount in minor units (like integer cents) and carries the currency code as part of its type signature.
// It is impossible to mix currencies by accident
const price = new Money(1000, "USD");
const shipping = new Money(500, "EUR");
// This throws a compile-time or runtime error immediately
const total = price.add(shipping);
2. Precise Arithmetic
Standard math operations (add, subtract, multiply, allocate) that guarantee precision.
- Allocation: Split a monetary amount into parts without losing a single cent.
- Scale: Multiply by a factor (like a tax rate) with explicit rounding strategies.
3. Currency Registry
A minimal, extensible registry for currency definitions. It comes with standard ISO 4217 currencies but allows you to define custom tokens, loyalty points, or internal credits.
Why Use Core?
You might choose Monetra Core over the full Monetra framework if:
- You are building a library: You want to export financial types without forcing a large dependency tree on your users.
- You have your own persistence layer: You don't need Monetra's ledger or audit history because you are storing data in a specific way (e.g., a custom SQL schema or a blockchain).
- Bundle size matters: You are running in a serverless function or an edge worker and need the smallest possible footprint.
The "Core" Philosophy
Monetra Core follows the Unix philosophy: do one thing and do it well.
It respects the fact that financial systems are diverse. A crypto exchange, a payroll provider, and an e-commerce checkout have vastly different needs for storage and reporting. But they all share the same need for correct math.
Monetra Core solves the math. The rest is up to you.
Features at a Glance
- Immutable by Default: Values never change; operations return new instances.
- Rounding Strategies: Full support for "Round Half Up", "Round Half Even" (Banker's Rounding), and more.
- Allocation Algorithms: Distribute funds (e.g., splitting a $100 bill 3 ways) while preserving the total value ($33.33, $33.33, $33.34).
- Type Safety: leveraged TypeScript to catch financial errors at compile time.
Example: The Allocation Problem
The classic test of any financial library is how it handles division.
import { Money, Currency } from "@zugobite/monetra-core";
const bill = new Money(100, Currency.USD); // $1.00
const split = bill.allocate([1, 1, 1]);
// Result:
// [34 cents, 33 cents, 33 cents]
// Total: 100 cents. Nothing lost.
Monetra Core handles the "remainder distribution" automatically, ensuring the sum of the parts always equals the whole.
Where Can I Learn More?
- Repository: GitHub Repo
- NPM Package: Official NPM Package
Monetra Core is the bedrock. Build on it with confidence.