wenmar-open 0.1.0 → 0.2.0

package/dist/offline/engine.js

@@ -0,0 +1,129 @@
+import { WenmarOpenError } from "../errors.js";
+const EXPORTS = ["memory", "wo_alloc", "wo_call", "wo_result", "wo_result_len"];
+function bytesOf(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+/**
+ * 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 async function compile(source) {
+    if (source instanceof WebAssembly.Module)
+        return source;
+    try {
+        const bytes = source ?? bytesOf((await import("./wasm-inline.js")).WASM_BASE64);
+        return await WebAssembly.compile(bytes);
+    }
+    catch (cause) {
+        throw new WenmarOpenError({
+            code: "internal_error",
+            message: "The decoder could not be loaded. Where bytes may not be compiled, as in Cloudflare Workers, pass { wasm } from: import wasm from \"wenmar-open/offline.wasm\".",
+            cause,
+        });
+    }
+}
+/** One running copy of the decoder. */
+export class Engine {
+    #exports;
+    #stopped = false;
+    constructor(exports) {
+        this.#exports = exports;
+    }
+    static async start(module) {
+        let instance;
+        try {
+            instance = await WebAssembly.instantiate(module, {});
+        }
+        catch (cause) {
+            throw new WenmarOpenError({
+                code: "internal_error",
+                message: "The decoder could not be started: the wasm given is not the one of this package.",
+                cause,
+            });
+        }
+        const exports = instance.exports;
+        for (const name of EXPORTS) {
+            if (exports[name] === undefined) {
+                throw new WenmarOpenError({
+                    code: "internal_error",
+                    message: "The decoder could not be started: the wasm given is not the one of this package.",
+                    details: { missing: name },
+                });
+            }
+        }
+        return new Engine(exports);
+    }
+    /** Whether a call stopped this copy. A stopped copy is never used again. */
+    get stopped() {
+        return this.#stopped;
+    }
+    #read() {
+        const { memory, wo_result, wo_result_len } = this.#exports;
+        // The memory may have grown during the call, so it is looked at afresh.
+        return new TextDecoder().decode(new Uint8Array(memory.buffer, wo_result(), wo_result_len()));
+    }
+    /**
+     * 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) {
+        if (this.#stopped) {
+            throw new WenmarOpenError({ code: "internal_error", message: "The decoder has stopped." });
+        }
+        let input;
+        try {
+            input = new TextEncoder().encode(JSON.stringify(request));
+        }
+        catch (cause) {
+            throw new WenmarOpenError({
+                code: "validation_failed",
+                message: "The question could not be written as JSON.",
+                cause,
+            });
+        }
+        const { memory, wo_alloc, wo_call } = this.#exports;
+        try {
+            const pointer = wo_alloc(input.length);
+            new Uint8Array(memory.buffer, pointer, input.length).set(input);
+            wo_call(pointer, input.length);
+        }
+        catch (cause) {
+            // WebAssembly cannot unwind, so a failure inside it ends the call
+            // here. What it was is left where the answer would have been.
+            this.#stopped = true;
+            let panic;
+            try {
+                panic = this.#read();
+            }
+            catch {
+                panic = undefined;
+            }
+            // An answer is always a JSON object and a panic's message never is:
+            // text that starts as an object is an answer left from before.
+            if (panic === "" || panic?.startsWith("{"))
+                panic = undefined;
+            throw new WenmarOpenError({
+                code: "internal_error",
+                message: "The decoder stopped unexpectedly. Please report the VIN or the question that caused it.",
+                details: panic === undefined ? {} : { panic },
+                cause,
+            });
+        }
+        try {
+            return JSON.parse(this.#read());
+        }
+        catch (cause) {
+            throw new WenmarOpenError({
+                code: "internal_error",
+                message: "The decoder gave an answer that could not be read.",
+                cause,
+            });
+        }
+    }
+}

package/dist/offline/index.d.ts

@@ -0,0 +1,10 @@
+export { MAX_BATCH, isBatchError } from "../batch.js";
+export { WenmarOpenError } from "../errors.js";
+export type { ApiErrorCode, ClientErrorCode, ErrorCode, OfflineErrorCode, WenmarOpenErrorInit, } from "../errors.js";
+export type { DecodeOptions, RequestOptions } from "../client.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 { MAX_STEPS, WenmarOpenOffline } from "./client.js";
+export type { OfflineOptions } from "./client.js";
+export type { CompiledWasm, WasmSource } from "./engine.js";
+export { d1Store, syncStore } from "./store.js";
+export type { D1Like, D1Statement, Param, Statement, Store, SyncDatabase, SyncStatement } from "./store.js";

package/dist/offline/index.js

@@ -0,0 +1,4 @@
+export { MAX_BATCH, isBatchError } from "../batch.js";
+export { WenmarOpenError } from "../errors.js";
+export { MAX_STEPS, WenmarOpenOffline } from "./client.js";
+export { d1Store, syncStore } from "./store.js";

package/dist/offline/node.d.ts

@@ -0,0 +1,20 @@
+import { WenmarOpenOffline } from "./client.js";
+import type { WasmSource } from "./engine.js";
+export interface NodeOptions {
+    /**
+     * The data file. Default: the one in the `wenmar-open-data` package,
+     * which must then be installed.
+     */
+    path?: string;
+    wasm?: WasmSource;
+    currentYear?: number;
+}
+/**
+ * Opens a data file with Node's own SQLite (Node 22.16 or later) and
+ * returns a client that reads it. The file is opened read-only and checked:
+ * a file of another schema version fails here, not at the first decode.
+ *
+ * On Node 20, open the file with `better-sqlite3` and give it to
+ * `syncStore` instead.
+ */
+export declare function openOffline(options?: NodeOptions): Promise<WenmarOpenOffline>;

package/dist/offline/node.js

@@ -0,0 +1,78 @@
+import { WenmarOpenError } from "../errors.js";
+import { WenmarOpenOffline } from "./client.js";
+import { syncStore } from "./store.js";
+/** Loaded by name at run time, so nothing is resolved when this file is read. */
+async function load(specifier) {
+    return (await import(specifier));
+}
+/**
+ * Opens a data file with Node's own SQLite (Node 22.16 or later) and
+ * returns a client that reads it. The file is opened read-only and checked:
+ * a file of another schema version fails here, not at the first decode.
+ *
+ * On Node 20, open the file with `better-sqlite3` and give it to
+ * `syncStore` instead.
+ */
+export async function openOffline(options = {}) {
+    let path = options.path;
+    if (path === undefined) {
+        try {
+            path = (await load("wenmar-open-data")).path;
+        }
+        catch (cause) {
+            throw new WenmarOpenError({
+                code: "no_data",
+                message: "There is no data file. Install the wenmar-open-data package, or pass { path }.",
+                cause,
+            });
+        }
+    }
+    let sqlite;
+    try {
+        sqlite = await load("node:sqlite");
+    }
+    catch (cause) {
+        throw new WenmarOpenError({
+            code: "store_error",
+            message: "node:sqlite is not available. It needs Node 22.16 or later; on older versions open the file with better-sqlite3 and pass it to syncStore.",
+            cause,
+        });
+    }
+    let database;
+    try {
+        database = new sqlite.DatabaseSync(path, { readOnly: true });
+    }
+    catch (cause) {
+        throw new WenmarOpenError({
+            code: "no_data",
+            message: `The data file at ${path} could not be opened.`,
+            details: { path },
+            cause,
+        });
+    }
+    const store = { ...syncStore(database), close: () => database.close() };
+    const client = new WenmarOpenOffline({
+        store,
+        ...(options.wasm === undefined ? {} : { wasm: options.wasm }),
+        ...(options.currentYear === undefined ? {} : { currentYear: options.currentYear }),
+    });
+    try {
+        await client.meta();
+    }
+    catch (error) {
+        database.close();
+        // SQLite opens a file that is not a database without complaint and
+        // fails on the first read; for a file on disk that means the file is
+        // not a data file, not that a connection dropped.
+        if (error instanceof WenmarOpenError && error.code === "store_error" && error.cause !== undefined) {
+            throw new WenmarOpenError({
+                code: "data_invalid",
+                message: `The file at ${path} could not be read as a Wenmar Open data file.`,
+                details: { path },
+                cause: error.cause,
+            });
+        }
+        throw error;
+    }
+    return client;
+}

package/dist/offline/store.d.ts

@@ -0,0 +1,72 @@
+/** A value bound to a statement: text, a number or null. */
+export type Param = string | number | null;
+/** One `SELECT`, with what binds to `?1`, `?2` and so on, in order. */
+export interface Statement {
+    readonly sql: string;
+    readonly params: readonly Param[];
+}
+/**
+ * A database holding a Wenmar Open data file. It is asked to run a list of
+ * `SELECT`s and gives back the rows of each, in the same order. A row is an
+ * array with one value per selected column, in the order selected: never an
+ * object, because two columns may share a name. It may answer at once or
+ * with a promise.
+ */
+export interface Store {
+    query(statements: readonly Statement[]): unknown[][][] | Promise<unknown[][][]>;
+    /** Called by `close()` on the client. A store the caller opened leaves this out. */
+    close?(): void;
+}
+/** A prepared statement of `node:sqlite` or of `better-sqlite3`. */
+export interface SyncStatement {
+    all(...params: (Param | Record<string, Param>)[]): unknown[];
+    /** `node:sqlite`, Node 22.16 and later. */
+    setReturnArrays?(enabled: boolean): void;
+    /** `better-sqlite3`. */
+    raw?(enabled?: boolean): unknown;
+}
+/**
+ * A database of `node:sqlite` (`DatabaseSync`) or of `better-sqlite3`. What
+ * `prepare` returns is used as a `SyncStatement`; it is typed loosely here
+ * so that both libraries' own declarations fit.
+ */
+export interface SyncDatabase {
+    prepare(sql: string): object;
+}
+/**
+ * Gives every bare `?` the number SQLite gives it (one more than the
+ * largest number so far), so a statement that mixes `?` and `?3` has only
+ * numbered parameters. Text in quotes and comments is left alone.
+ */
+export declare function numberParameters(sql: string): string;
+/**
+ * A store over a database the caller opened with `node:sqlite` or
+ * `better-sqlite3`. The caller closes it.
+ *
+ * The two bind differently. `node:sqlite` binds values to `?1`, `?2` by
+ * position. `better-sqlite3` reads `?1` as a parameter named `1`, which a
+ * positional value does not fill, so there the values are given as one
+ * object keyed by number.
+ */
+export declare function syncStore(database: SyncDatabase): Store;
+/** What `d1Store` uses of a D1 prepared statement. */
+export interface D1Statement {
+    bind(...values: Param[]): D1Statement;
+    raw(): Promise<unknown[][]>;
+}
+/** A Cloudflare D1 binding, or a session made with `withSession()`. */
+export interface D1Like {
+    prepare(sql: string): D1Statement;
+}
+/**
+ * A store over a Cloudflare D1 database that holds an imported data file.
+ * The statements of one step are sent together and each counts as one D1
+ * query.
+ */
+export declare function d1Store(database: D1Like): Store;
+/**
+ * The rows of one statement, as the decoder reads them: each value a
+ * number, text or null. A database set to return every integer as a BigInt
+ * is accepted. Bytes are not: the data file holds none.
+ */
+export declare function cleanRows(rows: unknown, sql: string): (string | number | null)[][];

package/dist/offline/store.js

@@ -0,0 +1,156 @@
+import { WenmarOpenError } from "../errors.js";
+/** How many prepared statements a store keeps. */
+const MOST_PREPARED = 256;
+/**
+ * Gives every bare `?` the number SQLite gives it (one more than the
+ * largest number so far), so a statement that mixes `?` and `?3` has only
+ * numbered parameters. Text in quotes and comments is left alone.
+ */
+export function numberParameters(sql) {
+    let out = "";
+    let largest = 0;
+    let index = 0;
+    while (index < sql.length) {
+        const char = sql.charAt(index);
+        const pair = sql.slice(index, index + 2);
+        let end = -1;
+        if (char === "'" || char === '"' || char === "`") {
+            end = sql.indexOf(char, index + 1);
+            while (end !== -1 && sql.charAt(end + 1) === char)
+                end = sql.indexOf(char, end + 2);
+            end = end === -1 ? sql.length : end + 1;
+        }
+        else if (pair === "--") {
+            end = sql.indexOf("\n", index);
+            end = end === -1 ? sql.length : end;
+        }
+        else if (pair === "/*") {
+            end = sql.indexOf("*/", index + 2);
+            end = end === -1 ? sql.length : end + 2;
+        }
+        if (end !== -1) {
+            out += sql.slice(index, end);
+            index = end;
+            continue;
+        }
+        if (char === "?") {
+            const digits = /^\d*/.exec(sql.slice(index + 1))?.[0] ?? "";
+            if (digits === "") {
+                largest += 1;
+                out += `?${largest}`;
+            }
+            else {
+                largest = Math.max(largest, Number(digits));
+                out += `?${digits}`;
+            }
+            index += 1 + digits.length;
+            continue;
+        }
+        out += char;
+        index += 1;
+    }
+    return out;
+}
+/**
+ * A store over a database the caller opened with `node:sqlite` or
+ * `better-sqlite3`. The caller closes it.
+ *
+ * The two bind differently. `node:sqlite` binds values to `?1`, `?2` by
+ * position. `better-sqlite3` reads `?1` as a parameter named `1`, which a
+ * positional value does not fill, so there the values are given as one
+ * object keyed by number.
+ */
+export function syncStore(database) {
+    const prepared = new Map();
+    const prepare = (sql) => {
+        const kept = prepared.get(sql);
+        if (kept !== undefined)
+            return kept;
+        let run;
+        const probe = database.prepare(sql);
+        if (typeof probe.setReturnArrays === "function") {
+            probe.setReturnArrays(true);
+            run = (params) => probe.all(...params);
+        }
+        else {
+            const statement = typeof probe.raw === "function" ? database.prepare(numberParameters(sql)) : probe;
+            if (typeof statement.raw !== "function") {
+                throw new WenmarOpenError({
+                    code: "store_error",
+                    message: "This database cannot return rows as arrays. Use node:sqlite from Node 22.16 or later, or better-sqlite3.",
+                });
+            }
+            statement.raw(true);
+            run = (params) => (params.length === 0
+                ? statement.all()
+                : statement.all(Object.fromEntries(params.map((value, index) => [index + 1, value]))));
+        }
+        if (prepared.size >= MOST_PREPARED)
+            prepared.clear();
+        prepared.set(sql, run);
+        return run;
+    };
+    return {
+        query: (statements) => statements.map(({ sql, params }) => prepare(sql)(params)),
+    };
+}
+/**
+ * A store over a Cloudflare D1 database that holds an imported data file.
+ * The statements of one step are sent together and each counts as one D1
+ * query.
+ */
+export function d1Store(database) {
+    return {
+        query: (statements) => Promise.all(statements.map(({ sql, params }) => database.prepare(sql).bind(...params).raw())),
+    };
+}
+function invalid(message, details) {
+    return new WenmarOpenError({ code: "data_invalid", message, details });
+}
+/**
+ * The rows of one statement, as the decoder reads them: each value a
+ * number, text or null. A database set to return every integer as a BigInt
+ * is accepted. Bytes are not: the data file holds none.
+ */
+export function cleanRows(rows, sql) {
+    if (!Array.isArray(rows)) {
+        throw new WenmarOpenError({
+            code: "store_error",
+            message: "The store did not return a list of rows for a statement.",
+            details: { sql },
+        });
+    }
+    return rows.map((row) => {
+        if (!Array.isArray(row)) {
+            throw new WenmarOpenError({
+                code: "store_error",
+                message: "The store must return each row as an array of values, in the order selected.",
+                details: { sql },
+            });
+        }
+        return row.map((value, column) => {
+            if (value === null || value === undefined)
+                return null;
+            if (typeof value === "string")
+                return value;
+            if (typeof value === "number") {
+                if (Number.isFinite(value))
+                    return value;
+                throw invalid("The database returned a number that is not finite.", { sql, column });
+            }
+            if (typeof value === "bigint") {
+                if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+                    return Number(value);
+                }
+                throw invalid("The database returned a whole number too large to read exactly.", { sql, column });
+            }
+            if (typeof value === "boolean")
+                return value ? 1 : 0;
+            throw invalid("The database returned a value that is not a number, text or null.", {
+                sql,
+                column,
+                kind: ArrayBuffer.isView(value) || value instanceof ArrayBuffer ? "bytes" : typeof value,
+            });
+        });
+    });
+}