rune-lab 0.4.0 → 0.4.1

package/src/runes/plugins/money/src/money.ts

@@ -0,0 +1,382 @@
+// sdk/core/src/money/money.ts
+// Framework-agnostic money utilities using Dinero.js v2
+// Consumers should never import Dinero directly — these helpers encapsulate it.
+
+import {
+  add as dineroAdd,
+  AED,
+  BRL,
+  CAD,
+  CNY,
+  convert as dineroConvert,
+  type Dinero,
+  dinero,
+  type DineroCurrency,
+  type DineroSnapshot,
+  EUR,
+  GBP,
+  INR,
+  JPY,
+  KRW,
+  multiply as dineroMultiply,
+  MXN,
+  subtract as dineroSubtract,
+  toDecimal,
+  // ISO 4217 currency definitions
+  toSnapshot,
+  transformScale as dineroTransformScale,
+  USD,
+} from "dinero.js";
+
+/**
+ * Map of ISO 4217 currency codes to Dinero currency objects
+ */
+export const CURRENCY_MAP: Record<string, DineroCurrency<number>> = {
+  USD,
+  EUR,
+  MXN,
+  JPY,
+  KRW,
+  CNY,
+  AED,
+  GBP,
+  CAD,
+  BRL,
+  INR,
+};
+
+/**
+ * Derived type of all built-in ISO 4217 currency codes.
+ * Enables IDE autocomplete while allowing any string for dynamic currencies.
+ */
+export type ISO4217Code = keyof typeof CURRENCY_MAP;
+
+/**
+ * Scaled integer rate for Dinero.js conversion.
+ * Avoids floating-point errors by using integer amounts with a scale.
+ */
+export type ScaledRate = { amount: number; scale: number };
+
+/**
+ * Map of currency codes to their exchange rates relative to a base currency.
+ * Rates can be plain numbers (integers) or ScaledRate objects.
+ */
+export type RateMap = Record<string, ScaledRate | number>;
+
+/**
+ * Converts a human-readable float rate (e.g., 17.23) into a ScaledRate.
+ * Defaults to 4 decimal places of precision if not specified.
+ */
+export function scaledRate(float: number, precision: number = 4): ScaledRate {
+  const factor = Math.pow(10, precision);
+  return {
+    amount: Math.round(float * factor),
+    scale: precision,
+  };
+}
+
+/**
+ * Register a new currency in CURRENCY_MAP atomically.
+ * Ensures the core registry and any store-level registries stay in sync.
+ */
+export function registerCurrency(
+  code: string,
+  currency: DineroCurrency<number>,
+): void {
+  CURRENCY_MAP[code] = currency;
+}
+
+/**
+ * Normalizes an unknown input into a valid finite number.
+ * Handles null, undefined, bigints, and SurrealDB Decimal objects via toString().
+ */
+function toNumber(amount: unknown): number {
+  if (amount === null || amount === undefined) return 0;
+  if (typeof amount === "number") return Number.isFinite(amount) ? amount : 0;
+  if (typeof amount === "bigint") return Number(amount);
+
+  // Handle SurrealDB Decimal (which has a toString method) or other objects
+  if (typeof amount === "object") {
+    try {
+      // SurrealDB Decimal.toString() returns a numeric string
+      const str = String(amount);
+      const parsed = parseFloat(str);
+      return Number.isFinite(parsed) ? parsed : 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  const coerced = Number(amount);
+  return Number.isFinite(coerced) ? coerced : 0;
+}
+
+/**
+ * Normalizes an unknown input into a valid integer for Dinero.js.
+ * Exported so consumers can apply the same defensive coercion.
+ */
+export function safeAmount(amount: unknown): number {
+  return Math.round(toNumber(amount));
+}
+
+/**
+ * Converts a major-unit amount (e.g., pesos) to a minor-unit integer (e.g., centavos).
+ * Uses the currency's exponent from CURRENCY_MAP.
+ */
+export function toMinorUnit(
+  amount: unknown,
+  currencyCode: ISO4217Code | string,
+): number {
+  const currency = CURRENCY_MAP[currencyCode];
+  if (!currency) {
+    throw new Error(
+      `Unknown currency code: ${currencyCode}. Register it first via registerCurrency().`,
+    );
+  }
+  const base = Array.isArray(currency.base) ? currency.base[0] : currency.base;
+  const factor = Math.pow(Number(base), Number(currency.exponent));
+  return Math.round(toNumber(amount) * factor);
+}
+
+/**
+ * Create a Dinero monetary value from an amount.
+ * @param amount - Amount (normalized internally via safeAmount)
+ * @param currencyCode - ISO 4217 currency code (e.g., "USD")
+ */
+export function createMoney(
+  amount: unknown,
+  currencyCode: ISO4217Code | string,
+): Dinero<number> {
+  const currency = CURRENCY_MAP[currencyCode];
+  if (!currency) {
+    throw new Error(
+      `Unknown currency code: ${currencyCode}. Register it first via registerCurrency().`,
+    );
+  }
+  return dinero({ amount: safeAmount(amount), currency });
+}
+
+/**
+ * Format a Dinero value as a locale-aware string
+ * @param money - Dinero monetary value
+ * @param locale - BCP 47 locale string (e.g., "en-US", "es-MX")
+ * @param currencyCode - ISO 4217 code for Intl.NumberFormat (e.g., "USD")
+ */
+export function formatMoney(
+  money: Dinero<number>,
+  locale: string = "en-US",
+  currencyCode?: string,
+): string {
+  return toDecimal(money, ({ value, currency }) => {
+    const code = currencyCode ??
+      Object.entries(CURRENCY_MAP).find(([, c]) => c.code === currency.code)
+        ?.[0] ??
+      currency.code;
+
+    return new Intl.NumberFormat(locale, {
+      style: "currency",
+      currency: code,
+      minimumFractionDigits: currency.exponent,
+      maximumFractionDigits: currency.exponent,
+    }).format(Number(value));
+  });
+}
+
+/**
+ * Format a raw amount as a locale-aware currency string.
+ * Convenience wrapper around createMoney + formatMoney.
+ */
+export function formatAmount(
+  amount: unknown,
+  currencyCode: ISO4217Code | string,
+  locale: string = "en-US",
+): string {
+  const money = createMoney(amount, currencyCode);
+  return formatMoney(money, locale, currencyCode);
+}
+
+/**
+ * Add two monetary values (must be same currency)
+ */
+export function addMoney(a: Dinero<number>, b: Dinero<number>): Dinero<number> {
+  return dineroAdd(a, b);
+}
+
+/**
+ * Subtract two monetary values (must be same currency)
+ */
+export function subtractMoney(
+  a: Dinero<number>,
+  b: Dinero<number>,
+): Dinero<number> {
+  return dineroSubtract(a, b);
+}
+
+/**
+ * Multiply a monetary value by a factor
+ */
+export function multiplyMoney(
+  money: Dinero<number>,
+  factor: number,
+): Dinero<number> {
+  return dineroMultiply(money, factor);
+}
+
+/**
+ * Converts a Dinero object to another currency.
+ * Both currencies must share the same base (base 10 for all standard ISO currencies).
+ */
+export function convertMoney(
+  money: Dinero<number>,
+  toCurrencyCode: string,
+  rates: RateMap,
+): Dinero<number> {
+  const targetCurrency = CURRENCY_MAP[toCurrencyCode];
+  if (!targetCurrency) {
+    throw new Error(
+      `Unknown target currency: ${toCurrencyCode}. Register it first via registerCurrency().`,
+    );
+  }
+
+  const rate = rates[toCurrencyCode];
+  if (rate === undefined) {
+    throw new Error(`Missing exchange rate for currency: ${toCurrencyCode}`);
+  }
+
+  try {
+    return dineroConvert(money, targetCurrency, { [toCurrencyCode]: rate });
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("base")) {
+      throw new Error(
+        `Cannot convert between currencies with different bases. Ensure both are base 10.`,
+      );
+    }
+    throw err;
+  }
+}
+
+/**
+ * Converts a raw minor-unit amount between currencies.
+ * Returns the original amount if from and to currencies are the same.
+ */
+export function convertAmount(
+  amount: number,
+  fromCode: string,
+  toCode: string,
+  rates: RateMap,
+): number {
+  if (fromCode === toCode) return amount;
+  const targetCurrency = CURRENCY_MAP[toCode];
+  if (!targetCurrency) {
+    throw new Error(`Unknown target currency: ${toCode}`);
+  }
+
+  const sourceMoney = createMoney(amount, fromCode);
+  const convertedMoney = convertMoney(sourceMoney, toCode, rates);
+
+  // Normalize back to the target currency's standard exponent
+  const targetMoney = dineroTransformScale(
+    convertedMoney,
+    targetCurrency.exponent,
+  );
+  const snapshot = toSnapshot(targetMoney);
+
+  return snapshot.amount;
+}
+
+/**
+ * Converts Dinero object to a Stripe-compatible payload.
+ */
+export function toStripeMoney(money: Dinero<number>): {
+  amount: number;
+  currency: string;
+} {
+  const snapshot = toSnapshot(money);
+  return {
+    amount: snapshot.amount,
+    currency: snapshot.currency.code.toLowerCase(),
+  };
+}
+
+/**
+ * Converts Dinero object to a PayPal-compatible payload.
+ */
+export function toPaypalMoney(money: Dinero<number>): {
+  value: string;
+  currency_code: string;
+} {
+  const value = toDecimal(money);
+  const snapshot = toSnapshot(money);
+  return {
+    value,
+    currency_code: snapshot.currency.code,
+  };
+}
+
+/**
+ * Converts Dinero object to an Adyen-compatible payload.
+ */
+export function toAdyenMoney(money: Dinero<number>): {
+  value: number;
+  currency: string;
+} {
+  const snapshot = toSnapshot(money);
+  return {
+    value: snapshot.amount,
+    currency: snapshot.currency.code.toUpperCase(),
+  };
+}
+
+/**
+ * Converts Dinero object to a Square-compatible payload (uses BigInt).
+ */
+export function toSquareMoney(money: Dinero<number>): {
+  amount: bigint;
+  currency: string;
+} {
+  const snapshot = toSnapshot(money);
+  return {
+    amount: BigInt(snapshot.amount),
+    currency: snapshot.currency.code,
+  };
+}
+
+/**
+ * Serializes a Dinero object into a plain object snapshot.
+ */
+export function toMoneySnapshot(money: Dinero<number>): {
+  amount: number;
+  currency: string;
+  scale: number;
+} {
+  const snapshot = toSnapshot(money);
+  return {
+    amount: snapshot.amount,
+    currency: snapshot.currency.code,
+    scale: snapshot.scale,
+  };
+}
+
+/**
+ * Restores a Dinero object from a snapshot.
+ */
+export function fromMoneySnapshot(snapshot: {
+  amount: number;
+  currency: string;
+  scale?: number;
+}): Dinero<number> {
+  const currency = CURRENCY_MAP[snapshot.currency];
+  if (!currency) {
+    throw new Error(
+      `Unknown currency: ${snapshot.currency}. Register it first.`,
+    );
+  }
+  return dinero({
+    amount: snapshot.amount,
+    currency,
+    scale: snapshot.scale ?? currency.exponent,
+  });
+}
+
+// Re-export types
+export type { Dinero, DineroCurrency, DineroSnapshot };

package/src/runes/plugins/money/src/strategies.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "vite-plus/test";
+import {
+  CONVERSION_STRATEGIES,
+  directConversion,
+  inverseConversion,
+  resolveRate,
+  triangularConversion,
+} from "./strategies.ts";
+
+describe("ConversionStrategies", () => {
+  describe("resolveRate", () => {
+    it("should pass through plain numbers", () => {
+      expect(resolveRate(20)).toBe(20);
+    });
+
+    it("should resolve ScaledRate to float", () => {
+      expect(resolveRate({ amount: 172300, scale: 4 })).toBeCloseTo(17.23);
+    });
+
+    it("should handle zero scale", () => {
+      expect(resolveRate({ amount: 1199, scale: 0 })).toBe(1199);
+    });
+  });
+
+  describe("directConversion", () => {
+    it("should multiply amount by rate", () => {
+      // 100 USD cents * 20 = 2000 MXN centavos
+      expect(directConversion(100, 20)).toBe(2000);
+    });
+
+    it("should handle fractional rates", () => {
+      // 100 * 0.91 = 91
+      expect(directConversion(100, 0.91)).toBe(91);
+    });
+
+    it("should handle zero amount", () => {
+      expect(directConversion(0, 20)).toBe(0);
+    });
+
+    it("should handle negative amounts", () => {
+      expect(directConversion(-100, 20)).toBe(-2000);
+    });
+
+    it("should handle large numbers", () => {
+      expect(directConversion(1_000_000, 20)).toBe(20_000_000);
+    });
+
+    it("should round to nearest integer", () => {
+      // 100 * 17.23 = 1723
+      expect(directConversion(100, 17.23)).toBe(1723);
+    });
+  });
+
+  describe("inverseConversion", () => {
+    it("should divide amount by rate", () => {
+      // 2000 MXN / 20 = 100 USD
+      expect(inverseConversion(2000, 20)).toBe(100);
+    });
+
+    it("should handle fractional results (rounded)", () => {
+      // 100 / 3 ≈ 33.33 → 33
+      expect(inverseConversion(100, 3)).toBe(33);
+    });
+
+    it("should throw on zero rate", () => {
+      expect(() => inverseConversion(100, 0)).toThrow("rate of zero");
+    });
+
+    it("should handle negative amounts", () => {
+      expect(inverseConversion(-2000, 20)).toBe(-100);
+    });
+
+    it("should handle zero amount", () => {
+      expect(inverseConversion(0, 20)).toBe(0);
+    });
+  });
+
+  describe("triangularConversion", () => {
+    it("should convert through base: MXN → USD → EUR", () => {
+      // 2000 MXN, 1 USD = 20 MXN, 1 USD = 0.91 EUR
+      // 2000 / 20 = 100 USD → 100 * 0.91 = 91 EUR
+      expect(triangularConversion(2000, 20, 0.91)).toBe(91);
+    });
+
+    it("should handle zero amount", () => {
+      expect(triangularConversion(0, 20, 0.91)).toBe(0);
+    });
+
+    it("should throw when source-to-base rate is zero", () => {
+      expect(() => triangularConversion(100, 0, 0.91)).toThrow(
+        "source-to-base rate is zero",
+      );
+    });
+
+    it("should handle large cross-rates", () => {
+      // 1000 BRL, 1 USD = 5 BRL, 1 USD = 150 JPY
+      // 1000 / 5 = 200 USD → 200 * 150 = 30000 JPY
+      expect(triangularConversion(1000, 5, 150)).toBe(30000);
+    });
+
+    it("should handle negative amounts", () => {
+      expect(triangularConversion(-2000, 20, 0.91)).toBe(-91);
+    });
+  });
+
+  describe("CONVERSION_STRATEGIES registry", () => {
+    it("should have direct, inverse, and triangular strategies", () => {
+      expect(CONVERSION_STRATEGIES).toHaveProperty("direct");
+      expect(CONVERSION_STRATEGIES).toHaveProperty("inverse");
+      expect(CONVERSION_STRATEGIES).toHaveProperty("triangular");
+    });
+
+    it("direct strategy matches standalone function", () => {
+      expect(CONVERSION_STRATEGIES["direct"](100, 20)).toBe(
+        directConversion(100, 20),
+      );
+    });
+
+    it("inverse strategy matches standalone function", () => {
+      expect(CONVERSION_STRATEGIES["inverse"](2000, 20)).toBe(
+        inverseConversion(2000, 20),
+      );
+    });
+
+    it("triangular strategy matches standalone function", () => {
+      expect(CONVERSION_STRATEGIES["triangular"](2000, 20, 0.91)).toBe(
+        triangularConversion(2000, 20, 0.91),
+      );
+    });
+
+    it("should be extensible", () => {
+      CONVERSION_STRATEGIES["custom"] = (
+        amount: number,
+        rate: number,
+      ): number => Math.round(amount * rate * 1.01); // 1% fee
+
+      expect(CONVERSION_STRATEGIES["custom"](100, 20)).toBe(2020);
+
+      // Clean up
+      delete CONVERSION_STRATEGIES["custom"];
+    });
+  });
+});

package/{dist/core/exchange-rate/strategies.js → src/runes/plugins/money/src/strategies.ts}

@@ -1,15 +1,27 @@
 // sdk/core/src/exchange-rate/strategies.ts
 // Pure conversion strategy functions — no store or context dependencies.
 // Extracted from ExchangeRateStore to enable independent testing and extensibility.
+
+import type { ScaledRate } from "./money.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+/**
+ * A pure function that converts a minor-unit amount using a rate.
+ * All strategy functions must be deterministic and side-effect-free.
+ */
+export type ConversionFn = (amount: number, ...rates: number[]) => number;
+
 /**
  * Resolves a ScaledRate or plain number into a float rate value.
  */
-export function resolveRate(rate) {
-    if (typeof rate === "number")
-        return rate;
-    return rate.amount / Math.pow(10, rate.scale);
+export function resolveRate(rate: ScaledRate | number): number {
+  if (typeof rate === "number") return rate;
+  return rate.amount / Math.pow(10, rate.scale);
 }
+
 // ── Strategy Functions ─────────────────────────────────────────────────────────
+
 /**
  * Direct conversion: base currency → target currency.
  * Multiplies the amount by the rate.
@@ -18,9 +30,10 @@ export function resolveRate(rate) {
  * @param rate - Conversion rate (1 source = `rate` target)
  * @returns Minor-unit amount in the target currency
  */
-export function directConversion(amount, rate) {
-    return Math.round(amount * rate);
+export function directConversion(amount: number, rate: number): number {
+  return Math.round(amount * rate);
 }
+
 /**
  * Inverse conversion: target currency → base currency.
  * Divides the amount by the rate.
@@ -29,12 +42,13 @@ export function directConversion(amount, rate) {
  * @param rate - Conversion rate of source relative to base (1 base = `rate` source)
  * @returns Minor-unit amount in the base currency
  */
-export function inverseConversion(amount, rate) {
-    if (rate === 0) {
-        throw new Error("Cannot perform inverse conversion with a rate of zero.");
-    }
-    return Math.round(amount / rate);
+export function inverseConversion(amount: number, rate: number): number {
+  if (rate === 0) {
+    throw new Error("Cannot perform inverse conversion with a rate of zero.");
+  }
+  return Math.round(amount / rate);
 }
+
 /**
  * Triangular conversion: source → base → target (cross-rate).
  * First divides by the source-to-base rate, then multiplies by the base-to-target rate.
@@ -44,14 +58,22 @@ export function inverseConversion(amount, rate) {
  * @param rateBaseToTarget - Rate of base to target (1 base = `rate` target)
  * @returns Minor-unit amount in the target currency
  */
-export function triangularConversion(amount, rateSourceToBase, rateBaseToTarget) {
-    if (rateSourceToBase === 0) {
-        throw new Error("Cannot perform triangular conversion: source-to-base rate is zero.");
-    }
-    const amountInBase = amount / rateSourceToBase;
-    return Math.round(amountInBase * rateBaseToTarget);
+export function triangularConversion(
+  amount: number,
+  rateSourceToBase: number,
+  rateBaseToTarget: number,
+): number {
+  if (rateSourceToBase === 0) {
+    throw new Error(
+      "Cannot perform triangular conversion: source-to-base rate is zero.",
+    );
+  }
+  const amountInBase = amount / rateSourceToBase;
+  return Math.round(amountInBase * rateBaseToTarget);
 }
+
 // ── Strategy Registry ──────────────────────────────────────────────────────────
+
 /**
  * Named map of conversion strategies.
  * Consumer code and the ExchangeRateStore can select a strategy by name.
@@ -64,9 +86,10 @@ export function triangularConversion(amount, rateSourceToBase, rateBaseToTarget)
  * };
  * ```
  */
-export const CONVERSION_STRATEGIES = {
-    direct: directConversion,
-    inverse: inverseConversion,
-    // triangularConversion takes 2 rates — wrapped for the registry signature
-    triangular: (amount, ...rates) => triangularConversion(amount, rates[0], rates[1]),
+export const CONVERSION_STRATEGIES: Record<string, ConversionFn> = {
+  direct: directConversion,
+  inverse: inverseConversion,
+  // triangularConversion takes 2 rates — wrapped for the registry signature
+  triangular: (amount: number, ...rates: number[]) =>
+    triangularConversion(amount, rates[0], rates[1]),
 };

package/src/runes/plugins/money/src/types.ts

@@ -0,0 +1,27 @@
+export {
+  addMoney,
+  convertAmount,
+  convertMoney,
+  createMoney,
+  CURRENCY_MAP,
+  type Dinero,
+  type DineroCurrency,
+  type DineroSnapshot,
+  formatAmount,
+  formatMoney,
+  fromMoneySnapshot,
+  type ISO4217Code,
+  multiplyMoney,
+  type RateMap,
+  registerCurrency,
+  safeAmount,
+  type ScaledRate,
+  scaledRate,
+  subtractMoney,
+  toAdyenMoney,
+  toMinorUnit,
+  toMoneySnapshot,
+  toPaypalMoney,
+  toSquareMoney,
+  toStripeMoney,
+} from "./money.ts";