@meterapp/vehicle-db 1.0.0

package/README.md

@@ -0,0 +1,162 @@
+# vehicle-db
+
+Offline NHTSA vehicle database. All U.S. vehicle makes and models from 1990–2026, bundled as a 3.8 MB SQLite file inside the package. No network requests needed.
+
+Covers three vehicle types: **Passenger Car**, **Truck**, and **Multipurpose Passenger Vehicle (MPV)**.
+
+Drop-in replacement for these NHTSA vPIC API endpoints:
+
+- `GetMakesForVehicleType/{type}`
+- `GetModelsForMakeYear/make/{make}/modelyear/{year}`
+- `GetModelsForMakeIdYear/makeId/{id}/modelyear/{year}/vehicleType/{type}`
+
+## Install
+
+```bash
+npm install @meterapp/vehicle-db
+```
+
+> Requires Node.js 18+. Uses [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) under the hood.
+
+## Usage
+
+```typescript
+import {
+  getVehicleTypes,
+  getMakesForVehicleType,
+  getModelsForMakeYear,
+  getAvailableYears,
+  close,
+} from "@meterapp/vehicle-db";
+
+// List available vehicle types
+const types = getVehicleTypes();
+// => Passenger Car, Truck, Multipurpose Passenger Vehicle (MPV)
+
+// Get all truck makes for a given year
+const makes = getMakesForVehicleType("Truck", 2024);
+// => { Count: 171, Message: "...", Results: [...] }
+
+// Get all models for a make and year (all vehicle types)
+const models = getModelsForMakeYear("Toyota", 2024);
+// => { Count: 27, Message: "...", Results: [...] }
+
+// Filter models by vehicle type
+const trucks = getModelsForMakeYear("Ford", 2024, "Truck");
+// => { Count: 10, Message: "...", Results: [F-150, Ranger, ...] }
+
+// See what years are available
+const years = getAvailableYears();
+// => [1990, 1991, ..., 2026]
+
+// Optional: close the DB connection when you're done
+close();
+```
+
+## API
+
+### `getVehicleTypes(): NHTSAResponse<VehicleType>`
+
+Returns all vehicle types in the database.
+
+```typescript
+{ VehicleTypeId: number; VehicleTypeName: string }
+```
+
+### `getMakesForVehicleType(vehicleType: string, year: number): NHTSAResponse<MakeResult>`
+
+Returns all makes for a given vehicle type and model year. Vehicle type is **case-insensitive**. Equivalent to:
+
+```
+GET https://vpic.nhtsa.dot.gov/api/vehicles/GetMakesForVehicleType/truck?year=2024&format=json
+```
+
+Each result contains:
+
+```typescript
+{
+  MakeId: number;          // e.g. 460
+  MakeName: string;        // e.g. "FORD"
+  VehicleTypeId: number;   // e.g. 3
+  VehicleTypeName: string; // e.g. "Truck"
+}
+```
+
+### `getModelsForMakeYear(make: string, year: number, vehicleType?: string): NHTSAResponse<ModelResult>`
+
+Returns all models for a given make and year. Make name is **case-insensitive**. Optionally filter by vehicle type.
+
+```
+GET https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeYear/make/Ford/modelyear/2024?format=json
+```
+
+Each result contains:
+
+```typescript
+{
+  Make_ID: number;    // e.g. 460
+  Make_Name: string;  // e.g. "FORD"
+  Model_ID: number;   // e.g. 1801
+  Model_Name: string; // e.g. "F-150"
+}
+```
+
+### `getAvailableYears(): number[]`
+
+Returns all years present in the database, sorted ascending.
+
+### `close(): void`
+
+Closes the SQLite connection. Safe to call multiple times. The connection reopens automatically on the next query.
+
+## Migrating from the NHTSA API
+
+Replace your fetch calls directly:
+
+```diff
+- const res = await fetch(
+-   `https://vpic.nhtsa.dot.gov/api/vehicles/GetMakesForVehicleType/car?year=${year}&format=json`
+- );
+- const makes = await res.json();
++ const makes = getMakesForVehicleType("Passenger Car", year);
+```
+
+```diff
+- const res = await fetch(
+-   `https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeYear/make/${encodeURIComponent(make)}/modelyear/${year}?format=json`
+- );
+- const models = await res.json();
++ const models = getModelsForMakeYear(make, year);
+```
+
+The response shape (`Count`, `Message`, `SearchCriteria`, `Results`) matches the NHTSA API, so downstream code should work unchanged.
+
+## Database stats
+
+| | |
+|---|---|
+| **Years** | 1990 – 2026 |
+| **Vehicle types** | 3 (Passenger Car, Truck, MPV) |
+| **Makes** | 400 |
+| **Model entries** | 51,270 |
+| **SQLite file size** | 3.8 MB |
+
+## Rebuilding the database
+
+To refresh the data from the NHTSA API:
+
+```bash
+npm run build:db
+```
+
+Or for a specific year range:
+
+```bash
+npm run build:db -- --start-year 2020 --end-year 2026
+```
+
+> The NHTSA API rate-limits aggressively. The build script retries failed requests, but some obscure makes may be skipped. Major manufacturers (Toyota, Honda, Ford, BMW, etc.) are always fetched successfully.
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+export interface VehicleType {
+    vehicleTypeId: number;
+    vehicleTypeName: string;
+}
+export interface Make {
+    makeId: number;
+    makeName: string;
+}
+export interface Model {
+    modelId: number;
+    modelName: string;
+    makeId: number;
+    makeName: string;
+    vehicleTypeId: number;
+    vehicleTypeName: string;
+}
+export interface GetMakesOptions {
+    year?: number;
+    vehicleTypeId?: number;
+}
+export interface GetModelsOptions {
+    year?: number;
+    vehicleTypeId?: number;
+    makeId?: number;
+}
+/**
+ * Returns all vehicle types in the database.
+ */
+export declare function getVehicleTypes(): VehicleType[];
+/**
+ * Returns makes, optionally filtered by year and/or vehicle type.
+ */
+export declare function getMakes(options?: GetMakesOptions): Make[];
+/**
+ * Returns models, optionally filtered by year, vehicle type, and/or make.
+ */
+export declare function getModels(options?: GetModelsOptions): Model[];
+/**
+ * Get all available years in the database.
+ */
+export declare function getAvailableYears(): number[];
+/**
+ * Close the database connection (optional cleanup).
+ */
+export declare function close(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,IAAI;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,KAAK;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAkBD;;GAEG;AACH,wBAAgB,eAAe,IAAI,WAAW,EAAE,CAU/C;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,IAAI,EAAE,CAkC9D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,KAAK,EAAE,CA8CjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAM5C;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAK5B"}

package/dist/index.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVehicleTypes = getVehicleTypes;
+exports.getMakes = getMakes;
+exports.getModels = getModels;
+exports.getAvailableYears = getAvailableYears;
+exports.close = close;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const path_1 = __importDefault(require("path"));
+const DB_PATH = path_1.default.join(__dirname, "..", "data", "nhtsa.db");
+// ---------------------------------------------------------------------------
+// Database singleton
+// ---------------------------------------------------------------------------
+let _db = null;
+function getDb() {
+    if (!_db) {
+        _db = new better_sqlite3_1.default(DB_PATH, { readonly: true, fileMustExist: true });
+    }
+    return _db;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Returns all vehicle types in the database.
+ */
+function getVehicleTypes() {
+    const db = getDb();
+    const rows = db
+        .prepare("SELECT vehicle_type_id, vehicle_type_name FROM vehicle_types ORDER BY vehicle_type_name")
+        .all();
+    return rows.map((r) => ({
+        vehicleTypeId: r.vehicle_type_id,
+        vehicleTypeName: r.vehicle_type_name,
+    }));
+}
+/**
+ * Returns makes, optionally filtered by year and/or vehicle type.
+ */
+function getMakes(options = {}) {
+    const db = getDb();
+    const conditions = [];
+    const params = [];
+    if (options.year != null) {
+        conditions.push("m.year = ?");
+        params.push(options.year);
+    }
+    if (options.vehicleTypeId != null) {
+        conditions.push("m.vehicle_type_id = ?");
+        params.push(options.vehicleTypeId);
+    }
+    let sql;
+    if (conditions.length > 0) {
+        sql = `SELECT DISTINCT mk.make_id, mk.make_name
+           FROM models m
+           JOIN makes mk USING (make_id)
+           WHERE ${conditions.join(" AND ")}
+           ORDER BY mk.make_name`;
+    }
+    else {
+        sql = `SELECT make_id, make_name FROM makes ORDER BY make_name`;
+    }
+    const rows = db.prepare(sql).all(...params);
+    return rows.map((r) => ({
+        makeId: r.make_id,
+        makeName: r.make_name,
+    }));
+}
+/**
+ * Returns models, optionally filtered by year, vehicle type, and/or make.
+ */
+function getModels(options = {}) {
+    const db = getDb();
+    const conditions = [];
+    const params = [];
+    if (options.year != null) {
+        conditions.push("m.year = ?");
+        params.push(options.year);
+    }
+    if (options.vehicleTypeId != null) {
+        conditions.push("m.vehicle_type_id = ?");
+        params.push(options.vehicleTypeId);
+    }
+    if (options.makeId != null) {
+        conditions.push("m.make_id = ?");
+        params.push(options.makeId);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const sql = `
+    SELECT m.model_id, m.model_name, mk.make_id, mk.make_name,
+           vt.vehicle_type_id, vt.vehicle_type_name
+    FROM models m
+    JOIN makes mk USING (make_id)
+    JOIN vehicle_types vt USING (vehicle_type_id)
+    ${where}
+    ORDER BY m.model_name`;
+    const rows = db.prepare(sql).all(...params);
+    return rows.map((r) => ({
+        modelId: r.model_id,
+        modelName: r.model_name,
+        makeId: r.make_id,
+        makeName: r.make_name,
+        vehicleTypeId: r.vehicle_type_id,
+        vehicleTypeName: r.vehicle_type_name,
+    }));
+}
+/**
+ * Get all available years in the database.
+ */
+function getAvailableYears() {
+    const db = getDb();
+    const rows = db
+        .prepare("SELECT DISTINCT year FROM models ORDER BY year")
+        .all();
+    return rows.map((r) => r.year);
+}
+/**
+ * Close the database connection (optional cleanup).
+ */
+function close() {
+    if (_db) {
+        _db.close();
+        _db = null;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@meterapp/vehicle-db",
+  "version": "1.0.0",
+  "description": "Offline NHTSA vehicle makes/models database bundled as SQLite",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "data/nhtsa.db"
+  ],
+  "scripts": {
+    "build:db": "tsx scripts/build-db.ts",
+    "build:ts": "tsc",
+    "build": "npm run build:ts",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "nhtsa",
+    "vehicles",
+    "makes",
+    "models",
+    "offline",
+    "sqlite"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "better-sqlite3": "^12.6.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.4.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}