validation.vin

export function validateVin(value: string): VinCheck

/** The result of checking a VIN. Strings and checkDigitMatches are null when valid is false; reason is null when it is true. */
export interface VinCheck {
  readonly valid: boolean;
  /** upper case, no spaces */
  readonly normalised: string | null;
  /** the world manufacturer identifier, the first three characters */
  readonly wmi: string | null;
  /** whether position 9 holds the computed check digit */
  readonly checkDigitMatches: boolean | null;
  /** empty, bad-character, bad-length, forbidden-letter or bad-check-digit */
  readonly reason: string | null;
}

import { validateVin } from "#fune/validation.vin@^1";

import { type VinCheck } from "./validation_vin_types.ts";

/**
 * Letter values from 49 CFR 565.15, indexed by letter A-Z. I, O and Q are
 * never used and hold -1; the others run 1-9 in three passes (A-I, J-R, S-Z)
 * with the forbidden letters' slots skipped.
 */
const LETTER_VALUES = [1, 2, 3, 4, 5, 6, 7, 8, -1, 1, 2, 3, 4, 5, -1, 7, -1, 9, 2, 3, 4, 5, 6, 7, 8, 9];

/** Position weights; position 9 is the check digit itself and weighs nothing. */
const WEIGHTS = [8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2];

function invalid(reason: string): VinCheck {
  return { valid: false, normalised: null, wmi: null, checkDigitMatches: null, reason };
}

/**
 * Check a 17-character VIN.
 *
 * The check digit is enforced only for North American VINs (first character
 * 1-5), where the law requires it; elsewhere a mismatch is reported in
 * checkDigitMatches but does not make the VIN invalid, because many European
 * and Asian VINs never carried one. Validators answer rather than throw.
 */
export function validateVin(value: string): VinCheck {
  if (typeof value !== "string") return invalid("empty");

  let vin = "";
  for (const ch of value) {
    if (ch === " ") continue;
    // Folded by hand: toUpperCase() is Unicode-aware and Rust's ASCII fold is not.
    vin += ch >= "a" && ch <= "z" ? String.fromCharCode(ch.charCodeAt(0) - 32) : ch;
  }
  if (vin.length === 0) return invalid("empty");
  for (const ch of vin) {
    if (!((ch >= "0" && ch <= "9") || (ch >= "A" && ch <= "Z"))) return invalid("bad-character");
  }
  if (vin.length !== 17) return invalid("bad-length");

  let total = 0;
  for (let i = 0; i < 17; i++) {
    const code = vin.charCodeAt(i);
    let n: number;
    if (code <= 57) n = code - 48;
    else {
      n = LETTER_VALUES[code - 65];
      // I, O and Q read as 1, 0 and 0, so the standard never issues them.
      if (n < 0) return invalid("forbidden-letter");
    }
    total += n * WEIGHTS[i];
  }
  const remainder = total % 11;
  const expected = remainder === 10 ? "X" : String(remainder);
  const matches = vin[8] === expected;

  // WMIs starting 1-5 are North American, where 49 CFR 565 makes the check
  // digit mandatory; anywhere else it is optional, so only report it.
  if (!matches && vin[0] >= "1" && vin[0] <= "5") return invalid("bad-check-digit");

  return { valid: true, normalised: vin, wmi: vin.slice(0, 3), checkDigitMatches: matches, reason: null };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add validation.vin

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./validation.vin-1.0.0-typescript.fune, or fetch it from a terminal with fune pull validation.vin@1.0.0:typescript.

The whole function, every language, is one file too: validation.vin-1.0.0.fune, 17,748 bytes, sha256 310dc9072c78fe16ddf0e7f98d75b9535b807ba32c97aed2874a45be9b7b36c6. It installs into a project of any language.

// fune: before validation.vin

// fune: after validation.vin

// fune: step validation.vin after <n|label>

More from the author

THE CALCULATION: each character becomes a number (digits are themselves; A-H are 1-8, J-N 1-5, P 7, R 9, S-Z 2-9, skipping the forbidden letters), is multiplied by the weight for its position (8 7 6 5 4 3 2 10 0 9 8 7 6 5 4 3 2), and the sum is taken modulo 11; a remainder of 10 is written `X`. Position 9, the check digit itself, has weight 0.

FORBIDDEN LETTERS: I, O and Q never appear in a VIN because they read as 1, 0 and 0. They get their own reason, `forbidden-letter`, because they almost always mean a transcription slip that the user can fix by retyping that one character.

ACCEPTED INPUT: letters in either case (folded to upper case) and digits; ASCII spaces are ignored anywhere. Hyphens and anything else are refused, because VINs are never printed with them.

| reason | meaning | |--------------------|----------------------------------------------------------| | `empty` | nothing but spaces, or not a string at all | | `bad-character` | anything other than A-Z, a-z, 0-9 and spaces | | `bad-length` | not exactly 17 characters | | `forbidden-letter` | contains I, O or Q | | `bad-check-digit` | a North American VIN (starts 1-5) whose check digit is wrong |

The checks run in that order; the first failure is the reason. Validators answer rather than throw.

Out of scope: decoding the model year (position 10), the plant, or the manufacturer's name from the WMI, and pre-1981 VINs, which were not 17 characters.

Sources: ISO 3779:2009 "Road vehicles - Vehicle identification number (VIN) - Content and structure"; US 49 CFR 565.15 "Content requirements" (check digit, transliteration and weight tables), https://www.ecfr.gov/current/title-49/subtitle-B/chapter-V/part-565/subpart-B/section-565.15.

Files