rune-lab 0.3.1 → 0.4.1

package/src/runes/plugins/money/src/exchange-rate.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+import { ExchangeRateStore } from "./exchange-rate.svelte.ts";
+import { currencyStore, setExchangeRateStore } from "./currency.svelte.ts";
+import { inMemoryDriver, RUNE_LAB_CONTEXT } from "@rune-lab/kernel";
+import { languageStore } from "../../../layout/src/language.svelte.ts";
+
+// Mock useMoney since it uses getContext and other stores
+vi.mock("./useMoney.ts", () => ({
+  useMoney: () => ({
+    format: (amount: number, code?: string, _unit?: unknown) =>
+      `${amount} ${code ?? "USD"}`,
+  }),
+}));
+
+describe("ExchangeRateStore", () => {
+  it("should initialize with default base", () => {
+    const store = new ExchangeRateStore();
+    expect(store.baseCurrency).toBe("USD");
+    expect(store.hasRates).toBe(false);
+  });
+
+  it("should set and retrieve rates", () => {
+    const store = new ExchangeRateStore();
+    store.setRates("USD", { MXN: 17.23, EUR: 0.91 });
+
+    expect(store.hasRates).toBe(true);
+    expect(store.baseCurrency).toBe("USD");
+
+    const rateToMxn = store.getRate("USD", "MXN");
+    expect(rateToMxn).toEqual({ amount: 17230000, scale: 6 });
+  });
+
+  it("should handle inverse rates", () => {
+    const store = new ExchangeRateStore();
+    store.setRates("USD", { MXN: 20 });
+
+    const rateToBase = store.getRate("MXN", "USD");
+    expect(rateToBase).toEqual({ amount: 5000000, scale: 8 });
+  });
+
+  it("should handle triangulation (cross-rates)", () => {
+    const store = new ExchangeRateStore();
+    store.setRates("USD", { MXN: 20, EUR: 0.5 });
+
+    const rateMxnToEur = store.getRate("MXN", "EUR");
+    expect(rateMxnToEur).toEqual({ amount: 2500000, scale: 8 });
+  });
+});
+
+describe("CurrencyStore Integration", () => {
+  it("should convert amount when ExchangeRateStore is wired", () => {
+    const exchangeRateStore = new ExchangeRateStore();
+    exchangeRateStore.setRates("USD", { MXN: 20 });
+
+    setExchangeRateStore(exchangeRateStore);
+
+    expect(currencyStore.canConvert).toBe(true);
+
+    const converted = currencyStore.convertAmount(10000, "USD", "MXN");
+    expect(converted).toBe(200000);
+  });
+
+  it("should return original amount if no rates available", () => {
+    const exchangeRateStore = new ExchangeRateStore();
+    setExchangeRateStore(exchangeRateStore);
+
+    expect(currencyStore.canConvert).toBe(false);
+
+    const converted = currencyStore.convertAmount(10000, "USD", "MXN");
+    expect(converted).toBe(10000);
+  });
+});
+
+describe("useMoneyFilter", () => {
+  // Simple test for logic, skipping full component mount for brevity
+  it("matches() should work with conversion", () => {
+    const exchangeRateStore = new ExchangeRateStore();
+    exchangeRateStore.setRates("USD", { MXN: 20 });
+
+    setExchangeRateStore(exchangeRateStore);
+
+    // Manual mock of context for the composable
+    // In a real test we'd use render() from @testing-library/svelte
+    const mockContext = new Map();
+    mockContext.set(RUNE_LAB_CONTEXT.currency, currencyStore);
+    mockContext.set(RUNE_LAB_CONTEXT.exchangeRate, exchangeRateStore);
+    mockContext.set(RUNE_LAB_CONTEXT.language, languageStore);
+
+    // We can't easily call useMoneyFilter outside component without more setup
+    // but we can verify the matches logic in CurrencyStore
+    const amountInMxn = 1000000; // 10,000 MXN
+    const amountInUsd = currencyStore.convertAmount(amountInMxn, "MXN", "USD");
+    expect(amountInUsd).toBe(50000); // 500 USD
+  });
+});

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

@@ -0,0 +1,79 @@
+import { defineRune, RUNE_LAB_CONTEXT } from "@rune-lab/kernel";
+import type { PersistenceDriver, RunePlugin } from "@rune-lab/kernel";
+import {
+  type Currency,
+  currencyStore,
+  setExchangeRateStore,
+} from "./currency.svelte.ts";
+import { createExchangeRateStore } from "./exchange-rate.svelte.ts";
+import type { ExchangeRateStore } from "./exchange-rate.svelte.ts";
+
+export * from "./currency.svelte.ts";
+export * from "./exchange-rate.svelte.ts";
+export * from "./types.ts";
+export * from "./money.ts";
+export * from "./strategies.ts";
+export * from "./money-primitive.ts";
+export * from "./useMoney.ts";
+export * from "./useMoneyFilter.ts";
+
+interface MoneyConfig {
+  exchangeRates?: {
+    base: string;
+    rates: Record<string, number>;
+  };
+  currencies?: Currency[];
+  defaultCurrency?: string;
+}
+
+/**
+ * Money Plugin — provides currency management and exchange rate conversion.
+ */
+export const MoneyPlugin: RunePlugin = defineRune({
+  id: "rune-lab.money",
+  stores: [
+    {
+      id: "exchangeRate",
+      contextKey: RUNE_LAB_CONTEXT.exchangeRate,
+      factory: (config: unknown) => {
+        const store = createExchangeRateStore();
+        const c = config as MoneyConfig;
+        if (c?.exchangeRates) {
+          store.setRates(c.exchangeRates.base, c.exchangeRates.rates);
+        }
+        return store;
+      },
+      noPersistence: true,
+    },
+    {
+      id: "currency",
+      contextKey: RUNE_LAB_CONTEXT.currency,
+      factory: (
+        config: unknown,
+        _driver: PersistenceDriver,
+        stores: Map<string, unknown>,
+      ) => {
+        const c = config as MoneyConfig;
+        setExchangeRateStore(stores.get("exchangeRate") as ExchangeRateStore);
+
+        if (c?.currencies) {
+          for (const cur of c.currencies) {
+            currencyStore.addCurrency(cur);
+          }
+        }
+
+        if (
+          c?.defaultCurrency &&
+          !(currencyStore as unknown as { current: unknown }).current
+        ) {
+          if (currencyStore.get(c.defaultCurrency as never)) {
+            currencyStore.set(c.defaultCurrency as never);
+          }
+        }
+
+        return currencyStore;
+      },
+      dependsOn: ["exchangeRate"],
+    },
+  ],
+});

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

@@ -0,0 +1,217 @@
+import { describe, expect, it } from "vite-plus/test";
+import { MoneyPrimitive } from "./money-primitive.ts";
+import { registerCurrency } from "./money.ts";
+
+describe("MoneyPrimitive", () => {
+  describe("Construction", () => {
+    it("should create from minor units", () => {
+      const money = MoneyPrimitive.fromMinor(1299, "USD");
+      expect(money.amount).toBe(1299);
+      expect(money.currencyCode).toBe("USD");
+      expect(money.scale).toBe(2);
+    });
+
+    it("should create from major units", () => {
+      const money = MoneyPrimitive.fromMajor(12.99, "USD");
+      expect(money.amount).toBe(1299);
+      expect(money.currencyCode).toBe("USD");
+      expect(money.scale).toBe(2);
+    });
+
+    it("should round fractional minor units", () => {
+      const money = MoneyPrimitive.fromMajor(12.999, "USD");
+      expect(money.amount).toBe(1300); // rounded
+    });
+
+    it("should throw for unknown currency", () => {
+      expect(() => MoneyPrimitive.fromMinor(100, "UNKNOWN")).toThrow(
+        "Unknown currency code",
+      );
+    });
+  });
+
+  describe("JPY (exponent 0)", () => {
+    it("should handle zero-exponent currencies", () => {
+      const yen = MoneyPrimitive.fromMinor(5000, "JPY");
+      expect(yen.minor).toBe(5000);
+      expect(yen.major).toBe(5000); // no decimal shift for JPY
+      expect(yen.scale).toBe(0);
+    });
+
+    it("should create from major with no decimal shift", () => {
+      const yen = MoneyPrimitive.fromMajor(5000, "JPY");
+      expect(yen.amount).toBe(5000);
+    });
+  });
+
+  describe("BHD (exponent 3)", () => {
+    it("should handle 3-exponent currencies", () => {
+      const BHD = { code: "BHD", base: 10, exponent: 3 };
+      registerCurrency("BHD", BHD);
+
+      const dinar = MoneyPrimitive.fromMajor(1.234, "BHD");
+      expect(dinar.amount).toBe(1234);
+      expect(dinar.major).toBe(1.234);
+      expect(dinar.scale).toBe(3);
+    });
+  });
+
+  describe("Getters", () => {
+    it(".minor returns the raw amount", () => {
+      const money = MoneyPrimitive.fromMinor(1500, "USD");
+      expect(money.minor).toBe(1500);
+    });
+
+    it(".major returns the human-readable float", () => {
+      const money = MoneyPrimitive.fromMinor(1500, "USD");
+      expect(money.major).toBe(15.0);
+    });
+
+    it(".major handles MXN (exponent 2)", () => {
+      const money = MoneyPrimitive.fromMinor(25050, "MXN");
+      expect(money.major).toBe(250.5);
+    });
+  });
+
+  describe("Formatting", () => {
+    it("should format USD in en-US", () => {
+      const money = MoneyPrimitive.fromMinor(1299, "USD");
+      expect(money.format("en-US")).toMatch(/\$12\.99/);
+    });
+
+    it("should format MXN in es-MX", () => {
+      const money = MoneyPrimitive.fromMinor(25050, "MXN");
+      expect(money.format("es-MX")).toMatch(/\$250\.50/);
+    });
+
+    it("should format JPY with no decimals", () => {
+      const money = MoneyPrimitive.fromMinor(5000, "JPY");
+      const formatted = money.format("ja-JP");
+      expect(formatted).toMatch(/5,000/);
+    });
+  });
+
+  describe("Arithmetic (immutability)", () => {
+    it("add returns a new instance", () => {
+      const a = MoneyPrimitive.fromMinor(1000, "USD");
+      const b = MoneyPrimitive.fromMinor(500, "USD");
+      const result = a.add(b);
+
+      expect(result.amount).toBe(1500);
+      expect(result).not.toBe(a); // new instance
+      expect(a.amount).toBe(1000); // original unchanged
+    });
+
+    it("subtract returns a new instance", () => {
+      const a = MoneyPrimitive.fromMinor(1000, "USD");
+      const b = MoneyPrimitive.fromMinor(300, "USD");
+      const result = a.subtract(b);
+
+      expect(result.amount).toBe(700);
+      expect(a.amount).toBe(1000);
+    });
+
+    it("multiply returns a new instance", () => {
+      const money = MoneyPrimitive.fromMinor(1000, "USD");
+      const result = money.multiply(2.5);
+
+      expect(result.amount).toBe(2500);
+      expect(money.amount).toBe(1000);
+    });
+
+    it("multiply rounds correctly", () => {
+      const money = MoneyPrimitive.fromMinor(100, "USD");
+      const result = money.multiply(0.33);
+
+      expect(result.amount).toBe(33);
+    });
+
+    it("throws on currency mismatch for add", () => {
+      const usd = MoneyPrimitive.fromMinor(100, "USD");
+      const eur = MoneyPrimitive.fromMinor(100, "EUR");
+
+      expect(() => usd.add(eur)).toThrow("Currency mismatch");
+    });
+
+    it("throws on currency mismatch for subtract", () => {
+      const usd = MoneyPrimitive.fromMinor(100, "USD");
+      const eur = MoneyPrimitive.fromMinor(100, "EUR");
+
+      expect(() => usd.subtract(eur)).toThrow("Currency mismatch");
+    });
+  });
+
+  describe("Comparison", () => {
+    it("equals returns true for identical values", () => {
+      const a = MoneyPrimitive.fromMinor(1000, "USD");
+      const b = MoneyPrimitive.fromMinor(1000, "USD");
+      expect(a.equals(b)).toBe(true);
+    });
+
+    it("equals returns false for different amounts", () => {
+      const a = MoneyPrimitive.fromMinor(1000, "USD");
+      const b = MoneyPrimitive.fromMinor(2000, "USD");
+      expect(a.equals(b)).toBe(false);
+    });
+
+    it("equals returns false for different currencies", () => {
+      const a = MoneyPrimitive.fromMinor(1000, "USD");
+      const b = MoneyPrimitive.fromMinor(1000, "EUR");
+      expect(a.equals(b)).toBe(false);
+    });
+
+    it("isZero returns true for zero amount", () => {
+      expect(MoneyPrimitive.fromMinor(0, "USD").isZero()).toBe(true);
+    });
+
+    it("isZero returns false for non-zero", () => {
+      expect(MoneyPrimitive.fromMinor(1, "USD").isZero()).toBe(false);
+    });
+
+    it("isNegative works correctly", () => {
+      expect(MoneyPrimitive.fromMinor(-100, "USD").isNegative()).toBe(true);
+      expect(MoneyPrimitive.fromMinor(0, "USD").isNegative()).toBe(false);
+      expect(MoneyPrimitive.fromMinor(100, "USD").isNegative()).toBe(false);
+    });
+  });
+
+  describe("Serialization (JSON round-trip)", () => {
+    it("should round-trip standard currency", () => {
+      const original = MoneyPrimitive.fromMinor(1299, "USD");
+      const json = original.toJSON();
+
+      expect(json).toEqual({
+        amount: 1299,
+        currencyCode: "USD",
+        scale: 2,
+      });
+
+      const restored = MoneyPrimitive.fromJSON(json);
+      expect(restored.equals(original)).toBe(true);
+    });
+
+    it("should round-trip JPY", () => {
+      const original = MoneyPrimitive.fromMinor(5000, "JPY");
+      const json = original.toJSON();
+      const restored = MoneyPrimitive.fromJSON(json);
+
+      expect(restored.amount).toBe(5000);
+      expect(restored.scale).toBe(0);
+      expect(restored.equals(original)).toBe(true);
+    });
+
+    it("should round-trip through JSON.stringify/parse", () => {
+      const original = MoneyPrimitive.fromMajor(42.5, "EUR");
+      const serialized = JSON.stringify(original);
+      const parsed = JSON.parse(serialized);
+      const restored = MoneyPrimitive.fromJSON(parsed);
+
+      expect(restored.equals(original)).toBe(true);
+    });
+
+    it("toString returns a debug-friendly string", () => {
+      const money = MoneyPrimitive.fromMinor(1299, "USD");
+      expect(money.toString()).toBe("MoneyPrimitive(1299 USD scale=2)");
+    });
+  });
+});

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

@@ -0,0 +1,220 @@
+// sdk/core/src/money/money-primitive.ts
+// Immutable Value Object for monetary amounts.
+// Zero Svelte dependencies — pure TypeScript class.
+
+import { CURRENCY_MAP, type ISO4217Code } from "./money.ts";
+
+/**
+ * Serializable representation of a MoneyPrimitive.
+ * Used for persistence drivers and JSON round-trips.
+ */
+export interface MoneyJSON {
+  amount: number;
+  currencyCode: string;
+  scale: number;
+}
+
+/**
+ * Immutable Value Object that encapsulates a monetary amount, its currency,
+ * and the scale (number of decimal places).
+ *
+ * Amounts are always stored in minor units (e.g., cents for USD, centavos for MXN).
+ * The scale is derived from the currency's exponent in CURRENCY_MAP.
+ *
+ * @example
+ * ```ts
+ * const price = MoneyPrimitive.fromMajor(12.99, "USD");
+ * price.minor;           // 1299
+ * price.major;           // 12.99
+ * price.format("en-US"); // "$12.99"
+ *
+ * const json = price.toJSON();
+ * const restored = MoneyPrimitive.fromJSON(json);
+ * ```
+ */
+export class MoneyPrimitive {
+  /** Raw amount in minor units (e.g., cents). */
+  readonly amount: number;
+  /** ISO 4217 currency code. */
+  readonly currencyCode: string;
+  /** Number of decimal places for this currency (e.g., 2 for USD, 0 for JPY). */
+  readonly scale: number;
+
+  private constructor(amount: number, currencyCode: string, scale: number) {
+    this.amount = Math.round(amount);
+    this.currencyCode = currencyCode;
+    this.scale = scale;
+  }
+
+  // ── Factories ────────────────────────────────────────────────────────────
+
+  /**
+   * Create a MoneyPrimitive from a minor-unit integer amount.
+   * @param amount - Amount in minor units (e.g., 1299 for $12.99)
+   * @param currencyCode - ISO 4217 currency code
+   */
+  static fromMinor(
+    amount: number,
+    currencyCode: ISO4217Code | string,
+  ): MoneyPrimitive {
+    const scale = MoneyPrimitive.resolveScale(currencyCode);
+    return new MoneyPrimitive(amount, currencyCode, scale);
+  }
+
+  /**
+   * Create a MoneyPrimitive from a major-unit float amount.
+   * @param amount - Amount in major units (e.g., 12.99 for $12.99)
+   * @param currencyCode - ISO 4217 currency code
+   */
+  static fromMajor(
+    amount: number,
+    currencyCode: ISO4217Code | string,
+  ): MoneyPrimitive {
+    const scale = MoneyPrimitive.resolveScale(currencyCode);
+    const factor = Math.pow(10, scale);
+    return new MoneyPrimitive(Math.round(amount * factor), currencyCode, scale);
+  }
+
+  /**
+   * Restore a MoneyPrimitive from its JSON representation.
+   */
+  static fromJSON(json: MoneyJSON): MoneyPrimitive {
+    return new MoneyPrimitive(json.amount, json.currencyCode, json.scale);
+  }
+
+  // ── Computed Getters ─────────────────────────────────────────────────────
+
+  /** Amount in minor units (alias for `amount`). */
+  get minor(): number {
+    return this.amount;
+  }
+
+  /** Amount in major units (e.g., 12.99 for 1299 cents). */
+  get major(): number {
+    if (this.scale === 0) return this.amount;
+    return this.amount / Math.pow(10, this.scale);
+  }
+
+  // ── Formatting ───────────────────────────────────────────────────────────
+
+  /**
+   * Format this monetary value as a locale-aware currency string.
+   * @param locale - BCP 47 locale string (default: "en-US")
+   */
+  format(locale: string = "en-US"): string {
+    return new Intl.NumberFormat(locale, {
+      style: "currency",
+      currency: this.currencyCode,
+      minimumFractionDigits: this.scale,
+      maximumFractionDigits: this.scale,
+    }).format(this.major);
+  }
+
+  // ── Arithmetic (returns new instances — immutability) ────────────────────
+
+  /**
+   * Add another MoneyPrimitive (must be same currency).
+   * Returns a new MoneyPrimitive.
+   */
+  add(other: MoneyPrimitive): MoneyPrimitive {
+    this.assertSameCurrency(other);
+    return new MoneyPrimitive(
+      this.amount + other.amount,
+      this.currencyCode,
+      this.scale,
+    );
+  }
+
+  /**
+   * Subtract another MoneyPrimitive (must be same currency).
+   * Returns a new MoneyPrimitive.
+   */
+  subtract(other: MoneyPrimitive): MoneyPrimitive {
+    this.assertSameCurrency(other);
+    return new MoneyPrimitive(
+      this.amount - other.amount,
+      this.currencyCode,
+      this.scale,
+    );
+  }
+
+  /**
+   * Multiply by a scalar factor. Returns a new MoneyPrimitive.
+   */
+  multiply(factor: number): MoneyPrimitive {
+    return new MoneyPrimitive(
+      Math.round(this.amount * factor),
+      this.currencyCode,
+      this.scale,
+    );
+  }
+
+  // ── Comparison ───────────────────────────────────────────────────────────
+
+  /**
+   * Value equality — two MoneyPrimitives are equal if they have the same
+   * amount, currency code, and scale.
+   */
+  equals(other: MoneyPrimitive): boolean {
+    return (
+      this.amount === other.amount &&
+      this.currencyCode === other.currencyCode &&
+      this.scale === other.scale
+    );
+  }
+
+  /**
+   * Returns true if this amount is zero.
+   */
+  isZero(): boolean {
+    return this.amount === 0;
+  }
+
+  /**
+   * Returns true if this amount is negative.
+   */
+  isNegative(): boolean {
+    return this.amount < 0;
+  }
+
+  // ── Serialization ────────────────────────────────────────────────────────
+
+  /**
+   * Serialize to a plain JSON-compatible object.
+   */
+  toJSON(): MoneyJSON {
+    return {
+      amount: this.amount,
+      currencyCode: this.currencyCode,
+      scale: this.scale,
+    };
+  }
+
+  toString(): string {
+    return `MoneyPrimitive(${this.amount} ${this.currencyCode} scale=${this.scale})`;
+  }
+
+  // ── Private Helpers ──────────────────────────────────────────────────────
+
+  private assertSameCurrency(other: MoneyPrimitive): void {
+    if (this.currencyCode !== other.currencyCode) {
+      throw new Error(
+        `Currency mismatch: cannot operate on ${this.currencyCode} and ${other.currencyCode}`,
+      );
+    }
+  }
+
+  /**
+   * Resolves the scale (exponent) for a currency code from CURRENCY_MAP.
+   * Throws if the currency is not registered.
+   */
+  private static resolveScale(currencyCode: string): number {
+    const currency = CURRENCY_MAP[currencyCode];
+    if (!currency) {
+      throw new Error(
+        `Unknown currency code: ${currencyCode}. Register it first via registerCurrency().`,
+      );
+    }
+    return currency.exponent;
+  }
+}