IAsyncResolver

Defined in: packages/engine/src/resolvers/ResolverRegistry.ts:49

Interface for async resolvers registered by packages/plugins.

Each resolver handles a domain of async data (currency rates, weather, stock prices, etc.). The preflight() method is called BEFORE VM execution to check if all data is cached. If not, it returns an AsyncCheckResult and the engine skips the VM, returning a Pending value instead.

Properties

local?

readonly optional local?: boolean;

Defined in: packages/engine/src/resolvers/ResolverRegistry.ts:63

True for a resolver that answers from engine state and never reaches a network: it waits on a value another line will produce, or reads a table the host loaded up front. Such a resolver keeps running when the host has switched live data off (network.enabled: false); every other resolver is skipped by that setting before its preflight() is called, so no request is ever started. Leave it unset (the default) for anything that fetches. The engine’s own global-variable resolver is the built-in case that sets it.

---

namespace

readonly namespace: string;

Defined in: packages/engine/src/resolvers/ResolverRegistry.ts:51

Unique namespace for cache key scoping (e.g., “currency”, “weather”)

---

pluginFunction?

readonly optional pluginFunction?: {
  name: string;
  package: string;
};

Defined in: packages/engine/src/resolvers/ResolverRegistry.ts:71

The plugin function this resolver answers for, when it was built by name (createQueryResolver with packageName and functionName). The engine refuses to register a package whose resolver names a function the package does not declare, since the call it waits for would never come.

name

readonly name: string;

package

readonly package: string;

---

watchedOpcodes?

readonly optional watchedOpcodes?: readonly OpCode[];

Defined in: packages/engine/src/resolvers/ResolverRegistry.ts:94

The opcodes this resolver’s preflight keys on, when it keys on any.

A preflight is a scan of a program for the instructions it can act on (a plugin call, a global read, a unit name pushed as a string), and it answers null for a program that has none of them. Naming those opcodes here lets the engine give that null without calling preflight, and lets a line no registered resolver could intercept skip the preflight, and the cancellation state it sets up, altogether. Six built-in packages register resolvers, so before this every plain line paid for seven scans.

The declaration is a promise about preflight: for a program containing none of the listed opcodes it would have returned null. Where there is a choice, name the opcode an ordinary line does not carry: the currency resolver watches PUSH_STRING, which every unit name arrives as, rather than the ADD its scan also checks. Leave it unset (the default, and how an empty list is read) to be consulted for every program as before; the cost of not declaring is speed, never a missed lookup. A program that calls a plugin function is consulted with every resolver whatever it declared, see ResolverRegistry.preflightAll.

Methods

destroy()

destroy(): void;

Defined in: packages/engine/src/resolvers/ResolverRegistry.ts:116

Called when the resolver’s namespace is being unregistered. Clean up any in-flight promises, clear caches, unsubscribe.

Returns

void

---

preflight()?

optional preflight(
   tokens,
   bytecode,
   packageId,
   signal,
   queryClient
):
  | AsyncCheckResult
  | null;

Defined in: packages/engine/src/resolvers/ResolverRegistry.ts:110

Pre-flight check: called BEFORE VM execution.

Returns null if all data for this expression is cached and ready. Returns an AsyncCheckResult if async work is needed.

This method is synchronous, it only checks caches, never fetches. If data is missing, it creates a Promise and returns immediately.

Parameters

Parameter	Type	Description
tokens	Token[]	The lexed tokens for the expression
bytecode	BytecodeProgram	The compiled bytecode program
packageId	string	-
signal	AbortSignal	AbortSignal for the current evaluation
queryClient	QueryClient	-

Returns

| AsyncCheckResult | null