solve-engine 2.2.0 → 2.4.0

package/dist/chunk-ZCNBT44X.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/resolvers/ResolverRegistry.ts"],"names":["ResolverRegistry","resolver","namespace","queryClient","tokens","bytecode","packageId","signal","result"],"mappings":"aAuEO,IAAMA,EAAN,KAAuB,CAAvB,WAAA,EAAA,CACN,IAAA,CAAQ,UAAY,IAAI,IAAA,CAWxB,QAAA,CAASC,CAAAA,CAAgC,CAEpC,IAAA,CAAK,SAAA,CAAU,GAAA,CAAIA,CAAAA,CAAS,SAAS,CAAA,GACxC,OAAA,CAAQ,IAAA,CACP,CAAA,8BAAA,EAAiCA,EAAS,SAAS,CAAA,+FAAA,EAExCA,CAAAA,CAAS,SAAS,YAAYA,CAAAA,CAAS,SAAS,CAAA,0EAAA,CAE5D,CAAA,CACA,KAAK,SAAA,CAAU,GAAA,CAAIA,CAAAA,CAAS,SAAS,EAAG,OAAA,EAAQ,CAAA,CAEjD,IAAA,CAAK,SAAA,CAAU,IAAIA,CAAAA,CAAS,SAAA,CAAWA,CAAQ,EAChD,CAMA,UAAA,CAAWC,CAAAA,CAAmBC,CAAAA,CAAiC,CAC9D,IAAMF,CAAAA,CAAW,IAAA,CAAK,SAAA,CAAU,GAAA,CAAIC,CAAS,CAAA,CACzCD,CAAAA,GACHA,CAAAA,CAAS,OAAA,GACT,IAAA,CAAK,SAAA,CAAU,MAAA,CAAOC,CAAS,GAI5BC,CAAAA,EACHA,CAAAA,CAAY,aAAA,CAAc,CAAE,SAAU,CAACD,CAAS,CAAE,CAAC,EAErD,CASA,YAAA,CAAaE,CAAAA,CAAiBC,CAAAA,CAA2BC,EAAmBC,CAAAA,CAAqBJ,CAAAA,CAAmD,CACnJ,IAAA,IAAWF,KAAY,IAAA,CAAK,SAAA,CAAU,MAAA,EAAO,CAAG,CAC/C,GAAI,CAACA,CAAAA,CAAS,SAAA,CAAW,SACzB,IAAMO,CAAAA,CAASP,CAAAA,CAAS,SAAA,CAAUG,EAAQC,CAAAA,CAAUC,CAAAA,CAAWC,CAAAA,CAAQJ,CAAW,EAClF,GAAIK,CAAAA,CAAQ,OAAOA,CACpB,CACA,OAAO,IACR,CAMA,GAAA,CAAIN,EAA+C,CAClD,OAAO,IAAA,CAAK,SAAA,CAAU,IAAIA,CAAS,CACpC,CAGA,IAAI,MAAe,CAClB,OAAO,IAAA,CAAK,SAAA,CAAU,IACvB,CAKA,GAAA,CAAIA,CAAAA,CAA4B,CAC/B,OAAO,IAAA,CAAK,SAAA,CAAU,GAAA,CAAIA,CAAS,CACpC,CAMA,KAAA,EAAc,CACb,IAAA,IAAWD,KAAY,IAAA,CAAK,SAAA,CAAU,MAAA,EAAO,CAC5CA,EAAS,OAAA,EAAQ,CAElB,KAAK,SAAA,CAAU,KAAA,GAChB,CACD","file":"chunk-ZCNBT44X.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"]}