npm package: @pumpkin46/money
Description: Tiny money class with formatter/parser and TS types
Latest version: 1.0.1

---

# 💰 Money Library

A **type-safe, immutable money library** for JavaScript/TypeScript.
Built to handle **currencies, math operations, formatting, and parsing** with precision and reliability.

---

## ✨ Features

* ✅ Immutable `Money` objects
* ✅ Works with **ISO 4217 currencies** (and many historic ones)
* ✅ Arithmetic operations (`add`, `subtract`, `multiply`, `divide`, `mod`, `ratioOf`)
* ✅ Comparison helpers (`equals`, `gt`, `gte`, `lt`, `lte`)
* ✅ Serialization (`toJSON`, `fromJSON`)
* ✅ Locale-aware **formatting & parsing** (via `Intl.NumberFormat`)
* ✅ Supports **0–3 decimal currencies** (e.g., JPY, USD, KWD)
* ✅ Zero-safe: create `Money.zero(currency)`

---

## 📦 Installation

```bash
npm install @pumpkin46/money
# or
yarn add @pumpkin46/money
# or
pnpm add @pumpkin46/money
```

---

## 🚀 Usage

### Create Money

```ts
import { Money } from "@pumpkin46/money";

const price = new Money(12345, "USD"); // $123.45
```

---

### Arithmetic

```ts
const a = new Money(1000, "USD"); // $10.00
const b = new Money(250, "USD");  // $2.50

const sum = a.add(b);             // $12.50
const diff = a.subtract(b);       // $7.50
const product = a.multiply(2);    // $20.00
const ratio = b.ratioOf(a);       // 0.25
```

---

### Comparison

```ts
a.equals(b); // false
a.gt(b);     // true
a.lte(b);    // false
```

---

### Formatting

```ts
import { MoneyFormatter } from "@pumpkin46/money";

const money = new Money(12345, "USD"); // $123.45
const formatter = new MoneyFormatter("USD", { locale: "en-US" });

formatter.format(money); // "$123.45"
```

---

### Parsing

```ts
import { MoneyParser } from "@pumpkin46/money";

const parser = new MoneyParser("en-US");
const money = parser.parse("$123.45", "USD");

console.log(money.amount);   // 12345
console.log(money.currency); // "USD"
```

---

### Serialization

```ts
const m = new Money(5000, "EUR"); // €50.00
const json = m.toJSON();          // { amount: 5000, currency: "EUR" }

const restored = Money.fromJSON(json);
```

---

## 🌍 Currency & Locale Support

* All currencies from **ISO 4217**, plus some historical ones.
* Locale → default currency mapping (`LOCALE_CURRENCY_MAP`).
* Respects decimal places for each currency (e.g., `USD` = 2, `JPY` = 0, `KWD` = 3).

---

## 📖 API Reference

### `Money`

* `constructor(amount: number, currency: Currency)`
* `add(m: Money): Money`
* `subtract(m: Money): Money`
* `multiply(factor: number): Money`
* `divide(divisor: number): Money`
* `mod(m: Money): Money`
* `abs(): Money`
* `ratioOf(m: Money): number`
* `equals(m: Money): boolean`
* `gt(m: Money): boolean`
* `gte(m: Money): boolean`
* `lt(m: Money): boolean`
* `lte(m: Money): boolean`
* `isZero(): boolean`
* `isPositive(): boolean`
* `isNegative(): boolean`
* `toJSON(): { amount: number; currency: Currency }`
* `static fromJSON(data): Money`
* `static zero(currency: Currency): Money`

### `MoneyFormatter`

* `constructor(currency: Currency, options?: FormatOptions)`
* `format(money: Money): string`

### `MoneyParser`

* `constructor(locale?: string)`
* `parse(input: string, currency: Currency): Money`

## 📜 License

MIT License © 2025

---