@meterapp/vehicle-db 2.3.0 → 2.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @meterapp/vehicle-db
 
-Offline NHTSA vehicle database plus Meter-owned auto-rickshaw and global market passenger fleet entries. All U.S. vehicle makes and models from 1990–2026, plus Atul Auto rickshaws and common global vans, MPVs, minibuses, sedans, SUVs, and EVs. Zero dependencies, ~190 KB on npm. No network requests needed.
+An offline, international vehicle make/model catalog for Node.js and TypeScript. The package combines U.S. model-year data, the UK registered fleet, and a manufacturer catalog into one small, zero-dependency API. It never makes runtime network requests.
 
-Covers four vehicle types: **Passenger Car**, **Truck**, **Multipurpose Passenger Vehicle (MPV)**, and **Auto Rickshaw**.
+The catalog covers seven vehicle types: **Motorcycle**, **Passenger Car**, **Truck**, **Bus**, **Multipurpose Passenger Vehicle (MPV)**, **Auto Rickshaw**, and **Other Vehicle**. The UK fleet source adds European and Asian market vehicles plus motorcycles, light and heavy goods vehicles, and the explicit “Buses and coaches” category.
 
 ## Install
 
@@ -10,152 +10,180 @@ Covers four vehicle types: **Passenger Car**, **Truck**, **Multipurpose Passenge
 npm install @meterapp/vehicle-db
 ```
 
-> Requires Node.js 18+. Zero runtime dependencies — data is bundled as JSON.
+Requires Node.js 18 or newer.
 
 ## Usage
 
 ```typescript
 import {
+  getDataSources,
   getVehicleTypes,
   getMakes,
   getModels,
   getAvailableYears,
-  close,
 } from "@meterapp/vehicle-db";
 
-// List available vehicle types
+// Inspect provenance and coverage before querying.
+const sources = getDataSources();
+
+// All seven categories, including Motorcycle (1) and Bus (5).
 const types = getVehicleTypes();
-// => [
-//   { vehicleTypeId: 2, vehicleTypeName: "Passenger Car" },
-//   { vehicleTypeId: 3, vehicleTypeName: "Truck" },
-//   { vehicleTypeId: 7, vehicleTypeName: "Multipurpose Passenger Vehicle (MPV)" },
-//   { vehicleTypeId: 10001, vehicleTypeName: "Auto Rickshaw" },
-// ]
-
-// Get all makes
-const allMakes = getMakes();
-
-// Get makes that have models in 2024
-const makes2024 = getMakes({ year: 2024 });
-
-// Get only truck makes for 2024
-const truckMakes = getMakes({ year: 2024, vehicleTypeId: 3 });
-
-// Get all Toyota models for 2024
-const toyotaModels = getModels({ makeId: 474, year: 2024 });
-// => [
-//   { modelId: 2469, modelName: "Camry", makeId: 474, makeName: "TOYOTA", vehicleTypeId: 2, vehicleTypeName: "Passenger Car" },
-//   { modelId: 2208, modelName: "Corolla", ... },
-//   ...
-// ]
-
-// Get only Ford trucks for 2024
-const fordTrucks = getModels({ makeId: 460, year: 2024, vehicleTypeId: 3 });
-// => [{ modelId: 1801, modelName: "F-150", ... }, ...]
-
-// Get Atul auto-rickshaw models for 2024
-const atulRickshaws = getModels({ makeId: 100001, year: 2024, vehicleTypeId: 10001 });
-// => [{ modelId: 100001, modelName: "RIK", makeName: "ATUL AUTO", vehicleTypeName: "Auto Rickshaw", ... }, ...]
-
-// Get all available years
-const years = getAvailableYears();
-// => [1990, 1991, ..., 2026]
 
-// Optional: close the DB connection when you're done
-close();
+// All makes with a 2024 motorcycle in the international UK fleet source.
+const motorcycleMakes = getMakes({
+  year: 2024,
+  vehicleTypeId: 1,
+  sourceId: "uk-dft-vehicle-licensing",
+});
+
+// Honda motorcycle models manufactured in 2024.
+const honda = motorcycleMakes.find((make) => make.makeName === "HONDA");
+const hondaMotorcycles = getModels({
+  makeId: honda!.makeId,
+  year: 2024,
+  vehicleTypeId: 1,
+  sourceId: "uk-dft-vehicle-licensing",
+});
+
+// Coach and transit bus makes/models use vehicle type 5.
+const busMakes = getMakes({ year: 2024, vehicleTypeId: 5 });
+const alexanderDennis = busMakes.find((make) => make.makeName === "ALEXANDER DENNIS");
+const buses = getModels({
+  makeId: alexanderDennis!.makeId,
+  year: 2024,
+  vehicleTypeId: 5,
+});
+
+// Existing queries remain valid.
+const toyota = getMakes({ year: 2024 }).find((make) => make.makeName === "TOYOTA");
+const toyotaModels = getModels({ makeId: toyota!.makeId, year: 2024 });
+const years = getAvailableYears();
 ```
 
 ## API
 
+### `getDataSources(): DataSource[]`
+
+Returns the provenance, license, region, retrieval date, year range, vehicle types, and record counts for every source.
+
+```typescript
+interface DataSource {
+  sourceId: string;
+  sourceName: string;
+  sourceUrl: string;
+  license: string;
+  licenseUrl?: string;
+  region: string;
+  description: string;
+  retrievedAt: string;
+  vehicleTypeIds: number[];
+  yearFrom: number;
+  yearTo: number;
+  makeCount: number;
+  modelCount: number;
+}
+```
+
 ### `getVehicleTypes(): VehicleType[]`
 
-Returns all vehicle types in the database.
+Returns every vehicle category in the bundled catalog.
 
 ```typescript
 interface VehicleType {
-  vehicleTypeId: number;   // e.g. 2
-  vehicleTypeName: string; // e.g. "Passenger Car"
+  vehicleTypeId: number;
+  vehicleTypeName: string;
 }
 ```
 
 ### `getMakes(options?): Make[]`
 
-Returns makes, optionally filtered by year and/or vehicle type.
+Returns makes, optionally filtered by `year`, `vehicleTypeId`, and/or `sourceId`.
 
 ```typescript
-getMakes()                                    // all makes
-getMakes({ year: 2024 })                      // makes with models in 2024
-getMakes({ vehicleTypeId: 3 })                // truck makes (all years)
-getMakes({ year: 2024, vehicleTypeId: 3 })    // truck makes in 2024
-getMakes({ year: 2024, vehicleTypeId: 10001 }) // auto-rickshaw makes in 2024
+getMakes();
+getMakes({ year: 2024 });
+getMakes({ year: 2024, vehicleTypeId: 5 });
+getMakes({ sourceId: "uk-dft-vehicle-licensing" });
 ```
 
 ```typescript
 interface Make {
-  makeId: number;   // e.g. 460
-  makeName: string; // e.g. "FORD"
+  makeId: number;
+  makeName: string;
 }
 ```
 
 ### `getModels(options?): Model[]`
 
-Returns models, optionally filtered by year, vehicle type, and/or make.
+Returns models, optionally filtered by `year`, `vehicleTypeId`, `makeId`, and/or `sourceId`. `sourceIds` preserves provenance when equivalent records appear in more than one source.
 
 ```typescript
-getModels({ makeId: 474, year: 2024 })                      // Toyota 2024 (all types)
-getModels({ makeId: 460, year: 2024, vehicleTypeId: 3 })    // Ford trucks 2024
-getModels({ makeId: 100001, year: 2024, vehicleTypeId: 10001 }) // Atul auto-rickshaws 2024
-getModels({ vehicleTypeId: 3 })                              // all trucks (all years)
-getModels({ year: 2024 })                                    // everything in 2024
+getModels({ makeId: 474, year: 2024 });
+getModels({ year: 2024, vehicleTypeId: 1 });
+getModels({ year: 2024, vehicleTypeId: 5, sourceId: "uk-dft-vehicle-licensing" });
 ```
 
 ```typescript
 interface Model {
-  modelId: number;          // e.g. 1801
-  modelName: string;        // e.g. "F-150"
-  makeId: number;           // e.g. 460
-  makeName: string;         // e.g. "FORD"
-  vehicleTypeId: number;    // e.g. 3
-  vehicleTypeName: string;  // e.g. "Truck"
+  modelId: number;
+  modelName: string;
+  makeId: number;
+  makeName: string;
+  vehicleTypeId: number;
+  vehicleTypeName: string;
+  sourceIds: string[];
 }
 ```
 
 ### `getAvailableYears(): number[]`
 
-Returns all years present in the database, sorted ascending.
+Returns all years present in the combined catalog, sorted ascending.
+
+## Data sources
+
+| Source | Coverage in this snapshot | Terms |
+|---|---|---|
+| [NHTSA vPIC](https://vpic.nhtsa.dot.gov/api/) | U.S. passenger cars, trucks, and MPVs; model years 1990–2026 | U.S. government public data |
+| [UK DfT/DVLA vehicle licensing statistics](https://www.gov.uk/government/statistical-data-sets/vehicle-licensing-statistics-data-files) | 701 normalized makes across cars, motorcycles, goods vehicles, buses and coaches, and other vehicles; manufacture years 1990–2025 | [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/) |
+| [Atul Auto product catalog](https://atulauto.co.in/products/) | Current Indian passenger and cargo auto-rickshaw range; catalog years 2024–2026 | Source attribution; factual product names only |
 
-### `close(): void`
+Year means the source’s model year for NHTSA, year of manufacture for DfT/DVLA (falling back to year of first use when manufacture year is unavailable), and catalog year for Atul Auto. DfT notes that its fields are administrative records and can contain classification or naming errors. Source filters let applications choose the semantics appropriate for their workflow.
 
-Closes the SQLite connection. Safe to call multiple times. The connection reopens automatically on the next query.
+UK source attribution: Contains public sector information licensed under the Open Government Licence v3.0. Source: Department for Transport and Driver and Vehicle Licensing Agency.
 
-## Database stats
+## Snapshot stats
 
 | | |
-|---|---|
-| **Years** | 1990 – 2026 |
-| **Vehicle types** | 4 (Passenger Car, Truck, MPV, Auto Rickshaw) |
-| **Makes** | 409 |
-| **Model entries** | 55,589 |
-| **Data file** | 1.3 MB (JSON) |
-| **npm package** | 190 KB |
-| **npm package size** | 1.5 MB |
+|---|---:|
+| Years | 1990–2026 |
+| Sources | 3 |
+| Vehicle types | 7 |
+| Makes | 1,017 |
+| Model names | 8,806 |
+| Deduplicated model-year entries | 108,308 |
+| Bundled TypeScript data | 3.32 MB |
 
-## Rebuilding the database
+## Refreshing and rebuilding
 
-To refresh the data from the NHTSA API:
+The committed source snapshots make the package build deterministic and offline:
 
 ```bash
-npm run build:db
+npm run build:data
+npm test
+npm run typecheck
+npm run build
 ```
 
-Or for a specific year range:
+Refresh either network source independently, then rebuild the combined catalog:
 
 ```bash
-npm run build:db -- --start-year 2020 --end-year 2026
+npm run refresh:uk-dft
+npm run refresh:nhtsa -- --start-year 1990 --end-year 2026
+npm run build:data
 ```
 
-> 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.
+The NHTSA API rate-limits aggressively, so a full NHTSA refresh can take time. The UK importer downloads the two official VEH0124 CSV files to a temporary directory, keeps valid make/generic-model/year records, assigns deterministic numeric IDs to non-NHTSA entities, and deletes the raw downloads when complete.
 
 ## License
 
-ISC
+The package code is ISC licensed. Upstream data remains subject to the terms listed above.

package/dist/data.d.ts

@@ -1,4 +1,19 @@
 interface CompactData {
+    sources: {
+        source_id: string;
+        source_name: string;
+        source_url: string;
+        license: string;
+        license_url?: string;
+        region: string;
+        description: string;
+        retrieved_at: string;
+        vehicle_type_ids: number[];
+        year_from: number;
+        year_to: number;
+        make_count: number;
+        model_count: number;
+    }[];
     vehicleTypes: {
         vehicle_type_id: number;
         vehicle_type_name: string;
@@ -8,7 +23,7 @@ interface CompactData {
         make_name: string;
     }[];
     modelNames: string[];
-    models: [number, number, number, number, number][];
+    models: [number, number, number, number, number, number][];
 }
 declare const data: CompactData;
 export default data;