wenmar-open 0.2.0 → 0.3.0

package/dist/offline/client.js

@@ -8,7 +8,18 @@ import { cleanRows } from "./store.js";
  * 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)}`;
+const keyOf = (statement) => `${statement.db ?? ""}\u0000${statement.sql}\u0000${JSON.stringify(statement.params)}`;
+/**
+ * The operations that are not about recalls alone and still read the shop
+ * file when there is one. Without a shop store they answer all the same.
+ */
+const READS_SHOP = new Set(["meta", "overview_vehicle", "overview_vin", "model_years"]);
+/** The operations about trouble codes. Each needs the shop file. */
+const CODE_OPS = new Set(["code", "codes", "vehicle_code", "jobs", "job", "labor_vehicle", "labor_vin"]);
+/** Whether a question reads the shop file, when there is one. */
+const needsShop = (question) => READS_SHOP.has(question.op) || question.op.startsWith("recall") || question.op === "safety" || question.op === "complaints" || FACTS.test(question.op) || CODE_OPS.has(question.op);
+/** The operations for fuel, specifications, fluids and tire fitments, such as `fuel_vin`. */
+const FACTS = /^(fuel|specs|fluids|tires)_(vehicle|vin)$/;
 function thrown(failure) {
     return new WenmarOpenError({ code: failure.code, message: failure.message, details: failure.details });
 }
@@ -47,12 +58,16 @@ async function read(store, statements) {
  */
 export class WenmarOpenOffline {
     #store;
+    #shop;
+    /** The copy of the decoder the shop file was opened on, and that opening. */
+    #shopOpened;
     #wasm;
     #currentYear;
     #module;
     #engine;
     constructor(options) {
         this.#store = options.store;
+        this.#shop = options.shop;
         this.#wasm = options.wasm;
         this.#currentYear = options.currentYear;
     }
@@ -114,16 +129,178 @@ export class WenmarOpenOffline {
     async vehicle(id, options = {}) {
         return this.#one({ op: "vehicle", args: { id: String(id) } }, options);
     }
+    /**
+     * NHTSA's crash test ratings for a model year, by its id such as
+     * `2018_ford_f-150`. NHTSA rates by body style and drive, so `ratings`
+     * often has several entries: each names the vehicle it is for. Needs a
+     * shop file that holds the ratings: without one it fails with
+     * `dataset_unavailable`.
+     */
+    async safety(id, options = {}) {
+        return this.#one({ op: "safety", args: { id: String(id) } }, options);
+    }
+    /**
+     * What owners reported to NHTSA about a model year, as counts by component
+     * with the median mileage they gave. Without a shop file that holds the
+     * complaints it fails with `dataset_unavailable`.
+     */
+    async complaints(id, options = {}) {
+        return this.#one({ op: "complaints", args: { id: String(id) } }, options);
+    }
+    /**
+     * Fuel consumption ratings of a model year, from EPA and Natural
+     * Resources Canada. Each says in `confidence` how far it was matched:
+     * `model`, `engine` or `submodel`. Needs a shop file that holds them:
+     * without one it fails with `dataset_unavailable`.
+     */
+    async fuel(id, query = {}, options = {}) {
+        return this.#one({ op: "fuel_vehicle", args: { ...query, id: String(id) } }, options);
+    }
+    /** Fuel ratings for the vehicle a VIN decodes to: one engine's when the decode settles it. */
+    async vinFuel(vin, query = {}, options = {}) {
+        return this.#one({ op: "fuel_vin", args: { ...query, vin: String(vin) } }, options);
+    }
+    /** Specifications of a model year from EPA's files, one entry per EPA rating. */
+    async specs(id, options = {}) {
+        return this.#one({ op: "specs_vehicle", args: { id: String(id) } }, options);
+    }
+    /** Specifications for the vehicle a VIN decodes to: one engine's when the decode settles it. */
+    async vinSpecs(vin, query = {}, options = {}) {
+        return this.#one({ op: "specs_vin", args: { ...query, vin: String(vin) } }, options);
+    }
+    /**
+     * Fluids of a model year: the engine oil viscosity grade the maker
+     * certified each engine with, per EPA, and the records a person read from
+     * the maker's own documents, each with its source and the day it was checked.
+     */
+    async fluids(id, options = {}) {
+        return this.#one({ op: "fluids_vehicle", args: { id: String(id) } }, options);
+    }
+    /** Fluids for the vehicle a VIN decodes to: one engine's when the decode settles it. */
+    async vinFluids(vin, query = {}, options = {}) {
+        return this.#one({ op: "fluids_vin", args: { ...query, vin: String(vin) } }, options);
+    }
+    /**
+     * Original-equipment tire fitments of a model year. Every size on record
+     * is listed with the trims it covers; none is picked.
+     */
+    async tires(id, options = {}) {
+        return this.#one({ op: "tires_vehicle", args: { id: String(id) } }, options);
+    }
+    /** Tire fitments of the model year a VIN decodes to. Never narrowed: a VIN does not name the wheels. */
+    async vinTires(vin, query = {}, options = {}) {
+        return this.#one({ op: "tires_vin", args: { ...query, vin: String(vin) } }, options);
+    }
+    /** The repair jobs a labour estimate can be about. Needs a shop file that holds the job list. */
+    async jobs(options = {}) {
+        return this.#one({ op: "jobs", args: {} }, options);
+    }
+    /** One repair job: what it covers, and what it typically takes by class of vehicle. */
+    async job(job, options = {}) {
+        return this.#one({ op: "job", args: { job: String(job) } }, options);
+    }
+    /**
+     * Wenmar's labour estimates for a model year, or for one `job` of it.
+     * An estimate, not a quote; credit it as `attribution` says. Needs a
+     * shop file that holds the estimates.
+     */
+    async labor(id, job, options = {}) {
+        return this.#one({ op: "labor_vehicle", args: { id: String(id), job } }, options);
+    }
+    /** Labour estimates for the vehicle a VIN decodes to, or for one `job` of it. */
+    async vinLabor(vin, job, options = {}) {
+        return this.#one({ op: "labor_vin", args: { vin: String(vin), job, year: options.year } }, options);
+    }
+    /**
+     * One generic trouble code, such as `P0420`, described in this project's
+     * own words. Needs a shop file that holds the codes: without one it
+     * fails with `dataset_unavailable`.
+     */
+    async code(code, options = {}) {
+        return this.#one({ op: "code", args: { code: String(code) } }, options);
+    }
+    /** The trouble codes that are described, by code, narrowed by text or system. */
+    async codes(query = {}, options = {}) {
+        return this.#one({ op: "codes", args: { ...query } }, options);
+    }
+    /**
+     * A trouble code on one model year: its description and the recalls
+     * about the same components. `bulletins` and `related.bulletins` are
+     * always `null` offline: bulletins are on the hosted service only.
+     */
+    async vehicleCode(id, code, options = {}) {
+        return this.#one({ op: "vehicle_code", args: { id: String(id), code: String(code) } }, options);
+    }
+    /**
+     * Recalls that may apply to a model year, by its id such as
+     * `2018_ford_f-150`. The list is for the year, make and model: it is not
+     * a lookup by VIN, and `lookup` says where one vehicle can be checked.
+     * Needs a shop file: without one it fails with `dataset_unavailable`.
+     */
+    async recalls(id, query = {}, options = {}) {
+        return this.#one({ op: "recalls_vehicle", args: { ...query, id: String(id) } }, options);
+    }
+    /**
+     * Recalls that may apply to the model year a VIN decodes to. The VIN only
+     * names the model year: no public data says a recall applies to one VIN.
+     */
+    async vinRecalls(vin, query = {}, options = {}) {
+        return this.#one({ op: "recalls_vin", args: { ...query, vin: String(vin) } }, options);
+    }
+    /** One recall campaign: `source` is `nhtsa` or `tc`. */
+    async recall(source, campaign, options = {}) {
+        return this.#one({ op: "recall", args: { source: String(source), campaign: String(campaign) } }, options);
+    }
+    /** Recall campaigns, newest first, narrowed by what is given. */
+    async searchRecalls(query = {}, options = {}) {
+        return this.#one({ op: "recalls_search", args: query }, options);
+    }
+    /**
+     * Everything held for a model year in one answer, by its id such as
+     * `2018_ford_f-150`. A block the files do not hold is `null`. `recalls`
+     * counts the campaigns that may apply to the year, make and model: it is
+     * not a lookup by VIN. With no shop file `recalls` is `null`, and the
+     * method still answers.
+     */
+    async overview(id, options = {}) {
+        return this.#one({ op: "overview_vehicle", args: { id: String(id) } }, options);
+    }
+    /**
+     * The overview of the model year a VIN decodes to, with `decode`. The VIN
+     * only names the model year: no public data says a recall applies to one
+     * VIN.
+     */
+    async vinOverview(vin, options = {}) {
+        return this.#one({ op: "overview_vin", args: { vin: String(vin), year: options.year } }, options);
+    }
+    /**
+     * Every model year of one model, newest first, each with its vehicle id
+     * and the number of recall campaigns that may apply to it: `null` with no
+     * shop file.
+     */
+    async modelYears(make, model, options = {}) {
+        return this.#one({ op: "model_years", args: { make: String(make), model: String(model) } }, options);
+    }
+    /**
+     * Recall campaigns reported on or after `since` (a day such as
+     * `2026-09-01`), newest first, each with the vehicles it may apply to.
+     * Needs a shop file: without one it fails with `dataset_unavailable`.
+     */
+    async recentRecalls(query, options = {}) {
+        return this.#one({ op: "recalls_recent", args: query }, options);
+    }
     /**
      * The data version, the vPIC release it came from, and the build time.
-     * `server_version` is the version of this package.
+     * `server_version` is the version of this package. `datasets` lists what
+     * the shop file holds, and is empty when no shop store was given.
      */
     async meta(options = {}) {
         return this.#one({ op: "meta", args: {} }, options);
     }
-    /** Closes the store, if the store was opened for this client. */
+    /** Closes the stores, if they were opened for this client. */
     close() {
         this.#store.close?.();
+        this.#shop?.close?.();
     }
     async #one(question, options) {
         const [outcome] = await this.#ask([question], options);
@@ -178,6 +355,64 @@ export class WenmarOpenOffline {
         }
         throw new WenmarOpenError({ code: "internal_error", message: "Opening the data did not finish." });
     }
+    /**
+     * The rows of every statement, each from the store its file is in: a
+     * statement marked `db: "shop"` is for the shop file.
+     */
+    async #read(statements) {
+        const ofShop = statements.map((statement) => statement.db === "shop");
+        if (!ofShop.includes(true))
+            return read(this.#store, statements);
+        const shop = this.#shop;
+        if (shop === undefined) {
+            throw new WenmarOpenError({
+                code: "internal_error",
+                message: "The decoder asked for the shop file, and no shop store was given.",
+            });
+        }
+        const forData = statements.filter((_, index) => !ofShop[index]);
+        const forShop = statements.filter((_, index) => ofShop[index]);
+        const [fromData, fromShop] = await Promise.all([
+            forData.length === 0 ? [] : read(this.#store, forData),
+            read(shop, forShop),
+        ]);
+        let [data, other] = [0, 0];
+        return statements.map((_, index) => (ofShop[index] ? fromShop[other++] : fromData[data++]) ?? []);
+    }
+    /**
+     * Opens the shop file on `engine`, once for each copy of the decoder. It
+     * is opened when a question first needs it, so a shop store that fails
+     * does not stop a VIN from being decoded.
+     */
+    async #withShop(engine) {
+        if (this.#shopOpened?.engine !== engine) {
+            this.#shopOpened = { engine, done: this.#openShop(engine) };
+        }
+        const opening = this.#shopOpened;
+        try {
+            await opening.done;
+        }
+        catch (error) {
+            if (this.#shopOpened === opening)
+                this.#shopOpened = undefined;
+            throw error;
+        }
+    }
+    async #openShop(engine) {
+        const answers = [];
+        for (let step = 0; step < MAX_STEPS; step += 1) {
+            const answer = engine.call({ op: "open_shop", answers });
+            if ("ok" in answer)
+                return;
+            if ("error" in answer)
+                throw thrown(answer.error);
+            const rows = await this.#read(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 shop file 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
@@ -202,6 +437,8 @@ export class WenmarOpenOffline {
                 });
             }
             const engine = await this.#ready();
+            if (this.#shop !== undefined && questions.some(needsShop))
+                await this.#withShop(engine);
             const wanted = new Map();
             const waiting = [];
             questions.forEach((question, index) => {
@@ -228,7 +465,7 @@ export class WenmarOpenOffline {
                 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 rows = await this.#read(statements);
             const found = new Map();
             statements.forEach((statement, index) => {
                 found.set(keyOf(statement), { ...statement, rows: cleanRows(rows[index], statement.sql) });

package/dist/offline/index.d.ts

@@ -2,7 +2,7 @@ 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 type { BatchItem, CheckDigit, Engine, EngineOil, EngineOption, EnginesQuery, Entry, FluidRecord, FuelRating, ErrorBody, Make, MakesQuery, Manufacturer, Meta, Model, ModelsQuery, ModelYears, Overview, OverviewRecalls, Plant, Recall, RecallCampaign, RecallCount, RecallList, RecallLookup, RecallSearchQuery, RecentRecalls, RecentRecallsQuery, Safety, SafetyRating, SearchQuery, Selection, Spec, Submodel, SubmodelsQuery, TireFitment, VehicleFluids, VehicleFuel, VehicleComplaints, VehicleFuelQuery, VehicleRecalls, VehicleRecallsQuery, Code, CodeLink, CodeList, CodeSearchQuery, VehicleCode, JobDetail, JobList, LaborFigure, VehicleLabor, VinLabor, VehicleSafety, VehicleSpecs, VehicleTires, VinDecode, VinFluids, VinFuel, VinFuelQuery, VinRecalls, VinRecallsQuery, VinSpecs, VinTires, VinYearQuery, 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";

package/dist/offline/node.d.ts

@@ -6,6 +6,12 @@ export interface NodeOptions {
      * which must then be installed.
      */
     path?: string;
+    /**
+     * The shop file, which holds the recalls. Default: the one in the
+     * `wenmar-open-data-shop` package, if that package is installed. `false`
+     * opens none even then.
+     */
+    shopPath?: string | false;
     wasm?: WasmSource;
     currentYear?: number;
 }

package/dist/offline/node.js

@@ -50,17 +50,44 @@ export async function openOffline(options = {}) {
             cause,
         });
     }
+    // The shop file: the one named, or the one of the wenmar-open-data-shop
+    // package when it is installed. With neither, recalls are
+    // `dataset_unavailable` and everything else works.
+    let shopPath = options.shopPath;
+    if (shopPath === undefined) {
+        shopPath = await load("wenmar-open-data-shop").then((module) => module.path, () => false);
+    }
+    let shopDatabase;
+    if (shopPath !== false) {
+        try {
+            shopDatabase = new sqlite.DatabaseSync(shopPath, { readOnly: true });
+        }
+        catch (cause) {
+            database.close();
+            throw new WenmarOpenError({
+                code: "no_data",
+                message: `The shop file at ${shopPath} could not be opened.`,
+                details: { path: shopPath },
+                cause,
+            });
+        }
+    }
+    const shop = shopDatabase;
     const store = { ...syncStore(database), close: () => database.close() };
     const client = new WenmarOpenOffline({
         store,
+        ...(shop === undefined ? {} : { shop: { ...syncStore(shop), close: () => shop.close() } }),
         ...(options.wasm === undefined ? {} : { wasm: options.wasm }),
         ...(options.currentYear === undefined ? {} : { currentYear: options.currentYear }),
     });
     try {
+        // `meta` opens the data file and, when there is one, the shop file,
+        // which must go with it.
         await client.meta();
     }
     catch (error) {
         database.close();
+        shop?.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.

package/dist/offline/store.d.ts

@@ -4,6 +4,12 @@ export type Param = string | number | null;
 export interface Statement {
     readonly sql: string;
     readonly params: readonly Param[];
+    /**
+     * Which file the statement is for. Left out: the data file. `"shop"`:
+     * the shop file, which holds the recalls. The client sends each statement
+     * to the store of its file, so a store never has to look at this.
+     */
+    readonly db?: "shop";
 }
 /**
  * A database holding a Wenmar Open data file. It is asked to run a list of