rune-lab 0.3.1 → 0.4.1

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

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vite-plus/test";
+import { toSnapshot } from "dinero.js";
+import {
+  convertAmount,
+  convertMoney,
+  createMoney,
+  CURRENCY_MAP,
+  formatAmount,
+  fromMoneySnapshot,
+  registerCurrency,
+  scaledRate,
+  toAdyenMoney,
+  toMinorUnit,
+  toMoneySnapshot,
+  toPaypalMoney,
+  toSquareMoney,
+  toStripeMoney,
+} from "./money.ts";
+
+describe("Money Core Utilities", () => {
+  describe("safeAmount()", () => {
+    it("should return 0 for null and undefined", () => {
+      // testing internal private function via public wrapper createMoney
+      expect(toSnapshot(createMoney(null, "USD")).amount).toBe(0);
+      expect(toSnapshot(createMoney(undefined, "USD")).amount).toBe(0);
+    });
+
+    it("should return finite numbers unchanged", () => {
+      expect(toSnapshot(createMoney(1234, "USD")).amount).toBe(1234);
+    });
+
+    it("should return 0 for NaN and Infinity", () => {
+      expect(toSnapshot(createMoney(NaN, "USD")).amount).toBe(0);
+      expect(toSnapshot(createMoney(Infinity, "USD")).amount).toBe(0);
+    });
+
+    it("should handle bigints", () => {
+      expect(toSnapshot(createMoney(BigInt(5000), "USD")).amount).toBe(5000);
+    });
+
+    it("should handle objects with toString (SurrealDB Decimal)", () => {
+      const decimal = { toString: () => "123.45" };
+      expect(toSnapshot(createMoney(decimal, "USD")).amount).toBe(123); // Math.round(123.45) = 123
+    });
+
+    it("should handle numeric strings", () => {
+      expect(toSnapshot(createMoney("999", "USD")).amount).toBe(999);
+    });
+  });
+
+  describe("toMinorUnit()", () => {
+    it("should convert major to minor for MXN (exponent 2)", () => {
+      expect(toMinorUnit(12900000, "MXN")).toBe(1290000000);
+    });
+
+    it("should convert major to minor for JPY (exponent 0)", () => {
+      expect(toMinorUnit(5000, "JPY")).toBe(5000);
+    });
+
+    it("should throw for unknown currency", () => {
+      expect(() => toMinorUnit(100, "UNKNOWN")).toThrow();
+    });
+  });
+
+  describe("registerCurrency()", () => {
+    it("should allow registering a new currency and creating money with it", () => {
+      const KWD = { code: "KWD", base: 10, exponent: 3 };
+      registerCurrency("KWD", KWD);
+
+      expect(CURRENCY_MAP["KWD"]).toEqual(KWD);
+
+      const money = createMoney(1000, "KWD");
+      expect(toSnapshot(money).currency.code).toBe("KWD");
+    });
+  });
+
+  describe("formatAmount()", () => {
+    it("should format minor units correctly for USD", () => {
+      // $1.50
+      expect(formatAmount(150, "USD", "en-US")).toMatch(/\$1\.50/);
+    });
+
+    it("should format minor units correctly for MXN", () => {
+      // MX$1.50 or $1.50 depending on locale
+      expect(formatAmount(150, "MXN", "es-MX")).toMatch(/\$1\.50/);
+    });
+  });
+
+  describe("Exchange Rates & Conversion", () => {
+    describe("scaledRate()", () => {
+      it("should convert float to ScaledRate with default precision", () => {
+        expect(scaledRate(17.23)).toEqual({ amount: 172300, scale: 4 });
+      });
+
+      it("should use custom precision", () => {
+        expect(scaledRate(0.89, 2)).toEqual({ amount: 89, scale: 2 });
+      });
+
+      it("should handle integer rates", () => {
+        expect(scaledRate(1199, 0)).toEqual({ amount: 1199, scale: 0 });
+      });
+    });
+
+    describe("convertMoney()", () => {
+      it("should convert USD to MXN", () => {
+        const usd = createMoney(100, "USD");
+        const rates = { MXN: scaledRate(20) };
+        const mxn = convertMoney(usd, "MXN", rates);
+        const snapshot = toSnapshot(mxn);
+        expect(snapshot.amount).toBe(20000000);
+        expect(snapshot.scale).toBe(6);
+        expect(snapshot.currency.code).toBe("MXN");
+      });
+
+      it("should throw for unknown target currency", () => {
+        const usd = createMoney(100, "USD");
+        expect(() => convertMoney(usd, "UNKNOWN", {})).toThrow();
+      });
+
+      it("should throw for missing rate", () => {
+        const usd = createMoney(100, "USD");
+        expect(() => convertMoney(usd, "MXN", {})).toThrow();
+      });
+    });
+
+    describe("convertAmount()", () => {
+      it("should return same amount if codes match", () => {
+        expect(convertAmount(100, "USD", "USD", {})).toBe(100);
+      });
+
+      it("should convert minor units correctly", () => {
+        const rates = { MXN: scaledRate(20) };
+        expect(convertAmount(100, "USD", "MXN", rates)).toBe(2000);
+      });
+    });
+  });
+
+  describe("Payment Provider Helpers", () => {
+    it("toStripeMoney should return lowercase currency and amount", () => {
+      const money = createMoney(150, "USD");
+      expect(toStripeMoney(money)).toEqual({ amount: 150, currency: "usd" });
+    });
+
+    it("toPaypalMoney should return decimal string and uppercase code", () => {
+      const money = createMoney(150, "USD");
+      expect(toPaypalMoney(money)).toEqual({
+        value: "1.50",
+        currency_code: "USD",
+      });
+    });
+
+    it("toAdyenMoney should return amount and uppercase code", () => {
+      const money = createMoney(150, "USD");
+      expect(toAdyenMoney(money)).toEqual({ value: 150, currency: "USD" });
+    });
+
+    it("toSquareMoney should return bigint amount and code", () => {
+      const money = createMoney(150, "USD");
+      expect(toSquareMoney(money)).toEqual({
+        amount: BigInt(150),
+        currency: "USD",
+      });
+    });
+  });
+
+  describe("Snapshots", () => {
+    it("should round-trip to/from money snapshot", () => {
+      const money = createMoney(123, "MXN");
+      const snapshot = toMoneySnapshot(money);
+      expect(snapshot).toEqual({ amount: 123, currency: "MXN", scale: 2 });
+
+      const restored = fromMoneySnapshot(snapshot);
+      expect(toSnapshot(restored)).toEqual(toSnapshot(money));
+    });
+
+    it("should preserve elevated scale", () => {
+      const _money = createMoney(123, "USD");
+      const snapshot = { amount: 12345, currency: "USD", scale: 4 };
+      const restored = fromMoneySnapshot(snapshot);
+      expect(toSnapshot(restored).scale).toBe(4);
+    });
+  });
+});

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"];
+    });
+  });
+});