rune-lab 0.4.0 → 0.4.1

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;
+  }
+}

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