solve-engine 1.0.1 → 1.1.0

package/dist/worker.d.cts

@@ -0,0 +1,509 @@
+import { E as EngineConfig } from './Configuration-C9W8tJv_.cjs';
+import { U as UnifiedParsingOptions, I as IEnginePackage, N as ParsedLine, O as ParsingResult } from './PackageRegistry-BHWJP83F.cjs';
+import { F as FormattingSettings } from './FormattingSettings-CJHyxcYu.cjs';
+import { E as EngineError } from './EngineError-B61GS1jp.cjs';
+import { b as ValueType, f as ColourFormat, V as Value } from './Value-BUi1RA3S.cjs';
+import { a as DiagnosticReportJSON } from './pipeline-CtfJtPQc.cjs';
+import { S as SerializedEngineError } from './WorkerError-gzmaopj2.cjs';
+import './Parselet-BHcgK9S7.cjs';
+import './BytecodeBuilder-Bp9xeTmX.cjs';
+import './Token-B1hdkedD.cjs';
+import './variables.cjs';
+import './Lexer-BOs7euZe.cjs';
+import './resolvers.cjs';
+import '@tanstack/query-core';
+import './TokenNormalizer-DRc1Js1V.cjs';
+import './ScopeManager-8vf02dwj.cjs';
+
+/**
+ * The seam between the harness and whatever actually carries messages.
+ *
+ * Both the client (`worker/client.ts`) and the runtime (`worker/runtime.ts`)
+ * talk to a {@link WorkerTransport} and nothing more, so the same code drives a
+ * browser `Worker`, a Node `worker_threads` port, or an in-process pair. The
+ * three factory functions below adapt each of those onto the interface; a host
+ * with a transport this file does not cover can implement the three methods
+ * directly.
+ */
+/**
+ * A bidirectional message channel with a single receive handler.
+ *
+ * `onMessage` registers the one handler the harness needs; calling it again
+ * replaces the previous handler. `terminate` tears the channel down and is safe
+ * to call more than once.
+ */
+interface WorkerTransport {
+    /** Send one message to the other end. The message must be clone-safe. */
+    postMessage(message: unknown): void;
+    /** Register the handler that receives messages from the other end. */
+    onMessage(handler: (message: unknown) => void): void;
+    /** Tear the channel down. Idempotent. */
+    terminate(): void;
+}
+/**
+ * A pair of linked in-process transports.
+ *
+ * `client` and `host` are two ends of one channel: a message posted on either
+ * is cloned at post time and delivered to the other on a microtask, so delivery
+ * is asynchronous (as a real worker's is) but deterministic (no timers, no I/O).
+ * Wire `client` into {@link createWorkerEngine} and `host` into
+ * {@link startWorkerRuntime} to run the whole protocol, DTO serialisation and
+ * cancellation included, without a second thread. This is the transport tests
+ * use, and a fit for a host that wants the message-passing shape on one thread.
+ */
+declare function createLinkedTransports(): {
+    client: WorkerTransport;
+    host: WorkerTransport;
+};
+/** The `postMessage`/`onmessage`/event-listener shape a browser `Worker`, a worker's `self`, or a DOM `MessagePort` presents. */
+interface EventTargetLike {
+    postMessage(message: unknown): void;
+    addEventListener?(type: "message", handler: (event: {
+        data: unknown;
+    }) => void): void;
+    onmessage?: ((event: {
+        data: unknown;
+    }) => void) | null;
+    terminate?(): void;
+    close?(): void;
+    start?(): void;
+}
+/**
+ * Adapt a browser-style message target onto a {@link WorkerTransport}.
+ *
+ * Covers the main-side `Worker`, the worker global `self`, and a DOM
+ * `MessagePort`: each posts with `postMessage` and receives a `MessageEvent`
+ * whose `data` is the payload. A `MessagePort` is `start`ed here so it begins
+ * dispatching. On the main side pass a `Worker`; inside a browser worker pass
+ * `self`.
+ */
+declare function eventTargetTransport(target: EventTargetLike): WorkerTransport;
+/** The `postMessage`/`on("message")` shape a Node `worker_threads` `Worker`, `parentPort`, or `MessagePort` presents. */
+interface MessagePortLike {
+    postMessage(message: unknown): void;
+    on(event: "message", handler: (message: unknown) => void): void;
+    terminate?(): void;
+    close?(): void;
+}
+/**
+ * Adapt a Node `worker_threads` port onto a {@link WorkerTransport}.
+ *
+ * Covers the main-side `Worker`, the worker's `parentPort`, and a
+ * `worker_threads` `MessagePort`: each posts with `postMessage` and emits a
+ * `"message"` event whose argument IS the payload (no `.data` wrapper, unlike
+ * the DOM). On the main side pass the `Worker`; inside the worker pass
+ * `parentPort`.
+ */
+declare function messagePortTransport(port: MessagePortLike): WorkerTransport;
+
+/**
+ * The serialisable result shapes the worker harness posts back across the
+ * boundary, one clone-safe projection per public result type.
+ *
+ * A raw {@link Value} cannot be posted: it carries `bigint`, class-instance
+ * matrix cells, symbolic trees, and the exact-decimal/rational sidecars, none
+ * of which structured cloning reproduces faithfully (and `bigint` alone breaks
+ * `JSON.stringify`). These interfaces are what crosses instead. Every field is
+ * a string, number, boolean, or an object of those, so a whole
+ * {@link SerializedParsingResult} survives both `structuredClone` (what
+ * `postMessage` uses) and `JSON` (what a host may cache or log), which is the
+ * property `worker/serialize.ts` is built to guarantee.
+ */
+
+/**
+ * A matrix flattened for transport.
+ *
+ * `cells` is column-major, the same order as {@link MatrixData.data}, so a host
+ * indexes it identically. Finite numeric and boolean cells pass through as
+ * themselves; a symbolic cell (a free-variable algebraic entry) becomes its
+ * formatted string, since a `SymbolicNode` is a class instance that would not
+ * survive the clone; and a non-finite numeric cell (`Infinity`/`-Infinity`/`NaN`,
+ * from e.g. a `[1/0, 2]`) becomes the same string tag the scalar
+ * {@link SerializedValue.nonFinite} uses, because a raw non-finite number does
+ * not survive `JSON` (it becomes `null`). A host reads a numeric string cell
+ * back with `Number(cell)`.
+ */
+interface SerializedMatrix {
+    rows: number;
+    cols: number;
+    cells: Array<number | boolean | string>;
+    hasSymbolic: boolean;
+}
+/**
+ * A single evaluated value, projected onto clone-safe fields.
+ *
+ * `text` is the formatted display string a host renders, and `number` is the
+ * numeric reading ({@link Value.toNumber}), present for every type (0 where a
+ * value has no numeric meaning, matching the engine's own convention). The
+ * type-specific fields below carry the rest of the payload where it does not
+ * fit in a plain number: `bigint` as a base-ten string, `matrix` and `range`
+ * as their own shapes.
+ */
+interface SerializedValue {
+    /** The {@link ValueType} discriminant (a number), so a host can branch on the kind. */
+    type: ValueType;
+    /** The formatted display string, what a host renders against the line. */
+    text: string;
+    /**
+     * The numeric reading via {@link Value.toNumber}: 0 for non-numeric types.
+     * Always finite so the DTO survives `JSON` (which turns `Infinity`/`NaN` into
+     * `null`): when the true reading is non-finite this is 0 and {@link nonFinite}
+     * names the real value. Read `nonFinite ? Number(nonFinite) : number` to
+     * recover it.
+     */
+    number: number;
+    /**
+     * Set only when the numeric reading is non-finite (`1/0`, `0/0`, an overflow),
+     * to a string a host turns back into the value with `Number(...)`. Carried
+     * separately because a non-finite number cannot cross `JSON`; see {@link number}.
+     */
+    nonFinite?: "Infinity" | "-Infinity" | "NaN";
+    /** Unit annotation for unit-of-measurement and non-decimal-base values, when present. */
+    unit?: string;
+    /** Base-ten string for a `bigint` payload, so no `BigInt` ever crosses `JSON`. */
+    bigint?: string;
+    /** Matrix shape and cells, present only for {@link ValueType.Matrix}. */
+    matrix?: SerializedMatrix;
+    /** Inclusive integer range bounds, present only for {@link ValueType.Range}. */
+    range?: {
+        min: number;
+        max: number;
+    };
+    /**
+     * Colour payload, present only for {@link ValueType.Colour}. `hex` is the
+     * canonical `#rrggbb`/`#rrggbbaa`; `r`,`g`,`b` are 0-255, `a` is 0-1;
+     * `format` is the authored form; `css` is a render-ready CSS string, so a
+     * host draws a swatch (e.g. `background: css`) with no recomputation.
+     */
+    colour?: {
+        hex: string;
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+        format: ColourFormat;
+        css: string;
+    };
+    /** Whether an async fallback timed out, carried through when the engine set it. */
+    timedOut?: boolean;
+}
+/**
+ * One inline solve and its serialised result, mirroring
+ * {@link InlineSolvePosition} with the live `Value` replaced by a
+ * {@link SerializedValue}.
+ */
+interface SerializedInlineSolve {
+    start: number;
+    end: number;
+    expression: string;
+    lineNumber: number;
+    columnNumber: number;
+    result: SerializedValue | null;
+    error: string | null;
+}
+/**
+ * One parsed line, mirroring {@link ParsedLine} with every live `Value`
+ * replaced by a {@link SerializedValue}.
+ */
+interface SerializedParsedLine {
+    lineNumber: number;
+    text: string;
+    startPosition: number;
+    endPosition: number;
+    isEmpty: boolean;
+    hasInlineSolves: boolean;
+    inlineSolves: SerializedInlineSolve[];
+    expression: string | null;
+    result: SerializedValue | null;
+    error: string | null;
+}
+/**
+ * A whole parsed document, mirroring {@link ParsingResult}.
+ *
+ * `diagnostics` is already the JSON form the engine emits ({@link
+ * DiagnosticReportJSON}), so it crosses unchanged when a host asked for it.
+ */
+interface SerializedParsingResult {
+    lines: SerializedParsedLine[];
+    totalLines: number;
+    errors: string[];
+    diagnostics?: DiagnosticReportJSON;
+}
+
+/**
+ * The main-side half of the harness: an async proxy of the core evaluate
+ * methods.
+ *
+ * {@link createWorkerEngine} performs the init handshake and resolves once the
+ * worker's engine is built, so the returned {@link WorkerEngine} is ready to
+ * call. Each call stamps a request id, tracks the pending promise, and settles
+ * it when the matching answer arrives, so several requests can be outstanding at
+ * once. An `AbortSignal` rejects the local promise and posts a `cancel` for the
+ * same id, mapping keystroke-level cancellation onto the boundary rather than
+ * re-inventing it.
+ */
+
+/** Configuration for {@link createWorkerEngine}. */
+interface WorkerEngineOptions {
+    /** The channel to the worker runtime. See `worker/transport.ts` for adapters. */
+    transport: WorkerTransport;
+    /** Locale for keywords and number formatting; defaults to English worker-side. */
+    localeCode?: string;
+    /** Whether the worker builds its engine with diagnostics enabled. */
+    diagnosticMode?: boolean;
+    /** Partial engine configuration, merged with the defaults worker-side. */
+    config?: Partial<EngineConfig>;
+    /**
+     * Names of built-in packages the worker should register. Omitted registers
+     * them all. Names rather than the packages themselves, since a package
+     * carries functions that cannot cross a `postMessage` boundary; a host with
+     * a custom package bakes it into its own worker entry and selects it here by
+     * name.
+     */
+    packages?: string[];
+    /** Formatting settings the worker uses when it renders a DTO's display text. */
+    formatting?: FormattingSettings;
+}
+/** Per-call options common to every proxied method. */
+interface WorkerCallOptions {
+    /** Abort the request. Rejects the returned promise and cancels the work worker-side. */
+    signal?: AbortSignal;
+}
+/**
+ * One line whose result changed after a live value resolved worker-side, carried
+ * as its freshly re-evaluated {@link SerializedValue}. The value the host renders
+ * against `lineNumber`, recovered worker-side so the main thread needs no further
+ * round-trip to display it.
+ */
+interface WorkerAsyncUpdate {
+    lineNumber: number;
+    value: SerializedValue;
+}
+/**
+ * A live-data resolution that failed worker-side. `error` is the same structured
+ * {@link EngineError} an in-process resolver failure would surface, rebuilt from
+ * its transported form, so a host branches on `code`/`category` as it always has.
+ */
+interface WorkerAsyncError {
+    queryKey: string;
+    packageId: string;
+    error: EngineError;
+}
+/**
+ * An async proxy of {@link ExpressionEngine}'s core evaluate methods.
+ *
+ * Each method mirrors its synchronous counterpart but returns a Promise of the
+ * serialisable DTO rather than a live `Value`, and accepts an `AbortSignal`.
+ */
+interface WorkerEngine {
+    /** Parse a whole document off-thread. Mirrors `ExpressionEngine.parseDocument`. */
+    parseDocument(input: string, options?: UnifiedParsingOptions & WorkerCallOptions): Promise<SerializedParsingResult>;
+    /** Evaluate an array of lines off-thread. Mirrors `ExpressionEngine.evaluateLines`. */
+    evaluateLines(lines: string[], options?: WorkerCallOptions): Promise<SerializedParsedLine[]>;
+    /** Evaluate a single expression off-thread. Mirrors `ExpressionEngine.evaluateExpression`. */
+    evaluateExpression(expression: string, options?: WorkerCallOptions): Promise<SerializedValue[]>;
+    /**
+     * Subscribe to live-data resolutions that land after a request already
+     * answered.
+     *
+     * A currency, weather or historical-rate value resolves inside the worker some
+     * time after `parseDocument` returned its pending result. When it does, the
+     * affected lines are re-evaluated worker-side and their fresh values arrive
+     * here as one batch. This is a subscription rather than a per-request promise
+     * because a resolution is tied to no single request: it belongs to whichever
+     * document is current when the value lands. Returns an unsubscribe function.
+     */
+    onResolved(listener: (lines: WorkerAsyncUpdate[]) => void): () => void;
+    /**
+     * Subscribe to live-data resolutions that failed. Returns an unsubscribe
+     * function. See {@link onResolved}; this is its failure channel.
+     */
+    onAsyncError(listener: (error: WorkerAsyncError) => void): () => void;
+    /** Reject every in-flight request and tear the transport down. Idempotent. */
+    terminate(): void;
+}
+/**
+ * Build a worker-backed engine and wait for it to be ready.
+ *
+ * ```ts
+ * const { client, host } = createLinkedTransports();
+ * startWorkerRuntime(host);
+ * const engine = await createWorkerEngine({ transport: client });
+ * const result = await engine.parseDocument(text);
+ * ```
+ *
+ * In production `client` wraps a real `Worker` (see `eventTargetTransport` /
+ * `messagePortTransport`), and `startWorkerRuntime` runs inside that worker.
+ */
+declare function createWorkerEngine(options: WorkerEngineOptions): Promise<WorkerEngine>;
+
+/**
+ * The worker-side half of the harness: it owns an {@link ExpressionEngine} and
+ * answers the protocol.
+ *
+ * {@link startWorkerRuntime} is transport-agnostic, so the same function runs
+ * behind a browser `Worker`, a Node `worker_threads` port, or an in-process
+ * link. A host's worker entry file is two lines: adapt the environment onto a
+ * {@link WorkerTransport} and call this.
+ *
+ * The runtime never posts a raw {@link Value}. Every result is projected onto a
+ * DTO first (`worker/serialize.ts`), and every failure is caught and flattened
+ * into a structured error, so a worker-side throw reaches the caller as an
+ * `EngineError` rather than a lost promise.
+ */
+
+/** Options a host bakes into its own worker entry, chiefly its custom packages. */
+interface WorkerRuntimeOptions {
+    /**
+     * The packages available to register, defaulting to {@link BUILTIN_PACKAGES}.
+     * A host with its own package authors a worker entry that passes them here,
+     * then selects among them by name from the main side. This is how a
+     * function-carrying package reaches the worker: baked into its bundle, never
+     * posted across the boundary.
+     */
+    packages?: IEnginePackage[];
+}
+/**
+ * Attach the runtime to a transport and start serving.
+ *
+ * Returns a teardown function that clears the engine and detaches, for a host
+ * that reuses a transport or shuts a worker down cleanly.
+ */
+declare function startWorkerRuntime(transport: WorkerTransport, options?: WorkerRuntimeOptions): () => void;
+
+/**
+ * Turn live engine results into the clone-safe DTOs the worker harness posts.
+ *
+ * These functions run on the worker side, just before a result crosses the
+ * boundary, and are also what the main side re-runs on a synchronous result to
+ * compare the two paths in tests. They are pure and deterministic given the
+ * same {@link FormattingSettings}, so a value serialised on either side is
+ * byte-for-byte the same DTO.
+ */
+
+/**
+ * Project a {@link Value} onto a {@link SerializedValue}.
+ *
+ * `text` and `number` are set for every value; the type-specific fields are
+ * added only where the payload needs them, so the DTO stays minimal and a
+ * deep-equal between the two evaluation paths does not trip on a property one
+ * side left `undefined`.
+ */
+declare function serializeValue(value: Value, settings?: FormattingSettings): SerializedValue;
+/** Project a parsed line onto its DTO, serialising its result and every inline solve. */
+declare function serializeParsedLine(line: ParsedLine, settings?: FormattingSettings): SerializedParsedLine;
+/** Project a whole parsing result onto its DTO. */
+declare function serializeParsingResult(result: ParsingResult, settings?: FormattingSettings): SerializedParsingResult;
+
+/**
+ * The message protocol spoken across the worker boundary.
+ *
+ * One request-id space runs both directions: the main side stamps every
+ * `init`, `request` and `cancel` with an id, and the worker echoes that id back
+ * on the matching `ready`, `result` or `error`, so a caller can correlate an
+ * answer with the call that asked for it even with several requests in flight.
+ * Every payload here is clone-safe by construction (strings, numbers, plain
+ * option objects, and the DTOs from `worker/dto.ts`), so the whole protocol
+ * survives `postMessage`.
+ */
+
+/** The core evaluate methods the harness proxies. */
+type WorkerMethod = "parseDocument" | "evaluateLines" | "evaluateExpression";
+/** Build the worker engine, sent once before any request. */
+interface InitMessage {
+    kind: "init";
+    id: number;
+    /** Locale for keywords and number formatting; defaults to English worker-side. */
+    localeCode?: string;
+    /** Whether to build the engine with its diagnostic pipeline enabled. */
+    diagnosticMode?: boolean;
+    /** Partial engine configuration, merged with the defaults worker-side. */
+    config?: Partial<EngineConfig>;
+    /**
+     * Names of built-in packages to register, resolved against the runtime's
+     * available set. Omitted registers them all. Names rather than the packages
+     * themselves, since an `IEnginePackage` carries functions that cannot cross
+     * a `postMessage` boundary.
+     */
+    packages?: string[];
+    /** Formatting settings the runtime uses when it renders a DTO's display text. */
+    formatting?: FormattingSettings;
+}
+/** Invoke one proxied method. `args` positionally matches the method's own signature. */
+interface RequestMessage {
+    kind: "request";
+    id: number;
+    method: WorkerMethod;
+    args: WorkerRequestArgs;
+}
+/**
+ * The positional arguments for each method, kept as a union so a request is
+ * type-checked against the method it names. An `AbortSignal` is never in here:
+ * it stays main-side and drives a {@link CancelMessage} instead.
+ */
+type WorkerRequestArgs = [input: string, options?: UnifiedParsingOptions] | [lines: string[]] | [expression: string];
+/** Ask the worker to abort the request with this id. */
+interface CancelMessage {
+    kind: "cancel";
+    id: number;
+}
+/** Everything the main side sends. */
+type MainToWorkerMessage = InitMessage | RequestMessage | CancelMessage;
+/** The engine finished building and is ready to serve requests. */
+interface ReadyMessage {
+    kind: "ready";
+    id: number;
+}
+/** A request or init succeeded; `value` is the serialised DTO for that method. */
+interface ResultMessage {
+    kind: "result";
+    id: number;
+    value: unknown;
+}
+/** A request or init failed; `error` is the structured failure, flattened for transport. */
+interface ErrorMessage {
+    kind: "error";
+    id: number;
+    error: SerializedEngineError;
+}
+/**
+ * One line whose result changed after a later async resolution settled, carried
+ * as its freshly re-evaluated {@link SerializedValue}. The value, not the line
+ * number alone: the engine's own event names only the affected lines and leaves
+ * the resolved value in its cache, so the worker re-reads each line before it
+ * posts, and the main side receives a value it can render without a round-trip.
+ */
+interface AsyncResolvedLine {
+    lineNumber: number;
+    value: SerializedValue;
+}
+/**
+ * A later async resolution settled, and these lines now carry live data.
+ *
+ * Unlike a {@link ResultMessage} this has no `id`: a resolution is not the
+ * answer to one request, it arrives whenever the live value lands, so it is a
+ * broadcast the main side routes to its subscribers rather than to a pending
+ * promise. `lines` is a batch because the engine collapses every resolution that
+ * settles in one tick into a single update.
+ */
+interface AsyncUpdateMessage {
+    kind: "async-update";
+    lines: AsyncResolvedLine[];
+}
+/**
+ * A later async resolution failed. Carries the query and package that failed,
+ * plus the structured error flattened the same way a {@link ErrorMessage} is, so
+ * the main side reads the same `code`/`category`/`message` it would in-process.
+ * Like {@link AsyncUpdateMessage} it has no `id`: a failed resolution is a
+ * broadcast, not the rejection of one request's promise.
+ */
+interface AsyncErrorMessage {
+    kind: "async-error";
+    queryKey: string;
+    packageId: string;
+    error: SerializedEngineError;
+}
+/** Everything the worker sends back. */
+type WorkerToMainMessage = ReadyMessage | ResultMessage | ErrorMessage | AsyncUpdateMessage | AsyncErrorMessage;
+
+export { type AsyncErrorMessage, type AsyncResolvedLine, type AsyncUpdateMessage, type CancelMessage, type ErrorMessage, type InitMessage, type MainToWorkerMessage, type ReadyMessage, type RequestMessage, type ResultMessage, type SerializedInlineSolve, type SerializedMatrix, type SerializedParsedLine, type SerializedParsingResult, type SerializedValue, type WorkerAsyncError, type WorkerAsyncUpdate, type WorkerCallOptions, type WorkerEngine, type WorkerEngineOptions, type WorkerMethod, type WorkerRequestArgs, type WorkerRuntimeOptions, type WorkerToMainMessage, type WorkerTransport, createLinkedTransports, createWorkerEngine, eventTargetTransport, messagePortTransport, serializeParsedLine, serializeParsingResult, serializeValue, startWorkerRuntime };