solve-engine 1.0.0-beta.0 → 1.0.0-beta.1

package/dist/chunk-X6K3HUOY.cjs

@@ -0,0 +1,86 @@
+'use strict';
+
+// src/resolvers/ResolverRegistry.ts
+var ResolverRegistry = class {
+  constructor() {
+    this.resolvers = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register an async resolver.
+   *
+   * Each resolver must have a unique `namespace`. If a resolver with the
+   * same namespace is already registered, the old one is destroyed and
+   * replaced (with a console warning). Packages that need multiple async
+   * operations should use `asyncResolvers: [...]` with distinct namespaces
+   * (e.g., `"weather:current"`, `"weather:forecast"`).
+   */
+  register(resolver) {
+    if (this.resolvers.has(resolver.namespace)) {
+      console.warn(
+        `[ResolverRegistry] Namespace "${resolver.namespace}" already registered. Destroying old resolver and overwriting. Use distinct namespaces (e.g., "${resolver.namespace}:sub1", "${resolver.namespace}:sub2") to avoid collisions when a package needs multiple async resolvers.`
+      );
+      this.resolvers.get(resolver.namespace).destroy();
+    }
+    this.resolvers.set(resolver.namespace, resolver);
+  }
+  /**
+   * Unregister a resolver by namespace.
+   * Calls destroy() and clears all cache entries with that namespace prefix.
+   */
+  unregister(namespace, queryClient) {
+    const resolver = this.resolvers.get(namespace);
+    if (resolver) {
+      resolver.destroy();
+      this.resolvers.delete(namespace);
+    }
+    if (queryClient) {
+      queryClient.removeQueries({ queryKey: [namespace] });
+    }
+  }
+  /**
+   * Run all registered resolvers' preflight checks against compiled bytecode.
+   *
+   * Returns the first AsyncCheckResult found, or null if all data is ready.
+   * Short-circuits on first pending, subsequent pending ops will be
+   * discovered on re-evaluation when the first resolves.
+   */
+  preflightAll(tokens, bytecode, packageId, signal, queryClient) {
+    for (const resolver of this.resolvers.values()) {
+      if (!resolver.preflight) continue;
+      const result = resolver.preflight(tokens, bytecode, packageId, signal, queryClient);
+      if (result) return result;
+    }
+    return null;
+  }
+  /**
+   * Get a resolver by namespace.
+   * Returns undefined if no resolver is registered for that namespace.
+   */
+  get(namespace) {
+    return this.resolvers.get(namespace);
+  }
+  /** Number of registered resolvers. */
+  get size() {
+    return this.resolvers.size;
+  }
+  /**
+   * Check if a resolver is registered for the given namespace.
+   */
+  has(namespace) {
+    return this.resolvers.has(namespace);
+  }
+  /**
+   * Clear all resolvers (document switch, engine reset).
+   * Calls destroy() on each resolver and clears the map.
+   */
+  clear() {
+    for (const resolver of this.resolvers.values()) {
+      resolver.destroy();
+    }
+    this.resolvers.clear();
+  }
+};
+
+exports.ResolverRegistry = ResolverRegistry;
+//# sourceMappingURL=chunk-X6K3HUOY.cjs.map
+//# sourceMappingURL=chunk-X6K3HUOY.cjs.map

package/dist/chunk-X6K3HUOY.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolvers/ResolverRegistry.ts"],"names":[],"mappings":";;;AAuEO,IAAM,mBAAN,MAAuB;AAAA,EAAvB,WAAA,GAAA;AACN,IAAA,IAAA,CAAQ,SAAA,uBAAgB,GAAA,EAA4B;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWpD,SAAS,QAAA,EAAgC;AAExC,IAAA,IAAI,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,QAAA,CAAS,SAAS,CAAA,EAAG;AAC3C,MAAA,OAAA,CAAQ,IAAA;AAAA,QACP,CAAA,8BAAA,EAAiC,SAAS,SAAS,CAAA,+FAAA,EAExC,SAAS,SAAS,CAAA,SAAA,EAAY,SAAS,SAAS,CAAA,0EAAA;AAAA,OAE5D;AACA,MAAA,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,QAAA,CAAS,SAAS,EAAG,OAAA,EAAQ;AAAA,IACjD;AACA,IAAA,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,QAAA,CAAS,SAAA,EAAW,QAAQ,CAAA;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAA,CAAW,WAAmB,WAAA,EAAiC;AAC9D,IAAA,MAAM,QAAA,GAAW,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,SAAS,CAAA;AAC7C,IAAA,IAAI,QAAA,EAAU;AACb,MAAA,QAAA,CAAS,OAAA,EAAQ;AACjB,MAAA,IAAA,CAAK,SAAA,CAAU,OAAO,SAAS,CAAA;AAAA,IAChC;AAGA,IAAA,IAAI,WAAA,EAAa;AAChB,MAAA,WAAA,CAAY,cAAc,EAAE,QAAA,EAAU,CAAC,SAAS,GAAG,CAAA;AAAA,IACpD;AAAA,EACD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,YAAA,CAAa,MAAA,EAAiB,QAAA,EAA2B,SAAA,EAAmB,QAAqB,WAAA,EAAmD;AACnJ,IAAA,KAAA,MAAW,QAAA,IAAY,IAAA,CAAK,SAAA,CAAU,MAAA,EAAO,EAAG;AAC/C,MAAA,IAAI,CAAC,SAAS,SAAA,EAAW;AACzB,MAAA,MAAM,SAAS,QAAA,CAAS,SAAA,CAAU,QAAQ,QAAA,EAAU,SAAA,EAAW,QAAQ,WAAW,CAAA;AAClF,MAAA,IAAI,QAAQ,OAAO,MAAA;AAAA,IACpB;AACA,IAAA,OAAO,IAAA;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAI,SAAA,EAA+C;AAClD,IAAA,OAAO,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,SAAS,CAAA;AAAA,EACpC;AAAA;AAAA,EAGA,IAAI,IAAA,GAAe;AAClB,IAAA,OAAO,KAAK,SAAA,CAAU,IAAA;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,SAAA,EAA4B;AAC/B,IAAA,OAAO,IAAA,CAAK,SAAA,CAAU,GAAA,CAAI,SAAS,CAAA;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KAAA,GAAc;AACb,IAAA,KAAA,MAAW,QAAA,IAAY,IAAA,CAAK,SAAA,CAAU,MAAA,EAAO,EAAG;AAC/C,MAAA,QAAA,CAAS,OAAA,EAAQ;AAAA,IAClB;AACA,IAAA,IAAA,CAAK,UAAU,KAAA,EAAM;AAAA,EACtB;AACD","file":"chunk-X6K3HUOY.cjs","sourcesContent":["import type { QueryClient } from \"@tanstack/query-core\";\nimport type { Token } from \"@solve-js/lexer\";\nimport type { BytecodeProgram } from \"@solve-js/parser/BytecodeBuilder\";\nimport type { Value } from \"@solve-js/vm/Value\";\n\n/**\n * Result from a resolver's preflight() check.\n * Returned when async data is needed, the orchestrator uses this\n * to subscribe to the resolver and return a Pending value immediately.\n */\nexport interface AsyncCheckResult {\n\t/** Unique cache key for deduplication (e.g., \"{packageId}:rates:USD:GBP\") */\n\tqueryKey: string;\n\t/** Promise that resolves to the final Value */\n\tresolver: Promise<Value>;\n\t/** Package owning this resolver */\n\tpackageId: string;\n\t/** AbortSignal for stale-data prevention */\n\tsignal: AbortSignal;\n\t/** Optional metadata for diagnostics */\n\tmetadata?: Record<string, unknown>;\n}\n\n/**\n * Interface for async resolvers registered by packages/plugins.\n *\n * Each resolver handles a domain of async data (currency rates,\n * weather, stock prices, etc.). The preflight() method is called\n * BEFORE VM execution to check if all data is cached. If not,\n * it returns an AsyncCheckResult and the engine skips the VM,\n * returning a Pending value instead.\n */\nexport interface IAsyncResolver {\n\t/** Unique namespace for cache key scoping (e.g., \"currency\", \"weather\") */\n\treadonly namespace: string;\n\n\t/**\n\t * Pre-flight check: called BEFORE VM execution.\n\t *\n\t * Returns null if all data for this expression is cached and ready.\n\t * Returns an AsyncCheckResult if async work is needed.\n\t *\n\t * This method is synchronous, it only checks caches, never fetches.\n\t * If data is missing, it creates a Promise and returns immediately.\n\t *\n\t * @param tokens - The lexed tokens for the expression\n\t * @param bytecode - The compiled bytecode program\n\t * @param pluginId - The plugin ID (for cache key scoping)\n\t * @param signal - AbortSignal for the current evaluation\n\t */\n\tpreflight?(tokens: Token[], bytecode: BytecodeProgram, packageId: string, signal: AbortSignal, queryClient: QueryClient): AsyncCheckResult | null;\n\n\t/**\n\t * Called when the resolver's namespace is being unregistered.\n\t * Clean up any in-flight promises, clear caches, unsubscribe.\n\t */\n\tdestroy(): void;\n}\n\n/**\n * Registry of async resolvers, keyed by namespace.\n *\n * Plugins/packages register resolvers alongside their parselets\n * and opcode handlers. The engine calls preflightAll() before\n * VM execution to short-circuit async expressions.\n *\n * Lifecycle:\n * - register(), when a package is loaded\n * - unregister(), when a package is unloaded (clears cache entries)\n * - clear(), on document switch (clears all resolvers)\n */\nexport class ResolverRegistry {\n\tprivate resolvers = new Map<string, IAsyncResolver>();\n\n\t/**\n\t * Register an async resolver.\n\t *\n\t * Each resolver must have a unique `namespace`. If a resolver with the\n\t * same namespace is already registered, the old one is destroyed and\n\t * replaced (with a console warning). Packages that need multiple async\n\t * operations should use `asyncResolvers: [...]` with distinct namespaces\n\t * (e.g., `\"weather:current\"`, `\"weather:forecast\"`).\n\t */\n\tregister(resolver: IAsyncResolver): void {\n\t\t// Clean up previous resolver with same namespace if any\n\t\tif (this.resolvers.has(resolver.namespace)) {\n\t\t\tconsole.warn(\n\t\t\t\t`[ResolverRegistry] Namespace \"${resolver.namespace}\" already registered. ` +\n\t\t\t\t`Destroying old resolver and overwriting. Use distinct namespaces ` +\n\t\t\t\t`(e.g., \"${resolver.namespace}:sub1\", \"${resolver.namespace}:sub2\") ` +\n\t\t\t\t`to avoid collisions when a package needs multiple async resolvers.`,\n\t\t\t);\n\t\t\tthis.resolvers.get(resolver.namespace)!.destroy();\n\t\t}\n\t\tthis.resolvers.set(resolver.namespace, resolver);\n\t}\n\n\t/**\n\t * Unregister a resolver by namespace.\n\t * Calls destroy() and clears all cache entries with that namespace prefix.\n\t */\n\tunregister(namespace: string, queryClient?: QueryClient): void {\n\t\tconst resolver = this.resolvers.get(namespace);\n\t\tif (resolver) {\n\t\t\tresolver.destroy();\n\t\t\tthis.resolvers.delete(namespace);\n\t\t}\n\t\t// Clear all cache entries for this namespace via TanStack Query\n\t\t// Hierarchical keys: [\"osrs\"] clears all [\"osrs\", ...] queries\n\t\tif (queryClient) {\n\t\t\tqueryClient.removeQueries({ queryKey: [namespace] });\n\t\t}\n\t}\n\n\t/**\n\t * Run all registered resolvers' preflight checks against compiled bytecode.\n\t *\n\t * Returns the first AsyncCheckResult found, or null if all data is ready.\n\t * Short-circuits on first pending, subsequent pending ops will be\n\t * discovered on re-evaluation when the first resolves.\n\t */\n\tpreflightAll(tokens: Token[], bytecode: BytecodeProgram, packageId: string, signal: AbortSignal, queryClient: QueryClient): AsyncCheckResult | null {\n\t\tfor (const resolver of this.resolvers.values()) {\n\t\t\tif (!resolver.preflight) continue;\n\t\t\tconst result = resolver.preflight(tokens, bytecode, packageId, signal, queryClient);\n\t\t\tif (result) return result;\n\t\t}\n\t\treturn null;\n\t}\n\n\t/**\n\t * Get a resolver by namespace.\n\t * Returns undefined if no resolver is registered for that namespace.\n\t */\n\tget(namespace: string): IAsyncResolver | undefined {\n\t\treturn this.resolvers.get(namespace);\n\t}\n\n\t/** Number of registered resolvers. */\n\tget size(): number {\n\t\treturn this.resolvers.size;\n\t}\n\n\t/**\n\t * Check if a resolver is registered for the given namespace.\n\t */\n\thas(namespace: string): boolean {\n\t\treturn this.resolvers.has(namespace);\n\t}\n\n\t/**\n\t * Clear all resolvers (document switch, engine reset).\n\t * Calls destroy() on each resolver and clears the map.\n\t */\n\tclear(): void {\n\t\tfor (const resolver of this.resolvers.values()) {\n\t\t\tresolver.destroy();\n\t\t}\n\t\tthis.resolvers.clear();\n\t}\n}\n"]}

package/dist/chunk-XJCMXB2E.cjs

@@ -0,0 +1,333 @@
+'use strict';
+
+var chunkVEKIWQ3F_cjs = require('./chunk-VEKIWQ3F.cjs');
+var chunkM4N5GA5Z_cjs = require('./chunk-M4N5GA5Z.cjs');
+
+// src/uom/CurrencyExchange.ts
+var CurrencyErrorCodes = {
+  /** Frankfurter's rates endpoint returned a non-OK HTTP status. */
+  API_ERROR: "CURRENCY_API_ERROR",
+  /** A requested currency/crypto code isn't in the fetched rate table, an unrecognized code, not an API failure. */
+  UNKNOWN_CODE: "UNKNOWN_CURRENCY_CODE",
+  /** CoinGecko's simple-price endpoint returned a non-OK HTTP status. */
+  CRYPTO_API_ERROR: "CRYPTO_PRICE_API_ERROR"
+};
+var _CurrencyExchangeService = class _CurrencyExchangeService {
+  constructor() {
+    /**
+     * Live rate tables cached from successful getRate() fetches, keyed by
+     * uppercase base currency. Each table holds every rate the API returned
+     * for that base (plus the base itself at 1), so any pair whose two codes
+     * appear in one fresh table can be served synchronously, including
+     * cross pairs via triangulation (EUR→GBP through a USD-base table).
+     * Stale tables are ignored, not evicted; the next successful fetch for
+     * the same base overwrites them.
+     */
+    this.baseTables = /* @__PURE__ */ new Map();
+  }
+  isCryptoCode(code) {
+    return code.toUpperCase() in _CurrencyExchangeService.CRYPTO_IDS;
+  }
+  /**
+   * Fetch the live exchange rate for converting 1 unit of `from` into `to`.
+   *
+   * Routes cryptocurrency codes (see {@link CRYPTO_IDS}) to CoinGecko and
+   * everything else to Frankfurter (ECB reference rates, fiat-only). On
+   * success, caches the whole returned rate table for `from` so subsequent
+   * lookups, including cross-pairs via triangulation, can be served
+   * synchronously by {@link getRateSync} within the freshness window.
+   *
+   * @throws If the currency code is unrecognized or the fetch fails/times out.
+   */
+  async getRate(from, to, signal) {
+    const fromUpper = from.toUpperCase();
+    const toUpper = to.toUpperCase();
+    if (this.isCryptoCode(fromUpper) || this.isCryptoCode(toUpper)) {
+      return this.getCryptoRate(fromUpper, toUpper, signal);
+    }
+    const { signal: fetchSignal, cleanup } = chunkVEKIWQ3F_cjs.createTimeoutSignal(
+      signal,
+      _CurrencyExchangeService.FETCH_TIMEOUT_MS,
+      "Currency API fetch"
+    );
+    try {
+      const response = await fetch(`https://api.frankfurter.dev/v2/rates?base=${fromUpper}`, { signal: fetchSignal });
+      if (!response.ok) throw chunkM4N5GA5Z_cjs.ErrorFactory.external(CurrencyErrorCodes.API_ERROR, `Currency API returned ${response.status}`, { status: response.status });
+      const data = await response.json();
+      const rates = Array.isArray(data) ? Object.fromEntries(
+        data.filter((entry) => {
+          if (typeof entry !== "object" || entry === null) return false;
+          const candidate = entry;
+          return typeof candidate.quote === "string" && typeof candidate.rate === "number";
+        }).map((entry) => [entry.quote.toUpperCase(), entry.rate])
+      ) : data.rates ?? {};
+      if (rates[toUpper] === void 0) throw chunkM4N5GA5Z_cjs.ErrorFactory.validation(CurrencyErrorCodes.UNKNOWN_CODE, `Unknown currency: ${toUpper}`, { code: toUpper });
+      this.baseTables.set(fromUpper, {
+        fetchedAt: Date.now(),
+        rates: { ...rates, [fromUpper]: 1 }
+      });
+      return rates[toUpper];
+    } finally {
+      cleanup();
+    }
+  }
+  /**
+   * Crypto rate fetch, routed through CoinGecko's no-auth simple-price
+   * endpoint instead of Frankfurter (fiat-only, has no BTC/ETH concept).
+   * Handles all three combinations, crypto→crypto, crypto→fiat
+   * fiat→crypto, via prices denominated in USD (or the target fiat
+   * directly, which CoinGecko's `vs_currencies` also accepts), then
+   * caches the result as a same-shaped base table so getRateSync /
+   * convertSync keep working unchanged for crypto pairs too.
+   */
+  async getCryptoRate(fromUpper, toUpper, signal) {
+    const { signal: fetchSignal, cleanup } = chunkVEKIWQ3F_cjs.createTimeoutSignal(
+      signal,
+      _CurrencyExchangeService.FETCH_TIMEOUT_MS,
+      "Crypto price API fetch"
+    );
+    try {
+      const fromIsCrypto = this.isCryptoCode(fromUpper);
+      const toIsCrypto = this.isCryptoCode(toUpper);
+      let rate;
+      if (fromIsCrypto && toIsCrypto) {
+        const fromId = _CurrencyExchangeService.CRYPTO_IDS[fromUpper];
+        const toId = _CurrencyExchangeService.CRYPTO_IDS[toUpper];
+        const data = await this.fetchCoinGeckoPrices([fromId, toId], "usd", fetchSignal);
+        const fromUsd = data[fromId]?.usd;
+        const toUsd = data[toId]?.usd;
+        if (typeof fromUsd !== "number") throw chunkM4N5GA5Z_cjs.ErrorFactory.validation(CurrencyErrorCodes.UNKNOWN_CODE, `Unknown currency: ${fromUpper}`, { code: fromUpper });
+        if (typeof toUsd !== "number") throw chunkM4N5GA5Z_cjs.ErrorFactory.validation(CurrencyErrorCodes.UNKNOWN_CODE, `Unknown currency: ${toUpper}`, { code: toUpper });
+        rate = fromUsd / toUsd;
+      } else if (fromIsCrypto) {
+        const fromId = _CurrencyExchangeService.CRYPTO_IDS[fromUpper];
+        const vs = toUpper.toLowerCase();
+        const data = await this.fetchCoinGeckoPrices([fromId], vs, fetchSignal);
+        const value = data[fromId]?.[vs];
+        if (typeof value !== "number") throw chunkM4N5GA5Z_cjs.ErrorFactory.validation(CurrencyErrorCodes.UNKNOWN_CODE, `Unknown currency: ${toUpper}`, { code: toUpper });
+        rate = value;
+      } else {
+        const toId = _CurrencyExchangeService.CRYPTO_IDS[toUpper];
+        const vs = fromUpper.toLowerCase();
+        const data = await this.fetchCoinGeckoPrices([toId], vs, fetchSignal);
+        const priceOfToInFrom = data[toId]?.[vs];
+        if (typeof priceOfToInFrom !== "number") throw chunkM4N5GA5Z_cjs.ErrorFactory.validation(CurrencyErrorCodes.UNKNOWN_CODE, `Unknown currency: ${fromUpper}`, { code: fromUpper });
+        rate = 1 / priceOfToInFrom;
+      }
+      this.baseTables.set(fromUpper, {
+        fetchedAt: Date.now(),
+        rates: { [fromUpper]: 1, [toUpper]: rate }
+      });
+      return rate;
+    } finally {
+      cleanup();
+    }
+  }
+  async fetchCoinGeckoPrices(ids, vsCurrency, signal) {
+    const url = `https://api.coingecko.com/api/v3/simple/price?ids=${ids.join(",")}&vs_currencies=${vsCurrency}`;
+    const response = await fetch(url, { signal });
+    if (!response.ok) throw chunkM4N5GA5Z_cjs.ErrorFactory.external(CurrencyErrorCodes.CRYPTO_API_ERROR, `Crypto price API returned ${response.status}`, { status: response.status });
+    return response.json();
+  }
+  /**
+   * Seed a base rate table without a network fetch.
+   *
+   * Intended for tests and for future user-provided offline rates
+   * production live data always comes from {@link getRate}. Seeded rates
+   * obey the same freshness window as fetched ones.
+   *
+   * @param base - Base currency code (e.g. "USD").
+   * @param rates - Map of currency code → rate relative to the base.
+   */
+  primeRates(base, rates) {
+    const baseUpper = base.toUpperCase();
+    this.baseTables.set(baseUpper, {
+      fetchedAt: Date.now(),
+      rates: { ...rates, [baseUpper]: 1 }
+    });
+  }
+  /**
+   * Drop every cached/primed rate table.
+   *
+   * Mainly for test isolation: {@link sharedCurrencyExchange} is a
+   * module-level singleton, so a rate primed or fetched by one test can
+   * silently leak into a later test in the same file. Also usable in
+   * production if a caller ever wants to force a full re-fetch.
+   */
+  clearRates() {
+    this.baseTables.clear();
+  }
+  /**
+   * Synchronous rate lookup: `1` for same-currency pairs, a cached LIVE
+   * rate if one was fetched within {@link RATE_FRESHNESS_MS}, otherwise
+   * `null`, callers fall through to the async fetch path and the
+   * expression shows Pending until real data arrives.
+   *
+   * There is deliberately no hardcoded fallback table: a stale made-up
+   * rate presented as a real conversion is worse than a Pending state.
+   */
+  getRateSync(from, to) {
+    const fromUpper = from.toUpperCase();
+    const toUpper = to.toUpperCase();
+    if (fromUpper === toUpper) {
+      return 1;
+    }
+    const now = Date.now();
+    for (const table of this.baseTables.values()) {
+      if (now - table.fetchedAt > _CurrencyExchangeService.RATE_FRESHNESS_MS) continue;
+      const fromRate = table.rates[fromUpper];
+      const toRate = table.rates[toUpper];
+      if (fromRate && toRate) {
+        return toRate / fromRate;
+      }
+    }
+    return null;
+  }
+  /** Convert `value` from `from` to `to` using a freshly-fetched live rate (see {@link getRate}). */
+  async convert(value, from, to) {
+    const rate = await this.getRate(from, to);
+    return value * rate;
+  }
+  /**
+   * Get all currently cached fresh rates, keyed "FROM:TO".
+   * @returns Snapshot of fresh live rates, or null when none are cached.
+   */
+  getAllRates() {
+    const now = Date.now();
+    const snapshot = {};
+    let any = false;
+    for (const [base, table] of this.baseTables) {
+      if (now - table.fetchedAt > _CurrencyExchangeService.RATE_FRESHNESS_MS) continue;
+      for (const [code, rate] of Object.entries(table.rates)) {
+        snapshot[`${base}:${code}`] = rate;
+        any = true;
+      }
+    }
+    return any ? snapshot : null;
+  }
+  /**
+   * Check whether any fresh live rates are currently cached.
+   */
+  hasRates() {
+    return this.getAllRates() !== null;
+  }
+  /**
+   * Synchronous conversion using cached rates only
+   * Returns null if rate not in cache
+   */
+  convertSync(value, from, to) {
+    const rate = this.getRateSync(from, to);
+    if (rate === null) return null;
+    return value * rate;
+  }
+  // ------------------------------------------------------------------------
+  // CURRENCY VALIDATION
+  // ------------------------------------------------------------------------
+  /**
+   * Check whether `code` is a recognized currency code (fiat or the
+   * cryptocurrencies in {@link CRYPTO_IDS}), a fixed allowlist, not a
+   * live lookup against any API.
+   */
+  isCurrency(code) {
+    const knownCurrencies = [
+      "USD",
+      "EUR",
+      "GBP",
+      "JPY",
+      "AUD",
+      "CAD",
+      "CHF",
+      "CNY",
+      "SEK",
+      "NOK",
+      "DKK",
+      "NZD",
+      "KRW",
+      "SGD",
+      "HKD",
+      "INR",
+      "BRL",
+      "ZAR",
+      "MXN",
+      "RUB",
+      "TRY",
+      "SAR",
+      "AED",
+      "ILS",
+      "PLN",
+      "CZK",
+      "HUF",
+      "THB",
+      "IDR",
+      "MYR",
+      "PHP",
+      "CLP",
+      "COP",
+      "ARS",
+      "NGN",
+      "EGP",
+      "PKR",
+      "BDT",
+      "VND",
+      "KES",
+      "MAD",
+      "QAR",
+      "KWD",
+      "OMR",
+      "BHD",
+      "JOD",
+      "BTC",
+      "ETH",
+      "SOL",
+      "XRP",
+      "ADA",
+      "DOGE",
+      "DOT"
+    ];
+    return knownCurrencies.includes(code.toUpperCase());
+  }
+};
+/**
+ * How long a fetched rate may be served synchronously by getRateSync().
+ * Beyond this window callers fall through to the async path (expression
+ * shows Pending until the fetch lands).
+ */
+_CurrencyExchangeService.RATE_FRESHNESS_MS = 15 * 60 * 1e3;
+/**
+ * Ticker → CoinGecko coin id, for the cryptocurrencies `isCurrency()`
+ * recognizes. Frankfurter (the fiat rate source below) is ECB reference
+ * rates only and has no concept of BTC/ETH/etc, routing a crypto code
+ * through it as `base=BTC` fails outright, which is why crypto pairs
+ * previously never resolved (see CurrencyAsyncResolver/VM.ts's ADD
+ * handling for the two bugs that let that failure pass silently instead
+ * of surfacing as a real fetch).
+ */
+_CurrencyExchangeService.CRYPTO_IDS = {
+  BTC: "bitcoin",
+  ETH: "ethereum",
+  SOL: "solana",
+  XRP: "ripple",
+  ADA: "cardano",
+  DOGE: "dogecoin",
+  DOT: "polkadot"
+};
+// ------------------------------------------------------------------------
+// RATE FETCHING
+// ------------------------------------------------------------------------
+/**
+ * Timeout (ms) for currency exchange rate fetches.
+ *
+ * If the frankfurter API doesn't respond within this window, the fetch
+ * is aborted, preventing indefinite "Pending" states in the playground
+ * and Obsidian plugin when the exchange rate API is unreachable.
+ */
+_CurrencyExchangeService.FETCH_TIMEOUT_MS = 1e4;
+var CurrencyExchangeService = _CurrencyExchangeService;
+var currencyExchangeService = new CurrencyExchangeService();
+var sharedCurrencyExchange = currencyExchangeService;
+
+exports.CurrencyExchangeService = CurrencyExchangeService;
+exports.currencyExchangeService = currencyExchangeService;
+exports.sharedCurrencyExchange = sharedCurrencyExchange;
+//# sourceMappingURL=chunk-XJCMXB2E.cjs.map
+//# sourceMappingURL=chunk-XJCMXB2E.cjs.map

package/dist/chunk-XJCMXB2E.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/uom/CurrencyExchange.ts"],"names":["createTimeoutSignal","ErrorFactory"],"mappings":"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","file":"chunk-XJCMXB2E.cjs","sourcesContent":["/**\n * Production-grade currency exchange service with scalable architecture\n * Integrates with DataQueryService for worker-based execution\n */\n\nimport { createTimeoutSignal } from \"@solve-js/utilities/TimeoutSignal\";\nimport { ErrorFactory } from \"@solve-js/errors/UnifiedErrorFramework\";\n\n/**\n * Error codes for this service. Co-located rather than unioned into\n * `errors/ErrorCode.ts`'s core catalog (that catalog is scoped to the\n * parser/VM/engine/errors/config/lexer layers, not yet the ~17 domain\n * packages. See that file's module doc for the intended per-package\n * pattern this follows).\n */\nexport const CurrencyErrorCodes = {\n  /** Frankfurter's rates endpoint returned a non-OK HTTP status. */\n  API_ERROR: \"CURRENCY_API_ERROR\",\n  /** A requested currency/crypto code isn't in the fetched rate table, an unrecognized code, not an API failure. */\n  UNKNOWN_CODE: \"UNKNOWN_CURRENCY_CODE\",\n  /** CoinGecko's simple-price endpoint returned a non-OK HTTP status. */\n  CRYPTO_API_ERROR: \"CRYPTO_PRICE_API_ERROR\",\n} as const;\n\n// ============================================================================\n// CURRENCY EXCHANGE SERVICE\n// ============================================================================\n\n/**\n * Caches exchange rates fetched from an external source.\n *\n * Rates are global market data rather than per-engine configuration, which is\n * why one instance is shared. Two engines with private copies would fetch the\n * same endpoint twice and could disagree about one pair at one moment. See\n * `engine/EngineContext.ts`.\n */\nexport class CurrencyExchangeService {\n  /**\n   * Live rate tables cached from successful getRate() fetches, keyed by\n   * uppercase base currency. Each table holds every rate the API returned\n   * for that base (plus the base itself at 1), so any pair whose two codes\n   * appear in one fresh table can be served synchronously, including\n   * cross pairs via triangulation (EUR→GBP through a USD-base table).\n   * Stale tables are ignored, not evicted; the next successful fetch for\n   * the same base overwrites them.\n   */\n  private baseTables: Map<string, { fetchedAt: number; rates: Record<string, number> }> = new Map();\n\n  /**\n   * How long a fetched rate may be served synchronously by getRateSync().\n   * Beyond this window callers fall through to the async path (expression\n   * shows Pending until the fetch lands).\n   */\n  private static readonly RATE_FRESHNESS_MS = 15 * 60 * 1000;\n\n  /**\n   * Ticker → CoinGecko coin id, for the cryptocurrencies `isCurrency()`\n   * recognizes. Frankfurter (the fiat rate source below) is ECB reference\n   * rates only and has no concept of BTC/ETH/etc, routing a crypto code\n   * through it as `base=BTC` fails outright, which is why crypto pairs\n   * previously never resolved (see CurrencyAsyncResolver/VM.ts's ADD\n   * handling for the two bugs that let that failure pass silently instead\n   * of surfacing as a real fetch).\n   */\n  private static readonly CRYPTO_IDS: Record<string, string> = {\n    BTC: \"bitcoin\", ETH: \"ethereum\", SOL: \"solana\", XRP: \"ripple\",\n    ADA: \"cardano\", DOGE: \"dogecoin\", DOT: \"polkadot\",\n  };\n\n  private isCryptoCode(code: string): boolean {\n    return code.toUpperCase() in CurrencyExchangeService.CRYPTO_IDS;\n  }\n\n  constructor() {}\n\n  // ------------------------------------------------------------------------\n  // RATE FETCHING\n  // ------------------------------------------------------------------------\n\n  /**\n   * Timeout (ms) for currency exchange rate fetches.\n   *\n   * If the frankfurter API doesn't respond within this window, the fetch\n   * is aborted, preventing indefinite \"Pending\" states in the playground\n   * and Obsidian plugin when the exchange rate API is unreachable.\n   */\n  private static readonly FETCH_TIMEOUT_MS = 10_000;\n\n  /**\n   * Fetch the live exchange rate for converting 1 unit of `from` into `to`.\n   *\n   * Routes cryptocurrency codes (see {@link CRYPTO_IDS}) to CoinGecko and\n   * everything else to Frankfurter (ECB reference rates, fiat-only). On\n   * success, caches the whole returned rate table for `from` so subsequent\n   * lookups, including cross-pairs via triangulation, can be served\n   * synchronously by {@link getRateSync} within the freshness window.\n   *\n   * @throws If the currency code is unrecognized or the fetch fails/times out.\n   */\n  async getRate(from: string, to: string, signal?: AbortSignal): Promise<number> {\n    const fromUpper = from.toUpperCase();\n    const toUpper = to.toUpperCase();\n\n    if (this.isCryptoCode(fromUpper) || this.isCryptoCode(toUpper)) {\n      return this.getCryptoRate(fromUpper, toUpper, signal);\n    }\n\n    // Combine the caller's optional abort signal with a hard timeout so a\n    // hanging currency API never blocks re-evaluation indefinitely.\n    const { signal: fetchSignal, cleanup } = createTimeoutSignal(\n      signal,\n      CurrencyExchangeService.FETCH_TIMEOUT_MS,\n      \"Currency API fetch\",\n    );\n\n    try {\n      const response = await fetch(`https://api.frankfurter.dev/v2/rates?base=${fromUpper}`, { signal: fetchSignal });\n      if (!response.ok) throw ErrorFactory.external(CurrencyErrorCodes.API_ERROR, `Currency API returned ${response.status}`, { status: response.status });\n      const data = await response.json();\n      // The v2 endpoint returns a flat array of { date, base, quote, rate }\n      // entries (one per target currency) rather than the classic v1 shape\n      // { base, date, rates: { CODE: rate } }. Reading data.rates against\n      // the real response is always undefined, so every conversion used to\n      // throw \"Unknown currency\" no matter which currencies were requested.\n      // Accept both shapes so a future API revision back to the object form\n      // doesn't silently break this again.\n      const rates: Record<string, number> = Array.isArray(data)\n        ? Object.fromEntries(\n            data\n              .filter((entry: unknown): entry is { quote: string; rate: number } => {\n                if (typeof entry !== \"object\" || entry === null) return false;\n                const candidate = entry as { quote?: unknown; rate?: unknown };\n                return typeof candidate.quote === \"string\" && typeof candidate.rate === \"number\";\n              })\n              .map((entry: { quote: string; rate: number }) => [entry.quote.toUpperCase(), entry.rate])\n          )\n        : (data.rates ?? {});\n      if (rates[toUpper] === undefined) throw ErrorFactory.validation(CurrencyErrorCodes.UNKNOWN_CODE, `Unknown currency: ${toUpper}`, { code: toUpper });\n\n      // The API returns ALL rates for the base currency, cache the whole\n      // table so subsequent conversions (including cross pairs via\n      // triangulation) resolve synchronously within the freshness window\n      // instead of going Pending again.\n      this.baseTables.set(fromUpper, {\n        fetchedAt: Date.now(),\n        rates: { ...rates, [fromUpper]: 1 },\n      });\n\n      return rates[toUpper];\n    } finally {\n      cleanup();\n    }\n  }\n\n  /**\n   * Crypto rate fetch, routed through CoinGecko's no-auth simple-price\n   * endpoint instead of Frankfurter (fiat-only, has no BTC/ETH concept).\n   * Handles all three combinations, crypto→crypto, crypto→fiat\n   * fiat→crypto, via prices denominated in USD (or the target fiat\n   * directly, which CoinGecko's `vs_currencies` also accepts), then\n   * caches the result as a same-shaped base table so getRateSync /\n   * convertSync keep working unchanged for crypto pairs too.\n   */\n  private async getCryptoRate(fromUpper: string, toUpper: string, signal?: AbortSignal): Promise<number> {\n    const { signal: fetchSignal, cleanup } = createTimeoutSignal(\n      signal,\n      CurrencyExchangeService.FETCH_TIMEOUT_MS,\n      \"Crypto price API fetch\",\n    );\n\n    try {\n      const fromIsCrypto = this.isCryptoCode(fromUpper);\n      const toIsCrypto = this.isCryptoCode(toUpper);\n      let rate: number;\n\n      if (fromIsCrypto && toIsCrypto) {\n        const fromId = CurrencyExchangeService.CRYPTO_IDS[fromUpper];\n        const toId = CurrencyExchangeService.CRYPTO_IDS[toUpper];\n        const data = await this.fetchCoinGeckoPrices([fromId, toId], \"usd\", fetchSignal);\n        const fromUsd = data[fromId]?.usd;\n        const toUsd = data[toId]?.usd;\n        if (typeof fromUsd !== \"number\") throw ErrorFactory.validation(CurrencyErrorCodes.UNKNOWN_CODE, `Unknown currency: ${fromUpper}`, { code: fromUpper });\n        if (typeof toUsd !== \"number\") throw ErrorFactory.validation(CurrencyErrorCodes.UNKNOWN_CODE, `Unknown currency: ${toUpper}`, { code: toUpper });\n        rate = fromUsd / toUsd;\n      } else if (fromIsCrypto) {\n        const fromId = CurrencyExchangeService.CRYPTO_IDS[fromUpper];\n        const vs = toUpper.toLowerCase();\n        const data = await this.fetchCoinGeckoPrices([fromId], vs, fetchSignal);\n        const value = data[fromId]?.[vs];\n        if (typeof value !== \"number\") throw ErrorFactory.validation(CurrencyErrorCodes.UNKNOWN_CODE, `Unknown currency: ${toUpper}`, { code: toUpper });\n        rate = value;\n      } else {\n        const toId = CurrencyExchangeService.CRYPTO_IDS[toUpper];\n        const vs = fromUpper.toLowerCase();\n        const data = await this.fetchCoinGeckoPrices([toId], vs, fetchSignal);\n        const priceOfToInFrom = data[toId]?.[vs];\n        if (typeof priceOfToInFrom !== \"number\") throw ErrorFactory.validation(CurrencyErrorCodes.UNKNOWN_CODE, `Unknown currency: ${fromUpper}`, { code: fromUpper });\n        rate = 1 / priceOfToInFrom;\n      }\n\n      // Cache as a single-pair base table, same shape Frankfurter fetches\n      // produce, so getRateSync/convertSync's triangulation logic doesn't\n      // need to know or care which source a rate came from.\n      this.baseTables.set(fromUpper, {\n        fetchedAt: Date.now(),\n        rates: { [fromUpper]: 1, [toUpper]: rate },\n      });\n\n      return rate;\n    } finally {\n      cleanup();\n    }\n  }\n\n  private async fetchCoinGeckoPrices(ids: string[], vsCurrency: string, signal: AbortSignal): Promise<Record<string, Record<string, number>>> {\n    const url = `https://api.coingecko.com/api/v3/simple/price?ids=${ids.join(\",\")}&vs_currencies=${vsCurrency}`;\n    const response = await fetch(url, { signal });\n    if (!response.ok) throw ErrorFactory.external(CurrencyErrorCodes.CRYPTO_API_ERROR, `Crypto price API returned ${response.status}`, { status: response.status });\n    return response.json();\n  }\n\n  /**\n   * Seed a base rate table without a network fetch.\n   *\n   * Intended for tests and for future user-provided offline rates\n   * production live data always comes from {@link getRate}. Seeded rates\n   * obey the same freshness window as fetched ones.\n   *\n   * @param base - Base currency code (e.g. \"USD\").\n   * @param rates - Map of currency code → rate relative to the base.\n   */\n  primeRates(base: string, rates: Record<string, number>): void {\n    const baseUpper = base.toUpperCase();\n    this.baseTables.set(baseUpper, {\n      fetchedAt: Date.now(),\n      rates: { ...rates, [baseUpper]: 1 },\n    });\n  }\n\n  /**\n   * Drop every cached/primed rate table.\n   *\n   * Mainly for test isolation: {@link sharedCurrencyExchange} is a\n   * module-level singleton, so a rate primed or fetched by one test can\n   * silently leak into a later test in the same file. Also usable in\n   * production if a caller ever wants to force a full re-fetch.\n   */\n  clearRates(): void {\n    this.baseTables.clear();\n  }\n\n  /**\n   * Synchronous rate lookup: `1` for same-currency pairs, a cached LIVE\n   * rate if one was fetched within {@link RATE_FRESHNESS_MS}, otherwise\n   * `null`, callers fall through to the async fetch path and the\n   * expression shows Pending until real data arrives.\n   *\n   * There is deliberately no hardcoded fallback table: a stale made-up\n   * rate presented as a real conversion is worse than a Pending state.\n   */\n  getRateSync(from: string, to: string): number | null {\n    const fromUpper = from.toUpperCase();\n    const toUpper = to.toUpperCase();\n    if (fromUpper === toUpper) {\n      return 1;\n    }\n    const now = Date.now();\n    for (const table of this.baseTables.values()) {\n      if (now - table.fetchedAt > CurrencyExchangeService.RATE_FRESHNESS_MS) continue;\n      const fromRate = table.rates[fromUpper];\n      const toRate = table.rates[toUpper];\n      if (fromRate && toRate) {\n        return toRate / fromRate;\n      }\n    }\n    return null;\n  }\n\n  /** Convert `value` from `from` to `to` using a freshly-fetched live rate (see {@link getRate}). */\n  async convert(value: number, from: string, to: string): Promise<number> {\n    const rate = await this.getRate(from, to);\n    return value * rate;\n  }\n\n  /**\n   * Get all currently cached fresh rates, keyed \"FROM:TO\".\n   * @returns Snapshot of fresh live rates, or null when none are cached.\n   */\n  getAllRates(): Record<string, number> | null {\n    const now = Date.now();\n    const snapshot: Record<string, number> = {};\n    let any = false;\n    for (const [base, table] of this.baseTables) {\n      if (now - table.fetchedAt > CurrencyExchangeService.RATE_FRESHNESS_MS) continue;\n      for (const [code, rate] of Object.entries(table.rates)) {\n        snapshot[`${base}:${code}`] = rate;\n        any = true;\n      }\n    }\n    return any ? snapshot : null;\n  }\n\n  /**\n   * Check whether any fresh live rates are currently cached.\n   */\n  hasRates(): boolean {\n    return this.getAllRates() !== null;\n  }\n\n  /**\n   * Synchronous conversion using cached rates only\n   * Returns null if rate not in cache\n   */\n  convertSync(value: number, from: string, to: string): number | null {\n    const rate = this.getRateSync(from, to);\n    if (rate === null) return null;\n    return value * rate;\n  }\n\n  // ------------------------------------------------------------------------\n  // CURRENCY VALIDATION\n  // ------------------------------------------------------------------------\n\n  /**\n   * Check whether `code` is a recognized currency code (fiat or the\n   * cryptocurrencies in {@link CRYPTO_IDS}), a fixed allowlist, not a\n   * live lookup against any API.\n   */\n  isCurrency(code: string): boolean {\n    // Check against known currency codes\n    const knownCurrencies = [\n      \"USD\", \"EUR\", \"GBP\", \"JPY\", \"AUD\", \"CAD\", \"CHF\", \"CNY\", \"SEK\", \"NOK\",\n      \"DKK\", \"NZD\", \"KRW\", \"SGD\", \"HKD\", \"INR\", \"BRL\", \"ZAR\", \"MXN\", \"RUB\",\n      \"TRY\", \"SAR\", \"AED\", \"ILS\", \"PLN\", \"CZK\", \"HUF\", \"THB\", \"IDR\", \"MYR\",\n      \"PHP\", \"CLP\", \"COP\", \"ARS\", \"NGN\", \"EGP\", \"PKR\", \"BDT\", \"VND\", \"KES\",\n      \"MAD\", \"QAR\", \"KWD\", \"OMR\", \"BHD\", \"JOD\",\n      \"BTC\", \"ETH\", \"SOL\", \"XRP\", \"ADA\", \"DOGE\", \"DOT\",\n    ];\n    return knownCurrencies.includes(code.toUpperCase());\n  }\n\n}\n\n// ============================================================================\n// SINGLETON INSTANCE\n// ============================================================================\n\n/** The shared rate cache. See {@link CurrencyExchangeService} for why it is shared. */\nexport const currencyExchangeService = new CurrencyExchangeService();\n\n// Export for backward compatibility\n/** Alias for {@link currencyExchangeService}, kept for older imports. */\nexport const sharedCurrencyExchange = currencyExchangeService;\n\n// Default export\nexport default currencyExchangeService;\n"]}