@indodev/toolkit 0.5.0 → 0.7.0

package/dist/utils-D4A4ro8M.d.ts

@@ -0,0 +1,507 @@
+/**
+ * Validates a NIK (Nomor Induk Kependudukan) format.
+ *
+ * A valid NIK must:
+ * - Be exactly 16 digits
+ * - Have a valid province code (positions 1-2)
+ * - Have a valid date (positions 7-12)
+ * - Not be in the future
+ * - Not be before 1900
+ *
+ * For female NIKs, the day is encoded as (actual day + 40).
+ * For example, a female born on the 15th would have day = 55.
+ *
+ * @param nik - The 16-digit NIK string to validate
+ * @returns `true` if the NIK is valid, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * validateNIK('3201234567890123'); // true - valid NIK
+ * validateNIK('1234'); // false - wrong length
+ * validateNIK('9912345678901234'); // false - invalid province
+ * ```
+ *
+ * @public
+ */
+declare function validateNIK(nik: string): boolean;
+
+/**
+ * Information extracted from a valid NIK.
+ *
+ * Contains parsed data including location codes, birth date, gender,
+ * and serial number from a 16-digit NIK string.
+ *
+ * @public
+ */
+interface NIKInfo {
+    /**
+     * Province information extracted from positions 1-2 of the NIK.
+     *
+     * @example
+     * ```typescript
+     * { code: '32', name: 'Jawa Barat' }
+     * ```
+     */
+    province: {
+        /** Two-digit province code (e.g., '32') */
+        code: string;
+        /** Full province name (e.g., 'Jawa Barat') */
+        name: string;
+    };
+    /**
+     * Regency (Kabupaten/Kota) information extracted from positions 3-4 of the NIK.
+     *
+     * @example
+     * ```typescript
+     * { code: '01', name: 'Kab. Bogor' }
+     * ```
+     */
+    regency: {
+        /** Two-digit regency code (e.g., '01') */
+        code: string;
+        /** Full regency name (e.g., 'Kab. Bogor') */
+        name: string;
+    };
+    /**
+     * District (Kecamatan) information extracted from positions 5-6 of the NIK.
+     * May be `null` if district data is not available.
+     *
+     * @example
+     * ```typescript
+     * { code: '23', name: 'Ciawi' }
+     * ```
+     */
+    district: {
+        /** Two-digit district code (e.g., '23') */
+        code: string;
+        /** Full district name, or `null` if data unavailable */
+        name: string | null;
+    };
+    /**
+     * Birth date extracted from positions 7-12 of the NIK.
+     * For females, the day is encoded as (actual day + 40).
+     * Returns `null` if the date is invalid.
+     *
+     * @example
+     * ```typescript
+     * new Date(1989, 0, 31) // January 31, 1989
+     * ```
+     */
+    birthDate: Date | null;
+    /**
+     * Gender derived from the day encoding in the NIK.
+     * - 'male': day is 1-31
+     * - 'female': day is 41-71 (actual day + 40)
+     * - `null`: if unable to determine
+     */
+    gender: 'male' | 'female' | null;
+    /**
+     * Serial number from positions 13-16 of the NIK.
+     * Uniquely identifies individuals with the same location and birth date.
+     * Returns `null` if unable to extract.
+     *
+     * @example
+     * ```typescript
+     * '0123'
+     * ```
+     */
+    serialNumber: string | null;
+    /**
+     * Whether the NIK passed validation checks.
+     * If `false`, other fields may be `null` or contain partial data.
+     */
+    isValid: boolean;
+}
+/**
+ * Options for masking a NIK to protect privacy.
+ *
+ * Controls how many characters to show at the start and end,
+ * what character to use for masking, and optional separators.
+ *
+ * @example
+ * Default masking:
+ * ```typescript
+ * { visibleStart: 4, visibleEnd: 4, maskChar: '*' }
+ * // Result: '3201********0123'
+ *
+ * // With separator
+ * { visibleStart: 4, visibleEnd: 4, maskChar: '*', separator: '-' }
+ * // Result: '3201-****-****-0123'
+ * ```
+ *
+ * @public
+ */
+interface MaskOptions {
+    /**
+     * Number of characters to show at the start.
+     *
+     * @defaultValue 4
+     */
+    visibleStart?: number;
+    /**
+     * Number of characters to show at the end.
+     *
+     * @defaultValue 4
+     */
+    visibleEnd?: number;
+    /**
+     * Character to use for masking hidden digits.
+     *
+     * @defaultValue '*'
+     */
+    maskChar?: string;
+    /**
+     * Optional separator to add between groups of digits.
+     * If provided, the NIK will be formatted with separators.
+     *
+     * @defaultValue undefined (no separator)
+     *
+     * @example
+     * ```typescript
+     * '-' // Results in format: '3201-****-****-0123'
+     * ' ' // Results in format: '3201 **** **** 0123'
+     * ```
+     */
+    separator?: string;
+    /**
+     * @deprecated Use `visibleStart` instead. Deprecated in v0.7.0.
+     */
+    start?: number;
+    /**
+     * @deprecated Use `visibleEnd` instead. Deprecated in v0.7.0.
+     */
+    end?: number;
+    /**
+     * @deprecated Use `maskChar` instead. Deprecated in v0.7.0.
+     */
+    char?: string;
+}
+/**
+ * Error thrown when an invalid NIK is provided to a function.
+ * Extends native Error with a `code` property for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   requireNIK('invalid');
+ * } catch (error) {
+ *   if (error instanceof InvalidNIKError) {
+ *     console.log(error.code); // 'INVALID_NIK'
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class InvalidNIKError extends Error {
+    /** Error code for programmatic identification */
+    readonly code: "INVALID_NIK";
+    constructor(message?: string);
+}
+/**
+ * Error codes for detailed NIK validation.
+ *
+ * @public
+ */
+type NIKErrorCode = 'INVALID_FORMAT' | 'INVALID_PROVINCE' | 'INVALID_MONTH' | 'INVALID_DAY' | 'INVALID_DATE' | 'FUTURE_DATE';
+/**
+ * A single validation error with code and message.
+ *
+ * @public
+ */
+interface NIKValidationError {
+    /** Error code for programmatic handling */
+    code: NIKErrorCode;
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Detailed validation result for NIK with structured error reporting.
+ *
+ * Use this for form validation where you need to show specific error
+ * messages per field.
+ *
+ * @example
+ * ```typescript
+ * const result = validateNIKDetailed('1234');
+ * if (!result.isValid) {
+ *   result.errors.forEach(err => {
+ *     console.log(err.code, err.message);
+ *   });
+ * }
+ * ```
+ *
+ * @public
+ */
+interface NIKValidationResult {
+    /** Whether the NIK is valid */
+    isValid: boolean;
+    /** List of validation errors (empty if valid) */
+    errors: NIKValidationError[];
+    /** Cleaned 16-digit NIK if valid, null otherwise */
+    nik: string | null;
+}
+/**
+ * Options for getAge function.
+ *
+ * @public
+ */
+interface GetAgeOptions {
+    /** Date to calculate age from (default: current date) */
+    referenceDate?: Date;
+    /** Return formatted Indonesian string instead of object */
+    asString?: boolean;
+}
+/**
+ * Age result object with years, months, and days.
+ *
+ * @public
+ */
+interface Age {
+    /** Full years */
+    years: number;
+    /** Remaining months after full years */
+    months: number;
+    /** Remaining days after full months */
+    days: number;
+}
+
+/**
+ * Parses a NIK and extracts all embedded information.
+ *
+ * Extracts province, regency, district codes, birth date, gender,
+ * and serial number from a 16-digit NIK string.
+ *
+ * @param nik - The 16-digit NIK string to parse
+ * @returns Parsed NIK information, or `null` if the NIK format is invalid
+ *
+ * @example
+ * Parse a valid male NIK:
+ * ```typescript
+ * const info = parseNIK('3201018901310123');
+ * console.log(info);
+ * // {
+ * //   province: { code: '32', name: 'Jawa Barat' },
+ * //   regency: { code: '01', name: 'Kab. Bogor' },
+ * //   district: { code: '01', name: null },
+ * //   birthDate: Date(1989, 0, 31), // Jan 31, 1989
+ * //   gender: 'male',
+ * //   serialNumber: '0123',
+ * //   isValid: true
+ * // }
+ * ```
+ *
+ * @example
+ * Parse a female NIK (day + 40):
+ * ```typescript
+ * const info = parseNIK('3201019508550123');
+ * console.log(info.gender); // 'female'
+ * console.log(info.birthDate); // Date(1995, 7, 15) - Aug 15, 1995
+ * ```
+ *
+ * @example
+ * Invalid NIK returns null:
+ * ```typescript
+ * const info = parseNIK('invalid');
+ * console.log(info); // null
+ * ```
+ *
+ * @public
+ */
+declare function parseNIK(nik: string): NIKInfo | null;
+
+/**
+ * Formats a NIK with separators for better readability.
+ *
+ * Groups the NIK into logical segments: province, regency, district,
+ * year, month, day, and serial number.
+ *
+ * @param nik - The 16-digit NIK string to format
+ * @param separator - Character to use as separator
+ * @returns Formatted NIK string, or original string if invalid format
+ *
+ * @example
+ * Default separator (dash):
+ * ```typescript
+ * formatNIK('3201234567890123');
+ * // '32-01-23-45-67-89-0123'
+ * ```
+ *
+ * @example
+ * Custom separator:
+ * ```typescript
+ * formatNIK('3201234567890123', ' ');
+ * // '32 01 23 45 67 89 0123'
+ * ```
+ *
+ * @example
+ * Invalid NIK returns as-is:
+ * ```typescript
+ * formatNIK('1234');
+ * // '1234'
+ * ```
+ *
+ * @public
+ */
+declare function formatNIK(nik: string, separator?: string): string;
+/**
+ * Masks a NIK to protect privacy while keeping partial visibility.
+ *
+ * By default, shows the first 4 and last 4 digits, masking the middle 8.
+ * Optionally formats the masked NIK with separators.
+ *
+ * @param nik - The 16-digit NIK string to mask
+ * @param options - Masking configuration options
+ * @returns Masked NIK string, or original string if invalid format
+ *
+ * @example
+ * Default masking (first 4, last 4):
+ * ```typescript
+ * maskNIK('3201234567890123');
+ * // '3201********0123'
+ * ```
+ *
+ * @example
+ * Custom mask character:
+ * ```typescript
+ * maskNIK('3201234567890123', { maskChar: 'X' });
+ * // '3201XXXXXXXX0123'
+ * ```
+ *
+ * @example
+ * With separator:
+ * ```typescript
+ * maskNIK('3201234567890123', { separator: '-' });
+ * // '32-01-**-**-**-**-0123'
+ * ```
+ *
+ * @example
+ * Custom visibleStart and visibleEnd:
+ * ```typescript
+ * maskNIK('3201234567890123', { visibleStart: 6, visibleEnd: 4 });
+ * // '320123******0123'
+ * ```
+ *
+ * @public
+ */
+declare function maskNIK(nik: string, options?: MaskOptions): string;
+
+/**
+ * Calculates the age of a person based on their NIK.
+ *
+ * Returns detailed age breakdown with years, months, and days, or a
+ * formatted Indonesian string. This is consistent with `datetime.getAge()`.
+ *
+ * @param nik - The 16-digit NIK string
+ * @param options - Options object with `referenceDate` and `asString`
+ * @returns Age object `{ years, months, days }`, formatted string, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * // Returns object by default
+ * getAge('3201018901310123');
+ * // { years: 35, months: 2, days: 6 } (as of 2026-04-06)
+ *
+ * // Returns formatted string
+ * getAge('3201018901310123', { asString: true });
+ * // '35 Tahun 2 Bulan 6 Hari'
+ *
+ * // Custom reference date
+ * getAge('3201018901310123', { referenceDate: new Date('2025-01-01') });
+ * // { years: 35, months: 11, days: 1 }
+ * ```
+ *
+ * @public
+ */
+declare function getAge(nik: string, options?: GetAgeOptions): Age | string | null;
+/**
+ * Compares two NIKs to check if they belong to the same person.
+ *
+ * Two NIKs are considered the same person if they have identical:
+ * - Province code (positions 1-2)
+ * - Regency code (positions 3-4)
+ * - District code (positions 5-6)
+ * - Birth date (year + month + day)
+ * - Gender (derived from day encoding)
+ * - Serial number (positions 13-16)
+ *
+ * @param nik1 - First NIK (accepts any format)
+ * @param nik2 - Second NIK (accepts any format)
+ * @returns True if both NIKs belong to the same person, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Same person, same format
+ * compareNIK('3201018901310123', '3201018901310123'); // true
+ *
+ * // Same person, different format
+ * compareNIK('3201018901310123', '3201-01-89-01-31-0123'); // true
+ *
+ * // Different serial number
+ * compareNIK('3201018901310123', '3201018901310124'); // false
+ *
+ * // Invalid NIK
+ * compareNIK('invalid', '3201018901310123'); // false
+ * ```
+ *
+ * @public
+ */
+declare function compareNIK(nik1: string, nik2: string): boolean;
+/**
+ * Checks if a person is an adult based on their NIK.
+ *
+ * By default, uses 17 years as the threshold (Indonesian KTP eligibility age).
+ * Indonesian law allows KTP at age 17, or upon marriage, or already married.
+ *
+ * @param nik - The 16-digit NIK string
+ * @param minAge - Minimum age threshold (default: 17)
+ * @returns True if the person is at least minAge years old, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Born 1995-01-01, reference 2026-04-06 (age 31)
+ * isAdult('3201950101950123'); // true (31 >= 17)
+ * isAdult('3201950101950123', 21); // true (31 >= 21)
+ *
+ * // Born 2010-01-01, reference 2026-04-06 (age 16)
+ * isAdult('3210010101950123'); // false (16 < 17)
+ * isAdult('3210010101950123', 16); // true (16 >= 16)
+ *
+ * // Invalid NIK
+ * isAdult('invalid'); // false
+ * ```
+ *
+ * @public
+ */
+declare function isAdult(nik: string, minAge?: number): boolean;
+/**
+ * Formats the birth date from a NIK into a human-readable string.
+ *
+ * @param nik - The 16-digit NIK string
+ * @param locale - The locale to use for formatting (default: 'id-ID')
+ * @returns Formatted birth date string, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * formatBirthDate('3201018901310123'); // '31 Januari 1989'
+ * ```
+ */
+declare function formatBirthDate(nik: string): string | null;
+/**
+ * Checks if a NIK matches a specific gender.
+ *
+ * @param nik - The 16-digit NIK string
+ * @param gender - The gender to check ('male' | 'female')
+ * @returns True if the NIK matches the gender, false otherwise
+ */
+declare function isValidForGender(nik: string, gender: 'male' | 'female'): boolean;
+/**
+ * Checks if a NIK matches a specific birth date.
+ *
+ * @param nik - The 16-digit NIK string
+ * @param birthDate - The birth date to check
+ * @returns True if the NIK matches the birth date, false otherwise
+ */
+declare function isValidForBirthDate(nik: string, birthDate: Date): boolean;
+
+export { type Age as A, type GetAgeOptions as G, InvalidNIKError as I, type MaskOptions as M, type NIKInfo as N, formatBirthDate as a, isValidForBirthDate as b, type NIKValidationResult as c, compareNIK as d, isAdult as e, formatNIK as f, getAge as g, type NIKValidationError as h, isValidForGender as i, type NIKErrorCode as j, maskNIK as m, parseNIK as p, validateNIK as v };

package/dist/vin/index.cjs

@@ -71,7 +71,70 @@ function validateVIN(vin) {
   return actualCheckDigit === expectedCheckDigit;
 }
 
+// src/vin/errors.ts
+var InvalidVINError = class extends Error {
+  constructor(message = "Invalid VIN provided") {
+    super(message);
+    this.code = "INVALID_VIN";
+    this.name = "InvalidVINError";
+  }
+};
+
+// src/vin/parse.ts
+function parseVIN(vin) {
+  if (!vin || typeof vin !== "string") {
+    return null;
+  }
+  const normalizedVIN = vin.toUpperCase();
+  if (normalizedVIN.length !== VIN_LENGTH) {
+    return null;
+  }
+  for (const char of EXCLUDED_VIN_CHARS) {
+    if (normalizedVIN.includes(char)) {
+      return null;
+    }
+  }
+  for (const char of normalizedVIN) {
+    if (VIN_CHAR_VALUES[char] === void 0) {
+      return null;
+    }
+  }
+  const isValid = validateCheckDigit(normalizedVIN);
+  const wmi = normalizedVIN.substring(0, 3);
+  const vds = normalizedVIN.substring(3, 9);
+  const checkDigit = normalizedVIN[VIN_CHECK_DIGIT_INDEX];
+  const modelYearCode = normalizedVIN[9];
+  const plantCode = normalizedVIN[10];
+  const serialNumber = normalizedVIN.substring(11, 17);
+  return {
+    wmi,
+    vds,
+    checkDigit,
+    modelYearCode,
+    plantCode,
+    serialNumber,
+    isValid
+  };
+}
+function validateCheckDigit(vin) {
+  let sum = 0;
+  for (let i = 0; i < VIN_LENGTH; i++) {
+    const char = vin[i];
+    const weight = VIN_WEIGHTS[i];
+    const val = VIN_CHAR_VALUES[char];
+    if (val === void 0) {
+      return false;
+    }
+    sum += val * weight;
+  }
+  const checkDigitValue = sum % VIN_MODULUS;
+  const expectedCheckDigit = checkDigitValue === 10 ? VIN_CHECK_DIGIT_X : checkDigitValue.toString();
+  const actualCheckDigit = vin[VIN_CHECK_DIGIT_INDEX];
+  return actualCheckDigit === expectedCheckDigit;
+}
+
 exports.EXCLUDED_VIN_CHARS = EXCLUDED_VIN_CHARS;
+exports.InvalidVINError = InvalidVINError;
 exports.VIN_CHAR_VALUES = VIN_CHAR_VALUES;
 exports.VIN_CHECK_DIGIT_INDEX = VIN_CHECK_DIGIT_INDEX;
 exports.VIN_CHECK_DIGIT_X = VIN_CHECK_DIGIT_X;
@@ -79,6 +142,7 @@ exports.VIN_LENGTH = VIN_LENGTH;
 exports.VIN_MODULUS = VIN_MODULUS;
 exports.VIN_VERSION = VIN_VERSION;
 exports.VIN_WEIGHTS = VIN_WEIGHTS;
+exports.parseVIN = parseVIN;
 exports.validateVIN = validateVIN;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/vin/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/vin/constants.ts","../../src/vin/validate.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * The standard length of a VIN (ISO 3779).\n */\nexport const VIN_LENGTH = 17;\n\n/**\n * The 0-based index of the check digit in the VIN (Position 9).\n */\nexport const VIN_CHECK_DIGIT_INDEX = 8;\n\n/**\n * The modulus used in the VIN checksum calculation.\n */\nexport const VIN_MODULUS = 11;\n\n/**\n * The character representing a checksum value of 10.\n */\nexport const VIN_CHECK_DIGIT_X = 'X';\n\n/**\n * Weights used in the VIN checksum calculation.\n * Each position (1-17) is multiplied by its corresponding weight.\n * Position 9 is the check digit itself (weight 0).\n */\nexport const VIN_WEIGHTS = [8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2];\n\n/**\n * Values assigned to each valid character for VIN calculation.\n * Invalid characters: I, O, Q are not allowed in VIN.\n */\nexport const VIN_CHAR_VALUES: Record<string, number> = {\n  '0': 0, '1': 1, '2': 2, '3': 3, '4': 4, '5': 5, '6': 6, '7': 7, '8': 8, '9': 9,\n  'A': 1, 'B': 2, 'C': 3, 'D': 4, 'E': 5, 'F': 6, 'G': 7, 'H': 8,\n  'J': 1, 'K': 2, 'L': 3, 'M': 4, 'N': 5, 'P': 7, 'R': 9,\n  'S': 2, 'T': 3, 'U': 4, 'V': 5, 'W': 6, 'X': 7, 'Y': 8, 'Z': 9,\n};\n\n/**\n * Characters excluded from VIN (I, O, Q).\n */\nexport const EXCLUDED_VIN_CHARS = ['I', 'O', 'Q'];\n\n/**\n * Version of the VIN utility module.\n */\nexport const VIN_VERSION = '1.0.0';\n\n","import {\n  VIN_WEIGHTS,\n  VIN_CHAR_VALUES,\n  EXCLUDED_VIN_CHARS,\n  VIN_LENGTH,\n  VIN_CHECK_DIGIT_INDEX,\n  VIN_MODULUS,\n  VIN_CHECK_DIGIT_X,\n} from './constants';\n\n/**\n * Validates a Vehicle Identification Number (VIN) based on ISO 3779.\n *\n * Checks for:\n * - Exactly 17 characters length.\n * - Exclusion of characters I, O, and Q.\n * - Checksum validation using the check digit at position 9.\n *\n * @param vin - The VIN string to validate\n * @returns boolean indicating if the VIN is valid\n *\n * @example\n * ```typescript\n * import { validateVIN } from '@indodev/toolkit/vin';\n *\n * validateVIN('1HBHA82L7ZB000001'); // true\n * validateVIN('1HBHA82I7ZB000001'); // false (contains 'I')\n * ```\n */\nexport function validateVIN(vin: string): boolean {\n  if (!vin || vin.length !== VIN_LENGTH) {\n    return false;\n  }\n\n  const normalizedVIN = vin.toUpperCase();\n\n  // 1. Check for excluded characters (I, O, Q)\n  for (const char of EXCLUDED_VIN_CHARS) {\n    if (normalizedVIN.includes(char)) {\n      return false;\n    }\n  }\n\n  // 2. Checksum validation (Position 9)\n  let sum = 0;\n  for (let i = 0; i < VIN_LENGTH; i++) {\n    const char = normalizedVIN[i];\n    const weight = VIN_WEIGHTS[i];\n    const val = VIN_CHAR_VALUES[char];\n\n    if (val === undefined) {\n      return false; // Invalid character found\n    }\n\n    sum += val * weight;\n  }\n\n  const checkDigitValue = sum % VIN_MODULUS;\n  const expectedCheckDigit =\n    checkDigitValue === 10 ? VIN_CHECK_DIGIT_X : checkDigitValue.toString();\n  const actualCheckDigit = normalizedVIN[VIN_CHECK_DIGIT_INDEX];\n\n  return actualCheckDigit === expectedCheckDigit;\n}\n"]}
+{"version":3,"sources":["../../src/vin/constants.ts","../../src/vin/validate.ts","../../src/vin/errors.ts","../../src/vin/parse.ts"],"names":[],"mappings":";;;AAGO,IAAM,UAAA,GAAa;AAKnB,IAAM,qBAAA,GAAwB;AAK9B,IAAM,WAAA,GAAc;AAKpB,IAAM,iBAAA,GAAoB;AAO1B,IAAM,cAAc,CAAC,CAAA,EAAG,GAAG,CAAA,EAAG,CAAA,EAAG,GAAG,CAAA,EAAG,CAAA,EAAG,EAAA,EAAI,CAAA,EAAG,GAAG,CAAA,EAAG,CAAA,EAAG,GAAG,CAAA,EAAG,CAAA,EAAG,GAAG,CAAC;AAMvE,IAAM,eAAA,GAA0C;AAAA,EACrD,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAC7E,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAC7D,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EACrD,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK,CAAA;AAAA,EAAG,GAAA,EAAK;AAC/D;AAKO,IAAM,kBAAA,GAAqB,CAAC,GAAA,EAAK,GAAA,EAAK,GAAG;AAKzC,IAAM,WAAA,GAAc;;;ACjBpB,SAAS,YAAY,GAAA,EAAsB;AAChD,EAAA,IAAI,CAAC,GAAA,IAAO,GAAA,CAAI,MAAA,KAAW,UAAA,EAAY;AACrC,IAAA,OAAO,KAAA;AAAA,EACT;AAEA,EAAA,MAAM,aAAA,GAAgB,IAAI,WAAA,EAAY;AAGtC,EAAA,KAAA,MAAW,QAAQ,kBAAA,EAAoB;AACrC,IAAA,IAAI,aAAA,CAAc,QAAA,CAAS,IAAI,CAAA,EAAG;AAChC,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AAGA,EAAA,IAAI,GAAA,GAAM,CAAA;AACV,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,UAAA,EAAY,CAAA,EAAA,EAAK;AACnC,IAAA,MAAM,IAAA,GAAO,cAAc,CAAC,CAAA;AAC5B,IAAA,MAAM,MAAA,GAAS,YAAY,CAAC,CAAA;AAC5B,IAAA,MAAM,GAAA,GAAM,gBAAgB,IAAI,CAAA;AAEhC,IAAA,IAAI,QAAQ,MAAA,EAAW;AACrB,MAAA,OAAO,KAAA;AAAA,IACT;AAEA,IAAA,GAAA,IAAO,GAAA,GAAM,MAAA;AAAA,EACf;AAEA,EAAA,MAAM,kBAAkB,GAAA,GAAM,WAAA;AAC9B,EAAA,MAAM,kBAAA,GACJ,eAAA,KAAoB,EAAA,GAAK,iBAAA,GAAoB,gBAAgB,QAAA,EAAS;AACxE,EAAA,MAAM,gBAAA,GAAmB,cAAc,qBAAqB,CAAA;AAE5D,EAAA,OAAO,gBAAA,KAAqB,kBAAA;AAC9B;;;AC9CO,IAAM,eAAA,GAAN,cAA8B,KAAA,CAAM;AAAA,EAGzC,WAAA,CAAY,UAAkB,sBAAA,EAAwB;AACpD,IAAA,KAAA,CAAM,OAAO,CAAA;AAHf,IAAA,IAAA,CAAS,IAAA,GAAO,aAAA;AAId,IAAA,IAAA,CAAK,IAAA,GAAO,iBAAA;AAAA,EACd;AACF;;;ACoBO,SAAS,SAAS,GAAA,EAA6B;AACpD,EAAA,IAAI,CAAC,GAAA,IAAO,OAAO,GAAA,KAAQ,QAAA,EAAU;AACnC,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,MAAM,aAAA,GAAgB,IAAI,WAAA,EAAY;AAEtC,EAAA,IAAI,aAAA,CAAc,WAAW,UAAA,EAAY;AACvC,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,KAAA,MAAW,QAAQ,kBAAA,EAAoB;AACrC,IAAA,IAAI,aAAA,CAAc,QAAA,CAAS,IAAI,CAAA,EAAG;AAChC,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF;AAEA,EAAA,KAAA,MAAW,QAAQ,aAAA,EAAe;AAChC,IAAA,IAAI,eAAA,CAAgB,IAAI,CAAA,KAAM,MAAA,EAAW;AACvC,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF;AAEA,EAAA,MAAM,OAAA,GAAU,mBAAmB,aAAa,CAAA;AAEhD,EAAA,MAAM,GAAA,GAAM,aAAA,CAAc,SAAA,CAAU,CAAA,EAAG,CAAC,CAAA;AACxC,EAAA,MAAM,GAAA,GAAM,aAAA,CAAc,SAAA,CAAU,CAAA,EAAG,CAAC,CAAA;AACxC,EAAA,MAAM,UAAA,GAAa,cAAc,qBAAqB,CAAA;AACtD,EAAA,MAAM,aAAA,GAAgB,cAAc,CAAC,CAAA;AACrC,EAAA,MAAM,SAAA,GAAY,cAAc,EAAE,CAAA;AAClC,EAAA,MAAM,YAAA,GAAe,aAAA,CAAc,SAAA,CAAU,EAAA,EAAI,EAAE,CAAA;AAEnD,EAAA,OAAO;AAAA,IACL,GAAA;AAAA,IACA,GAAA;AAAA,IACA,UAAA;AAAA,IACA,aAAA;AAAA,IACA,SAAA;AAAA,IACA,YAAA;AAAA,IACA;AAAA,GACF;AACF;AAOA,SAAS,mBAAmB,GAAA,EAAsB;AAChD,EAAA,IAAI,GAAA,GAAM,CAAA;AACV,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,UAAA,EAAY,CAAA,EAAA,EAAK;AACnC,IAAA,MAAM,IAAA,GAAO,IAAI,CAAC,CAAA;AAClB,IAAA,MAAM,MAAA,GAAS,YAAY,CAAC,CAAA;AAC5B,IAAA,MAAM,GAAA,GAAM,gBAAgB,IAAI,CAAA;AAEhC,IAAA,IAAI,QAAQ,MAAA,EAAW;AACrB,MAAA,OAAO,KAAA;AAAA,IACT;AAEA,IAAA,GAAA,IAAO,GAAA,GAAM,MAAA;AAAA,EACf;AAEA,EAAA,MAAM,kBAAkB,GAAA,GAAM,WAAA;AAC9B,EAAA,MAAM,kBAAA,GACJ,eAAA,KAAoB,EAAA,GAAK,iBAAA,GAAoB,gBAAgB,QAAA,EAAS;AACxE,EAAA,MAAM,gBAAA,GAAmB,IAAI,qBAAqB,CAAA;AAElD,EAAA,OAAO,gBAAA,KAAqB,kBAAA;AAC9B","file":"index.cjs","sourcesContent":["/**\n * The standard length of a VIN (ISO 3779).\n */\nexport const VIN_LENGTH = 17;\n\n/**\n * The 0-based index of the check digit in the VIN (Position 9).\n */\nexport const VIN_CHECK_DIGIT_INDEX = 8;\n\n/**\n * The modulus used in the VIN checksum calculation.\n */\nexport const VIN_MODULUS = 11;\n\n/**\n * The character representing a checksum value of 10.\n */\nexport const VIN_CHECK_DIGIT_X = 'X';\n\n/**\n * Weights used in the VIN checksum calculation.\n * Each position (1-17) is multiplied by its corresponding weight.\n * Position 9 is the check digit itself (weight 0).\n */\nexport const VIN_WEIGHTS = [8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2];\n\n/**\n * Values assigned to each valid character for VIN calculation.\n * Invalid characters: I, O, Q are not allowed in VIN.\n */\nexport const VIN_CHAR_VALUES: Record<string, number> = {\n  '0': 0, '1': 1, '2': 2, '3': 3, '4': 4, '5': 5, '6': 6, '7': 7, '8': 8, '9': 9,\n  'A': 1, 'B': 2, 'C': 3, 'D': 4, 'E': 5, 'F': 6, 'G': 7, 'H': 8,\n  'J': 1, 'K': 2, 'L': 3, 'M': 4, 'N': 5, 'P': 7, 'R': 9,\n  'S': 2, 'T': 3, 'U': 4, 'V': 5, 'W': 6, 'X': 7, 'Y': 8, 'Z': 9,\n};\n\n/**\n * Characters excluded from VIN (I, O, Q).\n */\nexport const EXCLUDED_VIN_CHARS = ['I', 'O', 'Q'];\n\n/**\n * Version of the VIN utility module.\n */\nexport const VIN_VERSION = '1.0.0';\n\n","import {\n  VIN_WEIGHTS,\n  VIN_CHAR_VALUES,\n  EXCLUDED_VIN_CHARS,\n  VIN_LENGTH,\n  VIN_CHECK_DIGIT_INDEX,\n  VIN_MODULUS,\n  VIN_CHECK_DIGIT_X,\n} from './constants';\n\n/**\n * Validates a Vehicle Identification Number (VIN) based on ISO 3779.\n *\n * Checks for:\n * - Exactly 17 characters length.\n * - Exclusion of characters I, O, and Q.\n * - Checksum validation using the check digit at position 9.\n *\n * @param vin - The VIN string to validate\n * @returns boolean indicating if the VIN is valid\n *\n * @example\n * ```typescript\n * import { validateVIN } from '@indodev/toolkit/vin';\n *\n * validateVIN('1HBHA82L7ZB000001'); // true\n * validateVIN('1HBHA82I7ZB000001'); // false (contains 'I')\n * ```\n */\nexport function validateVIN(vin: string): boolean {\n  if (!vin || vin.length !== VIN_LENGTH) {\n    return false;\n  }\n\n  const normalizedVIN = vin.toUpperCase();\n\n  // 1. Check for excluded characters (I, O, Q)\n  for (const char of EXCLUDED_VIN_CHARS) {\n    if (normalizedVIN.includes(char)) {\n      return false;\n    }\n  }\n\n  // 2. Checksum validation (Position 9)\n  let sum = 0;\n  for (let i = 0; i < VIN_LENGTH; i++) {\n    const char = normalizedVIN[i];\n    const weight = VIN_WEIGHTS[i];\n    const val = VIN_CHAR_VALUES[char];\n\n    if (val === undefined) {\n      return false; // Invalid character found\n    }\n\n    sum += val * weight;\n  }\n\n  const checkDigitValue = sum % VIN_MODULUS;\n  const expectedCheckDigit =\n    checkDigitValue === 10 ? VIN_CHECK_DIGIT_X : checkDigitValue.toString();\n  const actualCheckDigit = normalizedVIN[VIN_CHECK_DIGIT_INDEX];\n\n  return actualCheckDigit === expectedCheckDigit;\n}\n","/**\n * Error thrown when an invalid VIN is provided to a function.\n * Extends native Error with a `code` property for programmatic error handling.\n *\n * @example\n * ```typescript\n * try {\n *   requireVIN('invalid');\n * } catch (error) {\n *   if (error instanceof InvalidVINError) {\n *     console.log(error.code); // 'INVALID_VIN'\n *   }\n * }\n * ```\n *\n * @public\n */\nexport class InvalidVINError extends Error {\n  readonly code = 'INVALID_VIN' as const;\n\n  constructor(message: string = 'Invalid VIN provided') {\n    super(message);\n    this.name = 'InvalidVINError';\n  }\n}\n","import {\n  VIN_LENGTH,\n  VIN_CHAR_VALUES,\n  EXCLUDED_VIN_CHARS,\n  VIN_WEIGHTS,\n  VIN_CHECK_DIGIT_INDEX,\n  VIN_MODULUS,\n  VIN_CHECK_DIGIT_X,\n} from './constants';\nimport type { VINInfo } from './types';\n\n/**\n * Parses a Vehicle Identification Number (VIN) into its component parts.\n *\n * Extracts the WMI (World Manufacturer Identifier), VDS (Vehicle Descriptor Section),\n * check digit, model year code, plant code, and serial number from a VIN.\n *\n * @param vin - The VIN string to parse\n * @returns VINInfo object with extracted components, or null if invalid\n *\n * @example\n * Valid VIN:\n * ```typescript\n * parseVIN('1HBHA82L7ZB000001');\n * // {\n * //   wmi: '1HB',\n * //   vds: 'HA82L7',\n * //   checkDigit: '7',\n * //   modelYearCode: 'Z',\n * //   plantCode: 'B',\n * //   serialNumber: '0000001',\n * //   isValid: true\n * // }\n * ```\n *\n * @example\n * Invalid VIN returns null:\n * ```typescript\n * parseVIN('invalid');\n * // null\n * ```\n *\n * @public\n */\nexport function parseVIN(vin: string): VINInfo | null {\n  if (!vin || typeof vin !== 'string') {\n    return null;\n  }\n\n  const normalizedVIN = vin.toUpperCase();\n\n  if (normalizedVIN.length !== VIN_LENGTH) {\n    return null;\n  }\n\n  for (const char of EXCLUDED_VIN_CHARS) {\n    if (normalizedVIN.includes(char)) {\n      return null;\n    }\n  }\n\n  for (const char of normalizedVIN) {\n    if (VIN_CHAR_VALUES[char] === undefined) {\n      return null;\n    }\n  }\n\n  const isValid = validateCheckDigit(normalizedVIN);\n\n  const wmi = normalizedVIN.substring(0, 3);\n  const vds = normalizedVIN.substring(3, 9);\n  const checkDigit = normalizedVIN[VIN_CHECK_DIGIT_INDEX];\n  const modelYearCode = normalizedVIN[9];\n  const plantCode = normalizedVIN[10];\n  const serialNumber = normalizedVIN.substring(11, 17);\n\n  return {\n    wmi,\n    vds,\n    checkDigit,\n    modelYearCode,\n    plantCode,\n    serialNumber,\n    isValid,\n  };\n}\n\n/**\n * Validates the check digit of a VIN.\n *\n * @internal\n */\nfunction validateCheckDigit(vin: string): boolean {\n  let sum = 0;\n  for (let i = 0; i < VIN_LENGTH; i++) {\n    const char = vin[i];\n    const weight = VIN_WEIGHTS[i];\n    const val = VIN_CHAR_VALUES[char];\n\n    if (val === undefined) {\n      return false;\n    }\n\n    sum += val * weight;\n  }\n\n  const checkDigitValue = sum % VIN_MODULUS;\n  const expectedCheckDigit =\n    checkDigitValue === 10 ? VIN_CHECK_DIGIT_X : checkDigitValue.toString();\n  const actualCheckDigit = vin[VIN_CHECK_DIGIT_INDEX];\n\n  return actualCheckDigit === expectedCheckDigit;\n}\n"]}

package/dist/vin/index.d.cts

@@ -1,4 +1,4 @@
-export { V as VINOptions, a as VINValidationResult, v as validateVIN } from '../types-i5e6R0AS.cjs';
+export { I as InvalidVINError, b as VINInfo, V as VINOptions, a as VINValidationResult, p as parseVIN, v as validateVIN } from '../parse-DlrgrRfY.cjs';
 
 /**
  * The standard length of a VIN (ISO 3779).

package/dist/vin/index.d.ts

@@ -1,4 +1,4 @@
-export { V as VINOptions, a as VINValidationResult, v as validateVIN } from '../types-i5e6R0AS.js';
+export { I as InvalidVINError, b as VINInfo, V as VINOptions, a as VINValidationResult, p as parseVIN, v as validateVIN } from '../parse-DlrgrRfY.js';
 
 /**
  * The standard length of a VIN (ISO 3779).