wenmar-open 0.1.0 → 0.2.0

package/README.md

@@ -3,6 +3,7 @@
 A typed client for the [Wenmar Open](https://open.wenmarpro.com) API: VIN decoding and a year, make, model, trim and engine catalog for auto repair shops. The API needs no key and no account.
 
 - No dependencies. It uses the platform's `fetch`.
+- An [offline mode](#offline) that decodes from a data file with no network.
 - Runs in Node 20 and later, browsers, Cloudflare Workers, Deno and Bun.
 - Types are generated from the API's OpenAPI description.
 
@@ -175,6 +176,141 @@ Answers change only when the data does, about once a month. `open.meta()` return
 
 One address may make 600 requests a minute. A server that calls the API for many users shares one address, so cache catalog answers there. To decode a list of VINs, use `decodeVins`: a batch of 50 counts as one request.
 
+## Offline
+
+`wenmar-open/offline` answers the same questions with no network. It runs the same decoder the API runs, compiled to WebAssembly and shipped inside this package, over a Wenmar Open data file: a plain SQLite database of about 167 MB. The methods, their answers and the error codes are those of `WenmarOpen`, with three more codes for the data ([below](#switching-between-the-api-and-the-data-file)), so code written for one works with the other.
+
+The hosted client does not load any of this. An application that imports only `wenmar-open` gets the small client and nothing else.
+
+### In Node
+
+```bash
+npm install wenmar-open wenmar-open-data
+```
+
+`wenmar-open-data` is the data file as an npm package. It is 49 MB to download and 167 MB on disk, and a new version is published each month.
+
+```ts
+import { WenmarOpenError } from "wenmar-open/offline";
+import { openOffline } from "wenmar-open/offline/node";
+
+const open = await openOffline();
+
+try {
+  const vehicle = await open.decodeVin("KM8K2CAB4PU001140");
+  console.log(vehicle.year, vehicle.make, vehicle.model);
+  console.log(await open.models({ make: "honda", year: 2019 }));
+} catch (error) {
+  if (error instanceof WenmarOpenError) console.error(error.code, error.message);
+  else throw error;
+} finally {
+  open.close();
+}
+```
+
+`openOffline()` uses Node's own SQLite, so it needs Node 22.16 or later. It opens the file read-only and checks it before it returns. To read a file from somewhere else, such as one downloaded with `wenmar-open data pull`, pass its path:
+
+```ts
+import { openOffline } from "wenmar-open/offline/node";
+
+const open = await openOffline({ path: "/var/lib/wenmar-open/wenmar-open-2026.09.sqlite3" });
+console.log((await open.meta()).data_version);
+```
+
+On Node 20, or to use a database you opened yourself, give the client a store. `syncStore` takes a `DatabaseSync` of `node:sqlite` or a database of `better-sqlite3`:
+
+```js
+import Database from "better-sqlite3";
+import { path } from "wenmar-open-data";
+import { WenmarOpenOffline, syncStore } from "wenmar-open/offline";
+
+const database = new Database(path, { readonly: true });
+const open = new WenmarOpenOffline({ store: syncStore(database) });
+```
+
+### Switching between the API and the data file
+
+Both clients have the same methods, so the choice can be one line:
+
+```ts
+import { WenmarOpen } from "wenmar-open";
+import type { VinDecode } from "wenmar-open";
+import type { WenmarOpenOffline } from "wenmar-open/offline";
+import { openOffline } from "wenmar-open/offline/node";
+
+async function client(offline: boolean): Promise<WenmarOpen | WenmarOpenOffline> {
+  return offline ? openOffline() : new WenmarOpen();
+}
+
+const open = await client(true);
+const vehicle: VinDecode = await open.decodeVin("KM8K2CAB4PU001140");
+console.log(vehicle.catalog?.vehicle_id);
+```
+
+What differs offline:
+
+- `error.status` is always `undefined`: there is no HTTP answer. Branch on `error.code`.
+- Three more codes: `no_data` (no data file where one was looked for), `data_invalid` (the database is not a data file this version reads) and `store_error` (the database failed while it was read, including while it was first opened, so a retry may succeed; `data_invalid` is for rows that were read and are not a data file, and for a schema version this client does not read).
+- `search` reads the text as a year, a make, a model and a submodel, in that order. The API also finds a model from its words in any order, with an index the data file does not have. `search({ q: "civic type r" })` finds the Civic Type R in both; `search({ q: "type r" })` finds it only through the API.
+- `meta().server_version` is the version of this package.
+- `timeoutMs` and `signal` are checked each time the client goes back to the database, not while the database is working. There is no time limit unless you set one.
+- The current year, which bounds the model years a VIN can have, comes from the device's clock. Pass `currentYear` to set it.
+
+### In Cloudflare Workers
+
+A Worker cannot carry a 167 MB file. Import the data into a D1 database once (see the [`wenmar-open-data` README](https://www.npmjs.com/package/wenmar-open-data)), or use the hosted API.
+
+```js
+import { WenmarOpenOffline, d1Store } from "wenmar-open/offline";
+import wasm from "wenmar-open/offline.wasm";
+
+let open;
+
+export default {
+  async fetch(request, env) {
+    open ??= new WenmarOpenOffline({ store: d1Store(env.DB), wasm });
+    const vin = new URL(request.url).pathname.slice(1);
+    return Response.json(await open.decodeVin(vin));
+  },
+};
+```
+
+Workers do not compile WebAssembly from bytes, so the module is imported as a file and passed as `wasm`. Everywhere else the option is left out.
+
+A decode reads D1 6 or 7 times and runs 10 to 15 statements, each of which counts as one D1 query. The first question an isolate answers also reads about 12,000 rows of makes, once. `years()` reads every model-year row of the catalog, about 490,000, on every call: keep its answer.
+
+### A store of your own
+
+Anything that can run a `SELECT` on the data file can be a store: an object with one method, which is given a list of statements and returns the rows of each, in order, as arrays of values. It may return them at once or as a promise.
+
+```ts
+import { WenmarOpenOffline } from "wenmar-open/offline";
+import type { Statement, Store } from "wenmar-open/offline";
+
+declare function run(sql: string, params: readonly (string | number | null)[]): Promise<unknown[][]>;
+
+const store: Store = {
+  query: (statements: readonly Statement[]) => Promise.all(statements.map(({ sql, params }) => run(sql, params))),
+};
+export const open = new WenmarOpenOffline({ store });
+```
+
+Rows must be arrays, not objects keyed by column name: two columns of one statement may share a name. Integers may be numbers or BigInts.
+
+### Data versions
+
+A version of `wenmar-open` reads data files of one schema version, and `wenmar-open-data`'s major version is that schema version: `wenmar-open-data@3.202609.0` is the data of September 2026 in schema version 3. A file of another schema version is refused with `data_invalid` and a message naming both versions.
+
+| `wenmar-open` | reads `wenmar-open-data` |
+|---|---|
+| 0.2 | 3.x |
+
+### Size
+
+The decoder is 450 kB of WebAssembly (163 kB compressed). The package holds it twice, as a file and as text inside a module, so the package is 1.1 MB unpacked. None of it is loaded by `import "wenmar-open"`.
+
+In a browser the page's content security policy must allow WebAssembly (`'wasm-unsafe-eval'`). The data file is too large to send to a browser; use the hosted API there.
+
 ## CommonJS
 
 The package is an ES module. `require("wenmar-open")` works in Node 20.19 and later and in Node 22.12 and later. In older Node 20 releases use `await import("wenmar-open")`.

package/dist/batch.d.ts

@@ -0,0 +1,5 @@
+import type { BatchItem, ErrorBody } from "./types.js";
+/** The most VINs decoded in one batch. */
+export declare const MAX_BATCH = 50;
+/** Whether an item of a batch is the error for its VIN and not a decode. */
+export declare function isBatchError(item: BatchItem): item is ErrorBody;

package/dist/batch.js

@@ -0,0 +1,7 @@
+/** The most VINs decoded in one batch. */
+export const MAX_BATCH = 50;
+/** Whether an item of a batch is the error for its VIN and not a decode. */
+export function isBatchError(item) {
+    const error = item.error;
+    return typeof error === "object" && error !== null && !Array.isArray(error);
+}

package/dist/client.d.ts

@@ -1,10 +1,8 @@
-import type { BatchItem, EngineOption, EnginesQuery, Entry, ErrorBody, Make, MakesQuery, Meta, Model, ModelsQuery, SearchQuery, Submodel, SubmodelsQuery, VinDecode, YearsQuery } from "./types.js";
+import type { BatchItem, EngineOption, EnginesQuery, Entry, Make, MakesQuery, Meta, Model, ModelsQuery, SearchQuery, Submodel, SubmodelsQuery, VinDecode, YearsQuery } from "./types.js";
 /** The hosted API. */
 export declare const DEFAULT_BASE_URL = "https://open.wenmarpro.com";
 /** How long a request may take before it fails with `timeout`. */
 export declare const DEFAULT_TIMEOUT_MS = 10000;
-/** The most VINs the API decodes in one batch. */
-export declare const MAX_BATCH = 50;
 /** What the client asks of a `fetch`: the part of the standard it uses. */
 export interface FetchInit {
     method: string;
@@ -47,8 +45,6 @@ export interface DecodeOptions extends RequestOptions {
     /** Use this model year instead of working it out from the VIN. */
     year?: number;
 }
-/** Whether an item of a batch is the error for its VIN and not a decode. */
-export declare function isBatchError(item: BatchItem): item is ErrorBody;
 /** A client for the Wenmar Open API. It keeps no state between requests. */
 export declare class WenmarOpen {
     #private;

package/dist/client.js

@@ -1,10 +1,9 @@
+import { MAX_BATCH } from "./batch.js";
 import { WenmarOpenError, parseRetryAfter } from "./errors.js";
 /** The hosted API. */
 export const DEFAULT_BASE_URL = "https://open.wenmarpro.com";
 /** How long a request may take before it fails with `timeout`. */
 export const DEFAULT_TIMEOUT_MS = 10_000;
-/** The most VINs the API decodes in one batch. */
-export const MAX_BATCH = 50;
 function queryString(query) {
     const params = new URLSearchParams();
     for (const [name, value] of Object.entries((query ?? {}))) {
@@ -34,10 +33,6 @@ function segment(field, value) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** Whether an item of a batch is the error for its VIN and not a decode. */
-export function isBatchError(item) {
-    return isRecord(item.error);
-}
 /** A client for the Wenmar Open API. It keeps no state between requests. */
 export class WenmarOpen {
     baseUrl;

package/dist/errors.d.ts

@@ -11,11 +11,22 @@ export type ApiErrorCode = "invalid_vin" | "validation_failed" | "not_found" | "
  *   error page and a sign-in page from a captive portal both end up here.
  */
 export type ClientErrorCode = "network" | "timeout" | "aborted" | "bad_response";
+/**
+ * The codes of `wenmar-open/offline`, for failures of the data and not of
+ * the question. The command-line tool uses `no_data` and `data_invalid` for
+ * the same things.
+ *
+ * - `no_data`: there is no data file where one was looked for.
+ * - `data_invalid`: the database is not a data file this version reads: it
+ *   has another schema version, or a row is not what the layout says.
+ * - `store_error`: the database failed while it was being read.
+ */
+export type OfflineErrorCode = "no_data" | "data_invalid" | "store_error";
 /**
  * Every code known when this version was published. The API may add codes,
  * so `code` is typed to accept any string while still completing these.
  */
-export type ErrorCode = ApiErrorCode | ClientErrorCode | (string & {});
+export type ErrorCode = ApiErrorCode | ClientErrorCode | OfflineErrorCode | (string & {});
 export interface WenmarOpenErrorInit {
     code: ErrorCode;
     message: string;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, MAX_BATCH, WenmarOpen, isBatchError, } from "./client.js";
+export { MAX_BATCH, isBatchError } from "./batch.js";
+export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, WenmarOpen } from "./client.js";
 export type { ClientOptions, DecodeOptions, FetchInit, FetchLike, FetchResponse, RequestOptions, } from "./client.js";
 export { WenmarOpenError } from "./errors.js";
-export type { ApiErrorCode, ClientErrorCode, ErrorCode, WenmarOpenErrorInit } from "./errors.js";
+export type { ApiErrorCode, ClientErrorCode, ErrorCode, OfflineErrorCode, WenmarOpenErrorInit, } from "./errors.js";
 export type { BatchItem, CheckDigit, Engine, EngineOption, EnginesQuery, Entry, ErrorBody, Make, MakesQuery, Manufacturer, Meta, Model, ModelsQuery, Plant, Safety, SearchQuery, Selection, Submodel, SubmodelsQuery, VinDecode, Warning, YearsQuery, } from "./types.js";
 export type { components, operations, paths } from "./schema.js";

package/dist/index.js

@@ -1,2 +1,3 @@
-export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, MAX_BATCH, WenmarOpen, isBatchError, } from "./client.js";
+export { MAX_BATCH, isBatchError } from "./batch.js";
+export { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, WenmarOpen } from "./client.js";
 export { WenmarOpenError } from "./errors.js";

package/dist/offline/client.d.ts

@@ -0,0 +1,70 @@
+import type { DecodeOptions, RequestOptions } from "../client.js";
+import type { BatchItem, EngineOption, EnginesQuery, Entry, Make, MakesQuery, Meta, Model, ModelsQuery, SearchQuery, Submodel, SubmodelsQuery, VinDecode, YearsQuery } from "../types.js";
+import type { WasmSource } from "./engine.js";
+import type { Store } from "./store.js";
+/**
+ * The most times one question, or the opening of the data, may go back to
+ * the store. Opening takes 2; over the fixture of the tests a decode takes
+ * at most 7 and a search at most 4. Reaching this means something is wrong.
+ */
+export declare const MAX_STEPS = 32;
+export interface OfflineOptions {
+    /** Where the data is: `syncStore(...)`, `d1Store(...)`, or your own. */
+    store: Store;
+    /**
+     * The decoder. Leave it out everywhere but Cloudflare Workers, where it
+     * is the module `import wasm from "wenmar-open/offline.wasm"` gives.
+     */
+    wasm?: WasmSource;
+    /**
+     * The current calendar year, which bounds the model years a VIN can
+     * have. Default: the year of the device's clock, in UTC.
+     */
+    currentYear?: number;
+}
+/**
+ * VIN decoding and the vehicle catalog with no network: the methods of
+ * `WenmarOpen`, answered from a data file by the decoder inside the package.
+ * Every method gives what the hosted API gives for the same question and
+ * fails with the same `WenmarOpenError` codes.
+ */
+export declare class WenmarOpenOffline {
+    #private;
+    constructor(options: OfflineOptions);
+    /** Decode one VIN. Spaces, dashes and lowercase are accepted. */
+    decodeVin(vin: string, options?: DecodeOptions): Promise<VinDecode>;
+    /**
+     * Decode up to 50 VINs. The answer has one item per VIN, in order: a
+     * decode, or the error a single call for that VIN would have thrown.
+     * Tell them apart with `isBatchError`.
+     */
+    decodeVins(vins: readonly string[], options?: RequestOptions): Promise<BatchItem[]>;
+    /** Model years, newest first. */
+    years(query?: YearsQuery, options?: RequestOptions): Promise<number[]>;
+    /** Makes, popular ones first and the rest by name. */
+    makes(query?: MakesQuery, options?: RequestOptions): Promise<Make[]>;
+    /** Models of a make, by name. An unknown make has no models. */
+    models(query: ModelsQuery, options?: RequestOptions): Promise<Model[]>;
+    /** Submodels of a model year: trims, or series where there are no trims. */
+    submodels(query: SubmodelsQuery, options?: RequestOptions): Promise<Submodel[]>;
+    /** The same as `submodels`, under the name most people use. */
+    trims(query: SubmodelsQuery, options?: RequestOptions): Promise<Submodel[]>;
+    /** Engines of a model year, in short form. */
+    engines(query: EnginesQuery, options?: RequestOptions): Promise<EngineOption[]>;
+    /**
+     * Catalog entries for free text such as `2019 civic si`, best first. The
+     * hosted API also finds words in any order with an index of its own;
+     * here, text the catalog cannot read as year, make, model and submodel
+     * finds nothing.
+     */
+    search(query: SearchQuery, options?: RequestOptions): Promise<Entry[]>;
+    /** One catalog entry by its id, such as `2019_honda_civic_si`. */
+    vehicle(id: string, options?: RequestOptions): Promise<Entry>;
+    /**
+     * The data version, the vPIC release it came from, and the build time.
+     * `server_version` is the version of this package.
+     */
+    meta(options?: RequestOptions): Promise<Meta>;
+    /** Closes the store, if the store was opened for this client. */
+    close(): void;
+}

package/dist/offline/client.js

@@ -0,0 +1,245 @@
+import { MAX_BATCH } from "../batch.js";
+import { WenmarOpenError } from "../errors.js";
+import { Engine, compile } from "./engine.js";
+import { cleanRows } from "./store.js";
+/**
+ * The most times one question, or the opening of the data, may go back to
+ * the store. Opening takes 2; over the fixture of the tests a decode takes
+ * at most 7 and a search at most 4. Reaching this means something is wrong.
+ */
+export const MAX_STEPS = 32;
+const keyOf = (statement) => `${statement.sql}\u0000${JSON.stringify(statement.params)}`;
+function thrown(failure) {
+    return new WenmarOpenError({ code: failure.code, message: failure.message, details: failure.details });
+}
+/**
+ * The rows of every statement, from the store. A store that throws, and one
+ * that does not return one list for each statement, are `store_error`: the
+ * same whether the data is being opened or a question answered.
+ */
+async function read(store, statements) {
+    let rows;
+    try {
+        rows = await store.query(statements);
+    }
+    catch (cause) {
+        if (cause instanceof WenmarOpenError)
+            throw cause;
+        throw new WenmarOpenError({
+            code: "store_error",
+            message: "The database failed while it was being read.",
+            cause,
+        });
+    }
+    if (!Array.isArray(rows) || rows.length !== statements.length) {
+        throw new WenmarOpenError({
+            code: "store_error",
+            message: "The store must return one list of rows for each statement.",
+        });
+    }
+    return rows;
+}
+/**
+ * VIN decoding and the vehicle catalog with no network: the methods of
+ * `WenmarOpen`, answered from a data file by the decoder inside the package.
+ * Every method gives what the hosted API gives for the same question and
+ * fails with the same `WenmarOpenError` codes.
+ */
+export class WenmarOpenOffline {
+    #store;
+    #wasm;
+    #currentYear;
+    #module;
+    #engine;
+    constructor(options) {
+        this.#store = options.store;
+        this.#wasm = options.wasm;
+        this.#currentYear = options.currentYear;
+    }
+    /** Decode one VIN. Spaces, dashes and lowercase are accepted. */
+    async decodeVin(vin, options = {}) {
+        return this.#one({ op: "decode", args: { vin: String(vin), year: options.year } }, options);
+    }
+    /**
+     * Decode up to 50 VINs. The answer has one item per VIN, in order: a
+     * decode, or the error a single call for that VIN would have thrown.
+     * Tell them apart with `isBatchError`.
+     */
+    async decodeVins(vins, options = {}) {
+        if (vins.length > MAX_BATCH) {
+            throw new WenmarOpenError({
+                code: "validation_failed",
+                message: `a batch holds at most ${MAX_BATCH} VINs`,
+                details: { field: "vins", max: MAX_BATCH, received: vins.length },
+            });
+        }
+        const questions = vins.map((vin) => ({ op: "decode", args: { vin: String(vin) } }));
+        const outcomes = await this.#ask(questions, options);
+        return outcomes.map((outcome) => ("ok" in outcome ? outcome.ok : { error: outcome.error }));
+    }
+    /** Model years, newest first. */
+    async years(query = {}, options = {}) {
+        return this.#one({ op: "years", args: query }, options);
+    }
+    /** Makes, popular ones first and the rest by name. */
+    async makes(query = {}, options = {}) {
+        return this.#one({ op: "makes", args: query }, options);
+    }
+    /** Models of a make, by name. An unknown make has no models. */
+    async models(query, options = {}) {
+        return this.#one({ op: "models", args: query }, options);
+    }
+    /** Submodels of a model year: trims, or series where there are no trims. */
+    async submodels(query, options = {}) {
+        return this.#one({ op: "submodels", args: query }, options);
+    }
+    /** The same as `submodels`, under the name most people use. */
+    async trims(query, options = {}) {
+        return this.#one({ op: "submodels", args: query }, options);
+    }
+    /** Engines of a model year, in short form. */
+    async engines(query, options = {}) {
+        return this.#one({ op: "engines", args: query }, options);
+    }
+    /**
+     * Catalog entries for free text such as `2019 civic si`, best first. The
+     * hosted API also finds words in any order with an index of its own;
+     * here, text the catalog cannot read as year, make, model and submodel
+     * finds nothing.
+     */
+    async search(query, options = {}) {
+        return this.#one({ op: "search", args: query }, options);
+    }
+    /** One catalog entry by its id, such as `2019_honda_civic_si`. */
+    async vehicle(id, options = {}) {
+        return this.#one({ op: "vehicle", args: { id: String(id) } }, options);
+    }
+    /**
+     * The data version, the vPIC release it came from, and the build time.
+     * `server_version` is the version of this package.
+     */
+    async meta(options = {}) {
+        return this.#one({ op: "meta", args: {} }, options);
+    }
+    /** Closes the store, if the store was opened for this client. */
+    close() {
+        this.#store.close?.();
+    }
+    async #one(question, options) {
+        const [outcome] = await this.#ask([question], options);
+        if (outcome === undefined) {
+            throw new WenmarOpenError({ code: "internal_error", message: "The decoder gave no answer." });
+        }
+        if ("error" in outcome)
+            throw thrown(outcome.error);
+        return outcome.ok;
+    }
+    /** The decoder, started and with the data opened. Started again after a stop. */
+    async #ready() {
+        const current = this.#engine;
+        if (current !== undefined) {
+            const engine = await current;
+            if (!engine.stopped)
+                return engine;
+            if (this.#engine === current)
+                this.#engine = undefined;
+        }
+        this.#engine ??= this.#start();
+        try {
+            return await this.#engine;
+        }
+        catch (error) {
+            this.#engine = undefined;
+            throw error;
+        }
+    }
+    async #start() {
+        this.#module ??= compile(this.#wasm);
+        let module;
+        try {
+            module = await this.#module;
+        }
+        catch (error) {
+            this.#module = undefined;
+            throw error;
+        }
+        const engine = await Engine.start(module);
+        const answers = [];
+        for (let step = 0; step < MAX_STEPS; step += 1) {
+            const answer = engine.call({ op: "open", answers });
+            if ("ok" in answer)
+                return engine;
+            if ("error" in answer)
+                throw thrown(answer.error);
+            const rows = await read(this.#store, answer.need);
+            answer.need.forEach((statement, index) => {
+                answers.push({ ...statement, rows: cleanRows(rows[index], statement.sql) });
+            });
+        }
+        throw new WenmarOpenError({ code: "internal_error", message: "Opening the data did not finish." });
+    }
+    /**
+     * Answers every question, going back to the store as often as the
+     * decoder asks. What several questions need in the same step is read
+     * together, each statement once.
+     */
+    async #ask(questions, options) {
+        const signal = options.signal;
+        const timeoutMs = options.timeoutMs ?? 0;
+        const started = Date.now();
+        const currentYear = this.#currentYear ?? new Date().getUTCFullYear();
+        const answers = questions.map(() => []);
+        const outcomes = questions.map(() => undefined);
+        for (let step = 0;; step += 1) {
+            if (signal?.aborted) {
+                throw new WenmarOpenError({ code: "aborted", message: "The request was aborted.", cause: signal.reason });
+            }
+            if (timeoutMs > 0 && Date.now() - started > timeoutMs) {
+                throw new WenmarOpenError({
+                    code: "timeout",
+                    message: `No answer within ${timeoutMs} ms.`,
+                    details: { timeout_ms: timeoutMs },
+                });
+            }
+            const engine = await this.#ready();
+            const wanted = new Map();
+            const waiting = [];
+            questions.forEach((question, index) => {
+                if (outcomes[index] !== undefined)
+                    return;
+                const answer = engine.call({
+                    op: question.op,
+                    args: question.args,
+                    current_year: currentYear,
+                    answers: answers[index] ?? [],
+                });
+                if ("need" in answer) {
+                    waiting.push({ index, need: answer.need });
+                    for (const statement of answer.need)
+                        wanted.set(keyOf(statement), statement);
+                }
+                else {
+                    outcomes[index] = answer;
+                }
+            });
+            if (waiting.length === 0)
+                return outcomes;
+            if (step >= MAX_STEPS) {
+                throw new WenmarOpenError({ code: "internal_error", message: "The decoder kept asking for more data." });
+            }
+            const statements = [...wanted.values()];
+            const rows = await read(this.#store, statements);
+            const found = new Map();
+            statements.forEach((statement, index) => {
+                found.set(keyOf(statement), { ...statement, rows: cleanRows(rows[index], statement.sql) });
+            });
+            for (const { index, need } of waiting) {
+                for (const statement of need) {
+                    const answered = found.get(keyOf(statement));
+                    if (answered !== undefined)
+                        answers[index]?.push(answered);
+                }
+            }
+        }
+    }
+}

package/dist/offline/engine.d.ts

@@ -0,0 +1,53 @@
+import type { Statement } from "./store.js";
+/**
+ * A compiled `WebAssembly.Module`. It is written as `object` so that these
+ * declarations name nothing a project without the DOM library lacks.
+ */
+export type CompiledWasm = object;
+/**
+ * The decoder: a compiled module, or its bytes. Cloudflare Workers do not
+ * compile bytes, so there it is the module `import wasm from
+ * "wenmar-open/offline.wasm"` gives.
+ */
+export type WasmSource = CompiledWasm | ArrayBuffer | ArrayBufferView;
+/** A statement with the rows a store gave for it. */
+export interface Answered extends Statement {
+    readonly rows: readonly (readonly (string | number | null)[])[];
+}
+export interface EngineRequest {
+    op: string;
+    args?: object;
+    current_year?: number;
+    answers?: readonly Answered[];
+}
+export type EngineAnswer = {
+    need: Statement[];
+} | {
+    ok: unknown;
+} | {
+    error: {
+        code: string;
+        message: string;
+        details: Record<string, unknown>;
+    };
+};
+/**
+ * Compiles the decoder. With no source it is the copy inside the package,
+ * which is read as text and never fetched, so nothing here needs a file
+ * system or a network.
+ */
+export declare function compile(source?: WasmSource): Promise<CompiledWasm>;
+/** One running copy of the decoder. */
+export declare class Engine {
+    #private;
+    private constructor();
+    static start(module: CompiledWasm): Promise<Engine>;
+    /** Whether a call stopped this copy. A stopped copy is never used again. */
+    get stopped(): boolean;
+    /**
+     * One request, one answer. A request that cannot be written as JSON is
+     * refused before the decoder sees it. A stop inside the decoder is thrown
+     * as an error, and this copy is not used again.
+     */
+    call(request: EngineRequest): EngineAnswer;
+}