🐕 Corgi VIN Decoder

The fastest and most lightweight open-source VIN decoding library on the planet.

Corgi is a blazing-fast, fully offline VIN decoder built with TypeScript. Powered by an optimized VPIC database, it delivers comprehensive vehicle information with zero network dependencies and lightning-fast performance across Node.js, browsers, and Cloudflare Workers.

⚡ Performance First

Fully Offline: No API calls, no network dependencies, no rate limits
Lightning Fast: Optimized SQLite database with pattern-based decoding
Tiny Footprint: ~20MB compressed bundle with complete NHTSA dataset
Zero Dependencies: Self-contained with automatic database management
Universal: Works everywhere - Node.js, browsers, and edge computing

🚀 Quick Start

npm install @cardog/corgi

import { createDecoder } from "@cardog/corgi";

// One-line VIN decoding - database auto-managed
const decoder = await createDecoder();
const result = await decoder.decode("KM8K2CAB4PU001140");

console.log(result.components.vehicle);
// {
//   make: 'Hyundai',
//   model: 'Kona',
//   year: 2023,
//   series: 'SE',
//   bodyStyle: 'SUV',
//   driveType: '4WD/4-Wheel Drive/4x4',
//   fuelType: 'Gasoline',
//   doors: '5'
// }

await decoder.close();

📋 What You Get

Corgi extracts comprehensive vehicle information from any VIN:

Vehicle Details: Make, model, year, series, trim, body style
Technical Specs: Engine details, drivetrain, fuel type, doors
Manufacturing: Plant location, manufacturer, production details
Quality Metrics: Confidence scores and validation results
Standards Compliance: Full NHTSA VPIC dataset integration

🏗️ Platform Support

Node.js

import { createDecoder } from "@cardog/corgi";

// Automatic database management - downloads and caches on first run
const decoder = await createDecoder();
const result = await decoder.decode("1HGCM82633A123456");

// Or provide your own database path
const customDecoder = await createDecoder({
  databasePath: "/path/to/vpic.lite.db",
});

Browser

// Host the database file and provide the URL
const browserDecoder = await createDecoder({
  databasePath: "https://cdn.example.com/vpic.lite.db.gz",
  runtime: "browser",
});

Cloudflare Workers

import { createDecoder, initD1Adapter } from "@cardog/corgi";

// Initialize D1 adapter with your binding
initD1Adapter(env.D1_DATABASE);

// Create decoder
const decoder = await createDecoder({
  databasePath: "D1",
  runtime: "cloudflare",
});

⚙️ Configuration

Advanced Options

const decoder = await createDecoder({
  databasePath: "./custom/db/path.db", // Custom database location
  forceFresh: true, // Force fresh database setup
  defaultOptions: {
    includePatternDetails: true, // Pattern matching details
    includeRawData: false, // Raw database records
    confidenceThreshold: 0.8, // Confidence threshold (0-1)
    includeDiagnostics: true, // Performance metrics
  },
});

// Override options per decode
const result = await decoder.decode("VIN12345678901234", {
  modelYear: 2024, // Override detected year
  includePatternDetails: true, // Include pattern analysis
});

Quick Decode Helper

import { quickDecode } from "@cardog/corgi";

// One-line decoding with shared instance
const result = await quickDecode("1HGCM82633A123456");

📊 Response Structure

interface DecodeResult {
  vin: string; // Input VIN
  valid: boolean; // Overall validation status

  components: {
    vehicle?: {
      // Core vehicle information
      make: string; // e.g., "Honda", "Toyota"
      model: string; // e.g., "Civic", "Camry"
      year: number; // Model year
      series?: string; // Trim/series level
      bodyStyle?: string; // "Sedan", "SUV", "Pickup"
      driveType?: string; // "FWD", "AWD", "4WD"
      fuelType?: string; // "Gasoline", "Electric"
      doors?: string; // Number of doors
    };

    wmi?: {
      // World Manufacturer Identifier
      manufacturer: string; // Official manufacturer name
      make: string; // Brand name
      country: string; // Country of origin
      region: string; // Geographic region
    };

    plant?: {
      // Manufacturing details
      country: string; // Production country
      city?: string; // Production city
      code: string; // Plant code
    };

    engine?: {
      // Engine specifications
      model?: string; // Engine model/code
      cylinders?: string; // Cylinder count
      displacement?: string; // Engine displacement
      fuel?: string; // Fuel type
    };

    modelYear?: {
      // Year detection details
      year: number; // Detected year
      source: string; // Detection method
      confidence: number; // Confidence score
    };

    checkDigit?: {
      // VIN validation
      isValid: boolean; // Check digit validity
      expected?: string; // Expected value
      actual: string; // Actual value
    };
  };

  errors: DecodeError[]; // Validation errors
  metadata?: DiagnosticInfo; // Performance metrics
  patterns?: PatternMatch[]; // Pattern details (optional)
}

🚨 Error Handling

import { ErrorCode, ErrorCategory } from "@cardog/corgi";

const result = await decoder.decode("INVALID_VIN");

if (!result.valid) {
  result.errors.forEach((error) => {
    console.log(`${error.category}: ${error.message}`);

    // Handle specific error types
    switch (error.code) {
      case ErrorCode.INVALID_CHECK_DIGIT:
        console.log(`Expected: ${error.expected}, Got: ${error.actual}`);
        break;
      case ErrorCode.INVALID_LENGTH:
        console.log("VIN must be exactly 17 characters");
        break;
      case ErrorCode.WMI_NOT_FOUND:
        console.log("Unknown manufacturer code");
        break;
    }
  });
}

🖥️ Command Line Interface

# Quick VIN decode
npx @cardog/corgi decode 1HGCM82633A123456

# With options
npx @cardog/corgi decode 1HGCM82633A123456 \
  --patterns \
  --year 2022 \
  --format json

# Custom database
npx @cardog/corgi decode 1HGCM82633A123456 \
  --database ./custom/vpic.lite.db

# Help
npx @cardog/corgi --help

💾 Database & Caching

Automatic Database Management

Corgi uses an intelligent caching system to provide optimal performance:

// First run: Downloads, decompresses, and caches database
const decoder = await createDecoder();

// Subsequent runs: Uses cached database for instant startup
const decoder2 = await createDecoder();

// Force fresh download and cache refresh
const freshDecoder = await createDecoder({ forceFresh: true });

Cache Storage Locations

Node.js: ~/.corgi-cache/vpic.lite.db (User home directory)
Browser: Database loaded from your provided URL
Cloudflare: Managed by D1 database service

Database Details

Source: Official NHTSA VPIC dataset (updated automatically)
Compressed Size: ~20MB (vpic.lite.db.gz)
Uncompressed Size: ~40MB (vpic.lite.db)
Update Frequency: Monthly via automated pipeline
Coverage: Complete VIN database with optimized queries

Cache Management

import { getDatabasePath } from "@cardog/corgi";

// Get current cached database path
const dbPath = await getDatabasePath();
console.log(`Database cached at: ${dbPath}`);

// Force cache refresh (useful after package updates)
const decoder = await createDecoder({ forceFresh: true });

🔬 Advanced Features

Pattern-Based Decoding

const result = await decoder.decode("VIN12345678901234", {
  includePatternDetails: true,
  confidenceThreshold: 0.8,
});

// Analyze individual pattern matches
result.patterns?.forEach((pattern) => {
  console.log(`${pattern.element}: ${pattern.value} (${pattern.confidence})`);
});

// Overall decode confidence
console.log(`Confidence: ${result.metadata?.confidence}`);

Body Style Normalization

import { BodyStyle } from "@cardog/corgi";

// Automatic normalization to standard values
console.log(BodyStyle.SUV); // "SUV"
console.log(BodyStyle.SEDAN); // "Sedan"
console.log(BodyStyle.PICKUP); // "Pickup"

// Raw values like "Sport Utility Vehicle (SUV)/Multi-Purpose Vehicle (MPV)"
// become clean "SUV"

Performance Diagnostics

const result = await decoder.decode("VIN12345678901234", {
  includeDiagnostics: true,
});

console.log(`Processing time: ${result.metadata?.processingTime}ms`);
console.log(`Schema version: ${result.metadata?.schemaVersion}`);

🤝 Contributing

We welcome contributions from the automotive and developer communities! Corgi is built to be the fastest, most reliable VIN decoder available.

Quick Start

git clone https://github.com/cardog-ai/corgi.git
cd corgi
pnpm install
pnpm approve-builds
pnpm test

Development Workflow

Issues: Report bugs or request features via GitHub Issues
Pull Requests: Fork, create a feature branch, and submit a PR
Testing: All changes must include tests and pass existing test suite
Standards: Follow existing TypeScript patterns and conventions

Database Updates

The VPIC database is automatically maintained via CI/CD pipelines. Manual database updates are rarely needed, but documentation is available for contributors.

Community Guidelines

Be respectful and inclusive
Follow semantic versioning for changes
Write clear commit messages
Add tests for new functionality

Made with ❤️ by the automotive community

📄 License

ISC License - see LICENSE for details.

Package detail

@cardog/corgi

readme