This site describes solve-engine as it is on main: 2.43.0, which npm does not have yet. npm installs 2.40.0, so a page may show an answer that version does not give yet.
QueryResolverOptions
Defined in: packages/engine/src/resolvers/QueryResolver.ts:36
Generic async resolver for the common “single query string in, single
Value out” shape, one CALL_PLUGIN opcode with exactly one preceding
PUSH_STRING argument, resolved via a live fetch and cached through
TanStack Query. IAsyncResolver’s own JSDoc names this exact
target (“currency rates, weather, stock prices, etc.”); this factory is
the generalization of the pattern two existing implementations already
prove out by hand, uom/CurrencyResolver.ts (a currency-specific
dual-operand variant) and examples/osrs/OsrsAsyncResolver.ts
(examples/osrs/OsrsVmHandler.ts for the synchronous read-back half)
so a new query-based package (weather, stocks, a knowledge lookup) only
needs to supply the fetch call and the response-to-Value mapping,
not reimplement bytecode scanning, cache-key management, or
Suspense/timeout/cooldown plumbing again.
Usage: call createQueryResolver once per package, register the
returned resolver via IEnginePackage.asyncResolvers, and register the
returned pluginFunction at pluginFunctionIndex via
IEnginePackage.pluginFunctions (the same CALL_PLUGIN dispatch every
other package function uses. See allocatePluginFunctionIndex() in
vm/VMBuiltins.ts).
Properties
Section titled “Properties”failureCooldownMs?
Section titled “failureCooldownMs?”optional failureCooldownMs?: number;Defined in: packages/engine/src/resolvers/QueryResolver.ts:113
How long a FAILED fetch’s error result stays cached before the next
evaluation retries it. Without this, a transient outage would either
retry on every keystroke (no cooldown) or stay failed for the full
staleTimeMs (treating the error like real data). Default 30s.
fetchQuery
Section titled “fetchQuery”fetchQuery: (query, signal) => Promise<Value>;Defined in: packages/engine/src/resolvers/QueryResolver.ts:67
Perform the live fetch for query and return the resolved Value.
Receives an AbortSignal that fires on caller cancellation OR the
timeoutMs deadline, whichever comes first, pass it to fetch().
The returned value is stamped with where it came from (see
provider) unless it already carries sources of its own, which a
package sets when it knows more than the resolver does: a historical
figure’s day, say.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
query | string |
signal | AbortSignal |
Returns
Section titled “Returns”Promise<Value>
functionName?
Section titled “functionName?”optional functionName?: string;Defined in: packages/engine/src/resolvers/QueryResolver.ts:48
The plugin function’s name, with packageName.
maxConcurrent?
Section titled “maxConcurrent?”optional maxConcurrent?: number;Defined in: packages/engine/src/resolvers/QueryResolver.ts:106
The most fetches this resolver runs at once; the rest wait their turn, in
the order they were asked for. Default 6, the number of connections a
browser opens to one host. A positive whole number, or Infinity for no
limit.
A pasted or hostile document of 500 places used to start 500 requests to one service at once, all from the reader’s own address (#696). This bounds how many run together, not how many run: the 500 still run, six at a time. A query asked for again while it waits shares the one fetch, and one whose signal aborts while it waits leaves the queue without fetching.
namespace
Section titled “namespace”namespace: string;Defined in: packages/engine/src/resolvers/QueryResolver.ts:38
Unique namespace for cache-key scoping and diagnostics (e.g. “weather”).
onError?
Section titled “onError?”optional onError?: (query, error) => Value;Defined in: packages/engine/src/resolvers/QueryResolver.ts:121
Build the Value a failed fetch resolves to. Defaults to an honest
errorValue() (matching UOM_CONVERT_TO’s CURRENCY_RATE_UNAVAILABLE
pattern in vm/VM.ts, never silently substitute a stale/wrong value
for a real failure). Override for a package that prefers a graceful
fallback value instead (e.g. OSRS’s 0 gp with a timedOut flag).
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
query | string |
error | unknown |
Returns
Section titled “Returns”packageName?
Section titled “packageName?”optional packageName?: string;Defined in: packages/engine/src/resolvers/QueryResolver.ts:46
The name of the package the resolver belongs to, with functionName:
the plugin function it answers for, named the way a parselet names it to
emitPluginCall (#717). Registration refuses the package when its
pluginFunctions does not declare that name, where the resolver would
otherwise wait for a call that never comes.
pluginFunctionIndex?
Section titled “pluginFunctionIndex?”optional pluginFunctionIndex?: number;Defined in: packages/engine/src/resolvers/QueryResolver.ts:56
The CALL_PLUGIN index this resolver watches for, the older way to name
the function, kept for the packages built on it: the same index the
package’s parselet emits and registers pluginFunction under (via
allocatePluginFunctionIndex() or pluginFunctionIndexFor()). Give
either this or packageName with functionName.
provider?
Section titled “provider?”optional provider?: string;Defined in: packages/engine/src/resolvers/QueryResolver.ts:74
Who supplies the data, recorded on every value this resolver fetches so a
host can say where a figure came from and when ("Open-Meteo", or the name
of the provider a host plugged in). Defaults to namespace. See
vm/Provenance.ts.
refetchIntervalMs?
Section titled “refetchIntervalMs?”optional refetchIntervalMs?: number;Defined in: packages/engine/src/resolvers/QueryResolver.ts:86
Cadence, in ms, for proactive background refresh: how often a value that
is on screen refetches on its own, without the reader re-evaluating.
Omit (the default) for a value that should never refresh in the background
(an immutable historical close), or that should refresh only on the next
pull. It has effect only when the host has enabled background refresh
(backgroundRefresh.enabled); otherwise every value stays pull-only. This
is independent of staleTimeMs, which continues to govern the pull path.
staleTimeMs?
Section titled “staleTimeMs?”optional staleTimeMs?: number;Defined in: packages/engine/src/resolvers/QueryResolver.ts:76
TanStack Query staleTime in ms, how long a resolved value stays cached before a re-evaluation refetches it. Default 5 minutes.
timeoutMs?
Section titled “timeoutMs?”optional timeoutMs?: number;Defined in: packages/engine/src/resolvers/QueryResolver.ts:93
Hard timeout for fetchQuery, an unresponsive API must not block
re-evaluation indefinitely. Default 10s. The clock starts when the fetch
does, not while it waits for a slot (see maxConcurrent), and the
wait ends at the deadline even for a fetchQuery that ignores its signal.