car-json-datasets/README.md

Data-only package with finalized car JSON datasets (one per make)

# car-json-datasets

Data-only npm package containing finalized car JSON datasets generated by the `car-json-generator` project. Each make has its own directory and includes only the final aggregated JSON file (no `tree.json`).

## Install

```bash
npm install car-json-datasets
```

## Usage

### Basic Data Access

```js
// ESM
import mazda from "car-json-datasets/data/mazda/mazda.json" assert { type: "json" };

// CommonJS
const mazda = require("car-json-datasets/data/mazda/mazda.json");

console.log(mazda.make); // "Mazda"
```

### OOP API (Recommended)

The package provides a fluent, object-oriented API for querying car data:

```typescript
import { CarQuery } from "car-json-datasets";

// Create a query instance
const query = new CarQuery();

// Fluent interface - set make first
query.setMake("Volkswagen");

// Get available models for Volkswagen
const models = query.getAvailableModels();
console.log(models); // ['Golf', 'Passat', 'Tiguan', ...]

// Set model and get available series
query.setModel("Golf");
const series = query.getAvailableSeries();
console.log(series); // ['Mk1 (A1)', 'Mk2 (A2)', 'Mk3 (A3)', ...]

// Set year and get series filtered by year
query.setYear(2020);
const seriesForYear = query.getAvailableSeries(true);
console.log(seriesForYear); // Only series available in 2020

// Set series and get available body types
query.setSeries("Mk7 (A7)");
const bodyTypes = query.getAvailableBodyTypes();
console.log(bodyTypes); // ['Hatchback', 'Estate', 'Sportsvan']

// Set body type and get available engines
query.setBodyType("Hatchback");
const engines = query.getAvailableEngines();
console.log(engines); // Array of engine specifications

// Set year if needed
query.setYear(2020);

// Get the final result (properly typed)
const result = query.getResult();
console.log(result);
// {
//   make: "Volkswagen",
//   model?: { name: "Golf", minYear: 1974, maxYear: null, series: [...] },
//   series?: { name: "Mk7 (A7)", startYear: 2012, endYear: 2020, bodyTypes: [...] },
//   bodyType?: { type: "Hatchback", engines: [...] },
//   year?: 2020
// }

// Reset to start a new query
query.reset();
```

### Advanced Usage

```typescript
import { CarQuery, CarDataProvider } from "car-json-datasets";

// Custom data provider (for testing or custom data sources)
const customProvider = new CarDataProvider();
const query = new CarQuery(customProvider);

// Clone queries
const golfQuery = query.setMake("Volkswagen").setModel("Golf");
const passatQuery = golfQuery.clone().setModel("Passat");

// Check current state
if (query.isMakeSet()) {
  console.log("Make is set to:", query.getMake());
}

// Get all available makes
const allMakes = query.getAvailableMakes();
console.log("Available makes:", allMakes);
```

## Package structure

```
car-json-datasets/
  data/
    mazda/
      mazda.json
    volkswagen/
      volkswagen.json
    ...
  dist/
    index.js          # Compiled JavaScript
    index.d.ts        # TypeScript declarations
```

## API Reference

### CarQuery Class

Main class for building car queries with a fluent interface.

#### Methods

- `setMake(make: string): CarQuery` - Set the car make
- `setModel(model: string): CarQuery` - Set the car model
- `setSeries(series: string): CarQuery` - Set the car series
- `setBodyType(bodyType: string): CarQuery` - Set the body type
- `setYear(year: number): CarQuery` - Set the year
- `getResult(): any` - Get the current query result
- `execute(): any` - Alias for getResult()
- `reset(): CarQuery` - Reset all query parameters
- `clone(): CarQuery` - Create a copy of the current query

#### State Getters

- `getMake(): string | null`
- `getModel(): string | null`
- `getSeries(): string | null`
- `getBodyType(): string | null`
- `getYear(): number | null`

#### Available Options

- `getAvailableMakes(): string[]`
- `getAvailableModels(): string[]`
- `getAvailableSeries(includeYears?: boolean): string[]`
- `getAvailableBodyTypes(): string[]`
- `getAvailableYears(): number[]`

### Interfaces

- `ICarQuery` - Main query interface
- `ICarDataProvider` - Data provider interface
- `IQueryState` - Query state management interface

## SOLID Principles Implementation

1. **Single Responsibility**: Each class has one clear purpose

   - `CarQuery`: Orchestrates the query process
   - `CarDataProvider`: Handles data access
   - `QueryState`: Manages query state

2. **Open/Closed**: Easy to extend without modifying existing code

   - Custom data providers can implement `ICarDataProvider`
   - Custom state managers can implement `IQueryState`

3. **Liskov Substitution**: All implementations can be substituted for their interfaces

4. **Interface Segregation**: Small, focused interfaces for each responsibility

5. **Dependency Inversion**: High-level modules depend on abstractions, not concretions

This package is updated automatically when `car-json-generator`'s `main` branch is updated.