VIN
Utilities for working with Vehicle Identification Numbers (VIN) based on the ISO 3779 standard.
Overview
The VIN module provides utilities to validate the 17-character unique identification code for motor vehicles. It includes checksum validation using the standard Modulus 11 algorithm.
Features
- Validation: Check if a VIN is exactly 17 characters and follows ISO 3779 (excluding characters I, O, and Q).
- Checksum: Automated checksum calculation and verification using the check digit at position 9.
Installation
npm
npm install @indodev/toolkitQuick Start
import { validateVIN, parseVIN, maskVIN, cleanVIN } from '@indodev/toolkit/vin';
// Validate a VIN (with correct checksum)
validateVIN('1HGCM82633A004352'); // true
// Invalid VIN (contains prohibited character 'I')
validateVIN('1HBHA82I7ZB000001'); // false
// Invalid VIN (incorrect checksum)
validateVIN('1HGCM82633A004353'); // false
// Parse VIN
const info = parseVIN('1HGCM82633A004352');
console.log(info.wmi); // '1HG'
console.log(info.vds); // 'CM8263'
console.log(info.checkDigit); // '3'
console.log(info.modelYearCode); // 'A'
console.log(info.plantCode); // '0'
console.log(info.serialNumber); // '04352'
// Mask VIN (for privacy)
maskVIN('1HGBH41JXMN109186'); // '1HGBH41JXMN******'
// Clean VIN (remove non-alphanumeric)
cleanVIN('1HGBH-41JXMN-109186'); // '1HGBH41JXMN109186'API Reference
validateVIN()
Validates a Vehicle Identification Number (VIN) based on ISO 3779 standards.
Type Signature:
function validateVIN(vin: string): boolean;Parameters:
| Name | Type | Description |
|---|---|---|
vin | string | The VIN string to check |
Returns:
boolean - Returns true if valid, false otherwise.
parseVIN()
Parses a VIN and extracts its component parts.
Type Signature:
function parseVIN(vin: string): VINInfo | null;Parameters:
| Name | Type | Description |
|---|---|---|
vin | string | The VIN string to parse |
Returns:
VINInfo | null - Parsed VIN information or null if invalid.
Example:
const info = parseVIN('1HGCM82633A004352');
if (info) {
console.log(info.wmi); // '1HG'
console.log(info.vds); // 'CM8263'
console.log(info.checkDigit); // '3'
console.log(info.modelYearCode); // 'A'
console.log(info.plantCode); // '0'
console.log(info.serialNumber); // '04352'
console.log(info.isValid); // true
}maskVIN()
Masks a VIN for privacy.
Type Signature:
function maskVIN(vin: string, options?: VINMaskOptions): string;Parameters:
| Name | Type | Description |
|---|---|---|
vin | string | The VIN to mask |
options | VINMaskOptions | Optional masking configuration |
Returns:
string - Masked VIN, or empty string if invalid.
Example:
maskVIN('1HGBH41JXMN109186'); // '1HGBH41JXMN******'
maskVIN('1HGBH41JXMN109186', { visibleEnd: 2 }); // '1HGBH41JXMN****86'cleanVIN()
Cleans a VIN by removing all non-alphanumeric characters.
Type Signature:
function cleanVIN(vin: string): string;Parameters:
| Name | Type | Description |
|---|---|---|
vin | string | The VIN to clean |
Returns:
string - Cleaned VIN (alphanumeric only, uppercase).
Example:
cleanVIN('1HGBH-41JXMN-109186'); // '1HGBH41JXMN109186'Constants
VIN_WEIGHTS
Weights used in the VIN checksum calculation.
import { VIN_WEIGHTS } from '@indodev/toolkit/vin';VIN_CHAR_VALUES
Values assigned to each valid character for VIN calculation.
import { VIN_CHAR_VALUES } from '@indodev/toolkit/vin';VINInfo
Information extracted from a valid VIN.
interface VINInfo {
wmi: string; // World manufacturer identifier (positions 1-3)
vds: string; // Vehicle descriptor section (positions 4-9)
checkDigit: string; // Check digit (position 9)
modelYearCode: string; // Model year code (position 10)
plantCode: string; // Plant code (position 11)
serialNumber: string; // Serial number (positions 12-17)
isValid: boolean; // Whether the VIN passed validation
}VINMaskOptions
Options for masking a VIN.
interface VINMaskOptions {
visibleStart?: number; // Characters visible at start (default: 11)
visibleEnd?: number; // Characters visible at end (default: 0)
maskChar?: string; // Mask character (default: '*')
}InvalidVINError
Error class for invalid VIN with error code for programmatic handling.
class InvalidVINError extends Error {
readonly code = 'INVALID_VIN';
constructor(message?: string);
}Example:
import { InvalidVINError, validateVIN } from '@indodev/toolkit/vin';
try {
if (!validateVIN(vin)) {
throw new InvalidVINError('Invalid VIN format');
}
} catch (error) {
if (error instanceof InvalidVINError) {
console.log(error.code); // 'INVALID_VIN'
}
}