@storepass/money 0.0.1-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlas Alpha
+
+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,162 @@
+# sp-money
+
+Safe, consistent, deterministic money operations.
+
+- BigInt-backed internal arithmetic
+- Explicit currency metadata (`code`, `decimalPlaces`)
+- Deterministic rounding/conversion behavior
+- No floating-point drift in stored values
+
+## Install
+
+Package name: `@atlas-alpha/sp-money`
+
+### Current publish target
+
+This package is currently configured for GitHub Packages.
+
+```bash
+# npm
+npm install @atlas-alpha/sp-money
+
+# pnpm
+pnpm add @atlas-alpha/sp-money
+
+# yarn
+yarn add @atlas-alpha/sp-money
+
+# bun
+bun add @atlas-alpha/sp-money
+```
+
+If your org requires explicit registry config:
+
+```ini
+# .npmrc
+@atlas-alpha:registry=https://npm.pkg.github.com
+```
+
+### Open-source transition
+
+The project is being prepared for a public open-source release.
+
+## Quick Start
+
+```ts
+import { Currency, Money } from "@atlas-alpha/sp-money";
+
+const price = Money.fromMinor(Currency.USD, 1234); // $12.34
+const fee = Money.fromNumber(Currency.USD, 1.25);
+const total = price.add(fee);
+
+console.log(total.toMinor()); // 1359
+console.log(total.toNumber()); // 13.59
+console.log(total.currency.code); // "USD"
+```
+
+## API Overview
+
+### Money creation
+
+```ts
+import { Currency, Money } from "@atlas-alpha/sp-money";
+
+Money.fromMinor(Currency.USD, 1234); // $12.34
+Money.fromNumber(Currency.USD, 12.345, { rounding: "round" }); // $12.35
+Money.fromNumber(Currency.USD, 12.34, { strict: true }); // exact only
+```
+
+### Arithmetic and comparison
+
+```ts
+const a = Money.fromNumber(Currency.USD, 10);
+const b = Money.fromNumber(Currency.USD, 2.5);
+
+const sum = a.add(b); // 12.5
+const diff = a.subtract(b); // 7.5
+
+Money.compare(a, b); // 1
+Money.greaterThan(a, b); // true
+```
+
+### Allocation
+
+```ts
+const m = Money.fromNumber(Currency.USD, 10);
+const parts = m.allocate(3);
+
+parts.map((p) => p.toNumber()); // [3.34, 3.33, 3.33]
+Money.sum(parts).toNumber(); // 10
+```
+
+### Conversion and rounding
+
+```ts
+const usd = Money.fromNumber(Currency.USD, 10);
+const eur = usd.convert(Currency.EUR, 0.92); // exchange rate required
+
+const rounded = Money.fromNumber(Currency.USD, 12.37).round(0.05);
+rounded.toNumber(); // 12.35
+```
+
+### Percent operations
+
+```ts
+const subtotal = Money.fromNumber(Currency.USD, 100);
+
+subtotal.percentOf(8.25).toNumber(); // 8.25
+subtotal.incrementByPercent(8.25).toNumber(); // 108.25
+subtotal.decrementByPercent(10).toNumber(); // 90
+```
+
+### Custom currencies
+
+```ts
+import { defineCurrency, Money } from "@atlas-alpha/sp-money";
+
+const XAU = defineCurrency("XAU", 4);
+const gold = Money.fromNumber(XAU, 1.2345);
+```
+
+### Serialization
+
+```ts
+const m = Money.fromNumber(Currency.USD, 12.34);
+const json = m.toJSON();
+// { amount: 1234, currency: "USD" }
+```
+
+`amount` is always in minor units.
+
+## Notes and Guarantees
+
+- Currency mismatch operations throw (for example, adding USD to EUR).
+- Results that exceed JavaScript safe integer range throw.
+- Rounding modes supported: `"floor" | "ceil" | "round" | "trunc"`.
+- `Money` instances are immutable; operations return new instances.
+
+## Development
+
+```bash
+bun install       # install dependencies
+bun test          # run tests
+bun run build     # build ESM + CJS + d.ts into dist/
+bun run check     # biome check + auto-fix/write
+bun run lint      # lint only
+bun run format    # format only
+```
+
+## Releasing
+
+```bash
+./scripts/release.sh         # bump prerelease (default)
+./scripts/release.sh patch   # bump patch
+./scripts/release.sh minor   # bump minor
+./scripts/release.sh major   # bump major
+```
+
+The release script bumps version, commits, tags, and pushes commit + tags.
+
+## License
+
+MIT

package/dist/currency.d.ts

@@ -0,0 +1,121 @@
+export interface CurrencyDefinition {
+    code: string;
+    decimalPlaces: number;
+}
+export declare const Currency: {
+    readonly USD: {
+        readonly code: "USD";
+        readonly decimalPlaces: 2;
+    };
+    readonly USDH: {
+        readonly code: "USDH";
+        readonly decimalPlaces: 3;
+    };
+    readonly EUR: {
+        readonly code: "EUR";
+        readonly decimalPlaces: 2;
+    };
+    readonly GBP: {
+        readonly code: "GBP";
+        readonly decimalPlaces: 2;
+    };
+    readonly JPY: {
+        readonly code: "JPY";
+        readonly decimalPlaces: 0;
+    };
+    readonly CAD: {
+        readonly code: "CAD";
+        readonly decimalPlaces: 2;
+    };
+    readonly AUD: {
+        readonly code: "AUD";
+        readonly decimalPlaces: 2;
+    };
+    readonly NZD: {
+        readonly code: "NZD";
+        readonly decimalPlaces: 2;
+    };
+    readonly CHF: {
+        readonly code: "CHF";
+        readonly decimalPlaces: 2;
+    };
+    readonly SEK: {
+        readonly code: "SEK";
+        readonly decimalPlaces: 2;
+    };
+    readonly NOK: {
+        readonly code: "NOK";
+        readonly decimalPlaces: 2;
+    };
+    readonly DKK: {
+        readonly code: "DKK";
+        readonly decimalPlaces: 2;
+    };
+    readonly PLN: {
+        readonly code: "PLN";
+        readonly decimalPlaces: 2;
+    };
+    readonly CZK: {
+        readonly code: "CZK";
+        readonly decimalPlaces: 2;
+    };
+    readonly HUF: {
+        readonly code: "HUF";
+        readonly decimalPlaces: 2;
+    };
+    readonly BRL: {
+        readonly code: "BRL";
+        readonly decimalPlaces: 2;
+    };
+    readonly MXN: {
+        readonly code: "MXN";
+        readonly decimalPlaces: 2;
+    };
+    readonly ARS: {
+        readonly code: "ARS";
+        readonly decimalPlaces: 2;
+    };
+    readonly CLP: {
+        readonly code: "CLP";
+        readonly decimalPlaces: 0;
+    };
+    readonly INR: {
+        readonly code: "INR";
+        readonly decimalPlaces: 2;
+    };
+    readonly SGD: {
+        readonly code: "SGD";
+        readonly decimalPlaces: 2;
+    };
+    readonly HKD: {
+        readonly code: "HKD";
+        readonly decimalPlaces: 2;
+    };
+    readonly KRW: {
+        readonly code: "KRW";
+        readonly decimalPlaces: 0;
+    };
+    readonly CNY: {
+        readonly code: "CNY";
+        readonly decimalPlaces: 2;
+    };
+    readonly ZAR: {
+        readonly code: "ZAR";
+        readonly decimalPlaces: 2;
+    };
+    readonly AED: {
+        readonly code: "AED";
+        readonly decimalPlaces: 2;
+    };
+    readonly SAR: {
+        readonly code: "SAR";
+        readonly decimalPlaces: 2;
+    };
+    readonly BTC: {
+        readonly code: "BTC";
+        readonly decimalPlaces: 8;
+    };
+};
+export type CurrencyCode = keyof typeof Currency;
+export type CurrencyType = (typeof Currency)[CurrencyCode];
+export declare function defineCurrency(code: string, decimalPlaces: number): CurrencyDefinition;

package/dist/index.cjs

@@ -0,0 +1,423 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  defineCurrency: () => defineCurrency,
+  Money: () => Money,
+  Currency: () => Currency
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/currency.ts
+var Currency = {
+  USD: { code: "USD", decimalPlaces: 2 },
+  USDH: { code: "USDH", decimalPlaces: 3 },
+  EUR: { code: "EUR", decimalPlaces: 2 },
+  GBP: { code: "GBP", decimalPlaces: 2 },
+  JPY: { code: "JPY", decimalPlaces: 0 },
+  CAD: { code: "CAD", decimalPlaces: 2 },
+  AUD: { code: "AUD", decimalPlaces: 2 },
+  NZD: { code: "NZD", decimalPlaces: 2 },
+  CHF: { code: "CHF", decimalPlaces: 2 },
+  SEK: { code: "SEK", decimalPlaces: 2 },
+  NOK: { code: "NOK", decimalPlaces: 2 },
+  DKK: { code: "DKK", decimalPlaces: 2 },
+  PLN: { code: "PLN", decimalPlaces: 2 },
+  CZK: { code: "CZK", decimalPlaces: 2 },
+  HUF: { code: "HUF", decimalPlaces: 2 },
+  BRL: { code: "BRL", decimalPlaces: 2 },
+  MXN: { code: "MXN", decimalPlaces: 2 },
+  ARS: { code: "ARS", decimalPlaces: 2 },
+  CLP: { code: "CLP", decimalPlaces: 0 },
+  INR: { code: "INR", decimalPlaces: 2 },
+  SGD: { code: "SGD", decimalPlaces: 2 },
+  HKD: { code: "HKD", decimalPlaces: 2 },
+  KRW: { code: "KRW", decimalPlaces: 0 },
+  CNY: { code: "CNY", decimalPlaces: 2 },
+  ZAR: { code: "ZAR", decimalPlaces: 2 },
+  AED: { code: "AED", decimalPlaces: 2 },
+  SAR: { code: "SAR", decimalPlaces: 2 },
+  BTC: { code: "BTC", decimalPlaces: 8 }
+};
+function defineCurrency(code, decimalPlaces) {
+  if (!code || typeof code !== "string") {
+    throw new Error("Currency code must be a non-empty string");
+  }
+  if (!Number.isInteger(decimalPlaces) || decimalPlaces < 0) {
+    throw new Error("Decimal places must be a non-negative integer");
+  }
+  return Object.freeze({ code, decimalPlaces });
+}
+// src/money.ts
+var INTERNAL_PRECISION = 20;
+var INTERNAL_SCALE = 10n ** BigInt(INTERNAL_PRECISION);
+function numberToDecimalString(n) {
+  if (!Number.isFinite(n)) {
+    throw new Error(`Cannot convert ${n} to decimal string`);
+  }
+  if (n === 0)
+    return "0";
+  const str = n.toString();
+  if (str.includes("e") || str.includes("E")) {
+    return n.toPrecision(17);
+  }
+  return str;
+}
+function parseDecimalStringToScaled(str) {
+  const negative = str.startsWith("-");
+  if (negative)
+    str = str.slice(1);
+  const eIndex = str.toLowerCase().indexOf("e");
+  if (eIndex !== -1) {
+    const mantissa = str.slice(0, eIndex);
+    const exponent = parseInt(str.slice(eIndex + 1), 10);
+    const scaledMantissa = parseDecimalStringToScaled(mantissa);
+    const sign = negative ? -1n : 1n;
+    if (exponent >= 0) {
+      return sign * scaledMantissa * 10n ** BigInt(exponent);
+    } else {
+      return sign * scaledMantissa / 10n ** BigInt(-exponent);
+    }
+  }
+  const dotIndex = str.indexOf(".");
+  let intPart;
+  let decPart;
+  if (dotIndex === -1) {
+    intPart = str || "0";
+    decPart = "";
+  } else {
+    intPart = str.slice(0, dotIndex) || "0";
+    decPart = str.slice(dotIndex + 1);
+  }
+  decPart = decPart.padEnd(INTERNAL_PRECISION, "0").slice(0, INTERNAL_PRECISION);
+  const scaledInt = BigInt(intPart) * INTERNAL_SCALE;
+  const scaledDec = BigInt(decPart);
+  const result = scaledInt + scaledDec;
+  return negative ? -result : result;
+}
+function roundScaledToMinor(scaled, targetDecimalPlaces, mode) {
+  const targetScale = 10n ** BigInt(targetDecimalPlaces);
+  const divisor = INTERNAL_SCALE / targetScale;
+  const quotient = scaled / divisor;
+  const remainder = scaled % divisor;
+  if (remainder === 0n)
+    return quotient;
+  const isNegative = scaled < 0n;
+  const absRemainder = isNegative ? -remainder : remainder;
+  const halfDivisor = divisor / 2n;
+  switch (mode) {
+    case "floor":
+      return isNegative ? quotient - 1n : quotient;
+    case "ceil":
+      return isNegative ? quotient : quotient + 1n;
+    case "trunc":
+      return quotient;
+    default:
+      if (absRemainder > halfDivisor || absRemainder === halfDivisor && !isNegative) {
+        return isNegative ? quotient - 1n : quotient + 1n;
+      }
+      return quotient;
+  }
+}
+function assertCurrenciesMatch(a, b, operation) {
+  if (a.code !== b.code || a.decimalPlaces !== b.decimalPlaces) {
+    throw new Error(`Cannot ${operation} ${a.code} and ${b.code}: currency mismatch`);
+  }
+}
+function assertSafeResult(value) {
+  if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(-Number.MAX_SAFE_INTEGER)) {
+    throw new Error("Result too large: exceeds safe integer range");
+  }
+}
+
+class Money {
+  #minor;
+  #currency;
+  constructor(minor, currency) {
+    this.#minor = minor;
+    this.#currency = currency;
+  }
+  get currency() {
+    return this.#currency;
+  }
+  static fromNumber(currency, value, options = {}) {
+    const { rounding = "round", strict } = options;
+    const multiplier = 10 ** currency.decimalPlaces;
+    const estimatedMinor = Math.abs(value) * multiplier;
+    if (estimatedMinor > Number.MAX_SAFE_INTEGER) {
+      throw new Error(`Value too large: ${value} exceeds safe integer range when converted to minor units`);
+    }
+    const valueStr = numberToDecimalString(value);
+    const scaledValue = parseDecimalStringToScaled(valueStr);
+    if (strict) {
+      const targetScale = 10n ** BigInt(currency.decimalPlaces);
+      const divisor = INTERNAL_SCALE / targetScale;
+      if (scaledValue % divisor !== 0n) {
+        throw new Error(`Precision loss: ${value} cannot be exactly represented with ${currency.decimalPlaces} decimal places`);
+      }
+    }
+    const minor = roundScaledToMinor(scaledValue, currency.decimalPlaces, rounding);
+    assertSafeResult(minor);
+    return new Money(minor, currency);
+  }
+  static fromMinor(currency, minor) {
+    return new Money(BigInt(minor), currency);
+  }
+  toNumber() {
+    const divisor = 10 ** this.#currency.decimalPlaces;
+    return Number(this.#minor) / divisor;
+  }
+  toMinor() {
+    return Number(this.#minor);
+  }
+  static add(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "add");
+    const result = a.#minor + b.#minor;
+    assertSafeResult(result);
+    return new Money(result, a.#currency);
+  }
+  static subtract(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "subtract");
+    const result = a.#minor - b.#minor;
+    assertSafeResult(result);
+    return new Money(result, a.#currency);
+  }
+  static sum(items) {
+    const first = items[0];
+    if (first === undefined) {
+      throw new Error("Cannot sum empty array: at least one Money value required");
+    }
+    const currency = first.#currency;
+    let total = 0n;
+    for (const item of items) {
+      assertCurrenciesMatch(item.#currency, currency, "sum");
+      total += item.#minor;
+    }
+    assertSafeResult(total);
+    return new Money(total, currency);
+  }
+  static equals(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    return a.#minor === b.#minor;
+  }
+  static compare(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    if (a.#minor < b.#minor)
+      return -1;
+    if (a.#minor > b.#minor)
+      return 1;
+    return 0;
+  }
+  static lessThan(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    return a.#minor < b.#minor;
+  }
+  static greaterThan(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    return a.#minor > b.#minor;
+  }
+  static lessThanOrEqual(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    return a.#minor <= b.#minor;
+  }
+  static greaterThanOrEqual(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    return a.#minor >= b.#minor;
+  }
+  add(other) {
+    return Money.add(this, other);
+  }
+  subtract(other) {
+    return Money.subtract(this, other);
+  }
+  equals(other) {
+    return Money.equals(this, other);
+  }
+  compare(other) {
+    return Money.compare(this, other);
+  }
+  lessThan(other) {
+    return Money.lessThan(this, other);
+  }
+  greaterThan(other) {
+    return Money.greaterThan(this, other);
+  }
+  lessThanOrEqual(other) {
+    return Money.lessThanOrEqual(this, other);
+  }
+  greaterThanOrEqual(other) {
+    return Money.greaterThanOrEqual(this, other);
+  }
+  isZero() {
+    return this.#minor === 0n;
+  }
+  isPositive() {
+    return this.#minor > 0n;
+  }
+  isNegative() {
+    return this.#minor < 0n;
+  }
+  static allocate(money, parts) {
+    if (!Number.isInteger(parts) || parts < 1) {
+      throw new Error("Allocation count must be a positive integer");
+    }
+    if (!Number.isSafeInteger(parts)) {
+      throw new Error("Allocation count must be a safe integer");
+    }
+    const partsBigInt = BigInt(parts);
+    const base = money.#minor / partsBigInt;
+    const remainder = money.#minor % partsBigInt;
+    const absRemainder = remainder < 0n ? -remainder : remainder;
+    const sign = remainder < 0n ? -1n : 1n;
+    const result = [];
+    for (let i = 0n;i < partsBigInt; i++) {
+      const extra = i < absRemainder ? sign : 0n;
+      result.push(new Money(base + extra, money.#currency));
+    }
+    return result;
+  }
+  allocate(parts) {
+    return Money.allocate(this, parts);
+  }
+  static convert(money, targetCurrency, rate, options = {}) {
+    if (!Number.isFinite(rate) || rate <= 0) {
+      throw new Error("Exchange rate must be a finite positive number");
+    }
+    const { rounding = "round" } = options;
+    const scaledRate = parseDecimalStringToScaled(numberToDecimalString(rate));
+    const sourceScale = 10n ** BigInt(money.#currency.decimalPlaces);
+    const scaledSource = money.#minor * (INTERNAL_SCALE / sourceScale);
+    const rawProduct = scaledSource * scaledRate / INTERNAL_SCALE;
+    const resultMinor = roundScaledToMinor(rawProduct, targetCurrency.decimalPlaces, rounding);
+    assertSafeResult(resultMinor);
+    return new Money(resultMinor, targetCurrency);
+  }
+  convert(targetCurrency, rate, options) {
+    return Money.convert(this, targetCurrency, rate, options);
+  }
+  static roundTo(money, increment, mode = "round") {
+    if (!Number.isFinite(increment) || increment <= 0) {
+      throw new Error("Rounding increment must be a finite positive number");
+    }
+    const scaledIncrement = parseDecimalStringToScaled(numberToDecimalString(increment));
+    const targetScale = 10n ** BigInt(money.#currency.decimalPlaces);
+    const divisor = INTERNAL_SCALE / targetScale;
+    if (scaledIncrement % divisor !== 0n) {
+      throw new Error(`Rounding increment ${increment} cannot be exactly represented with ${money.#currency.decimalPlaces} decimal places`);
+    }
+    const incrementMinor = scaledIncrement / divisor;
+    if (incrementMinor === 0n) {
+      throw new Error("Rounding increment is too small for this currency's precision");
+    }
+    const minor = money.#minor;
+    const remainder = minor % incrementMinor;
+    if (remainder === 0n) {
+      return new Money(minor, money.#currency);
+    }
+    const base = minor - remainder;
+    let rounded;
+    switch (mode) {
+      case "trunc":
+        rounded = base;
+        break;
+      case "floor":
+        rounded = minor < 0n ? base - incrementMinor : base;
+        break;
+      case "ceil":
+        rounded = minor < 0n ? base : base + incrementMinor;
+        break;
+      default: {
+        const absRemainder = remainder < 0n ? -remainder : remainder;
+        const cmp = absRemainder * 2n - incrementMinor;
+        if (cmp < 0n) {
+          rounded = base;
+        } else if (cmp > 0n) {
+          rounded = minor < 0n ? base - incrementMinor : base + incrementMinor;
+        } else {
+          rounded = minor < 0n ? base : base + incrementMinor;
+        }
+        break;
+      }
+    }
+    assertSafeResult(rounded);
+    return new Money(rounded, money.#currency);
+  }
+  round(increment, mode) {
+    return Money.roundTo(this, increment, mode);
+  }
+  static percentOf(money, percent, options = {}) {
+    const { rounding = "round" } = options;
+    const scaledPercent = parseDecimalStringToScaled(numberToDecimalString(percent));
+    const scaledHundred = 100n * INTERNAL_SCALE;
+    const currencyScale = 10n ** BigInt(money.#currency.decimalPlaces);
+    const scaledMoney = money.#minor * (INTERNAL_SCALE / currencyScale);
+    const rawResult = scaledMoney * scaledPercent / scaledHundred;
+    const resultMinor = roundScaledToMinor(rawResult, money.#currency.decimalPlaces, rounding);
+    assertSafeResult(resultMinor);
+    return new Money(resultMinor, money.#currency);
+  }
+  static incrementByPercent(money, percent, options = {}) {
+    const { rounding = "round" } = options;
+    const scaledPercent = parseDecimalStringToScaled(numberToDecimalString(percent));
+    const scaledHundred = 100n * INTERNAL_SCALE;
+    const currencyScale = 10n ** BigInt(money.#currency.decimalPlaces);
+    const scaledMoney = money.#minor * (INTERNAL_SCALE / currencyScale);
+    const rawResult = scaledMoney * (scaledHundred + scaledPercent) / scaledHundred;
+    const resultMinor = roundScaledToMinor(rawResult, money.#currency.decimalPlaces, rounding);
+    assertSafeResult(resultMinor);
+    return new Money(resultMinor, money.#currency);
+  }
+  static decrementByPercent(money, percent, options = {}) {
+    const { rounding = "round" } = options;
+    const scaledPercent = parseDecimalStringToScaled(numberToDecimalString(percent));
+    const scaledHundred = 100n * INTERNAL_SCALE;
+    const currencyScale = 10n ** BigInt(money.#currency.decimalPlaces);
+    const scaledMoney = money.#minor * (INTERNAL_SCALE / currencyScale);
+    const rawResult = scaledMoney * (scaledHundred - scaledPercent) / scaledHundred;
+    const resultMinor = roundScaledToMinor(rawResult, money.#currency.decimalPlaces, rounding);
+    assertSafeResult(resultMinor);
+    return new Money(resultMinor, money.#currency);
+  }
+  percentOf(percent, options) {
+    return Money.percentOf(this, percent, options);
+  }
+  incrementByPercent(percent, options) {
+    return Money.incrementByPercent(this, percent, options);
+  }
+  decrementByPercent(percent, options) {
+    return Money.decrementByPercent(this, percent, options);
+  }
+  toJSON() {
+    return {
+      amount: this.toMinor(),
+      currency: this.#currency.code
+    };
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Currency, type CurrencyCode, type CurrencyDefinition, type CurrencyType, defineCurrency, } from "./currency";
+export { type FromNumberOptions, Money, type RoundingMode } from "./money";

package/dist/index.js

@@ -0,0 +1,391 @@
+// src/currency.ts
+var Currency = {
+  USD: { code: "USD", decimalPlaces: 2 },
+  USDH: { code: "USDH", decimalPlaces: 3 },
+  EUR: { code: "EUR", decimalPlaces: 2 },
+  GBP: { code: "GBP", decimalPlaces: 2 },
+  JPY: { code: "JPY", decimalPlaces: 0 },
+  CAD: { code: "CAD", decimalPlaces: 2 },
+  AUD: { code: "AUD", decimalPlaces: 2 },
+  NZD: { code: "NZD", decimalPlaces: 2 },
+  CHF: { code: "CHF", decimalPlaces: 2 },
+  SEK: { code: "SEK", decimalPlaces: 2 },
+  NOK: { code: "NOK", decimalPlaces: 2 },
+  DKK: { code: "DKK", decimalPlaces: 2 },
+  PLN: { code: "PLN", decimalPlaces: 2 },
+  CZK: { code: "CZK", decimalPlaces: 2 },
+  HUF: { code: "HUF", decimalPlaces: 2 },
+  BRL: { code: "BRL", decimalPlaces: 2 },
+  MXN: { code: "MXN", decimalPlaces: 2 },
+  ARS: { code: "ARS", decimalPlaces: 2 },
+  CLP: { code: "CLP", decimalPlaces: 0 },
+  INR: { code: "INR", decimalPlaces: 2 },
+  SGD: { code: "SGD", decimalPlaces: 2 },
+  HKD: { code: "HKD", decimalPlaces: 2 },
+  KRW: { code: "KRW", decimalPlaces: 0 },
+  CNY: { code: "CNY", decimalPlaces: 2 },
+  ZAR: { code: "ZAR", decimalPlaces: 2 },
+  AED: { code: "AED", decimalPlaces: 2 },
+  SAR: { code: "SAR", decimalPlaces: 2 },
+  BTC: { code: "BTC", decimalPlaces: 8 }
+};
+function defineCurrency(code, decimalPlaces) {
+  if (!code || typeof code !== "string") {
+    throw new Error("Currency code must be a non-empty string");
+  }
+  if (!Number.isInteger(decimalPlaces) || decimalPlaces < 0) {
+    throw new Error("Decimal places must be a non-negative integer");
+  }
+  return Object.freeze({ code, decimalPlaces });
+}
+// src/money.ts
+var INTERNAL_PRECISION = 20;
+var INTERNAL_SCALE = 10n ** BigInt(INTERNAL_PRECISION);
+function numberToDecimalString(n) {
+  if (!Number.isFinite(n)) {
+    throw new Error(`Cannot convert ${n} to decimal string`);
+  }
+  if (n === 0)
+    return "0";
+  const str = n.toString();
+  if (str.includes("e") || str.includes("E")) {
+    return n.toPrecision(17);
+  }
+  return str;
+}
+function parseDecimalStringToScaled(str) {
+  const negative = str.startsWith("-");
+  if (negative)
+    str = str.slice(1);
+  const eIndex = str.toLowerCase().indexOf("e");
+  if (eIndex !== -1) {
+    const mantissa = str.slice(0, eIndex);
+    const exponent = parseInt(str.slice(eIndex + 1), 10);
+    const scaledMantissa = parseDecimalStringToScaled(mantissa);
+    const sign = negative ? -1n : 1n;
+    if (exponent >= 0) {
+      return sign * scaledMantissa * 10n ** BigInt(exponent);
+    } else {
+      return sign * scaledMantissa / 10n ** BigInt(-exponent);
+    }
+  }
+  const dotIndex = str.indexOf(".");
+  let intPart;
+  let decPart;
+  if (dotIndex === -1) {
+    intPart = str || "0";
+    decPart = "";
+  } else {
+    intPart = str.slice(0, dotIndex) || "0";
+    decPart = str.slice(dotIndex + 1);
+  }
+  decPart = decPart.padEnd(INTERNAL_PRECISION, "0").slice(0, INTERNAL_PRECISION);
+  const scaledInt = BigInt(intPart) * INTERNAL_SCALE;
+  const scaledDec = BigInt(decPart);
+  const result = scaledInt + scaledDec;
+  return negative ? -result : result;
+}
+function roundScaledToMinor(scaled, targetDecimalPlaces, mode) {
+  const targetScale = 10n ** BigInt(targetDecimalPlaces);
+  const divisor = INTERNAL_SCALE / targetScale;
+  const quotient = scaled / divisor;
+  const remainder = scaled % divisor;
+  if (remainder === 0n)
+    return quotient;
+  const isNegative = scaled < 0n;
+  const absRemainder = isNegative ? -remainder : remainder;
+  const halfDivisor = divisor / 2n;
+  switch (mode) {
+    case "floor":
+      return isNegative ? quotient - 1n : quotient;
+    case "ceil":
+      return isNegative ? quotient : quotient + 1n;
+    case "trunc":
+      return quotient;
+    default:
+      if (absRemainder > halfDivisor || absRemainder === halfDivisor && !isNegative) {
+        return isNegative ? quotient - 1n : quotient + 1n;
+      }
+      return quotient;
+  }
+}
+function assertCurrenciesMatch(a, b, operation) {
+  if (a.code !== b.code || a.decimalPlaces !== b.decimalPlaces) {
+    throw new Error(`Cannot ${operation} ${a.code} and ${b.code}: currency mismatch`);
+  }
+}
+function assertSafeResult(value) {
+  if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(-Number.MAX_SAFE_INTEGER)) {
+    throw new Error("Result too large: exceeds safe integer range");
+  }
+}
+
+class Money {
+  #minor;
+  #currency;
+  constructor(minor, currency) {
+    this.#minor = minor;
+    this.#currency = currency;
+  }
+  get currency() {
+    return this.#currency;
+  }
+  static fromNumber(currency, value, options = {}) {
+    const { rounding = "round", strict } = options;
+    const multiplier = 10 ** currency.decimalPlaces;
+    const estimatedMinor = Math.abs(value) * multiplier;
+    if (estimatedMinor > Number.MAX_SAFE_INTEGER) {
+      throw new Error(`Value too large: ${value} exceeds safe integer range when converted to minor units`);
+    }
+    const valueStr = numberToDecimalString(value);
+    const scaledValue = parseDecimalStringToScaled(valueStr);
+    if (strict) {
+      const targetScale = 10n ** BigInt(currency.decimalPlaces);
+      const divisor = INTERNAL_SCALE / targetScale;
+      if (scaledValue % divisor !== 0n) {
+        throw new Error(`Precision loss: ${value} cannot be exactly represented with ${currency.decimalPlaces} decimal places`);
+      }
+    }
+    const minor = roundScaledToMinor(scaledValue, currency.decimalPlaces, rounding);
+    assertSafeResult(minor);
+    return new Money(minor, currency);
+  }
+  static fromMinor(currency, minor) {
+    return new Money(BigInt(minor), currency);
+  }
+  toNumber() {
+    const divisor = 10 ** this.#currency.decimalPlaces;
+    return Number(this.#minor) / divisor;
+  }
+  toMinor() {
+    return Number(this.#minor);
+  }
+  static add(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "add");
+    const result = a.#minor + b.#minor;
+    assertSafeResult(result);
+    return new Money(result, a.#currency);
+  }
+  static subtract(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "subtract");
+    const result = a.#minor - b.#minor;
+    assertSafeResult(result);
+    return new Money(result, a.#currency);
+  }
+  static sum(items) {
+    const first = items[0];
+    if (first === undefined) {
+      throw new Error("Cannot sum empty array: at least one Money value required");
+    }
+    const currency = first.#currency;
+    let total = 0n;
+    for (const item of items) {
+      assertCurrenciesMatch(item.#currency, currency, "sum");
+      total += item.#minor;
+    }
+    assertSafeResult(total);
+    return new Money(total, currency);
+  }
+  static equals(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    return a.#minor === b.#minor;
+  }
+  static compare(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    if (a.#minor < b.#minor)
+      return -1;
+    if (a.#minor > b.#minor)
+      return 1;
+    return 0;
+  }
+  static lessThan(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    return a.#minor < b.#minor;
+  }
+  static greaterThan(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    return a.#minor > b.#minor;
+  }
+  static lessThanOrEqual(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    return a.#minor <= b.#minor;
+  }
+  static greaterThanOrEqual(a, b) {
+    assertCurrenciesMatch(a.#currency, b.#currency, "compare");
+    return a.#minor >= b.#minor;
+  }
+  add(other) {
+    return Money.add(this, other);
+  }
+  subtract(other) {
+    return Money.subtract(this, other);
+  }
+  equals(other) {
+    return Money.equals(this, other);
+  }
+  compare(other) {
+    return Money.compare(this, other);
+  }
+  lessThan(other) {
+    return Money.lessThan(this, other);
+  }
+  greaterThan(other) {
+    return Money.greaterThan(this, other);
+  }
+  lessThanOrEqual(other) {
+    return Money.lessThanOrEqual(this, other);
+  }
+  greaterThanOrEqual(other) {
+    return Money.greaterThanOrEqual(this, other);
+  }
+  isZero() {
+    return this.#minor === 0n;
+  }
+  isPositive() {
+    return this.#minor > 0n;
+  }
+  isNegative() {
+    return this.#minor < 0n;
+  }
+  static allocate(money, parts) {
+    if (!Number.isInteger(parts) || parts < 1) {
+      throw new Error("Allocation count must be a positive integer");
+    }
+    if (!Number.isSafeInteger(parts)) {
+      throw new Error("Allocation count must be a safe integer");
+    }
+    const partsBigInt = BigInt(parts);
+    const base = money.#minor / partsBigInt;
+    const remainder = money.#minor % partsBigInt;
+    const absRemainder = remainder < 0n ? -remainder : remainder;
+    const sign = remainder < 0n ? -1n : 1n;
+    const result = [];
+    for (let i = 0n;i < partsBigInt; i++) {
+      const extra = i < absRemainder ? sign : 0n;
+      result.push(new Money(base + extra, money.#currency));
+    }
+    return result;
+  }
+  allocate(parts) {
+    return Money.allocate(this, parts);
+  }
+  static convert(money, targetCurrency, rate, options = {}) {
+    if (!Number.isFinite(rate) || rate <= 0) {
+      throw new Error("Exchange rate must be a finite positive number");
+    }
+    const { rounding = "round" } = options;
+    const scaledRate = parseDecimalStringToScaled(numberToDecimalString(rate));
+    const sourceScale = 10n ** BigInt(money.#currency.decimalPlaces);
+    const scaledSource = money.#minor * (INTERNAL_SCALE / sourceScale);
+    const rawProduct = scaledSource * scaledRate / INTERNAL_SCALE;
+    const resultMinor = roundScaledToMinor(rawProduct, targetCurrency.decimalPlaces, rounding);
+    assertSafeResult(resultMinor);
+    return new Money(resultMinor, targetCurrency);
+  }
+  convert(targetCurrency, rate, options) {
+    return Money.convert(this, targetCurrency, rate, options);
+  }
+  static roundTo(money, increment, mode = "round") {
+    if (!Number.isFinite(increment) || increment <= 0) {
+      throw new Error("Rounding increment must be a finite positive number");
+    }
+    const scaledIncrement = parseDecimalStringToScaled(numberToDecimalString(increment));
+    const targetScale = 10n ** BigInt(money.#currency.decimalPlaces);
+    const divisor = INTERNAL_SCALE / targetScale;
+    if (scaledIncrement % divisor !== 0n) {
+      throw new Error(`Rounding increment ${increment} cannot be exactly represented with ${money.#currency.decimalPlaces} decimal places`);
+    }
+    const incrementMinor = scaledIncrement / divisor;
+    if (incrementMinor === 0n) {
+      throw new Error("Rounding increment is too small for this currency's precision");
+    }
+    const minor = money.#minor;
+    const remainder = minor % incrementMinor;
+    if (remainder === 0n) {
+      return new Money(minor, money.#currency);
+    }
+    const base = minor - remainder;
+    let rounded;
+    switch (mode) {
+      case "trunc":
+        rounded = base;
+        break;
+      case "floor":
+        rounded = minor < 0n ? base - incrementMinor : base;
+        break;
+      case "ceil":
+        rounded = minor < 0n ? base : base + incrementMinor;
+        break;
+      default: {
+        const absRemainder = remainder < 0n ? -remainder : remainder;
+        const cmp = absRemainder * 2n - incrementMinor;
+        if (cmp < 0n) {
+          rounded = base;
+        } else if (cmp > 0n) {
+          rounded = minor < 0n ? base - incrementMinor : base + incrementMinor;
+        } else {
+          rounded = minor < 0n ? base : base + incrementMinor;
+        }
+        break;
+      }
+    }
+    assertSafeResult(rounded);
+    return new Money(rounded, money.#currency);
+  }
+  round(increment, mode) {
+    return Money.roundTo(this, increment, mode);
+  }
+  static percentOf(money, percent, options = {}) {
+    const { rounding = "round" } = options;
+    const scaledPercent = parseDecimalStringToScaled(numberToDecimalString(percent));
+    const scaledHundred = 100n * INTERNAL_SCALE;
+    const currencyScale = 10n ** BigInt(money.#currency.decimalPlaces);
+    const scaledMoney = money.#minor * (INTERNAL_SCALE / currencyScale);
+    const rawResult = scaledMoney * scaledPercent / scaledHundred;
+    const resultMinor = roundScaledToMinor(rawResult, money.#currency.decimalPlaces, rounding);
+    assertSafeResult(resultMinor);
+    return new Money(resultMinor, money.#currency);
+  }
+  static incrementByPercent(money, percent, options = {}) {
+    const { rounding = "round" } = options;
+    const scaledPercent = parseDecimalStringToScaled(numberToDecimalString(percent));
+    const scaledHundred = 100n * INTERNAL_SCALE;
+    const currencyScale = 10n ** BigInt(money.#currency.decimalPlaces);
+    const scaledMoney = money.#minor * (INTERNAL_SCALE / currencyScale);
+    const rawResult = scaledMoney * (scaledHundred + scaledPercent) / scaledHundred;
+    const resultMinor = roundScaledToMinor(rawResult, money.#currency.decimalPlaces, rounding);
+    assertSafeResult(resultMinor);
+    return new Money(resultMinor, money.#currency);
+  }
+  static decrementByPercent(money, percent, options = {}) {
+    const { rounding = "round" } = options;
+    const scaledPercent = parseDecimalStringToScaled(numberToDecimalString(percent));
+    const scaledHundred = 100n * INTERNAL_SCALE;
+    const currencyScale = 10n ** BigInt(money.#currency.decimalPlaces);
+    const scaledMoney = money.#minor * (INTERNAL_SCALE / currencyScale);
+    const rawResult = scaledMoney * (scaledHundred - scaledPercent) / scaledHundred;
+    const resultMinor = roundScaledToMinor(rawResult, money.#currency.decimalPlaces, rounding);
+    assertSafeResult(resultMinor);
+    return new Money(resultMinor, money.#currency);
+  }
+  percentOf(percent, options) {
+    return Money.percentOf(this, percent, options);
+  }
+  incrementByPercent(percent, options) {
+    return Money.incrementByPercent(this, percent, options);
+  }
+  decrementByPercent(percent, options) {
+    return Money.decrementByPercent(this, percent, options);
+  }
+  toJSON() {
+    return {
+      amount: this.toMinor(),
+      currency: this.#currency.code
+    };
+  }
+}
+export {
+  defineCurrency,
+  Money,
+  Currency
+};

package/dist/money.d.ts

@@ -0,0 +1,67 @@
+import type { CurrencyDefinition } from "./currency";
+export type RoundingMode = "floor" | "ceil" | "round" | "trunc";
+export interface FromNumberOptions {
+    rounding?: RoundingMode;
+    strict?: boolean;
+}
+export declare class Money {
+    #private;
+    private constructor();
+    get currency(): CurrencyDefinition;
+    static fromNumber(currency: CurrencyDefinition, value: number, options?: FromNumberOptions): Money;
+    static fromMinor(currency: CurrencyDefinition, minor: number): Money;
+    toNumber(): number;
+    toMinor(): number;
+    static add(a: Money, b: Money): Money;
+    static subtract(a: Money, b: Money): Money;
+    static sum(items: Money[]): Money;
+    static equals(a: Money, b: Money): boolean;
+    static compare(a: Money, b: Money): number;
+    static lessThan(a: Money, b: Money): boolean;
+    static greaterThan(a: Money, b: Money): boolean;
+    static lessThanOrEqual(a: Money, b: Money): boolean;
+    static greaterThanOrEqual(a: Money, b: Money): boolean;
+    add(other: Money): Money;
+    subtract(other: Money): Money;
+    equals(other: Money): boolean;
+    compare(other: Money): number;
+    lessThan(other: Money): boolean;
+    greaterThan(other: Money): boolean;
+    lessThanOrEqual(other: Money): boolean;
+    greaterThanOrEqual(other: Money): boolean;
+    isZero(): boolean;
+    isPositive(): boolean;
+    isNegative(): boolean;
+    static allocate(money: Money, parts: number): Money[];
+    allocate(parts: number): Money[];
+    static convert(money: Money, targetCurrency: CurrencyDefinition, rate: number, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    convert(targetCurrency: CurrencyDefinition, rate: number, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    static roundTo(money: Money, increment: number, mode?: RoundingMode): Money;
+    round(increment: number, mode?: RoundingMode): Money;
+    static percentOf(money: Money, percent: number, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    static incrementByPercent(money: Money, percent: number, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    static decrementByPercent(money: Money, percent: number, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    percentOf(percent: number, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    incrementByPercent(percent: number, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    decrementByPercent(percent: number, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    toJSON(): {
+        amount: number;
+        currency: string;
+    };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@storepass/money",
+	"version": "0.0.1-alpha.5",
+	"description": "Money primitive library",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"require": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.cjs"
+			}
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "bun run build:esm && bun run build:cjs && bun run build:types",
+		"build:esm": "bun build ./src/index.ts --outfile ./dist/index.js --format esm --target node",
+		"build:cjs": "bun build ./src/index.ts --outfile ./dist/index.cjs --format cjs --target node",
+		"build:types": "tsc -p tsconfig.build.json",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"check": "biome check --write .",
+		"format": "biome format --write .",
+		"lint": "biome lint .",
+		"lint:fix": "biome lint --write ."
+	},
+	"engines": {
+		"node": ">=16"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.3.11",
+		"@types/bun": "latest",
+		"typescript": "^5.9.3"
+	}
+}