monetra 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zascia Hugo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# Monetra
+
+**Monetra** is a currency-aware, integer-based money engine designed for financial correctness. It explicitly avoids floating-point arithmetic and enforces strict monetary invariants.
+
+It is intended for use in wallet-based financial systems where correctness is paramount.
+
+![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)
+
+## Features
+
+- ❌ **No floating-point arithmetic**: All values are stored in minor units (BigInt).
+- ❌ **No silent rounding**: Rounding must be explicit.
+- ❌ **No implicit currency conversion**: Operations between different currencies throw errors.
+- ✅ **Immutable**: All operations return new objects.
+- ✅ **Locale-aware formatting**: Built on `Intl` standards.
+- ✅ **Allocation Engine**: Deterministic splitting of funds (e.g., 33% / 33% / 34%).
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Usage Examples](#usage-examples)
+- [Documentation](#documentation)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install monetra
+# or
+yarn add monetra
+# or
+pnpm add monetra
+```
+
+### Basic Usage
+
+```typescript
+import { Money, USD, RoundingMode } from "monetra";
+
+// Create money from major units (e.g., "10.50")
+const price = Money.fromMajor("10.50", USD);
+
+// Create money from minor units (e.g., 100 cents)
+const tax = Money.fromMinor(100, USD); // $1.00
+
+// Arithmetic
+const total = price.add(tax); // $11.50
+
+// Formatting
+console.log(total.format()); // "$11.50"
+console.log(total.format({ locale: "de-DE" })); // "11,50 $"
+
+// Multiplication with explicit rounding
+const discount = total.multiply(0.15, { rounding: RoundingMode.HALF_UP });
+const finalPrice = total.subtract(discount);
+```
+
+## Core Concepts
+
+### 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.
+
+- `$10.50` is stored as `1050n`.
+- `¥100` is stored as `100n`.
+
+### Immutability
+
+Money objects are immutable. Operations like `add` or `multiply` return new instances.
+
+```typescript
+const a = Money.fromMajor("10.00", USD);
+const b = a.add(Money.fromMajor("5.00", USD));
+
+console.log(a.format()); // "$10.00" (unchanged)
+console.log(b.format()); // "$15.00"
+```
+
+### Explicit Rounding
+
+Operations that result in fractional minor units (like multiplication) require an explicit rounding mode.
+
+```typescript
+const m = Money.fromMajor("10.00", USD);
+// m.multiply(0.333); // Throws RoundingRequiredError
+m.multiply(0.333, { rounding: RoundingMode.HALF_UP }); // OK
+```
+
+## Usage Examples
+
+### Allocation (Splitting Funds)
+
+Split money without losing a cent. Remainders are distributed deterministically using the largest remainder method.
+
+```typescript
+const pot = Money.fromMajor("100.00", USD);
+const [part1, part2, part3] = pot.allocate([1, 1, 1]);
+
+// part1: $33.34
+// part2: $33.33
+// part3: $33.33
+// Sum: $100.00
+```
+
+## Documentation
+
+For more detailed information, please refer to the documentation in the `docs` folder:
+
+- [API Reference](docs/001-API-REFERENCE.md)
+- [Feature Guide](docs/002-FEATURE-GUIDE.md)
+
+## Testing
+
+We maintain 100% test coverage to ensure financial correctness.
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Generate coverage report
+npm run test:coverage
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/index 2.js

@@ -0,0 +1,424 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CURRENCIES: () => CURRENCIES,
+  CurrencyMismatchError: () => CurrencyMismatchError,
+  EUR: () => EUR,
+  GBP: () => GBP,
+  InsufficientFundsError: () => InsufficientFundsError,
+  InvalidPrecisionError: () => InvalidPrecisionError,
+  JPY: () => JPY,
+  MonetraError: () => MonetraError,
+  Money: () => Money,
+  OverflowError: () => OverflowError,
+  RoundingMode: () => RoundingMode,
+  RoundingRequiredError: () => RoundingRequiredError,
+  USD: () => USD,
+  ZAR: () => ZAR,
+  divideWithRounding: () => divideWithRounding,
+  getCurrency: () => getCurrency,
+  getMinorUnitExponent: () => getMinorUnitExponent
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors/BaseError.ts
+var MonetraError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/errors/CurrencyMismatchError.ts
+var CurrencyMismatchError = class extends MonetraError {
+  constructor(expected, actual) {
+    super(`Currency mismatch: expected ${expected}, got ${actual}`);
+  }
+};
+
+// src/errors/InvalidPrecisionError.ts
+var InvalidPrecisionError = class extends MonetraError {
+  constructor(message) {
+    super(message);
+  }
+};
+
+// src/errors/RoundingRequiredError.ts
+var RoundingRequiredError = class extends MonetraError {
+  constructor() {
+    super("Rounding is required for this operation but was not provided.");
+  }
+};
+
+// src/errors/InsufficientFundsError.ts
+var InsufficientFundsError = class extends MonetraError {
+  constructor() {
+    super("Insufficient funds for this operation.");
+  }
+};
+
+// src/errors/OverflowError.ts
+var OverflowError = class extends MonetraError {
+  constructor(message = "Arithmetic overflow") {
+    super(message);
+  }
+};
+
+// src/money/guards.ts
+function assertSameCurrency(a, b) {
+  if (a.currency.code !== b.currency.code) {
+    throw new CurrencyMismatchError(a.currency.code, b.currency.code);
+  }
+}
+
+// src/rounding/strategies.ts
+var RoundingMode = /* @__PURE__ */ ((RoundingMode3) => {
+  RoundingMode3["HALF_UP"] = "HALF_UP";
+  RoundingMode3["HALF_DOWN"] = "HALF_DOWN";
+  RoundingMode3["HALF_EVEN"] = "HALF_EVEN";
+  RoundingMode3["FLOOR"] = "FLOOR";
+  RoundingMode3["CEIL"] = "CEIL";
+  return RoundingMode3;
+})(RoundingMode || {});
+
+// src/rounding/index.ts
+function divideWithRounding(numerator, denominator, mode) {
+  if (denominator === 0n) {
+    throw new Error("Division by zero");
+  }
+  const quotient = numerator / denominator;
+  const remainder = numerator % denominator;
+  if (remainder === 0n) {
+    return quotient;
+  }
+  const sign = (numerator >= 0n ? 1n : -1n) * (denominator >= 0n ? 1n : -1n);
+  const absRemainder = remainder < 0n ? -remainder : remainder;
+  const absDenominator = denominator < 0n ? -denominator : denominator;
+  const isHalf = absRemainder * 2n === absDenominator;
+  const isMoreThanHalf = absRemainder * 2n > absDenominator;
+  switch (mode) {
+    case "FLOOR" /* FLOOR */:
+      return sign > 0n ? quotient : quotient - 1n;
+    case "CEIL" /* CEIL */:
+      return sign > 0n ? quotient + 1n : quotient;
+    case "HALF_UP" /* HALF_UP */:
+      if (isMoreThanHalf || isHalf) {
+        return sign > 0n ? quotient + 1n : quotient - 1n;
+      }
+      return quotient;
+    case "HALF_DOWN" /* HALF_DOWN */:
+      if (isMoreThanHalf) {
+        return sign > 0n ? quotient + 1n : quotient - 1n;
+      }
+      return quotient;
+    case "HALF_EVEN" /* HALF_EVEN */:
+      if (isMoreThanHalf) {
+        return sign > 0n ? quotient + 1n : quotient - 1n;
+      }
+      if (isHalf) {
+        if (quotient % 2n !== 0n) {
+          return sign > 0n ? quotient + 1n : quotient - 1n;
+        }
+      }
+      return quotient;
+    default:
+      throw new Error(`Unsupported rounding mode: ${mode}`);
+  }
+}
+
+// src/money/arithmetic.ts
+function add(a, b) {
+  return a + b;
+}
+function subtract(a, b) {
+  return a - b;
+}
+function multiply(amount, multiplier, rounding) {
+  const { numerator, denominator } = parseMultiplier(multiplier);
+  const product = amount * numerator;
+  if (product % denominator === 0n) {
+    return product / denominator;
+  }
+  if (!rounding) {
+    throw new RoundingRequiredError();
+  }
+  return divideWithRounding(product, denominator, rounding);
+}
+function parseMultiplier(multiplier) {
+  const s = multiplier.toString();
+  if (/[eE]/.test(s)) {
+    throw new Error("Scientific notation not supported");
+  }
+  const parts = s.split(".");
+  if (parts.length > 2) {
+    throw new Error("Invalid number format");
+  }
+  const integerPart = parts[0];
+  const fractionalPart = parts[1] || "";
+  const denominator = 10n ** BigInt(fractionalPart.length);
+  const numerator = BigInt(integerPart + fractionalPart);
+  return { numerator, denominator };
+}
+
+// src/money/allocation.ts
+function allocate(amount, ratios) {
+  if (ratios.length === 0) {
+    throw new Error("Cannot allocate to empty ratios");
+  }
+  const scaledRatios = ratios.map((r) => {
+    const s = r.toString();
+    if (/[eE]/.test(s)) throw new Error("Scientific notation not supported");
+    const parts = s.split(".");
+    const decimals = parts[1] ? parts[1].length : 0;
+    const value = BigInt(parts[0] + (parts[1] || ""));
+    return { value, decimals };
+  });
+  const maxDecimals = Math.max(...scaledRatios.map((r) => r.decimals));
+  const normalizedRatios = scaledRatios.map((r) => {
+    const factor = 10n ** BigInt(maxDecimals - r.decimals);
+    return r.value * factor;
+  });
+  const total = normalizedRatios.reduce((sum, r) => sum + r, 0n);
+  if (total === 0n) {
+    throw new Error("Total ratio must be greater than zero");
+  }
+  const results = [];
+  let allocatedTotal = 0n;
+  for (let i = 0; i < normalizedRatios.length; i++) {
+    const ratio = normalizedRatios[i];
+    const share = amount * ratio / total;
+    const remainder = amount * ratio % total;
+    results.push({ share, remainder, index: i });
+    allocatedTotal += share;
+  }
+  let leftOver = amount - allocatedTotal;
+  results.sort((a, b) => {
+    if (b.remainder > a.remainder) return 1;
+    if (b.remainder < a.remainder) return -1;
+    return 0;
+  });
+  for (let i = 0; i < Number(leftOver); i++) {
+    results[i].share += 1n;
+  }
+  results.sort((a, b) => a.index - b.index);
+  return results.map((r) => r.share);
+}
+
+// src/format/parser.ts
+function parseToMinor(amount, currency) {
+  if (/[eE]/.test(amount)) {
+    throw new Error("Scientific notation not supported");
+  }
+  if (/[^0-9.-]/.test(amount)) {
+    throw new Error("Invalid characters in amount");
+  }
+  const parts = amount.split(".");
+  if (parts.length > 2) {
+    throw new Error("Invalid format: multiple decimal points");
+  }
+  const integerPart = parts[0];
+  const fractionalPart = parts[1] || "";
+  if (fractionalPart.length > currency.decimals) {
+    throw new InvalidPrecisionError(
+      `Precision ${fractionalPart.length} exceeds currency decimals ${currency.decimals}`
+    );
+  }
+  const paddedFractional = fractionalPart.padEnd(currency.decimals, "0");
+  const combined = integerPart + paddedFractional;
+  if (combined === "-" || combined === "") {
+    throw new Error("Invalid format");
+  }
+  return BigInt(combined);
+}
+
+// src/format/formatter.ts
+function format(money, options) {
+  const locale = options?.locale || money.currency.locale || "en-US";
+  const showSymbol = options?.symbol ?? true;
+  const decimals = money.currency.decimals;
+  const minor = money.minor;
+  const absMinor = minor < 0n ? -minor : minor;
+  const divisor = 10n ** BigInt(decimals);
+  const integerPart = absMinor / divisor;
+  const fractionalPart = absMinor % divisor;
+  const fractionalStr = fractionalPart.toString().padStart(decimals, "0");
+  const parts = new Intl.NumberFormat(locale, {
+    style: "decimal",
+    minimumFractionDigits: 1
+  }).formatToParts(1.1);
+  const decimalSeparator = parts.find((p) => p.type === "decimal")?.value || ".";
+  const integerFormatted = new Intl.NumberFormat(locale, {
+    style: "decimal",
+    useGrouping: true
+  }).format(integerPart);
+  const absString = decimals > 0 ? `${integerFormatted}${decimalSeparator}${fractionalStr}` : integerFormatted;
+  if (!showSymbol) {
+    return minor < 0n ? `-${absString}` : absString;
+  }
+  const templateParts = new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: money.currency.code
+  }).formatToParts(minor < 0n ? -1 : 1);
+  let result = "";
+  let numberInserted = false;
+  for (const part of templateParts) {
+    if (["integer", "group", "decimal", "fraction"].includes(part.type)) {
+      if (!numberInserted) {
+        result += absString;
+        numberInserted = true;
+      }
+    } else if (part.type === "currency") {
+      result += part.value;
+    } else {
+      result += part.value;
+    }
+  }
+  return result;
+}
+
+// src/money/Money.ts
+var Money = class _Money {
+  constructor(minor, currency) {
+    this.minor = minor;
+    this.currency = currency;
+  }
+  static fromMinor(minor, currency) {
+    return new _Money(BigInt(minor), currency);
+  }
+  static fromMajor(amount, currency) {
+    const minor = parseToMinor(amount, currency);
+    return new _Money(minor, currency);
+  }
+  static zero(currency) {
+    return new _Money(0n, currency);
+  }
+  add(other) {
+    assertSameCurrency(this, other);
+    return new _Money(add(this.minor, other.minor), this.currency);
+  }
+  subtract(other) {
+    assertSameCurrency(this, other);
+    return new _Money(subtract(this.minor, other.minor), this.currency);
+  }
+  multiply(multiplier, options) {
+    const result = multiply(this.minor, multiplier, options?.rounding);
+    return new _Money(result, this.currency);
+  }
+  allocate(ratios) {
+    const shares = allocate(this.minor, ratios);
+    return shares.map((share) => new _Money(share, this.currency));
+  }
+  format(options) {
+    return format(this, options);
+  }
+  equals(other) {
+    return this.currency.code === other.currency.code && this.minor === other.minor;
+  }
+  greaterThan(other) {
+    assertSameCurrency(this, other);
+    return this.minor > other.minor;
+  }
+  lessThan(other) {
+    assertSameCurrency(this, other);
+    return this.minor < other.minor;
+  }
+  isZero() {
+    return this.minor === 0n;
+  }
+  isNegative() {
+    return this.minor < 0n;
+  }
+};
+
+// src/currency/iso4217.ts
+var USD = {
+  code: "USD",
+  decimals: 2,
+  symbol: "$",
+  locale: "en-US"
+};
+var EUR = {
+  code: "EUR",
+  decimals: 2,
+  symbol: "\u20AC",
+  locale: "de-DE"
+  // Default locale, can be overridden
+};
+var GBP = {
+  code: "GBP",
+  decimals: 2,
+  symbol: "\xA3",
+  locale: "en-GB"
+};
+var JPY = {
+  code: "JPY",
+  decimals: 0,
+  symbol: "\xA5",
+  locale: "ja-JP"
+};
+var ZAR = {
+  code: "ZAR",
+  decimals: 2,
+  symbol: "R",
+  locale: "en-ZA"
+};
+var CURRENCIES = {
+  USD,
+  EUR,
+  GBP,
+  JPY,
+  ZAR
+};
+function getCurrency(code) {
+  const currency = CURRENCIES[code.toUpperCase()];
+  if (!currency) {
+    throw new Error(`Unknown currency code: ${code}`);
+  }
+  return currency;
+}
+
+// src/currency/precision.ts
+function getMinorUnitExponent(currency) {
+  return 10n ** BigInt(currency.decimals);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CURRENCIES,
+  CurrencyMismatchError,
+  EUR,
+  GBP,
+  InsufficientFundsError,
+  InvalidPrecisionError,
+  JPY,
+  MonetraError,
+  Money,
+  OverflowError,
+  RoundingMode,
+  RoundingRequiredError,
+  USD,
+  ZAR,
+  divideWithRounding,
+  getCurrency,
+  getMinorUnitExponent
+});
+//# sourceMappingURL=index.js.map