Car API - Documentation

Installation

Install via your preferred package manager. No extra dependencies required.

npm install auto-parts-db

yarn add auto-parts-db

pnpm add auto-parts-db

bun add auto-parts-db

ℹ️

The package ships three build targets: dist/esm for ESM, dist/cjs for CommonJS, and dist/browser/auto-parts-db.min.js as a browser-ready IIFE bundle. The correct one is resolved automatically.

Quick Start

Import the functions you need and start querying immediately.

          TypeScript / ESM
          
        

import { getBrands, getModelsByBrand, searchParts } from 'auto-parts-db';

// Get all car brand names
const brands = getBrands();
console.log(brands); // ['Audi', 'BMW', 'Toyota', ...]

// Get all models for a brand
const models = getModelsByBrand('Audi');
console.log(models[0]);
// { name: 'A4', generations: [{ name: 'B5', yearFrom: 1994, yearTo: 2001 }, ...] }

// Search parts by name or slug
const results = searchParts('absorber');
console.log(results); // [{ slug: 'absorber-bampera', name: '...' }, ...]
        

Node.js / CommonJS

Works out of the box with require() in any Node.js project.

          JavaScript
          index.js
          
const { getBrands, getModelsByBrand, getParts } = require('auto-parts-db');

const brands = getBrands();
console.log(`Loaded ${brands.length} brands`);

const bmwModels = getModelsByBrand('BMW');
console.log(bmwModels);

✅

The main field in package.json points to dist/cjs/index.js — Node.js picks it up automatically with no extra config.

ESM / TypeScript

Full TypeScript support with bundled type definitions. Tree-shakeable — import only what you use.

          TypeScript
          example.ts
          
        

import {
  getBrands,
  getBrand,
  getModelsByBrand,
  getGenerations,
  getGenerationByYear,
} from 'auto-parts-db';
import type { Brand, Model, Generation } from 'auto-parts-db';

// TypeScript knows the exact return types
const brand: Brand | null = getBrand('Toyota');
const gen: Generation | null = getGenerationByYear('BMW', '3 Series', 2019);

console.log(gen); // { name: 'G20', yearFrom: 2018, yearTo: null }
        

📘

Types are shipped in dist/types/index.d.ts and resolved automatically via the types field in package.json. No @types package needed.

React

Use with hooks for dynamic filtering — the data is synchronous so no async required.

          TSX
          BrandSelector.tsx
          
        

import { useState } from 'react';
import { getBrands, getModelsByBrand, searchParts } from 'auto-parts-db';
import type { Model } from 'auto-parts-db';

export default function BrandSelector() {
  const [selected, setSelected] = useState('');
  const [models, setModels] = useState<Model[]>([]);

  const handleBrand = (brand: string) => {
    setSelected(brand);
    setModels(getModelsByBrand(brand));
  };

  return (
    <div>
      <select onChange={e => handleBrand(e.target.value)}>
        <option>Select brand</option>
        {getBrands().map(b => (
          <option key={b} value={b}>{b}</option>
        ))}
      </select>
      <ul>
        {models.map(m => <li key={m.name}>{m.name}</li>)}
      </ul>
    </div>
  );
}
        

Vue 3

Works with the Composition API and <script setup>.

          Vue
          BrandPicker.vue
          
        

<script setup lang="ts">
import { ref } from 'vue';
import { getBrands, getModelsByBrand } from 'auto-parts-db';
import type { Model } from 'auto-parts-db';

const brands = getBrands();
const models = ref<Model[]>([]);

function onBrandChange(e: Event) {
  const val = (e.target as HTMLSelectElement).value;
  models.value = getModelsByBrand(val);
}
</script>

<template>
  <select @change="onBrandChange">
    <option v-for="b in brands" :key="b">{{ b }}</option>
  </select>
  <ul>
    <li v-for="m in models" :key="m.name">{{ m.name }}</li>
  </ul>
</template>
        

Angular

Import directly in a component or wrap in a service for dependency injection.

          TypeScript
          cars.service.ts
          
        

import { Injectable } from '@angular/core';
import { getBrands, getModelsByBrand, searchParts } from 'auto-parts-db';
import type { Model, Part } from 'auto-parts-db';

@Injectable({ providedIn: 'root' })
export class CarsService {
  getBrands(): string[] { return getBrands(); }
  getModels(brand: string): Model[] { return getModelsByBrand(brand); }
  searchParts(q: string): Part[] { return searchParts(q); }
}
        

Browser / CDN

No bundler needed. Drop a single <script> tag and access everything via the global AutoPartsDB object.

Via jsDelivr (recommended)

          HTML
          
        

<script src="https://cdn.jsdelivr.net/npm/auto-parts-db/dist/browser/auto-parts-db.min.js"></script>
<script>
  // All functions available on the AutoPartsDB global object
  const brands = AutoPartsDB.getBrands();
  console.log(brands); // ['Audi', 'BMW', ...]

  const parts = AutoPartsDB.searchParts('absorber');
  console.log(parts);
</script>
        

Full example page

          HTML
          index.html
          
        

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/auto-parts-db/dist/browser/auto-parts-db.min.js"></script>
</head>
<body>
  <select id="brand"></select>
  <ul id="models"></ul>

  <script>
    const { getBrands, getModelsByBrand } = AutoPartsDB;
    const sel = document.getElementById('brand');

    getBrands().forEach(b => {
      const opt = document.createElement('option');
      opt.value = opt.textContent = b;
      sel.append(opt);
    });

    sel.addEventListener('change', () => {
      const list = document.getElementById('models');
      list.innerHTML = getModelsByBrand(sel.value)
        .map(m => `<li>${m.name}</li>`)
        .join('');
    });
  </script>
</body>
</html>
        

⚠️

The browser bundle is ~533 KB because it includes all data inline. For production apps with a bundler, use the npm package instead — tree shaking will reduce the size significantly.

Available globals

After the script loads, all functions are available via AutoPartsDB.*:

AutoPartsDB.getBrands()
AutoPartsDB.getBrand(brandName)
AutoPartsDB.getModelsByBrand(brandName)
AutoPartsDB.getGenerations(brandName, modelName)
AutoPartsDB.getGenerationByYear(brandName, modelName, year)
AutoPartsDB.searchModels(query)
AutoPartsDB.getParts()
AutoPartsDB.getPartBySlug(slug)
AutoPartsDB.searchParts(query)
AutoPartsDB.getPartSlugs()
// Raw data arrays (tree-shaking doesn't apply in browser bundle)
AutoPartsDB.brands
AutoPartsDB.parts
        

API — Brands & Models

All functions are synchronous and return plain objects or arrays.

Function	Parameters	Returns	Description
getBrands()	—	string[]	List of all brand names
getBrand()	brandName: string	Brand \| null	Full brand object with all models
getModelsByBrand()	brandName: string	Model[]	All models for a brand. Case-insensitive.
getGenerations()	brandName, modelName	Generation[]	All generations of a specific model
getGenerationByYear()	brand, model, year	Generation \| null	Generation active in a given year
searchModels()	query: string	{ brand, model }[]	Search models across all brands by partial name

Usage examples

          TypeScript
          
import { getGenerationByYear, searchModels } from 'auto-parts-db';

// Find which generation a 2019 BMW 3 Series is
const gen = getGenerationByYear('BMW', '3 Series', 2019);
// → { name: 'G20', yearFrom: 2018, yearTo: null }

// Search models containing "golf" across all brands
const hits = searchModels('golf');
// → [{ brand: 'Volkswagen', model: { name: 'Golf', generations: [...] } }]

API — Parts

1200+ auto parts with bilingual slugs and names. Search supports Russian and English.

Function	Parameters	Returns	Description
getParts()	—	Part[]	Full list of all auto parts
getPartBySlug()	slug: string	Part \| null	Find a single part by its slug
searchParts()	query: string	Part[]	Search by name or slug. Case-insensitive.
getPartSlugs()	—	string[]	All part slugs (useful for routing/validation)

          TypeScript
          
        

import { searchParts, getPartBySlug } from 'auto-parts-db';

// Search in English
searchParts('absorber');
// → [{ slug: 'absorber-bampera', name: 'Абсорбер (наполнитель бампера)' }, ...]

// Search in Russian
searchParts('тормоз');
// → all brake-related parts

// Lookup by slug
getPartBySlug('akkumuljator');
// → { slug: 'akkumuljator', name: 'Аккумулятор (модуль высоковольтного накопителя батарея)' }
        

TypeScript Types

All types are exported from the package root.

          TypeScript
          
        

import type { Brand, Model, Generation, Part } from 'auto-parts-db';

type Generation = {
  name: string;
  yearFrom: number;
  yearTo: number | null; // null = still in production
};

type Model = {
  name: string;
  generations: Generation[];
};

type Brand = {
  brand: string;
  models: Model[];
};

type Part = {
  slug: string;
  name: string;
};
        

Data Structure

Example of what a brand object looks like in raw form.

          JSON
          
        

{
  "brand": "BMW",
  "models": [
    {
      "name": "3 Series",
      "generations": [
        { "name": "E21", "yearFrom": 1975, "yearTo": 1983 },
        { "name": "E30", "yearFrom": 1982, "yearTo": 1994 },
        { "name": "E36", "yearFrom": 1990, "yearTo": 2000 },
        { "name": "E46", "yearFrom": 1997, "yearTo": 2006 },
        { "name": "E90", "yearFrom": 2004, "yearTo": 2013 },
        { "name": "F30", "yearFrom": 2011, "yearTo": 2019 },
        { "name": "G20", "yearFrom": 2018, "yearTo": null }
      ]
    }
  ]
}
        

💡

A yearTo value of null means the model/generation is still in production as of the latest data update.

Contributing

The database is maintained as plain TypeScript arrays — contributions are welcome and straightforward.

      bash
      
    

# 1. Fork the repository

# 2. Clone your fork locally
git clone https://github.com/lifeofcapo/car-list.git
cd car-list

# 3. Add original repo as upstream (for sync)
git remote add upstream https://github.com/lifeofcapo/car-list.git

# 4. Create a new branch for your changes
git checkout -b add-new-brand

# 5. Install dependencies
npm install

# 6. Make your changes

# 7. Build to verify everything works
npm run build

# 8. Commit and push to your fork
git add .
git commit -m "feat: add new car brand X"
git push origin add-new-brand

# 9. Create Pull Request on GitHub
#    Go to your fork → "Contribute" → "Open Pull Request"
    

💡

All types are inferred automatically — no schema changes needed. Just add your data to the arrays and the TypeScript types will update themselves.

The automotive database for JavaScript

Installation

Quick Start

Node.js / CommonJS

ESM / TypeScript

React

Vue 3

Angular

Browser / CDN

Via jsDelivr (recommended)

Full example page

Available globals

API — Brands & Models

Usage examples

API — Parts

TypeScript Types

Data Structure

Contributing

The automotive
database for
JavaScript