The goal is honest short-circuit: remember "this normalized VIN is not worth another upstream call for a while," show a clear invalid/error state, and never invent a successful decode card from a negative entry.

Negative cache vs positive caches

Use a negative cache when:

• Client-side checks (length, charset, check digit) already fail before HTTP
• Upstream returned a clear "no decode / error / empty Results" for that VIN
• The same bad paste repeats within a short TTL (fat-finger retries, bot loops)

Do not use negative cache to store successful DecodeVinValues bodies (ETag / warmup territory), invent folklore Make/Model/Year, suppress live calls forever (bound TTL), or treat 429/outages as permanent "invalid VIN."

When the entry expires or the failure was transient (5xx, timeout), allow a live retry. Client-invalid shapes can use a longer TTL than soft upstream empties.

Classify before you store

Separate client-invalid (never call upstream) from upstream-negative (you called, got a clear no-decode). Both can live in one map keyed by normalized VIN, with different reasons and TTLs.

export type NegReason =
  | "client-length"
  | "client-charset"
  | "client-check-digit"
  | "upstream-empty"
  | "upstream-error";

export type NegEntry = {
  vinNormalized: string;
  reason: NegReason;
  storedAt: number; // epoch ms
  ttlMs: number;
  message: string; // user-safe, no invented specs
};

export type NegStore = Map<string, NegEntry>;

const CLIENT_TTL_MS = 60 * 60 * 1000; // 1h for obvious typos
const UPSTREAM_TTL_MS = 15 * 60 * 1000; // 15m for empty/error bodies

export function normalizeVin(raw: string): string {
  return raw.trim().toUpperCase().replace(/[^A-HJ-NPR-Z0-9]/g, "");
}

export function clientInvalidReason(vin: string): NegReason | null {
  if (vin.length !== 17) return "client-length";
  if (!/^[A-HJ-NPR-Z0-9]{17}$/.test(vin)) return "client-charset";
  // Check-digit algorithm omitted for brevity; return "client-check-digit" on fail
  return null;
}

export function putNegative(
  store: NegStore,
  vinNormalized: string,
  reason: NegReason,
  message: string,
  nowMs = Date.now(),
): NegEntry {
  const ttlMs =
    reason.startsWith("client-") ? CLIENT_TTL_MS : UPSTREAM_TTL_MS;
  const entry: NegEntry = {
    vinNormalized,
    reason,
    storedAt: nowMs,
    ttlMs,
    message,
  };
  store.set(vinNormalized, entry);
  return entry;
}

export function getNegative(
  store: NegStore,
  vinNormalized: string,
  nowMs = Date.now(),
): NegEntry | null {
  const hit = store.get(vinNormalized);
  if (!hit) return null;
  if (nowMs - hit.storedAt >= hit.ttlMs) {
    store.delete(vinNormalized);
    return null;
  }
  return hit;
}

Never put a successful body into this map. Never upgrade a negative hit into Make/Model/Year rows.

Decode path with short-circuit

export type DecodeOutcome =
  | { kind: "negative"; entry: NegEntry }
  | { kind: "live"; body: Record<string, string | null> }
  | { kind: "transient-error"; status: number };

export async function decodeWithNegCache(
  store: NegStore,
  rawVin: string,
  fetchLive: (vin: string) => Promise<{
    ok: boolean;
    status: number;
    body: Record<string, string | null> | null;
    empty: boolean;
  }>,
  nowMs = Date.now(),
): Promise<DecodeOutcome> {
  const vin = normalizeVin(rawVin);
  const cached = getNegative(store, vin, nowMs);
  if (cached) return { kind: "negative", entry: cached };

  const clientReason = clientInvalidReason(vin);
  if (clientReason) {
    const entry = putNegative(
      store,
      vin,
      clientReason,
      "VIN failed local validation -- not sent to NHTSA",
      nowMs,
    );
    return { kind: "negative", entry };
  }

  const live = await fetchLive(vin);
  if (!live.ok && live.status >= 500) {
    return { kind: "transient-error", status: live.status };
  }
  if (!live.ok || live.empty || !live.body) {
    const entry = putNegative(
      store,
      vin,
      live.ok ? "upstream-empty" : "upstream-error",
      "No decode available from vPIC for this VIN",
      nowMs,
    );
    return { kind: "negative", entry };
  }
  return { kind: "live", body: live.body };
}

Transient 5xx stays out of the negative store (or uses a very short TTL if you must). That keeps outages from branding a good VIN as permanently invalid.

Forbidden upgrades

Product pressure often asks for:

1. Serving a fake "success" card from a negative hit so the UI looks complete
2. Infinite TTL so one empty response never rechecks after catalog updates
3. Collapsing rate-limit 429 into "invalid VIN" negatives
4. Mixing negative keys with positive ETag bodies in one undifferentiated blob

Refuse those. Negative cache is a courtesy throttle and UX shortcut -- not a second invent-specs path.

export function assertNoNegInvent(moduleSource: string): void {
  const banned = [
    /invent.*(make|model|year)/i,
    /negative.*success.?card/i,
    /forever.?invalid/i,
    /treat.?429.?as.?invalid/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(`Negative cache must not invent decode cards: ${re}`);
    }
  }
}

export function uiMessage(entry: NegEntry): string {
  return entry.message;
}

UI copy that stays honest

Prefer:

• "VIN failed local validation -- not sent to NHTSA"
• "No decode available from vPIC for this VIN (cached briefly)"
• "Temporary upstream error -- try again shortly" for transient failures

Avoid Make/Model/Year from memory on negative hits, "invalid forever" without TTL disclosure, and silent success styling on a negative entry.

Quick checks

import assert from "node:assert/strict";

const store: NegStore = new Map();
const short = normalizeVin("123");
assert.equal(clientInvalidReason(short), "client-length");

const neg = putNegative(
  store,
  short,
  "client-length",
  "VIN failed local validation -- not sent to NHTSA",
  1_000,
);
assert.equal(getNegative(store, short, 1_000)?.reason, "client-length");
assert.equal(getNegative(store, short, 1_000 + CLIENT_TTL_MS)?.reason, undefined);

assert.equal(uiMessage(neg).includes("Make"), false);
assert.ok(!/standard|verified|package/i.test(uiMessage(neg)));

Review rule: negative-cache modules must not invent successful decode fields. Bound TTL; separate transient errors from invalid VINs.

Takeaway

A negative cache stops bad digits and known empty upstream results from hammering NHTSA on every retry. Store reason + TTL, short-circuit with honest UI copy, and leave successful bodies to ETag and warmup paths. Invalid pastes stay remembered briefly -- never upgraded into invented catalog rows.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/negatively-caching-invalid-vin-responses-so-bad-digits-do-not-hammer-nhtsa-2dok

This post is about a request-id / generation-counter stale-response guard: bump a monotonic id when you start a decode, stamp it on the in-flight promise, and commit UI state only when that id still matches the latest generation. AbortSignal, input-clear cancel UX, and timeout-overlap races are separate topics. Here the focus is out-of-order success and error payloads after a newer request already owns the screen.

The failure mode

Typical buggy sequence:

1. User pastes VIN A; you fetch and keep the promise.
2. Before A resolves, the user pastes VIN B; you start a second fetch (with or without aborting A).
3. B returns first; you paint Make/Model for B. Good so far.
4. A returns later; a careless .then still calls setResult(rowA).
5. The input shows B, the card shows A's identity. Support tickets look like "decode lies."

Aborting A helps when cancel is honored. It fails when the proxy already finished, a shared promise lacks a generation stamp, or you only abort on empty input. A generation counter (or UUID request id) is the last line of defense: late bodies must be ignored when no longer current.

One generation per decode start

Bump generation (or mint a requestId) every time you start a decode for a normalized VIN. Store the stamp on the session. Every success and failure path checks session.generation === latestGeneration before mutating result, error, or loading.

export type DecodeRow = Record<string, string>;

export type DecodeUiState = {
  vin: string | null;
  row: DecodeRow | null;
  error: string | null;
  loading: boolean;
  generation: number;
};

export type DecodeSession = {
  generation: number;
  vinNormalized: string;
};

export function nextGeneration(state: DecodeUiState): number {
  return state.generation + 1;
}

export function isCurrent(
  session: DecodeSession,
  latestGeneration: number,
): boolean {
  return session.generation === latestGeneration;
}

export function applyDecodeSuccess(
  state: DecodeUiState,
  session: DecodeSession,
  row: DecodeRow,
): DecodeUiState {
  if (!isCurrent(session, state.generation)) {
    return state; // stale -- newer request already owns the UI
  }
  return {
    ...state,
    vin: session.vinNormalized,
    row,
    error: null,
    loading: false,
  };
}

export function applyDecodeError(
  state: DecodeUiState,
  session: DecodeSession,
  error: string,
): DecodeUiState {
  if (!isCurrent(session, state.generation)) {
    return state;
  }
  return {
    ...state,
    vin: session.vinNormalized,
    row: null,
    error,
    loading: false,
  };
}

The guard is deliberately boring. Stale successes and stale errors both refuse to write. A late "404 from NHTSA" for A must not wipe B's good row. Treat "current generation" as the single source of truth for which VIN owns the card -- not whichever promise happens to settle last.

Wire it at the promise boundary

Start the session when you kick off work. Pass the same session into both branches. Do not close over a mutable let result without the check.

export async function runDecode(
  state: DecodeUiState,
  vinNormalized: string,
  fetchRow: (vin: string) => Promise<DecodeRow>,
): Promise<DecodeUiState> {
  const generation = nextGeneration(state);
  const session: DecodeSession = { generation, vinNormalized };
  let next: DecodeUiState = {
    ...state,
    generation,
    loading: true,
    error: null,
  };

  try {
    const row = await fetchRow(vinNormalized);
    next = applyDecodeSuccess(next, session, row);
  } catch (err) {
    const message = err instanceof Error ? err.message : "Decode failed";
    next = applyDecodeError(next, session, message);
  }
  return next;
}

If setState lands after another start bumped generation, applyDecodeSuccess no-ops. Product guarantee: newer request wins; older responses become no-ops.

What this is not

Do not conflate this guard with AbortSignal plumbing, input-clear cancel UX, timeout-only races, or SWR cache revalidation. Those are adjacent. You can combine abort + generation: abort reduces wasted work; generation prevents wrong paint when abort is incomplete.

Forbidden "fixes"

Product pressure often asks for:

1. "Just always take the last response that arrives" without comparing ids (that is the bug)
2. Showing a spinner until all in-flight promises settle (hangs the UI on abandoned A)
3. Merging row A and row B fields because "some data is better than none"
4. Skipping the guard for errors ("errors are harmless") -- they are not; they blank good cards
5. Reusing one global promise for every VIN without stamping which VIN it belongs to

Refuse those. One stamp per start; commit only if current. The expensive bug is not a wasted network call -- it is a trustworthy-looking card that silently shows the wrong vehicle.

Quick checks

import assert from "node:assert/strict";

const base: DecodeUiState = {
  vin: null,
  row: null,
  error: null,
  loading: false,
  generation: 0,
};

const sessionA: DecodeSession = { generation: 1, vinNormalized: "A".repeat(17) };
const sessionB: DecodeSession = { generation: 2, vinNormalized: "B".repeat(17) };

let state: DecodeUiState = { ...base, generation: 2, loading: true };
state = applyDecodeSuccess(state, sessionB, { Make: "Beta" });
assert.equal(state.row?.Make, "Beta");

// Late A must not overwrite B
state = applyDecodeSuccess(state, sessionA, { Make: "Alpha" });
assert.equal(state.row?.Make, "Beta");

// Late A error must not wipe B
state = applyDecodeError(state, sessionA, "upstream timeout");
assert.equal(state.row?.Make, "Beta");
assert.equal(state.error, null);

assert.equal(isCurrent(sessionA, 2), false);
assert.equal(isCurrent(sessionB, 2), true);

Review rule: decode commit paths must ignore mismatched generations. Never apply a resolved body solely because loading was once true.

Takeaway

Out-of-order VIN decode responses are normal on a chatty form. Stamp every start with a request id or generation counter, and ignore successes and errors that no longer match. Your free VIN UI stays trustworthy when the newest request owns the card -- and older payloads become silent no-ops instead of identity flip-flops.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/ignoring-stale-vin-decode-responses-after-a-newer-request-wins-the-race-4j99

This post is about debounce-before-request: wait until typing pauses before you start a decode for a still-settling VIN, and only schedule work when the normalized value is a full 17-character candidate. Input-clear cancel (#131 family) decides when to stop an in-flight request. Stale-response guards decide which response may commit. Here the focus is delaying the start so partial digits never become upstream traffic.

The failure mode

Typical sequence without debounce-before-request:

1. User types character by character toward a 17-character VIN.
2. Your handler treats length >= 17 (or even length == 17 after a typo-fix) as "ready" and fires immediately on the first full-looking string.
3. The user backspaces digit 17, types a correction, and you fire again -- sometimes three times in under a second.
4. NHTSA (or your proxy quota) sees a burst of near-identical incomplete or wrong VINs.
5. The UI flickers loading states for candidates the user never intended to submit.

Cancel-on-clear does not prevent the burst: each intermediate full-looking string already started. Stale-response ignore only drops late commits; it does not reduce upstream calls that already left the browser.

Debounce the schedule, not the paste

Own one timer per input session. On every change, normalize the VIN. If it is not a decodeable 17-character candidate, clear any pending timer and do not start. If it is decodeable, reschedule a single delayed start instead of calling fetch immediately. A paste of a complete VIN still waits the short debounce once -- or you may short-circuit paste with an immediate path; the important part is that mid-typing corrections collapse into one scheduled call.

const VIN_RE = /^[A-HJ-NPR-Z0-9]{17}$/;

export function normalizeVin(raw: string): string {
  return raw.trim().toUpperCase().replace(/[\s\-._]/g, "");
}

export function shouldDecode(normalized: string): boolean {
  return VIN_RE.test(normalized);
}

export type DebounceHandle = {
  timer: ReturnType<typeof setTimeout> | null;
  generation: number;
};

export function createDebounceHandle(): DebounceHandle {
  return { timer: null, generation: 0 };
}

export function scheduleDecode(opts: {
  raw: string;
  handle: DebounceHandle;
  delayMs: number;
  startDecode: (vin: string, generation: number) => void;
}): void {
  const next = normalizeVin(opts.raw);
  if (opts.handle.timer != null) {
    clearTimeout(opts.handle.timer);
    opts.handle.timer = null;
  }

  if (!shouldDecode(next)) {
    // Partial digits: never start; do not leave a pending timer.
    return;
  }

  const generation = ++opts.handle.generation;
  opts.handle.timer = setTimeout(() => {
    opts.handle.timer = null;
    opts.startDecode(next, generation);
  }, opts.delayMs);
}

Partial lengths never schedule. Full candidates schedule once; each new keystroke resets the timer so only the pause after the last edit becomes a request.

Pair with generation, not only AbortController

When the timer fires, pass a generation (or the exact VIN string) into the fetch path. If a newer schedule already bumped generation, ignore the stale start. This is complementary to AbortSignal: debounce reduces how often you create controllers; abort and stale guards clean up what already started.

export type DecodeSession = {
  controller: AbortController;
  vinNormalized: string;
  generation: number;
};

export function startIfCurrent(opts: {
  vin: string;
  generation: number;
  handle: DebounceHandle;
  session: DecodeSession | null;
  setSession: (s: DecodeSession | null) => void;
  fetchDecode: (vin: string, signal: AbortSignal) => Promise<unknown>;
}): void {
  if (opts.generation !== opts.handle.generation) return;

  opts.session?.controller.abort();
  const controller = new AbortController();
  opts.setSession({
    controller,
    vinNormalized: opts.vin,
    generation: opts.generation,
  });

  void opts.fetchDecode(opts.vin, controller.signal);
}

Do not fire on every input event for length 1-16. Do not treat debounce as a substitute for clear-cancel: if the user empties the box after a timer was scheduled, clear the timer and abort any session that already started.

What this is not

• Not input-clear cancel: that aborts when the box becomes empty mid-flight.
• Not stale-response ignore: that drops commits when a newer request won the race.
• Not "debounce complete pastes forever": paste of a valid 17-character VIN may use a shorter delay or immediate fire; the hammering problem is partial and rapidly corrected digits.

You can combine debounce-before-request, clear-cancel, and stale guards. Debounce is the gate that keeps incomplete typing off the wire.

Quick checks

import assert from "node:assert/strict";

const calls: string[] = [];
const handle = createDebounceHandle();

scheduleDecode({
  raw: "1HGCM82633A00435", // 16 chars
  handle,
  delayMs: 300,
  startDecode: (vin) => calls.push(vin),
});
assert.equal(handle.timer, null);
assert.deepEqual(calls, []);

scheduleDecode({
  raw: "1HGCM82633A004352",
  handle,
  delayMs: 300,
  startDecode: (vin) => calls.push(vin),
});
assert.ok(handle.timer != null);

scheduleDecode({
  raw: "1HGCM82633A004353", // corrected last digit
  handle,
  delayMs: 300,
  startDecode: (vin) => calls.push(vin),
});
assert.ok(handle.timer != null);

// Simulate timer fire for the latest schedule only.
const gen = handle.generation;
if (handle.timer) {
  clearTimeout(handle.timer);
  handle.timer = null;
}
startIfCurrent({
  vin: "1HGCM82633A004353",
  generation: gen,
  handle,
  session: null,
  setSession: () => {},
  fetchDecode: async (vin) => {
    calls.push(`fetch:${vin}`);
    return {};
  },
});
assert.deepEqual(calls, ["fetch:1HGCM82633A004353"]);

Review rule: partial VINs must not schedule upstream work; rapid corrections must collapse into one delayed start.

Choosing a delay

A delay in the 250-400ms range usually absorbs hunt-and-peck corrections without feeling sticky on paste. Measure your audience: if most users paste a full VIN, prefer the short end (or an immediate path when inputType indicates insertFromPaste). If most users type digit-by-digit on mobile, the longer end collapses more accidental 17-character flashes. Log scheduled-versus-fired counts in staging to see how often the timer saved an upstream call.

Takeaway

Debounce VIN input before you request DecodeVinValues so partial digits and rapid corrections never hammer NHTSA. Schedule only decodeable 17-character candidates, reset the timer on each edit, and pair the fire with a generation or AbortController so stale starts cannot pile up. Keep this gate separate from clear-cancel and stale-response guards. Your free VIN form stays kind to upstream quotas when typing noise stays in the browser until the user actually pauses on a full VIN.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/debouncing-vin-input-so-partial-digits-do-not-hammer-nhtsa-82n

The goal is narrow: under a latency deadline, finish primary decode first; cancel or skip non-critical enrichers; show partial results with clear provenance; refuse fake filler specs.

Graceful degrade vs load-shed, circuits, concurrency, retry budget

• Load shed -- refuse or drop requests when the edge is overloaded
• Circuit breaker -- stop calling an unhealthy dependency globally for a cool-down
• Concurrency / retry budget -- cap in-flight calls and per-VIN attempts
• Graceful degrade -- keep serving the critical decode path; secondary enrichers become optional under a remaining-time budget

Degrade is about partial success for one request. Shed is about protecting the fleet. You can degrade without shedding, and shed without offering a partial card.

Priority tiers and a remaining-time budget

Assign each step a priority. Primary DecodeVinValues is required. Secondary enrichers run only while remaining deadline allows. On skip, record reason -- never fabricate their fields.

export type EnricherId =
  | "vpic-primary"
  | "recall-snippet"
  | "photo-hint"
  | "analytics-ping";

export type EnricherResult =
  | { id: EnricherId; status: "ok"; data: Record<string, string> }
  | { id: EnricherId; status: "skipped"; reason: "deadline" | "dependency" }
  | { id: EnricherId; status: "error"; message: string };

export type Deadline = { startMs: number; budgetMs: number };

export function remainingMs(d: Deadline, now = Date.now()): number {
  return d.budgetMs - (now - d.startMs);
}

export type Enricher = {
  id: EnricherId;
  critical: boolean;
  minMs: number; // bail if remaining below this
  run: (vin: string, signal: AbortSignal) => Promise<Record<string, string>>;
};

export async function runWithGracefulDegrade(
  vin: string,
  enrichers: Enricher[],
  deadline: Deadline,
): Promise<EnricherResult[]> {
  const out: EnricherResult[] = [];
  for (const e of enrichers) {
    const left = remainingMs(deadline);
    if (!e.critical && left < e.minMs) {
      out.push({ id: e.id, status: "skipped", reason: "deadline" });
      continue;
    }
    const ac = new AbortController();
    const timer = setTimeout(
      () => ac.abort(),
      Math.max(0, e.critical ? left : Math.min(left, e.minMs * 2)),
    );
    try {
      const data = await e.run(vin, ac.signal);
      out.push({ id: e.id, status: "ok", data });
    } catch (err) {
      if (e.critical) {
        out.push({
          id: e.id,
          status: "error",
          message: err instanceof Error ? err.message : "primary failed",
        });
        break;
      }
      out.push({ id: e.id, status: "skipped", reason: "deadline" });
    } finally {
      clearTimeout(timer);
    }
  }
  return out;
}

export type CardRow = { label: string; value: string };

export function cardFromResults(results: EnricherResult[]): CardRow[] {
  const rows: CardRow[] = [];
  for (const r of results) {
    if (r.status === "ok") {
      for (const [k, v] of Object.entries(r.data)) {
        rows.push({ label: k, value: v });
      }
      continue;
    }
    if (r.id === "vpic-primary" && r.status !== "ok") {
      rows.push({ label: "Decode", value: "primary decode unavailable" });
      continue;
    }
    // Secondary: honest skip -- never invent enrichment values
    rows.push({
      label: r.id,
      value:
        r.status === "skipped"
          ? `skipped (${r.reason}) -- not provided this request`
          : `error -- not provided this request`,
    });
  }
  return rows;
}

Primary failure fails the request (or returns a clear error). Secondary skips leave the core Make/Model/Year rows intact when primary succeeded.

UI honesty under degrade

Prefer:

• Core vPIC rows from a successful primary
• "Recall snippet: skipped (deadline) -- not provided this request"
• A banner: "Partial decode -- secondary enrichment deferred"

Avoid:

• Grey fake recall counts or "no recalls" invented on skip
• Hiding that photo-hint never ran
• Relabeling a degraded card as "full enrichment complete"

Forbidden upgrades

1. Inventing secondary enrichment fields when skipped for deadline
2. Blocking the whole card on non-critical enrichers after primary succeeded
3. Treating graceful degrade as a license to ignore concurrency / retry budgets
4. Opening the circuit solely because one enricher skipped (different tool)
5. Shedding healthy primary decodes when you only needed to skip analytics

Refuse those. Partial + labeled beats complete + fake.

Quick checks

import assert from "node:assert/strict";

const enrichers: Enricher[] = [
  {
    id: "vpic-primary",
    critical: true,
    minMs: 50,
    run: async () => ({ Make: "HONDA", Model: "Accord" }),
  },
  {
    id: "recall-snippet",
    critical: false,
    minMs: 80,
    run: async (_v, signal) => {
      await new Promise((r, j) => {
        const t = setTimeout(r, 200);
        signal.addEventListener("abort", () => {
          clearTimeout(t);
          j(new Error("aborted"));
        });
      });
      return { recalls: "0" };
    },
  },
];

const results = await runWithGracefulDegrade("1HGCM82633A004352", enrichers, {
  startMs: Date.now(),
  budgetMs: 100,
});
assert.ok(results.some((r) => r.id === "vpic-primary" && r.status === "ok"));
assert.ok(
  results.some(
    (r) => r.id === "recall-snippet" && r.status === "skipped",
  ),
);
const rows = cardFromResults(results);
assert.ok(rows.some((r) => r.label === "Make" && r.value === "HONDA"));
assert.ok(
  rows.some((r) => /skipped|not provided this request/i.test(r.value)),
);
assert.ok(!rows.some((r) => r.label === "recalls" && r.value === "0"));

Review rule: degrade modules must preserve primary success and must not invent secondary fields on skip.

Takeaway

Graceful degradation keeps the critical DecodeVinValues path on time when NHTSA latency spikes, while secondary enrichers skip under a remaining-time budget with honest labels. Pair it with load shedding, circuits, concurrency limits, and retry budgets -- each owns a different pressure valve. Your free VIN card stays trustworthy when partial results are labeled partial -- never padded with invented enrichment marketing.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/gracefully-degrading-secondary-vin-enrichment-when-nhtsa-latency-spikes-1270

The goal is narrow: one submit, one deadline, one cancellable fetch chain. Do not confuse this with hedged dual-fire, idempotency keys, or jittered retries. Here the job is: when the UI no longer wants the result, stop waiting on the proxy path that would call NHTSA.

Where orphaned work comes from

Orphans appear when deadlines live only at one layer:

• Browser AbortController aborts the BFF fetch, but the BFF ignores req.signal and keeps calling DecodeVinValues
• BFF has a hard setTimeout that returns 504 to the client while the outbound NHTSA promise is still pending
• A second form submit starts a new decode without aborting the first in-flight attempt
• Serverless budgets shrink remaining time, but nobody wires that remaining budget into fetch(..., { signal })

Each case spends free-quota units on work the card will never show. Propagation means the same abort reason travels from submit handler to outbound proxy call.

Mint a deadline at submit, pass the signal

Create the controller when the user submits (or when the form auto-decodes once). Attach a wall-clock deadline, pass signal to your BFF, and abort on unmount, navigation, or superseding submit.

export type DecodeSubmitOpts = {
  vin: string;
  deadlineMs: number; // e.g. 8_000 from UX budget
  fetchProxy: (vin: string, signal: AbortSignal) => Promise<unknown>;
};

export function submitDecodeWithDeadline(
  opts: DecodeSubmitOpts,
): { promise: Promise<unknown>; abort: (reason?: unknown) => void } {
  const ctrl = new AbortController();
  const timer = setTimeout(() => {
    ctrl.abort(new Error("CLIENT_DEADLINE"));
  }, opts.deadlineMs);

  const promise = opts
    .fetchProxy(opts.vin, ctrl.signal)
    .finally(() => clearTimeout(timer));

  return {
    promise,
    abort: (reason) => ctrl.abort(reason ?? new Error("CLIENT_CANCEL")),
  };
}

export function supersedePrevious(
  previous: { abort: (reason?: unknown) => void } | null,
): void {
  previous?.abort(new Error("SUPERSEDED"));
}

On a second tap, abort the previous handle before minting a new one. Do not let two proxy calls race "for completeness" when only the latest submit should paint the card.

Proxy: forward the inbound signal to NHTSA

Your BFF must treat the inbound request signal as authoritative. Compose it with any remaining serverless budget so either expiry aborts the outbound DecodeVinValues fetch.

export function mergeAbortSignals(
  ...signals: AbortSignal[]
): AbortSignal {
  const ctrl = new AbortController();
  for (const s of signals) {
    if (s.aborted) {
      ctrl.abort(s.reason);
      return ctrl.signal;
    }
    s.addEventListener(
      "abort",
      () => ctrl.abort(s.reason),
      { once: true },
    );
  }
  return ctrl.signal;
}

export async function proxyDecodeVin(args: {
  vin: string;
  inbound: AbortSignal;
  budgetSignal: AbortSignal;
  decodeVinValues: (vin: string, signal: AbortSignal) => Promise<unknown>;
}): Promise<unknown> {
  const signal = mergeAbortSignals(args.inbound, args.budgetSignal);
  if (signal.aborted) {
    throw signal.reason ?? new Error("ABORTED_BEFORE_UPSTREAM");
  }
  return args.decodeVinValues(args.vin, signal);
}

If the client already aborted, do not open a new upstream socket "to populate cache anyway." Cache warming is a separate, explicitly scheduled job -- not a side effect of a cancelled user decode.

Budgets and propagation compose: the serverless remaining-time check decides whether a retry is allowed; the AbortSignal decides whether work already in flight should stop. Propagating a deadline without aborting outbound fetch only returns early to the browser while NHTSA keeps running -- the orphan problem this post targets.

Forbidden upgrades

Product pressure often asks for:

1. Ignoring client aborts so the proxy "finishes for analytics"
2. Returning a synthetic 200 after abort by merging a partial body
3. Letting superseded submits complete in the background without metrics
4. Treating deadline abort as a retry trigger (that belongs in backoff modules)
5. Counting only displayed responses against quota while aborted upstreams stay invisible

Refuse those. Log decode_aborted_client, decode_aborted_budget, and decode_superseded. Count issued DecodeVinValues calls, including ones cancelled after the request left your edge.

Ops copy that stays honest

Prefer:

• Metrics that separate user cancel, deadline, and supersede
• Proxy logs that record whether outbound fetch received an AbortSignal
• A kill switch that fails closed (reject new submits) when abort rate spikes with dual open upstreams

Avoid:

• Silent background completion after the UI showed a timeout
• Alerting only on HTTP 5xx while orphans inflate NHTSA traffic
• Documenting "we always finish the decode" as a reliability feature when the card is gone

Quick checks

import assert from "node:assert/strict";

const calls: string[] = [];
const { promise, abort } = submitDecodeWithDeadline({
  vin: "1HGCM82633A004352",
  deadlineMs: 50,
  fetchProxy: async (_vin, signal) => {
    calls.push("start");
    await new Promise<void>((resolve, reject) => {
      const t = setTimeout(() => resolve(), 500);
      signal.addEventListener("abort", () => {
        clearTimeout(t);
        reject(signal.reason);
      });
    });
    calls.push("done");
    return {};
  },
});

await assert.rejects(promise);
assert.ok(!calls.includes("done"));

const inbound = AbortSignal.abort(new Error("CLIENT_CANCEL"));
await assert.rejects(
  proxyDecodeVin({
    vin: "1HGCM82633A004352",
    inbound,
    budgetSignal: new AbortController().signal,
    decodeVinValues: async () => {
      calls.push("upstream");
      return {};
    },
  }),
);
assert.ok(!calls.includes("upstream"));

Review rule: proxy decode modules must pass a merged AbortSignal into outbound NHTSA fetch and must not start upstream work when the inbound signal is already aborted.

Takeaway

Deadline propagation turns a form-level cancel into a cancellable NHTSA proxy call. Without it, client timeouts and superseded submits leave orphaned DecodeVinValues work that burns free quota for a card nobody will see. Mint the AbortController at submit, forward the signal through the BFF, merge it with any serverless budget, and refuse background "finish anyway" completions. Keep this path separate from hedges and idempotency keys so abandoned VIN lookups stop spending upstream time as soon as the UI stops caring.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/propagating-deadlines-from-vin-form-submit-to-nhtsa-proxy-without-orphaned-work-48l2

The goal is narrow: isolate in-flight decode slots by tenant, route, or failure class so a saturated bulkhead rejects or queues locally instead of consuming every shared worker. Do not confuse this with circuit breakers that open on error rates, idempotency keys, or jittered retries. Here the job is: cap how many concurrent NHTSA-bound calls one noisy path may hold.

Where pool starvation comes from

Starvation appears when every decode shares one unbounded (or globally capped) queue:

• A single API key or browser session opens dozens of parallel DecodeVinValues calls
• A stuck upstream keeps workers occupied until client timeouts pile retries on top
• Batch import and interactive form traffic share the same pool with no separate ceilings
• A "bad VIN" hot path retries forever while interactive users wait for free slots

Each case turns free-quota and worker time into a tragedy of the commons. Bulkheads give each path its own concurrency budget so exhaustion stays local.

Cap concurrency per bulkhead key

Assign each decode a bulkhead key (tenant id, route name, or interactive vs batch). Acquire a slot before calling the proxy; release it in finally. When the bulkhead is full, fail fast or queue with a short local timeout -- do not steal slots from other keys.

export type Bulkhead = {
  key: string;
  limit: number;
  inFlight: number;
  waiters: Array<() => void>;
};

export function createBulkhead(key: string, limit: number): Bulkhead {
  return { key, limit, inFlight: 0, waiters: [] };
}

export async function withBulkhead<T>(
  bh: Bulkhead,
  run: () => Promise<T>,
): Promise<T> {
  if (bh.inFlight >= bh.limit) {
    await new Promise<void>((resolve, reject) => {
      const timer = setTimeout(() => {
        const i = bh.waiters.indexOf(wake);
        if (i >= 0) bh.waiters.splice(i, 1);
        reject(new Error("BULKHEAD_TIMEOUT"));
      }, 2_000);
      const wake = () => {
        clearTimeout(timer);
        resolve();
      };
      bh.waiters.push(wake);
    });
  }
  bh.inFlight += 1;
  try {
    return await run();
  } finally {
    bh.inFlight -= 1;
    const next = bh.waiters.shift();
    if (next) next();
  }
}

export function bulkheadKey(opts: {
  tenantId?: string;
  route: "interactive" | "batch";
}): string {
  return `${opts.route}:${opts.tenantId ?? "anon"}`;
}

Interactive form traffic can use a higher per-tenant limit than batch imports. Anonymous clients get a small shared ceiling so one scraper cannot monopolize DecodeVinValues.

Forbidden "fixes"

Product pressure often asks for:

1. Raising the global worker limit instead of partitioning noisy paths
2. Letting batch jobs borrow interactive slots when the batch bulkhead is full
3. Retrying BULKHEAD_TIMEOUT immediately without backoff (which re-saturates the same key)
4. Sharing one bulkhead across all tenants "for simplicity"
5. Treating bulkhead rejection as an NHTSA outage and opening a global breaker

Refuse those. A full bulkhead is a local capacity signal, not proof that vPIC is down. Keep breaker logic on upstream error rates; keep bulkheads on concurrency ownership.

export type DecodePool = Map<string, Bulkhead>;

export function getBulkhead(
  pool: DecodePool,
  key: string,
  limits: { interactive: number; batch: number },
): Bulkhead {
  let bh = pool.get(key);
  if (!bh) {
    const route = key.startsWith("batch:") ? "batch" : "interactive";
    bh = createBulkhead(
      key,
      route === "batch" ? limits.batch : limits.interactive,
    );
    pool.set(key, bh);
  }
  return bh;
}

export async function decodeBehindBulkhead<T>(
  pool: DecodePool,
  opts: { tenantId?: string; route: "interactive" | "batch" },
  run: () => Promise<T>,
): Promise<T> {
  const key = bulkheadKey(opts);
  const bh = getBulkhead(pool, key, { interactive: 8, batch: 2 });
  return withBulkhead(bh, run);
}

Separate interactive and batch ceilings. Never let a saturated batch key drain the interactive pool, and never map bulkhead rejection into a fabricated "NHTSA unavailable" banner when other bulkheads still succeed.

UI and API copy that stays honest

Prefer:

• "Decode busy for this session -- try again shortly" on BULKHEAD_TIMEOUT
• Metrics labeled by bulkhead key, not a single global "queue depth"
• A short footnote in ops docs: local concurrency cap, not an upstream grade

Avoid:

• "NHTSA is down" when only one tenant bulkhead is full
• Silently queueing batch work on interactive workers
• Grey spinners that look like a decode in flight after you already rejected the slot

Quick checks

import assert from "node:assert/strict";

const bh = createBulkhead("interactive:t1", 1);
let released = false;
const first = withBulkhead(bh, async () => {
  await new Promise((r) => setTimeout(r, 50));
  released = true;
  return "ok";
});

await assert.rejects(
  withBulkhead(bh, async () => "nope"),
  /BULKHEAD_TIMEOUT/,
);
assert.equal(released, false);
assert.equal(await first, "ok");
assert.equal(bh.inFlight, 0);

assert.equal(
  bulkheadKey({ tenantId: "a", route: "batch" }),
  "batch:a",
);

const pool: DecodePool = new Map();
const interactive = getBulkhead(pool, "interactive:x", {
  interactive: 8,
  batch: 2,
});
const batch = getBulkhead(pool, "batch:x", { interactive: 8, batch: 2 });
assert.equal(interactive.limit, 8);
assert.equal(batch.limit, 2);
assert.notEqual(interactive, batch);

Review rule: bulkhead modules must fail closed on local saturation, never steal slots across keys, and must not relabel rejection as a global NHTSA outage.

Takeaway

Bulkheading VIN decode workers keeps one bad path from starving the shared pool. Cap concurrency per tenant and route, fail or wait locally when a bulkhead is full, and keep that signal separate from breakers, hedges, and deadlines. Your free VIN proxy stays fair when interactive decodes cannot be crowded out by a single noisy batch or retry storm -- and when rejection copy admits local capacity, not invented upstream failure.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/bulkheading-vin-decode-workers-so-one-bad-vin-path-cannot-starve-the-pool-21gf

The goal is narrow: implement get-or-load for normalized VINs, single-populate on miss, expose cache age to the UI, and keep misses from becoming folklore cards. Cache-aside is deliberately boring infrastructure -- its value is correct loading and honest labeling, not clever speculation about what a VIN "should" contain.

Cache-aside vs SWR, ETag, negative, stampede, warmup

• SWR -- serve soft-stale while revalidating in background
• ETag -- conditional revalidation with validators
• Negative cache -- remember failures / invalid VINs
• Stampede control -- one refresher when many hit expiry together
• Warmup -- populate before first user miss
• Cache-aside -- read path loads on miss; writer is the read path (or explicit put after live success)

Cache-aside is the default lazy pattern. Pair it with stampede control when popular keys expire; do not confuse a simple miss-fill with SWR's soft-stale serve. On a cold miss you wait for live; on a warm hit you must still admit the body's age.

Get-or-load with honest age

export type CacheAsideEntry = {
  vinNormalized: string;
  body: string;
  storedAt: number;
  maxAgeMs: number;
};

export type CacheAsideStore = Map<string, CacheAsideEntry>;

export type CacheAsideResult = {
  body: string;
  hit: boolean;
  ageMs: number;
  source: "cache" | "live";
};

export type LiveDecode = (vin: string) => Promise<string>;

export function getAside(
  store: CacheAsideStore,
  vinNormalized: string,
  now = Date.now(),
): CacheAsideEntry | null {
  const e = store.get(vinNormalized);
  if (!e) return null;
  if (now - e.storedAt > e.maxAgeMs) {
    store.delete(vinNormalized);
    return null;
  }
  return e;
}

export function putAside(
  store: CacheAsideStore,
  vinNormalized: string,
  body: string,
  maxAgeMs = 86_400_000,
  now = Date.now(),
): CacheAsideEntry {
  const e: CacheAsideEntry = { vinNormalized, body, storedAt: now, maxAgeMs };
  store.set(vinNormalized, e);
  return e;
}

export async function getOrLoad(
  store: CacheAsideStore,
  vinNormalized: string,
  live: LiveDecode,
  maxAgeMs = 86_400_000,
  now = Date.now(),
): Promise<CacheAsideResult> {
  const hit = getAside(store, vinNormalized, now);
  if (hit) {
    return {
      body: hit.body,
      hit: true,
      ageMs: now - hit.storedAt,
      source: "cache",
    };
  }
  const body = await live(vinNormalized);
  putAside(store, vinNormalized, body, maxAgeMs, Date.now());
  return { body, hit: false, ageMs: 0, source: "live" };
}

export function freshnessLabel(r: CacheAsideResult): string {
  if (r.source === "live") {
    return "Decoded from live NHTSA (cache miss filled)";
  }
  const ageSec = Math.round(r.ageMs / 1000);
  return `Cache hit -- catalog body age ~${ageSec}s (not inventing newer specs)`;
}

On live failure, do not put a folklore body. Leave the key missing so the next call retries, or use negative cache (separate tool) for known-invalid VINs. If many clients miss the same key together, wrap getOrLoad's live call in singleflight or stampede leadership so you still count one NHTSA fill -- cache-aside defines where the body lives; those tools define who may load it.

Honesty rules for hits and misses

Prefer:

1. One live fill per miss (add singleflight/stampede if many waiters share the miss)
2. Age labels on hits so UI does not say "live just now"
3. TTL expiry deletes or treats as miss -- no eternal silent hits
4. No write of partial invented fields when live returns sparse Results (partial payload honesty elsewhere)

Avoid serving a hit while claiming live completion, and avoid miss paths that invent Make from WMI charts. Emit metrics for hit ratio, miss latency, and average age-at-hit so you can tune maxAgeMs from data instead of folklore about how often vPIC changes.

Forbidden upgrades

1. Populating cache with guessed catalog JSON when NHTSA fails
2. Labeling every hit as "live NHTSA just now"
3. Skipping TTL because "VIN decode never changes" (patterns and fields do evolve)
4. Using cache-aside put to store negative failures as successful empty cars
5. Warming by writing folklore for popular makes without a live body

Refuse those. Cache-aside speeds repeats; it does not mint specs.

Quick checks

import assert from "node:assert/strict";

const store: CacheAsideStore = new Map();
let liveCalls = 0;
const live: LiveDecode = async () => {
  liveCalls += 1;
  return JSON.stringify({ Results: [{ Make: "HONDA" }] });
};

const a = await getOrLoad(store, "1HGCM82633A004352", live);
assert.equal(a.hit, false);
assert.equal(a.source, "live");
assert.equal(liveCalls, 1);

const b = await getOrLoad(store, "1HGCM82633A004352", live);
assert.equal(b.hit, true);
assert.equal(b.source, "cache");
assert.equal(liveCalls, 1);
assert.ok(/Cache hit/i.test(freshnessLabel(b)));
assert.ok(!/live NHTSA just now/i.test(freshnessLabel(b)));

// expired entry becomes miss
const e = store.get("1HGCM82633A004352")!;
e.storedAt = Date.now() - e.maxAgeMs - 1;
const c = await getOrLoad(store, "1HGCM82633A004352", live);
assert.equal(c.hit, false);
assert.equal(liveCalls, 2);

Review rule: cache-aside modules must fill from live on miss, label hit age honestly, and must not invent bodies on upstream failure.

Takeaway

Cache-aside VIN decodes hit NHTSA once per miss, store the real body, and serve repeats with an honest age label. Leave SWR, ETag, negative cache, stampede control, and warmup for their own jobs. Your free VIN edge stays fast when the cache is a shelf for sourced payloads -- never a factory for folklore catalog cards. Speed without age labels is how cached data pretends to be live.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

DEV article: forthcoming

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/cache-aside-vin-decodes-so-misses-hit-nhtsa-once-and-hits-stay-honest-about-age-57p1

The goal: stop a thundering herd when soft TTL ends across tabs or workers, without inventing specs mid-herd, and without claiming a stampede-safe serve is "live just now."

Stampede vs SWR, singleflight, warmup, negative cache

• SWR -- when a soft-stale body may be served while refreshing
• Singleflight -- merge identical in-flight promises once refresh starts
• Warmup / negative cache -- preload popular keys; skip known-bad VINs
• Stampede control -- who may start a refresh when many clients hit soft expiry, plus jitter so TTLs do not align

Stampede without singleflight still doubles live calls across workers; SWR without stampede control invites a herd the moment soft TTL flips.

Detect the herd window

When soft TTL has expired but hard TTL has not, every concurrent reader wants a refresh. Without a leader lock, each calls live NHTSA.

export type StampedeEntry = {
  vinNormalized: string;
  body: string;
  storedAt: number;
  softTtlMs: number;
  hardTtlMs: number;
  refreshLockUntil?: number; // epoch ms; leader holds refresh
  inflight?: Promise<string>;
};

export type StampedeStore = Map<string, StampedeEntry>;

export function softExpired(e: StampedeEntry, now = Date.now()): boolean {
  return now - e.storedAt > e.softTtlMs;
}

export function hardExpired(e: StampedeEntry, now = Date.now()): boolean {
  return now - e.storedAt > e.hardTtlMs;
}

/** Jitter soft TTL so popular VINs do not expire in lockstep. */
export function softTtlWithJitter(
  baseMs: number,
  vinNormalized: string,
  jitterFrac = 0.1,
): number {
  let h = 0;
  for (let i = 0; i < vinNormalized.length; i++) {
    h = (Math.imul(31, h) + vinNormalized.charCodeAt(i)) | 0;
  }
  const unit = ((h >>> 0) % 1000) / 1000; // 0..1
  const delta = (unit * 2 - 1) * jitterFrac; // -jitter..+jitter
  return Math.floor(baseMs * (1 + delta));
}

Jitter alone does not stop a herd after expiry -- it only desynchronizes when soft expiry hits. You still need a refresh leader.

One leader revalidates; others serve stale

On soft-stale hit: try to acquire a short refresh lock. Winner starts one live decode (optionally via singleflight). Losers return the stale body with an honest revalidating / stale label. Never invent Make/Model/Year while waiting.

export type LiveDecode = (vin: string) => Promise<string>;

export type StampedeResult = {
  body: string;
  freshness: "fresh" | "stale" | "revalidating";
  source: "cache" | "live";
  leader: boolean;
};

const LOCK_MS = 5_000;

export async function getAvoidingStampede(
  store: StampedeStore,
  vinNormalized: string,
  live: LiveDecode,
  now = Date.now(),
): Promise<StampedeResult> {
  let entry = store.get(vinNormalized);
  if (!entry || hardExpired(entry, now)) {
    const body = await live(vinNormalized);
    const softTtlMs = softTtlWithJitter(3_600_000, vinNormalized);
    store.set(vinNormalized, {
      vinNormalized,
      body,
      storedAt: now,
      softTtlMs,
      hardTtlMs: 86_400_000,
    });
    return { body, freshness: "fresh", source: "live", leader: true };
  }

  if (!softExpired(entry, now)) {
    return {
      body: entry.body,
      freshness: "fresh",
      source: "cache",
      leader: false,
    };
  }

  // Soft-stale: elect a leader for refresh
  const lockHeld =
    entry.refreshLockUntil !== undefined && entry.refreshLockUntil > now;
  if (!lockHeld && !entry.inflight) {
    entry.refreshLockUntil = now + LOCK_MS;
    entry.inflight = live(vinNormalized)
      .then((body) => {
        store.set(vinNormalized, {
          vinNormalized,
          body,
          storedAt: Date.now(),
          softTtlMs: softTtlWithJitter(3_600_000, vinNormalized),
          hardTtlMs: 86_400_000,
        });
        return body;
      })
      .finally(() => {
        const cur = store.get(vinNormalized);
        if (cur) {
          delete cur.inflight;
          delete cur.refreshLockUntil;
        }
      });
    return {
      body: entry.body,
      freshness: "revalidating",
      source: "cache",
      leader: true,
    };
  }

  // Followers: serve stale, do not start another live call
  return {
    body: entry.body,
    freshness: entry.inflight ? "revalidating" : "stale",
    source: "cache",
    leader: false,
  };
}

export function stampedeFootnote(r: StampedeResult): string {
  if (r.freshness === "fresh" && r.source === "live") {
    return "Decoded from live NHTSA for this request";
  }
  if (r.freshness === "revalidating") {
    return r.leader
      ? "Serving soft-stale body; this tab leads refresh"
      : "Serving soft-stale body; another tab leads refresh";
  }
  return "Serving soft-stale catalog body; soft TTL expired";
}

Across processes, replace the in-memory lock with Redis SET NX or a similar lease. Honesty stays: followers never invent a card; leaders never label a pre-refresh stale body as live.

Forbidden upgrades

1. Letting every soft-expired tab call NHTSA "just to be sure"
2. Extending hard TTL forever to dodge stampedes (hides staleness forever)
3. Filling missing fields during the herd with Make/Model/Year folklore
4. Labeling follower stale serves as "live NHTSA just now"
5. Dropping the stale body and returning an empty spinner for every follower

Refuse those. Stampede control is about upstream calm and honest freshness -- not fake completeness.

Quick checks

import assert from "node:assert/strict";

const store: StampedeStore = new Map();
const vin = "1HGCM82633A004352";
let liveCalls = 0;
const live: LiveDecode = async () => {
  liveCalls += 1;
  await new Promise((r) => setTimeout(r, 20));
  return JSON.stringify({ Results: [{ Make: "HONDA" }] });
};

const t0 = 1_000;
const first = await getAvoidingStampede(store, vin, live, t0);
assert.equal(first.source, "live");
assert.equal(liveCalls, 1);

const softAt = t0 + store.get(vin)!.softTtlMs + 1;
const a = getAvoidingStampede(store, vin, live, softAt);
const b = getAvoidingStampede(store, vin, live, softAt);
const [ra, rb] = await Promise.all([a, b]);
assert.equal(ra.source, "cache");
assert.equal(rb.source, "cache");
assert.ok(ra.leader !== rb.leader); // exactly one leader
assert.equal(liveCalls, 2); // miss + one revalidate, not three
assert.ok(!/live NHTSA just now/i.test(stampedeFootnote(rb)));
await store.get(vin)?.inflight;

Review rule: stampede modules must elect one refresh leader per key and must not invent specs for followers.

Takeaway

When soft TTL expires across many tabs, a VIN decode cache can stampede NHTSA unless one leader revalidates and followers keep serving soft-stale bodies with honest labels. Jitter desynchronizes expiry; locks or singleflight collapse the herd; hard TTL still forces a live wait when the body is too old. Stampede control beside SWR stays fast and truthful -- without pretending every stale serve was a fresh live decode.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

DEV article: forthcoming

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/preventing-vin-decode-cache-stampedes-when-soft-ttl-expires-across-many-tabs-56l1

This post is about server/edge singleflight: a process-local map from normalized VIN to one in-flight promise so concurrent identical lookups share one DecodeVinValues. Client-side request coalesce (duplicate pastes in one browser session) is a related idea with a different boundary -- see that pattern separately. Debounce decides when typing may start a call. ETag caches skip repeats after success. Here the focus is sharing one in-flight promise across concurrent server callers for the same VIN.

The failure mode

Typical sequence without singleflight on the edge:

1. Request A arrives for VIN X; the handler starts DecodeVinValues.
2. Request B arrives for the same normalized X before A settles (second tab, prefetch, or parallel SSR).
3. The handler starts a second identical upstream fetch.
4. NHTSA sees two calls; your edge latency and quota budget take a hit for no new information.
5. Both responses return; you still paid twice for one pattern.

Client coalesce does not fix this: the duplicates already crossed the network as separate HTTP requests. A response cache helps after success, not while the first edge fetch is still pending. A global mutex that serializes all VINs is worse -- unrelated lookups wait on each other.

One promise per normalized VIN on the process

Own a module-scoped map from normalized VIN to the in-flight Promise. On decode:

1. Normalize and validate the VIN.
2. If the map already has an entry for that key, return it.
3. Otherwise create the upstream promise, store it, and finally delete the key when settled.

Concurrent waiters on the same isolate share the result. Distinct VINs still run in parallel -- singleflight is keyed by identity, not a process-wide lock. Multi-isolate cold starts still duplicate until you add a shared cache; singleflight only collapses concurrency inside one runtime.

const VIN_RE = /^[A-HJ-NPR-Z0-9]{17}$/;

export function normalizeVin(raw: string): string {
  return raw.trim().toUpperCase().replace(/[\s\-._]/g, "");
}

export type DecodeRow = Record<string, string>;

export type SingleflightMap = Map<string, Promise<DecodeRow>>;

export function singleflightDecode(
  inflight: SingleflightMap,
  rawVin: string,
  fetchDecode: (vin: string) => Promise<DecodeRow>,
): Promise<DecodeRow> {
  const vin = normalizeVin(rawVin);
  if (!VIN_RE.test(vin)) {
    return Promise.reject(new Error("invalid_vin"));
  }

  const existing = inflight.get(vin);
  if (existing) return existing;

  const pending = fetchDecode(vin).finally(() => {
    if (inflight.get(vin) === pending) inflight.delete(vin);
  });
  inflight.set(vin, pending);
  return pending;
}

The finally cleanup matters. Leaving settled promises in the map would pin memory and block honest retries after a failed attempt. Delete only when the map still points at this promise so a concurrent re-entry after failure can start fresh work.

Forbidden shortcuts

Product pressure often asks for:

1. A process-wide lock so every decode waits on whichever VIN started first
2. Treating singleflight as a substitute for a shared Redis/ETag cache across isolates
3. Claiming "instant decode -- no NHTSA" when you only shared one in-flight edge call
4. Keeping failed 5xx promises in the map so retries never leave
5. Keying by raw query string without normalize (case or hyphens create duplicate flights)

Refuse those. Singleflight identical valid in-flight work on one process. Keep client coalesce for same-session duplicate pastes, debounce for typing, and durable caches for post-success repeats across instances. Do not invent offline or "skipped upstream" marketing from a shared promise.

export function assertNoSingleflightAbuse(moduleSource: string): void {
  const banned = [
    /global.?lock.?all.?vins/i,
    /skip.?nhtsa.?via.?singleflight/i,
    /instant.?decode.?no.?upstream/i,
    /singleflight.?replaces.?cache/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(`Singleflight module misuse: ${re}`);
    }
  }
}

export async function decodeWithSingleflight(
  inflight: SingleflightMap,
  rawVin: string,
  fetchDecode: (vin: string) => Promise<DecodeRow>,
  onShared: () => void,
): Promise<DecodeRow> {
  const vin = normalizeVin(rawVin);
  const wasShared = inflight.has(vin);
  const row = await singleflightDecode(inflight, rawVin, fetchDecode);
  if (wasShared) onShared();
  return row;
}

Instrument onShared (or a metric) so you can see how often concurrent edge callers joined. That is observability, not a claim that decode is free or that NHTSA was skipped.

API copy that stays honest

Prefer:

• Silent share: concurrent waiters see the same loading outcome without a second upstream span
• Optional quiet log or metric: "joined in-flight singleflight for this VIN"
• Clear error if the shared promise rejects -- every waiter sees the same failure

Avoid:

• "Cached instantly -- no NHTSA call" when you only singleflighted an open edge request
• Hiding a shared failure from secondary waiters
• Showing success for VIN B because A's in-flight promise was incorrectly keyed

Quick checks

import assert from "node:assert/strict";

const inflight: SingleflightMap = new Map();
let calls = 0;
const fetchDecode = async (vin: string): Promise<DecodeRow> => {
  calls += 1;
  await new Promise((r) => setTimeout(r, 20));
  return { VIN: vin, Make: "TEST" };
};

const p1 = singleflightDecode(inflight, "1HGCM82633A004352", fetchDecode);
const p2 = singleflightDecode(inflight, "1hgcm82633a004352", fetchDecode);
assert.equal(p1, p2);
const [a, b] = await Promise.all([p1, p2]);
assert.equal(a.Make, "TEST");
assert.equal(b.Make, "TEST");
assert.equal(calls, 1);
assert.equal(inflight.size, 0);

const p3 = singleflightDecode(inflight, "1HGCM82633A004352", fetchDecode);
await p3;
assert.equal(calls, 2);

Review rule: singleflight modules must share by normalized VIN only while pending on this process, clear on settle, and never claim to replace client coalesce, debounce, or durable response caches.

Takeaway

Server/edge singleflight collapses concurrent identical VIN lookups into one upstream DecodeVinValues call per process. Pair it with client coalesce (same-session duplicates), debounce (start timing), and ETag caches (post-success repeats) -- do not substitute one for another. Your free VIN API stays kind to NHTSA when mid-flight work on one runtime shares a promise, then clears so the next lookup can run honestly.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/singleflight-vin-decode-lookups-so-concurrent-identical-vins-share-one-in-flight-promise-29nn

The goal is narrow: cap simultaneous upstream calls from your edge (or BFF), queue excess work briefly or reject with an honest busy signal, and never fabricate a decode card to "keep the UI full" under load.

Concurrency limit vs rate limit, singleflight, stampede

• Token bucket / rate limit -- how many starts per second over a window
• Quota headers -- honor upstream Retry-After / remaining when told
• Singleflight -- one shared promise per identical VIN key
• Stampede control -- one soft-TTL refresh leader per key
• Concurrency limit -- how many live upstream calls may be in flight at once, regardless of VIN identity

A rate limit of 10/s can still open 50 sockets if each call takes 5s. A concurrency cap of 8 keeps peak sockets honest even when many distinct VINs arrive together.

Semaphore shape

Track inFlight and a FIFO wait queue. Acquire before calling live NHTSA; release in finally. Bound queue length and wait time so tabs do not hang forever.

export type LiveDecode = (vin: string) => Promise<string>;

export type LimitResult =
  | { ok: true; body: string; waitedMs: number }
  | { ok: false; reason: "queue-full" | "wait-timeout"; waitedMs: number };

export type ConcurrencyLimit = {
  maxInFlight: number;
  maxQueue: number;
  maxWaitMs: number;
  inFlight: number;
  waiters: Array<{
    enqueuedAt: number;
    resolve: (granted: boolean) => void;
    timer: ReturnType<typeof setTimeout>;
  }>;
};

export function createLimit(
  maxInFlight = 8,
  maxQueue = 32,
  maxWaitMs = 3_000,
): ConcurrencyLimit {
  return { maxInFlight, maxQueue, maxWaitMs, inFlight: 0, waiters: [] };
}

function grant(limit: ConcurrencyLimit): void {
  limit.inFlight += 1;
}

function release(limit: ConcurrencyLimit): void {
  limit.inFlight -= 1;
  const next = limit.waiters.shift();
  if (!next) return;
  clearTimeout(next.timer);
  next.resolve(true);
}

async function acquire(
  limit: ConcurrencyLimit,
  now = Date.now(),
): Promise<{ granted: boolean; waitedMs: number }> {
  if (limit.inFlight < limit.maxInFlight) {
    grant(limit);
    return { granted: true, waitedMs: 0 };
  }
  if (limit.waiters.length >= limit.maxQueue) {
    return { granted: false, waitedMs: 0 };
  }
  const enqueuedAt = now;
  const granted = await new Promise<boolean>((resolve) => {
    const timer = setTimeout(() => {
      const idx = limit.waiters.findIndex((w) => w.resolve === resolve);
      if (idx >= 0) limit.waiters.splice(idx, 1);
      resolve(false);
    }, limit.maxWaitMs);
    limit.waiters.push({ enqueuedAt, resolve, timer });
  });
  const waitedMs = Date.now() - enqueuedAt;
  if (!granted) return { granted: false, waitedMs };
  grant(limit);
  return { granted: true, waitedMs };
}

export async function decodeWithLimit(
  limit: ConcurrencyLimit,
  vinNormalized: string,
  live: LiveDecode,
): Promise<LimitResult> {
  const { granted, waitedMs } = await acquire(limit);
  if (!granted) {
    return {
      ok: false,
      reason: waitedMs > 0 ? "wait-timeout" : "queue-full",
      waitedMs,
    };
  }
  try {
    const body = await live(vinNormalized);
    return { ok: true, body, waitedMs };
  } finally {
    release(limit);
  }
}

export function busyMessage(r: Extract<LimitResult, { ok: false }>): string {
  return r.reason === "queue-full"
    ? "Decode busy: upstream concurrency queue full -- try again shortly"
    : "Decode busy: waited too long for an upstream slot -- try again shortly";
}

Never map a reject into a fake Make/Model/Year card. Show the busy message; optionally retry client-side with backoff after the user confirms.

Queue wait vs reject

Product pressure often wants infinite queues so "nobody sees an error." Prefer bounded wait:

1. Short queue + timeout -- absorb bursts, then reject honestly
2. Reject fast when full -- protects NHTSA and your edge memory
3. Do not invent specs while a tab waits for a slot
4. Combine with singleflight after acquire so identical VINs still share one live body
5. Combine with token bucket so even under the concurrency cap you do not exceed sustained rate

Concurrency limits are about peak sockets; rate limits are about sustained starts. Use both.

Forbidden upgrades

1. Raising maxInFlight to "unlimited" under load so every tab opens a socket
2. Returning folklore catalog rows when queue-full or wait-timeout fires
3. Labeling a queued wait as "live NHTSA completed" before acquire succeeds
4. Dropping the semaphore because singleflight "already dedupes" (it does not cap distinct VINs)
5. Ignoring NHTSA quota headers because the concurrency cap "should be enough"

Refuse those. An honest busy state beats a stampeded upstream and a lying card.

Quick checks

import assert from "node:assert/strict";

const limit = createLimit(2, 2, 50);
let liveCalls = 0;
const live: LiveDecode = async (vin) => {
  liveCalls += 1;
  await new Promise((r) => setTimeout(r, 80));
  return JSON.stringify({ Results: [{ VIN: vin }] });
};

const jobs = ["VINAAAA", "VINBBBB", "VINCCCC", "VINDDDD", "VINEEEE"].map(
  (v) => decodeWithLimit(limit, v, live),
);
const results = await Promise.all(jobs);
const oks = results.filter((r) => r.ok);
const fails = results.filter((r) => !r.ok);
assert.ok(oks.length >= 2);
assert.ok(fails.length >= 1);
assert.ok(liveCalls <= 4); // cap + short queue, not five parallel forever
assert.ok(
  fails.every((f) => !f.ok && /busy|queue|waited/i.test(busyMessage(f))),
);
assert.ok(
  !results.some(
    (r) => r.ok && /folklore|invented/i.test(r.body),
  ),
);

Review rule: concurrency modules must bound in-flight upstream calls and must not invent decode bodies on reject.

Takeaway

A concurrency limit keeps browser tabs from opening unbounded DecodeVinValues sockets against NHTSA. Cap in-flight calls, bound the wait queue, reject with an honest busy signal, and leave rate limits, quota headers, singleflight, and stampede control in their own lanes. Your free VIN edge stays calm when peak concurrency is explicit -- and never fills a busy moment with invented catalog marketing.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

DEV article: https://dev.to/vin_lookup_8dbd4710f77e9e/limiting-concurrent-vin-decode-upstream-calls-so-browser-tabs-do-not-exhaust-nhtsa-46a3

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/limiting-concurrent-vin-decode-upstream-calls-so-browser-tabs-do-not-exhaust-nhtsa-46a3

The goal is narrow: return a cached body past soft TTL while a revalidate runs, expose fresh vs stale vs revalidating to callers, and never invent specs or claim "live NHTSA just now" when you served stale.

SWR vs ETag, negative cache, and warmup

Use SWR when:

• Soft TTL expired but hard TTL has not -- body may still be useful
• A repeat lookup should paint fast while a background DecodeVinValues runs
• Callers can show "catalog snapshot; refreshing..." without blocking

Do not confuse SWR with:

• ETag / If-None-Match conditional fetches (validator equality, not soft-stale serve)
• Negative cache of invalid VINs (no successful body to serve stale)
• Make-pattern warmup (prefetch popular keys before first user hit)

SWR is about freshness semantics on a successful cached body. When hard TTL expires, drop the entry and require a blocking live fetch. Never serve a negative entry as a successful card.

Soft TTL, hard TTL, and honesty labels

Store soft and hard windows. Soft expiry allows stale serve + background revalidate. Hard expiry forces a live wait. Label every response so the UI cannot lie.

export type Freshness = "fresh" | "stale" | "revalidating" | "miss";

export type SwrEntry = {
  vinNormalized: string;
  body: string;
  storedAt: number; // epoch ms
  softTtlMs: number;
  hardTtlMs: number;
  revalidating?: Promise<string>;
};

export type SwrStore = Map<string, SwrEntry>;

export type SwrResult = {
  body: string | null;
  freshness: Freshness;
  source: "cache" | "live" | "missing";
};

const SOFT_TTL_MS = 60 * 60 * 1000; // 1h soft
const HARD_TTL_MS = 24 * 60 * 60 * 1000; // 24h hard

export function ageMs(entry: SwrEntry, now = Date.now()): number {
  return now - entry.storedAt;
}

export function classify(entry: SwrEntry, now = Date.now()): Freshness {
  const age = ageMs(entry, now);
  if (age > entry.hardTtlMs) return "miss";
  if (age <= entry.softTtlMs) return "fresh";
  if (entry.revalidating) return "revalidating";
  return "stale";
}

A fresh body may still be hours old relative to wall clock -- that is fine if soft TTL allows it. What is not fine is labeling a soft-stale serve as "live decode completed just now."

Serve stale, revalidate once

On soft-stale hit: return the cached body immediately, start one background revalidate (coalesce concurrent callers onto the same promise), and surface revalidating so the UI can footnote.

export type LiveDecode = (vin: string) => Promise<string>;

export async function getWithSwr(
  store: SwrStore,
  vinNormalized: string,
  live: LiveDecode,
  now = Date.now(),
): Promise<SwrResult> {
  const entry = store.get(vinNormalized);
  if (!entry || ageMs(entry, now) > entry.hardTtlMs) {
    const body = await live(vinNormalized);
    store.set(vinNormalized, {
      vinNormalized,
      body,
      storedAt: now,
      softTtlMs: SOFT_TTL_MS,
      hardTtlMs: HARD_TTL_MS,
    });
    return { body, freshness: "fresh", source: "live" };
  }

  const freshness = classify(entry, now);
  if (freshness === "fresh") {
    return { body: entry.body, freshness: "fresh", source: "cache" };
  }

  // Soft-stale: serve body, kick revalidate if not already running
  if (!entry.revalidating) {
    entry.revalidating = live(vinNormalized)
      .then((body) => {
        store.set(vinNormalized, {
          vinNormalized,
          body,
          storedAt: Date.now(),
          softTtlMs: SOFT_TTL_MS,
          hardTtlMs: HARD_TTL_MS,
        });
        return body;
      })
      .finally(() => {
        const cur = store.get(vinNormalized);
        if (cur) delete cur.revalidating;
      });
  }

  return {
    body: entry.body,
    freshness: "revalidating",
    source: "cache",
  };
}

export function freshnessFootnote(r: SwrResult): string {
  switch (r.freshness) {
    case "fresh":
      return r.source === "live"
        ? "Decoded from live NHTSA for this request"
        : "Cached catalog body within soft TTL";
    case "stale":
      return "Serving stale catalog body; soft TTL expired";
    case "revalidating":
      return "Serving stale catalog body while refreshing from NHTSA";
    case "miss":
      return "No usable cache entry; live decode required";
  }
}

Never rewrite the stale body while revalidate is in flight. Swap only when the live promise resolves. If revalidate fails, keep serving the prior body with an honest error footnote -- do not invent Make/Model/Year to "heal" the miss.

Forbidden upgrades

Product pressure often asks for:

1. Labeling every SWR serve as "live NHTSA just now"
2. Extending hard TTL forever so stale bodies never expire
3. Serving negative-cache failures as successful decode cards
4. Inventing missing catalog fields while a revalidate is pending
5. Hiding the revalidating footnote so cards look always-fresh

Refuse those. Speed without honesty is a lie about freshness.

Quick checks

import assert from "node:assert/strict";

const store: SwrStore = new Map();
const vin = "1HGCM82633A004352";
let liveCalls = 0;
const live: LiveDecode = async () => {
  liveCalls += 1;
  return JSON.stringify({ Results: [{ Make: "HONDA" }] });
};

const first = await getWithSwr(store, vin, live, 1_000);
assert.equal(first.freshness, "fresh");
assert.equal(first.source, "live");
assert.equal(liveCalls, 1);

const softStaleAt = 1_000 + SOFT_TTL_MS + 1;
const second = await getWithSwr(store, vin, live, softStaleAt);
assert.equal(second.source, "cache");
assert.equal(second.freshness, "revalidating");
assert.ok(/stale|refreshing/i.test(freshnessFootnote(second)));
assert.ok(!/live NHTSA just now/i.test(freshnessFootnote(second)));

// Concurrent soft-stale callers share one revalidate
const third = await getWithSwr(store, vin, live, softStaleAt);
assert.equal(third.freshness, "revalidating");
await store.get(vin)!.revalidating;
assert.equal(liveCalls, 2); // one live + one revalidate, not three

Review rule: SWR modules must expose freshness labels and must not claim live completion for stale serves.

Takeaway

Stale-while-revalidate keeps repeat VIN lookups fast by serving a soft-stale catalog body while NHTSA refreshes in the background. Pair soft and hard TTLs, coalesce revalidates, and label every response so users never confuse a stale snapshot with a just-completed live decode. Speed and honesty travel together; ETag, negative, and warmup caches stay in their own lanes.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/serving-stale-while-revalidate-vin-decodes-so-repeat-lookups-stay-fast-without-lying-about-freshness-1h99

The goal is narrow: one logical decode attempt, one client key, zero duplicate NHTSA hits when the network or the user repeats themselves. Do not confuse this with VIN-content caching ("same VIN forever") or with circuit breakers that open on slow upstreams.

Why the client must mint the key

Server-derived keys built only from normalized VIN + userId collide across different user intents: yesterday's decode and today's deliberate refresh share the same fingerprint. For quota protection on retries, you want the opposite of forever-dedupe: a short-lived key that is stable for one button press and its automatic retries, then expires so a later deliberate click is a new charge.

The browser (or mobile app) is the right place to mint that key:

1. User taps Decode (or the form auto-submits once)
2. Client creates a UUID (or ULID) and stores it next to the in-flight VIN
3. Every retry of that attempt sends the same Idempotency-Key header
4. A fresh tap after success or cancel mints a new key

That pattern preserves legitimate second decodes while collapsing double-clicks and transport retries onto one upstream budget.

Shape the request, not the VIN

export type DecodeAttempt = {
  vinNormalized: string;
  idempotencyKey: string;
  createdAt: number;
};

const ATTEMPT_TTL_MS = 60_000;

export function mintDecodeAttempt(vinNormalized: string): DecodeAttempt {
  return {
    vinNormalized,
    idempotencyKey: crypto.randomUUID(),
    createdAt: Date.now(),
  };
}

export function headerForAttempt(attempt: DecodeAttempt): HeadersInit {
  return {
    "Idempotency-Key": attempt.idempotencyKey,
    "Content-Type": "application/json",
  };
}

export function isAttemptFresh(attempt: DecodeAttempt, now = Date.now()): boolean {
  return now - attempt.createdAt < ATTEMPT_TTL_MS;
}

Send the key on POST (or on your BFF's decode route). Do not bake the key into the VIN string. Do not reuse yesterday's key from localStorage across sessions -- that silently merges unrelated user actions and can skip a decode the buyer intended.

Edge / BFF: honor the key before calling NHTSA

Your product layer still owns side effects (metrics, audit rows, UI history). The client key lets the edge short-circuit before DecodeVinValues:

type GateResult =
  | { kind: "proceed" }
  | { kind: "replay"; body: unknown }
  | { kind: "inflight" };

type StoredAttempt = {
  status: "pending" | "complete";
  body?: unknown;
  expiresAt: number;
};

const attempts = new Map<string, StoredAttempt>(); // Redis in production

export function gateUpstream(
  key: string,
  ttlMs = 60_000,
): GateResult {
  const now = Date.now();
  const existing = attempts.get(key);
  if (existing && existing.expiresAt > now) {
    if (existing.status === "complete") {
      return { kind: "replay", body: existing.body };
    }
    return { kind: "inflight" };
  }
  attempts.set(key, { status: "pending", expiresAt: now + ttlMs });
  return { kind: "proceed" };
}

export function completeAttempt(key: string, body: unknown, ttlMs = 60_000): void {
  attempts.set(key, {
    status: "complete",
    body,
    expiresAt: Date.now() + ttlMs,
  });
}

On proceed, call NHTSA once, then completeAttempt. On replay, return the stored body without touching upstream. On inflight, return 409 or a typed "decode already in progress" so the client waits instead of opening a second socket.

Client retry loop that keeps the key

export async function decodeWithClientKey(
  attempt: DecodeAttempt,
  post: (init: RequestInit) => Promise<Response>,
  maxRetries = 2,
): Promise<Response> {
  if (!isAttemptFresh(attempt)) {
    throw new Error("idempotency attempt expired; mint a new key");
  }
  let last: Response | undefined;
  for (let i = 0; i <= maxRetries; i++) {
    last = await post({
      method: "POST",
      headers: headerForAttempt(attempt),
      body: JSON.stringify({ vin: attempt.vinNormalized }),
    });
    if (last.status === 409) {
      await new Promise((r) => setTimeout(r, 200 * (i + 1)));
      continue;
    }
    if (last.ok || last.status < 500) return last;
  }
  return last!;
}

Critical rule: retries must not call mintDecodeAttempt again. Minting on each retry is how you double-charge quota while believing you are being careful.

Quota accounting stays honest

Count an upstream charge only when DecodeVinValues actually leaves your process. Replays from gateUpstream and 409-inflight waits must not increment NHTSA counters or "decodes today" meters. If the dashboard shows three upstream calls for one client key, the gate is wrong or the retry loop is minting keys. Keep server TTL short (30–90s) so deliberate refreshes stay real charges.

Forbidden patterns

1. Deriving the only key from VIN alone (collides intentional refreshes; also skips cache-bust when you need one)
2. Minting a new UUID on every retry tick
3. Persisting keys forever in localStorage so next week's visit replays last week's body
4. Treating a client key as proof the VIN is valid -- still validate length and check digit locally
5. Counting local validation failures as upstream quota events

Client keys protect transport and double-submit windows. They do not replace honest field display, circuit breakers, or long-term VIN result caches.

Quick checks

import assert from "node:assert/strict";

const a = mintDecodeAttempt("1HGCM82633A004352");
const b = mintDecodeAttempt("1HGCM82633A004352");
assert.notEqual(a.idempotencyKey, b.idempotencyKey);

assert.equal(gateUpstream(a.idempotencyKey).kind, "proceed");
assert.equal(gateUpstream(a.idempotencyKey).kind, "inflight");
completeAttempt(a.idempotencyKey, { make: "HONDA" });
const replay = gateUpstream(a.idempotencyKey);
assert.equal(replay.kind, "replay");

const headers = headerForAttempt(a);
assert.equal(
  (headers as Record<string, string>)["Idempotency-Key"],
  a.idempotencyKey,
);

Review rule: retry helpers must accept an existing attempt object; they must not mint inside the loop.

Takeaway

Client idempotency keys stop retry storms and double-clicks from burning NHTSA quota twice for one decode intent. Mint once per tap, send the same header on every retry, gate upstream before DecodeVinValues, and expire keys quickly so deliberate refreshes remain real. Handler idempotency and VIN caches remain useful -- they solve different windows. Quota honesty starts at the client key.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/client-idempotency-keys-for-vin-decode-retries-without-double-charging-upstream-quotas-2ap

This post is about honest display: show the ESC catalog value when vPIC provides it, refuse stability-safety inventing, and allow a clean "not provided" state when the field is empty. Keep ESC catalog tokens separate from yaw-rate sensor health, brake-pressure tests, and road-course handling scores. A sourced token is still only a token: it does not prove the system is present, calibrated, or undamaged on the listed vehicle. (ABS honesty is a separate topic; here the focus is ESC.)

What ESC is (and is not) in vPIC

ESC (or the equivalent electronic stability control field your decode maps) is a catalog attribute associated with the VIN pattern. It answers a narrow question: which ESC-related token did the decode associate with this pattern?

It does not answer:

• Whether the vehicle currently meets a stability or rollover performance standard
• Whether ESC modules, yaw sensors, or hydraulic actuators work on this specific vehicle today
• Traction control, ABS, or brake-assist packages you did not source as separate keys
• Whether a dashboard ESC light is on, off, or silenced after a repair
• A composite "stability safety score" built from missing neighboring fields

Empty ESC does not authorize a default "Standard" badge, and a positive token does not mean "skid control verified." Do not fill gaps from Make/Model/Year folklore or a chart keyed only by model year.

Normalize empties, do not invent grades

Treat blank, "Not Applicable", "N/A", and similar tokens as missing. Keep a sourced string when present; do not rewrite it into "ESC Grade A" or a stability-inspection score.

const EMPTY = new Set([
  "",
  "not applicable",
  "n/a",
  "na",
  "null",
  "none",
  "unknown",
]);

export type EscView = {
  value: string | null;
  source: "vpic" | "missing";
};

export function viewEsc(fields: {
  ESC?: string | null;
}): EscView {
  const raw = (fields.ESC ?? "").trim();
  if (!raw || EMPTY.has(raw.toLowerCase())) {
    return { value: null, source: "missing" };
  }
  return { value: raw, source: "vpic" };
}

export function escLines(view: EscView): string[] {
  if (view.source === "missing") {
    return ["ESC: not provided by vPIC for this VIN"];
  }
  return [
    `ESC (vPIC): ${view.value}`,
    "Catalog token only -- not a stability-control safety grade",
  ];
}

The footnote matters. Buyers over-read a single ESC field as verified skid prevention. Show the sourced token; if blank, say "not provided" -- no greyed "Standard" and no invented stability grade.

Forbidden upgrades

Product pressure often asks for:

1. Mapping any non-empty ESC into "electronic stability control verified"
2. Inventing IIHS / Euro NCAP / star-equivalent stability-safety language from the catalog field
3. Bundling ESC with ABS or traction-control keys into "Full Stability Safety Package"
4. Defaulting blank ESC to "Standard" so mid-trim cars look complete
5. Renaming catalog tokens into OEM chassis-suite marketing names you did not source

Refuse those. If you show neighboring catalog fields from separate sourced keys, show each on its own row. Never invent skid-prevention or package language inside the ESC mapper.

export function assertNoEscStabilityInvent(moduleSource: string): void {
  const banned = [
    /esc verified/i,
    /stability.?control safety grade/i,
    /skid prevention verified/i,
    /iihs/i,
    /full stability safety/i,
    /euro ncap/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(
        `ESC module must not invent stability grades: ${re}`,
      );
    }
  }
}

export type CardRow = { label: string; value: string };

export function cardRows(fields: {
  ESC?: string | null;
  ABS?: string | null;
  TractionControl?: string | null;
}): CardRow[] {
  const view = viewEsc(fields);
  const out: CardRow[] = [];
  if (view.source === "missing") {
    out.push({ label: "ESC", value: "not provided" });
  } else {
    out.push({ label: "ESC", value: String(view.value) });
  }

  const abs = (fields.ABS ?? "").trim();
  if (abs && !EMPTY.has(abs.toLowerCase())) {
    out.push({ label: "ABS (vPIC)", value: abs });
  }
  const tc = (fields.TractionControl ?? "").trim();
  if (tc && !EMPTY.has(tc.toLowerCase())) {
    out.push({ label: "Traction control (vPIC)", value: tc });
  }
  return out;
}

Keep neighboring catalog fields on their own labeled rows. Never concatenate them into "Full Stability Safety Package," and never treat a separate ABS catalog key as proof that ESC implies a safety grade.

UI copy that stays honest

Prefer:

• "ESC (vPIC): Standard"
• "ESC: not provided by vPIC for this VIN"
• A short footnote: catalog token, not a stability-control safety grade

Avoid:

• "IIHS stability Superior -- verified"
• "ESC Grade A included"
• Grey placeholders that look like real ESC data when the field was empty

Quick checks

import assert from "node:assert/strict";

assert.equal(viewEsc({}).source, "missing");
assert.deepEqual(escLines(viewEsc({})), [
  "ESC: not provided by vPIC for this VIN",
]);

const std = viewEsc({ ESC: "Standard" });
assert.equal(std.value, "Standard");
assert.ok(
  escLines(std).some((l) => /not a stability-control safety grade/i.test(l)),
);
assert.ok(
  !escLines(std).some((l) =>
    /iihs|esc verified|stability safety package/i.test(l),
  ),
);

const rows = cardRows({
  ESC: "",
  ABS: "Standard",
  TractionControl: "Standard",
});
assert.ok(
  rows.some((r) => r.label === "ESC" && r.value === "not provided"),
);
assert.ok(rows.some((r) => r.label.includes("ABS")));
assert.ok(rows.some((r) => r.label.includes("Traction")));
assert.ok(!rows.some((r) => /iihs|esc verified/i.test(r.value)));

Review rule: ESC modules must not contain stability-upgrade or safety-grade phrases except in forbidding tests. Never upgrade a blank into "Standard."

Takeaway

ESC is a catalog token. Display it with clear sourcing, allow "not provided," and never use it as a key into invented stability-control safety grades, skid-prevention claims, or "full stability safety" bundles. Your free VIN UI stays trustworthy when ESC data is either a real vPIC value with a modest footnote -- or absent -- and chassis-performance marketing lives somewhere else, clearly labeled, or not at all.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/showing-esc-from-vpic-without-inventing-stability-control-safety-grades-13c1

This post is about honest display: show AdaptiveCruiseControl when vPIC provides it, refuse autonomy inventing, and allow a clean "not provided" state when the field is empty. Keep adaptive-cruise catalog values separate from SAE automation levels, OEM suite marketing, and highway-pilot branding. A sourced token is still only a token: it does not prove the feature is present, calibrated, or undamaged on the listed vehicle. Do not upgrade a cruise catalog string into a driverless narrative. (Forward-collision honesty is a separate topic; here the focus is AdaptiveCruiseControl.)

What AdaptiveCruiseControl is (and is not)

AdaptiveCruiseControl is a catalog attribute associated with the VIN decode. It answers a narrow question: which adaptive-cruise token did the decode associate with this pattern?

It does not answer:

• Whether the vehicle is SAE Level 2, Level 3, or "autonomous"
• Whether lane-centering, hands-free, or traffic-jam assist is included
• Radar vs camera hardware, following-distance modes, or stop-and-go behavior you did not source
• Whether the feature works today, was optioned, or was deleted after manufacture
• A composite "autonomy score" built from missing neighboring fields

Empty AdaptiveCruiseControl does not authorize a default "Standard" badge, and a positive token does not mean "self-driving verified." Do not fill gaps from Make/Model/Year folklore or a chart keyed only by model year.

Normalize empties, do not invent autonomy

Treat blank, "Not Applicable", "N/A", and similar tokens as missing. Keep a sourced string when present; do not rewrite it into "Level 2 Standard" or an autonomy marketing grade.

const EMPTY = new Set([
  "",
  "not applicable",
  "n/a",
  "na",
  "null",
  "none",
  "unknown",
]);

export type AccView = {
  value: string | null;
  source: "vpic" | "missing";
};

export function viewAdaptiveCruiseControl(fields: {
  AdaptiveCruiseControl?: string | null;
}): AccView {
  const raw = (fields.AdaptiveCruiseControl ?? "").trim();
  if (!raw || EMPTY.has(raw.toLowerCase())) {
    return { value: null, source: "missing" };
  }
  return { value: raw, source: "vpic" };
}

export function adaptiveCruiseLines(view: AccView): string[] {
  if (view.source === "missing") {
    return [
      "Adaptive cruise control: not provided by vPIC for this VIN",
    ];
  }
  return [
    `Adaptive cruise control (vPIC): ${view.value}`,
    "Catalog token only -- not an autonomy or SAE level claim",
  ];
}

The footnote matters. Buyers over-read a single adaptive-cruise field as verified hands-free driving. Show the sourced token; if blank, say "not provided" -- no greyed "Standard" and no invented autonomy claim.

Forbidden upgrades

Product pressure often asks for:

1. Mapping any non-empty AdaptiveCruiseControl into "Level 2 included"
2. Inventing SAE / NHTSA automation-level language from the catalog field
3. Bundling AdaptiveCruiseControl with lane-keep keys into "Full Autonomy Package"
4. Defaulting blank AdaptiveCruiseControl to "Standard" so mid-trim cars look complete
5. Renaming catalog tokens into OEM highway-pilot marketing names you did not source

Refuse those. If you show other ADAS catalog fields from separate sourced keys, show each on its own row. Never invent SAE levels or package language inside the AdaptiveCruiseControl mapper.

export function assertNoAccAutonomyInvent(moduleSource: string): void {
  const banned = [
    /level\s*[123]/i,
    /self-?driving/i,
    /autonom(y|ous)/i,
    /hands-?free/i,
    /full autonomy package/i,
    /sae\s*level/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(
        `AdaptiveCruiseControl module must not invent autonomy: ${re}`,
      );
    }
  }
}

export type CardRow = { label: string; value: string };

export function cardRows(fields: {
  AdaptiveCruiseControl?: string | null;
  ForwardCollisionWarning?: string | null;
  LaneKeepingSystem?: string | null;
}): CardRow[] {
  const view = viewAdaptiveCruiseControl(fields);
  const out: CardRow[] = [];
  if (view.source === "missing") {
    out.push({
      label: "Adaptive cruise control",
      value: "not provided",
    });
  } else {
    out.push({
      label: "Adaptive cruise control",
      value: String(view.value),
    });
  }

  const fcw = (fields.ForwardCollisionWarning ?? "").trim();
  if (fcw && !EMPTY.has(fcw.toLowerCase())) {
    out.push({ label: "Forward collision (vPIC)", value: fcw });
  }
  const lks = (fields.LaneKeepingSystem ?? "").trim();
  if (lks && !EMPTY.has(lks.toLowerCase())) {
    out.push({ label: "Lane keeping (vPIC)", value: lks });
  }
  return out;
}

Keep neighboring catalog fields on their own labeled rows. Never concatenate them into "Full Autonomy Package," and never treat a separate lane-keeping catalog key as proof that AdaptiveCruiseControl implies SAE Level 2.

UI copy that stays honest

Prefer:

• "Adaptive cruise control (vPIC): Standard"
• "Adaptive cruise control: not provided by vPIC for this VIN"
• A short footnote: catalog token, not an autonomy or SAE level claim

Avoid:

• "SAE Level 2 -- verified"
• "Self-driving / hands-free included"
• Grey placeholders that look like real adaptive-cruise data when the field was empty

Quick checks

import assert from "node:assert/strict";

assert.equal(viewAdaptiveCruiseControl({}).source, "missing");
assert.deepEqual(
  adaptiveCruiseLines(viewAdaptiveCruiseControl({})),
  ["Adaptive cruise control: not provided by vPIC for this VIN"],
);

const std = viewAdaptiveCruiseControl({
  AdaptiveCruiseControl: "Standard",
});
assert.equal(std.value, "Standard");
assert.ok(
  adaptiveCruiseLines(std).some((l) =>
    /not an autonomy or SAE level/i.test(l),
  ),
);
assert.ok(
  !adaptiveCruiseLines(std).some((l) =>
    /level\s*2|self-driving|autonomy package/i.test(l),
  ),
);

const rows = cardRows({
  AdaptiveCruiseControl: "",
  ForwardCollisionWarning: "Standard",
  LaneKeepingSystem: "Standard",
});
assert.ok(
  rows.some(
    (r) =>
      r.label.includes("Adaptive cruise") && r.value === "not provided",
  ),
);
assert.ok(rows.some((r) => r.label.includes("Forward collision")));
assert.ok(rows.some((r) => r.label.includes("Lane keeping")));
assert.ok(!rows.some((r) => /level\s*2|self-driving/i.test(r.value)));

Review rule: adaptive-cruise modules must not contain SAE-upgrade or autonomy-package phrases except in forbidding tests. Never upgrade a blank into "Standard."

Takeaway

AdaptiveCruiseControl is a catalog token. Display it with clear sourcing, allow "not provided," and never use it as a key into invented SAE levels, self-driving claims, or "full autonomy" bundles. Your free VIN UI stays trustworthy when adaptive-cruise data is either a real vPIC value with a modest footnote -- or absent -- and autonomy marketing lives somewhere else, clearly labeled, or not at all.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/displaying-adaptivecruisecontrol-from-vpic-without-inventing-autonomy-claims-57eh

This post is about latency-aware circuit breaking for free VIN decode: treat sustained slowness as a trip condition, fail fast for concurrent forms while open, and keep one slow call from stalling the whole UI surface. Classic consecutive-failure breakers are covered elsewhere; here the focus is slow upstream stalls every form.

Slow is not the same as down

A form that shares one decode client (module singleton, server action pool, or browser fetch queue) is especially fragile. Without a breaker, the first hung request occupies the only in-flight slot; the second submit waits; the third looks "broken" even though validation is fine.

What should count as slow failure

Define an explicit per-call budget (for example 6–8s wall time). When the call exceeds the budget -- via AbortSignal.timeout, a racing Promise, or your HTTP client's deadline -- record a slow failure for the breaker, abort the in-flight work, and return a typed UPSTREAM_SLOW result.

Count toward the trip:

• Timeouts and deadline aborts
• Network errors that leave the request unresolved
• HTTP 502 / 503 / 504 after a long wait (still a failure; also slow)

Do not count:

• Local validation rejects (never called upstream)
• Fast 200s with empty ABS / Make gaps (honest sparse success)
• User-aborted navigations when you already cancelled cleanly

Mixing validation noise into slow-failure counts opens the circuit on bad paste days and blocks good VINs for no reason.

TypeScript sketch: latency trips + form gate

type BreakerState = "closed" | "open" | "half_open";

export type LatencyBreakerConfig = {
  slowThresholdMs: number; // e.g. 7000
  failureThreshold: number; // e.g. 3 consecutive slow/hard failures
  cooldownMs: number; // e.g. 20_000
  halfOpenMaxProbes: number; // e.g. 1
};

export class LatencyCircuitBreaker {
  private state: BreakerState = "closed";
  private consecutiveFailures = 0;
  private openedAt = 0;
  private halfOpenProbes = 0;

  constructor(private readonly cfg: LatencyBreakerConfig) {}

  canRequest(): boolean {
    if (this.state === "closed") return true;
    if (this.state === "open") {
      if (Date.now() - this.openedAt >= this.cfg.cooldownMs) {
        this.state = "half_open";
        this.halfOpenProbes = 0;
        return true;
      }
      return false;
    }
    return this.halfOpenProbes < this.cfg.halfOpenMaxProbes;
  }

  beforeRequest(): void {
    if (this.state === "half_open") this.halfOpenProbes += 1;
  }

  recordSuccess(): void {
    this.consecutiveFailures = 0;
    this.state = "closed";
    this.halfOpenProbes = 0;
  }

  recordFailure(): void {
    this.consecutiveFailures += 1;
    if (
      this.state === "half_open" ||
      this.consecutiveFailures >= this.cfg.failureThreshold
    ) {
      this.state = "open";
      this.openedAt = Date.now();
      this.halfOpenProbes = 0;
    }
  }
}

export type DecodeResult<T> =
  | { ok: true; data: T }
  | { ok: false; reason: "circuit_open" | "upstream_slow" | "upstream" };

export async function decodeWithLatencyBreaker<T>(
  breaker: LatencyCircuitBreaker,
  call: (signal: AbortSignal) => Promise<T>,
  cfg: { slowThresholdMs: number },
): Promise<DecodeResult<T>> {
  if (!breaker.canRequest()) {
    return { ok: false, reason: "circuit_open" };
  }
  breaker.beforeRequest();
  const controller = new AbortController();
  const timer = setTimeout(
    () => controller.abort(),
    cfg.slowThresholdMs,
  );
  const started = Date.now();
  try {
    const data = await call(controller.signal);
    clearTimeout(timer);
    breaker.recordSuccess();
    return { ok: true, data };
  } catch (err) {
    clearTimeout(timer);
    breaker.recordFailure();
    const timedOut =
      controller.signal.aborted &&
      Date.now() - started >= cfg.slowThresholdMs - 50;
    return {
      ok: false,
      reason: timedOut ? "upstream_slow" : "upstream",
    };
  }
}

Gate every form submit on canRequest() before disabling inputs or starting a spinner. When the circuit is open, return immediately with circuit_open so sibling forms stay interactive.

UX that does not stall the form

Prefer:

• Instant "decode temporarily unavailable -- upstream is slow" when open
• Disable only the submit that would call NHTSA; keep paste/clear/help controls alive
• Optional stale last-good decode for that VIN, labeled "cached earlier; live refresh paused"

Avoid:

• A global page-level spinner held by one hung fetch
• Mapping circuit_open or upstream_slow to "invalid VIN"
• Silent retries that re-queue the same hung call behind the open circuit

Keep reason codes separate (CIRCUIT_OPEN vs UPSTREAM_SLOW vs VIN_INVALID) so support and status copy stay accurate.

Quick checks

import assert from "node:assert/strict";

const breaker = new LatencyCircuitBreaker({
  slowThresholdMs: 50,
  failureThreshold: 2,
  cooldownMs: 60_000,
  halfOpenMaxProbes: 1,
});

async function hang(_signal: AbortSignal): Promise<never> {
  await new Promise(() => {});
  throw new Error("unreachable");
}

const a = await decodeWithLatencyBreaker(breaker, hang, {
  slowThresholdMs: 50,
});
assert.equal(a.ok, false);
if (!a.ok) assert.equal(a.reason, "upstream_slow");

const b = await decodeWithLatencyBreaker(breaker, hang, {
  slowThresholdMs: 50,
});
assert.equal(b.ok, false);

assert.equal(breaker.canRequest(), false);
const blocked = await decodeWithLatencyBreaker(breaker, hang, {
  slowThresholdMs: 50,
});
assert.deepEqual(blocked, { ok: false, reason: "circuit_open" });

Review rule: form submit handlers must short-circuit on open before awaiting upstream. Never let one slow call own the only concurrency slot without a budget.

Takeaway

One slow NHTSA call should not freeze every VIN form. Budget each decode, count timeouts as failures, open the circuit before the queue piles up, and fail fast with an honest "temporarily unavailable" state. Layer latency breakers with validation and single-flight, and free VIN decode stays responsive when the public API merely crawls instead of crashing.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/circuit-breaking-nhtsa-calls-so-one-slow-upstream-does-not-stall-every-vin-form-2clc

This post is about honest display: show the ABS catalog value when vPIC provides it, refuse brake-safety inventing, and allow a clean "not provided" state when the field is empty. Keep ABS catalog tokens separate from brake-pad wear, hydraulic pressure, and road-test stopping distances. A sourced token is still only a token: it does not prove the system is present, calibrated, or undamaged on the listed vehicle. (TPMS and seat-belt honesty are separate topics; here the focus is ABS.)

What ABS is (and is not) in vPIC

ABS (or the equivalent anti-lock brake field your decode maps) is a catalog attribute associated with the VIN pattern. It answers a narrow question: which ABS-related token did the decode associate with this pattern?

It does not answer:

• Whether brakes currently meet a stopping-distance or fade standard
• Whether ABS modules, sensors, or pumps work on this specific vehicle today
• Electronic stability control, traction control, or brake-assist packages you did not source
• Whether a dashboard ABS light is on, off, or silenced after a repair
• A composite "brake safety score" built from missing neighboring fields

Empty ABS does not authorize a default "Standard" badge, and a positive token does not mean "brakes verified safe." Do not fill gaps from Make/Model/Year folklore or a chart keyed only by model year.

Normalize empties, do not invent grades

Treat blank, "Not Applicable", "N/A", and similar tokens as missing. Keep a sourced string when present; do not rewrite it into "ABS Grade A" or a brake-inspection score.

const EMPTY = new Set([
  "",
  "not applicable",
  "n/a",
  "na",
  "null",
  "none",
  "unknown",
]);

export type AbsView = {
  value: string | null;
  source: "vpic" | "missing";
};

export function viewAbs(fields: {
  ABS?: string | null;
}): AbsView {
  const raw = (fields.ABS ?? "").trim();
  if (!raw || EMPTY.has(raw.toLowerCase())) {
    return { value: null, source: "missing" };
  }
  return { value: raw, source: "vpic" };
}

export function absLines(view: AbsView): string[] {
  if (view.source === "missing") {
    return ["ABS: not provided by vPIC for this VIN"];
  }
  return [
    `ABS (vPIC): ${view.value}`,
    "Catalog token only -- not a brake-system safety grade",
  ];
}

The footnote matters. Buyers over-read a single ABS field as verified stopping performance. Show the sourced token; if blank, say "not provided" -- no greyed "Standard" and no invented brake grade.

Forbidden upgrades

Product pressure often asks for:

1. Mapping any non-empty ABS into "anti-lock brakes verified"
2. Inventing IIHS / Euro NCAP / star-equivalent brake-safety language from the catalog field
3. Bundling ABS with ESC or traction-control keys into "Full Brake Safety Package"
4. Defaulting blank ABS to "Standard" so mid-trim cars look complete
5. Renaming catalog tokens into OEM brake-suite marketing names you did not source

Refuse those. If you show neighboring catalog fields from separate sourced keys, show each on its own row. Never invent stopping-distance or package language inside the ABS mapper.

export function assertNoAbsBrakeInvent(moduleSource: string): void {
  const banned = [
    /abs verified/i,
    /brake.?system safety grade/i,
    /stopping distance/i,
    /iihs/i,
    /full brake safety/i,
    /euro ncap/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(
        `ABS module must not invent brake grades: ${re}`,
      );
    }
  }
}

export type CardRow = { label: string; value: string };

export function cardRows(fields: {
  ABS?: string | null;
  ESC?: string | null;
  TractionControl?: string | null;
}): CardRow[] {
  const view = viewAbs(fields);
  const out: CardRow[] = [];
  if (view.source === "missing") {
    out.push({ label: "ABS", value: "not provided" });
  } else {
    out.push({ label: "ABS", value: String(view.value) });
  }

  const esc = (fields.ESC ?? "").trim();
  if (esc && !EMPTY.has(esc.toLowerCase())) {
    out.push({ label: "ESC (vPIC)", value: esc });
  }
  const tc = (fields.TractionControl ?? "").trim();
  if (tc && !EMPTY.has(tc.toLowerCase())) {
    out.push({ label: "Traction control (vPIC)", value: tc });
  }
  return out;
}

Keep neighboring catalog fields on their own labeled rows. Never concatenate them into "Full Brake Safety Package," and never treat a separate ESC catalog key as proof that ABS implies a safety grade.

UI copy that stays honest

Prefer:

• "ABS (vPIC): Standard"
• "ABS: not provided by vPIC for this VIN"
• A short footnote: catalog token, not a brake-system safety grade

Avoid:

• "IIHS brake safety Superior -- verified"
• "ABS Grade A included"
• Grey placeholders that look like real ABS data when the field was empty

Quick checks

import assert from "node:assert/strict";

assert.equal(viewAbs({}).source, "missing");
assert.deepEqual(absLines(viewAbs({})), [
  "ABS: not provided by vPIC for this VIN",
]);

const std = viewAbs({ ABS: "Standard" });
assert.equal(std.value, "Standard");
assert.ok(
  absLines(std).some((l) => /not a brake-system safety grade/i.test(l)),
);
assert.ok(
  !absLines(std).some((l) =>
    /iihs|abs verified|brake safety package/i.test(l),
  ),
);

const rows = cardRows({
  ABS: "",
  ESC: "Standard",
  TractionControl: "Standard",
});
assert.ok(
  rows.some((r) => r.label === "ABS" && r.value === "not provided"),
);
assert.ok(rows.some((r) => r.label.includes("ESC")));
assert.ok(rows.some((r) => r.label.includes("Traction")));
assert.ok(!rows.some((r) => /iihs|abs verified/i.test(r.value)));

Review rule: ABS modules must not contain brake-upgrade or safety-grade phrases except in forbidding tests. Never upgrade a blank into "Standard."

Takeaway

ABS is a catalog token. Display it with clear sourcing, allow "not provided," and never use it as a key into invented brake-system safety grades, stopping-distance claims, or "full brake safety" bundles. Your free VIN UI stays trustworthy when ABS data is either a real vPIC value with a modest footnote -- or absent -- and brake-performance marketing lives somewhere else, clearly labeled, or not at all.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/showing-abs-from-vpic-without-inventing-brake-system-safety-grades-50jc

This post is about honest display: show the TPMS catalog value when vPIC provides it, refuse tire-safety inventing, and allow a clean "not provided" state when the field is empty. Keep TPMS catalog tokens separate from live sensor readings, tire tread depth, and inspection results. A sourced token is still only a token: it does not prove the system is present, calibrated, or undamaged on the listed vehicle.

What TPMS is (and is not) in vPIC

TPMS (or the equivalent tire-pressure monitoring field your decode maps) is a catalog attribute associated with the VIN pattern. It answers a narrow question: which TPMS-related token did the decode associate with this pattern?

It does not answer:

• Whether tires currently hold safe pressure or need inflation
• Whether sensors are installed, paired, or reporting correctly today
• Direct vs indirect TPMS hardware details you did not source
• Whether a dashboard light is on, off, or silenced after a wheel swap
• A composite "tire safety score" built from missing neighboring fields

Empty TPMS does not authorize a default "Standard" badge, and a positive token does not mean "tires verified safe." Do not fill gaps from Make/Model/Year folklore or a chart keyed only by model year.

Normalize empties, do not invent health

Treat blank, "Not Applicable", "N/A", and similar tokens as missing. Keep a sourced string when present; do not rewrite it into "TPMS Healthy" or a tire-inspection grade.

const EMPTY = new Set([
  "",
  "not applicable",
  "n/a",
  "na",
  "null",
  "none",
  "unknown",
]);

export type TpmsView = {
  value: string | null;
  source: "vpic" | "missing";
};

export function viewTpms(fields: {
  TPMS?: string | null;
}): TpmsView {
  const raw = (fields.TPMS ?? "").trim();
  if (!raw || EMPTY.has(raw.toLowerCase())) {
    return { value: null, source: "missing" };
  }
  return { value: raw, source: "vpic" };
}

export function tpmsLines(view: TpmsView): string[] {
  if (view.source === "missing") {
    return ["TPMS: not provided by vPIC for this VIN"];
  }
  return [
    `TPMS (vPIC): ${view.value}`,
    "Catalog token only -- not a tire-health or sensor status claim",
  ];
}

The footnote matters. Buyers over-read a TPMS catalog field as proof that tires are safe to drive. Show the sourced token; if blank, say "not provided" -- no greyed "Direct" and no invented "pressure OK" badge.

Forbidden upgrades

Product pressure often asks for:

1. Mapping any non-empty TPMS into "Tire pressure monitoring working"
2. Inventing psi readings, tread depth, or inspection grades from the catalog field
3. Bundling TPMS with unrelated safety keys into "Full Tire Safety Package"
4. Defaulting blank TPMS to "Standard" so mid-trim cars look complete
5. Renaming catalog tokens into OEM sensor marketing names you did not source

Refuse those. If you show other catalog fields from separate sourced keys, show each on its own row. Never invent live tire health inside the TPMS mapper.

export function assertNoTpmsHealthInvent(moduleSource: string): void {
  const banned = [
    /tire.?health/i,
    /pressure ok/i,
    /psi verified/i,
    /tread depth/i,
    /sensors working/i,
    /full tire safety/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(
        `TPMS module must not invent tire-safety claims: ${re}`,
      );
    }
  }
}

export type CardRow = { label: string; value: string };

export function cardRows(fields: {
  TPMS?: string | null;
  TirePressureMonitoringType?: string | null;
  WheelBaseType?: string | null;
}): CardRow[] {
  const view = viewTpms(fields);
  const out: CardRow[] = [];
  if (view.source === "missing") {
    out.push({ label: "TPMS", value: "not provided" });
  } else {
    out.push({ label: "TPMS", value: String(view.value) });
  }

  const kind = (fields.TirePressureMonitoringType ?? "").trim();
  if (kind && !EMPTY.has(kind.toLowerCase())) {
    out.push({
      label: "TPMS type (vPIC)",
      value: kind,
    });
  }
  const wheel = (fields.WheelBaseType ?? "").trim();
  if (wheel && !EMPTY.has(wheel.toLowerCase())) {
    out.push({ label: "Wheel base type (vPIC)", value: wheel });
  }
  return out;
}

Keep neighboring catalog fields on their own labeled rows. Never concatenate them into "Full Tire Safety Package," and never treat a separate type key as live sensor telemetry.

UI copy that stays honest

Prefer:

• "TPMS (vPIC): Direct"
• "TPMS: not provided by vPIC for this VIN"
• A short footnote: catalog token, not a tire-health or sensor status claim

Avoid:

• "Tire pressure OK -- verified"
• "Sensors working / full tire safety included"
• Grey placeholders that look like real TPMS data when the field was empty

Quick checks

import assert from "node:assert/strict";

assert.equal(viewTpms({}).source, "missing");
assert.deepEqual(tpmsLines(viewTpms({})), [
  "TPMS: not provided by vPIC for this VIN",
]);

const direct = viewTpms({ TPMS: "Direct" });
assert.equal(direct.value, "Direct");
assert.ok(
  tpmsLines(direct).some((l) =>
    /not a tire-health or sensor status/i.test(l),
  ),
);
assert.ok(
  !tpmsLines(direct).some((l) =>
    /pressure ok|tread|sensors working/i.test(l),
  ),
);

const rows = cardRows({
  TPMS: "",
  TirePressureMonitoringType: "Direct",
  WheelBaseType: "Long",
});
assert.ok(
  rows.some((r) => r.label === "TPMS" && r.value === "not provided"),
);
assert.ok(rows.some((r) => r.label.includes("TPMS type")));
assert.ok(rows.some((r) => r.label.includes("Wheel base")));
assert.ok(!rows.some((r) => /pressure ok|tire health/i.test(r.value)));

Review rule: TPMS modules must not contain tire-health or live-sensor phrases except in forbidding tests. Never upgrade a blank into "Standard" or "Direct."

Takeaway

TPMS from vPIC is a catalog token. Display it with clear sourcing, allow "not provided," and never use it as a key into invented psi readings, sensor-working claims, or "full tire safety" bundles. Your free VIN UI stays trustworthy when TPMS data is either a real vPIC value with a modest footnote -- or absent -- and tire inspection marketing lives somewhere else, clearly labeled, or not at all.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/displaying-tpms-from-vpic-without-inventing-tire-safety-claims-4me6

This post is about parse honesty: refuse to render incomplete vehicle identity as success, distinguish transport truncation from sparse-but-valid catalog rows, and guard JSON.parse plus result shape. Sparse fields after a valid parse are a different topic; here the failure mode is broken or partial JSON itself.

What "partial JSON" means here

A truncated or partial JSON body is not the same as a successful decode with empty Trim. It answers a narrow question: did we receive a complete, parseable document that matches the expected DecodeVinValues shape?

It does not authorize:

• Showing a "decoded" card from a string that throws mid-parse
• Guessing closed braces, inventing missing keys, or repairing Results by hand
• Promoting a partial object (Make present, ModelYear missing because the stream cut off) into a success state
• Reusing the last successful card when the new body failed to parse
• Treating HTTP 200 plus a truncated body as "good enough for identity"

HTTP status alone is not enough. A 200 with a cut-off Content-Length or a proxy that clipped the body is still a parse failure for UI purposes.

Parse, then validate shape -- never invent

Wrap JSON.parse so throwables become an explicit error state. After parse, require the Results array and enough identity keys to justify a card -- or refuse success.

const EMPTY = new Set([
  "",
  "not applicable",
  "n/a",
  "na",
  "null",
  "none",
  "unknown",
]);

export type ParseOutcome =
  | { ok: true; row: Record<string, string> }
  | { ok: false; reason: "truncated_or_invalid_json" | "missing_results" | "incomplete_identity" };

function nonEmpty(raw: string | null | undefined): string | null {
  const t = (raw ?? "").trim();
  if (!t || EMPTY.has(t.toLowerCase())) return null;
  return t;
}

export function parseVpicBody(bodyText: string): ParseOutcome {
  let parsed: unknown;
  try {
    parsed = JSON.parse(bodyText);
  } catch {
    return { ok: false, reason: "truncated_or_invalid_json" };
  }

  if (!parsed || typeof parsed !== "object") {
    return { ok: false, reason: "truncated_or_invalid_json" };
  }

  const results = (parsed as { Results?: unknown }).Results;
  if (!Array.isArray(results) || results.length === 0) {
    return { ok: false, reason: "missing_results" };
  }

  const row = results[0];
  if (!row || typeof row !== "object") {
    return { ok: false, reason: "missing_results" };
  }

  const rec = row as Record<string, string>;
  const make = nonEmpty(rec.Make);
  const model = nonEmpty(rec.Model);
  const year = nonEmpty(rec.ModelYear);
  if (!make || !model || !year) {
    return { ok: false, reason: "incomplete_identity" };
  }

  return { ok: true, row: rec };
}

Incomplete identity after a valid parse (Make present, Model blank because vPIC left it empty) can be a sparse success elsewhere. Here we refuse full success unless Make, Model, and ModelYear are all sourced. Adjust the bar for a deliberate "partial identity" state -- but never invent the missing pieces.

Forbidden upgrades

Product pressure often asks for:

1. Catching JSON.parse errors and still rendering a card from regex scraps
2. Auto-closing truncated JSON with "}]}" so the spinner stops
3. Showing Make from a half-object while labelling Model "estimating..."
4. Falling back to the previous VIN's card when the new body is truncated
5. Logging "decode ok" because status was 200 even when parse failed

Refuse those. A truncated body is an error or retry -- not a vehicle.

export type CardState =
  | { kind: "ready"; make: string; model: string; modelYear: string }
  | { kind: "error"; message: string };

const ERROR_MSG = {
  truncated_or_invalid_json:
    "Decode response was truncated or invalid JSON -- not showing a vehicle card",
  missing_results:
    "Decode response had no Results row -- not showing a vehicle card",
  incomplete_identity:
    "Decode response lacked Make, Model, or ModelYear -- not treating as success",
} as const;

export function cardFromBody(bodyText: string): CardState {
  const outcome = parseVpicBody(bodyText);
  if (!outcome.ok) {
    return { kind: "error", message: ERROR_MSG[outcome.reason] };
  }
  return {
    kind: "ready",
    make: String(nonEmpty(outcome.row.Make)),
    model: String(nonEmpty(outcome.row.Model)),
    modelYear: String(nonEmpty(outcome.row.ModelYear)),
  };
}

UI copy that stays honest

Prefer:

• "Decode response was truncated or invalid JSON -- try again"
• "No Results row in decode response"
• "Make, Model, or ModelYear missing -- not showing a complete vehicle card"

Avoid:

• "Decoded (partial)" with invented Model beside a Make scraped from a broken body
• Skeleton text that looks like catalog values while parse is still failing
• Silent reuse of the last successful decode when the new parse failed

Quick checks

import assert from "node:assert/strict";

const truncated = parseVpicBody('{"Count":1,"Results":[{"Make":"TOYOTA"');
assert.equal(truncated.ok, false);
assert.equal(truncated.reason, "truncated_or_invalid_json");

const sparse = JSON.stringify({
  Count: 1,
  Results: [{ Make: "TOYOTA", Model: "", ModelYear: "2019" }],
});
assert.equal(parseVpicBody(sparse).ok, false);
assert.equal(parseVpicBody(sparse).reason, "incomplete_identity");

const good = JSON.stringify({
  Count: 1,
  Results: [
    { Make: "TOYOTA", Model: "Camry", ModelYear: "2019", Trim: "" },
  ],
});
const card = cardFromBody(good);
assert.equal(card.kind, "ready");
if (card.kind === "ready") {
  assert.equal(card.make, "TOYOTA");
  assert.equal(card.model, "Camry");
  assert.equal(card.modelYear, "2019");
}

const badCard = cardFromBody("{not-json");
assert.equal(badCard.kind, "error");
assert.ok(/truncated or invalid JSON/i.test(
  badCard.kind === "error" ? badCard.message : "",
));

Review rule: parse modules must not repair JSON or reuse a previous card. Never paint identity from an unparseable body.

Takeaway

Truncated or partial vPIC JSON is a failure for vehicle-card purposes, not a prompt to invent Model or repair braces. Parse explicitly, validate Results and identity keys, and show error or retry when the document is incomplete. Your free VIN UI stays trustworthy when success means a real, complete parse -- not a half-invented car from scraps of a broken response.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/handling-truncated-or-partial-vpic-json-without-displaying-half-invented-vehicles-1894

This post is about honest display: show ForwardCollisionWarning when vPIC provides it, refuse crash-avoidance inventing, and allow a clean "not provided" state when the field is empty. Keep forward-collision catalog values separate from automatic emergency braking marketing, star ratings, and OEM suite names. A sourced token is still only a token: it does not prove the feature is present, calibrated, or undamaged on the listed vehicle. (Lane-departure and blind-spot honesty are separate topics; here the focus is ForwardCollisionWarning.)

What ForwardCollisionWarning is (and is not)

ForwardCollisionWarning is a catalog attribute associated with the VIN decode. It answers a narrow question: which forward-collision warning token did the decode associate with this pattern?

It does not answer:

• Whether the vehicle includes Automatic Emergency Braking (AEB) or pedestrian AEB
• Whether IIHS or NHTSA awarded a crash-avoidance or front-crash-prevention grade
• Camera vs radar hardware, braking intervention, or alert modality you did not source
• Whether the feature works today, was optioned, or was deleted after manufacture
• A composite "collision prevention score" built from missing neighboring fields

Empty ForwardCollisionWarning does not authorize a default "Standard" badge, and a positive token does not mean "AEB verified." Do not fill gaps from Make/Model/Year folklore or a chart keyed only by model year.

Normalize empties, do not invent grades

Treat blank, "Not Applicable", "N/A", and similar tokens as missing. Keep a sourced string when present; do not rewrite it into "AEB Standard" or an IIHS-style crash-avoidance grade.

const EMPTY = new Set([
  "",
  "not applicable",
  "n/a",
  "na",
  "null",
  "none",
  "unknown",
]);

export type ForwardCollisionView = {
  value: string | null;
  source: "vpic" | "missing";
};

export function viewForwardCollisionWarning(fields: {
  ForwardCollisionWarning?: string | null;
}): ForwardCollisionView {
  const raw = (fields.ForwardCollisionWarning ?? "").trim();
  if (!raw || EMPTY.has(raw.toLowerCase())) {
    return { value: null, source: "missing" };
  }
  return { value: raw, source: "vpic" };
}

export function forwardCollisionLines(view: ForwardCollisionView): string[] {
  if (view.source === "missing") {
    return [
      "Forward collision warning: not provided by vPIC for this VIN",
    ];
  }
  return [
    `Forward collision warning (vPIC): ${view.value}`,
    "Catalog token only -- not an AEB or crash-avoidance grade",
  ];
}

The footnote matters. Buyers over-read a single forward-collision field as verified AEB. Show the sourced token; if blank, say "not provided" -- no greyed "Standard" and no invented braking claim.

Forbidden upgrades

Product pressure often asks for:

1. Mapping any non-empty ForwardCollisionWarning into "AEB included"
2. Inventing IIHS / Euro NCAP / star-equivalent crash-avoidance language from the catalog field
3. Bundling ForwardCollisionWarning with other ADAS keys into "Full Collision Prevention"
4. Defaulting blank ForwardCollisionWarning to "Standard" so mid-trim cars look complete
5. Renaming catalog tokens into OEM suite marketing names you did not source

Refuse those. If you show other ADAS catalog fields from separate sourced keys, show each on its own row. Never invent AEB or package language inside the ForwardCollisionWarning mapper.

export function assertNoFcwCrashInvent(moduleSource: string): void {
  const banned = [
    /aeb included/i,
    /automatic emergency braking/i,
    /iihs/i,
    /crash.?avoidance grade/i,
    /front crash prevention/i,
    /full collision prevention/i,
    /euro ncap/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(
        `ForwardCollisionWarning module must not invent crash grades: ${re}`,
      );
    }
  }
}

export type CardRow = { label: string; value: string };

export function cardRows(fields: {
  ForwardCollisionWarning?: string | null;
  AdaptiveCruiseControl?: string | null;
  PedestrianAutomaticEmergencyBraking?: string | null;
}): CardRow[] {
  const view = viewForwardCollisionWarning(fields);
  const out: CardRow[] = [];
  if (view.source === "missing") {
    out.push({
      label: "Forward collision warning",
      value: "not provided",
    });
  } else {
    out.push({
      label: "Forward collision warning",
      value: String(view.value),
    });
  }

  const acc = (fields.AdaptiveCruiseControl ?? "").trim();
  if (acc && !EMPTY.has(acc.toLowerCase())) {
    out.push({ label: "Adaptive cruise (vPIC)", value: acc });
  }
  const paeb = (fields.PedestrianAutomaticEmergencyBraking ?? "").trim();
  if (paeb && !EMPTY.has(paeb.toLowerCase())) {
    out.push({
      label: "Pedestrian AEB catalog (vPIC)",
      value: paeb,
    });
  }
  return out;
}

Keep neighboring catalog fields on their own labeled rows. Never concatenate them into "Full Collision Prevention Package," and never treat a separate pedestrian-AEB catalog key as proof that ForwardCollisionWarning implies braking.

UI copy that stays honest

Prefer:

• "Forward collision warning (vPIC): Standard"
• "Forward collision warning: not provided by vPIC for this VIN"
• A short footnote: catalog token, not an AEB or crash-avoidance grade

Avoid:

• "IIHS Front Crash Prevention Superior -- verified"
• "AEB Standard included"
• Grey placeholders that look like real forward-collision data when the field was empty

Quick checks

import assert from "node:assert/strict";

assert.equal(viewForwardCollisionWarning({}).source, "missing");
assert.deepEqual(
  forwardCollisionLines(viewForwardCollisionWarning({})),
  ["Forward collision warning: not provided by vPIC for this VIN"],
);

const std = viewForwardCollisionWarning({
  ForwardCollisionWarning: "Standard",
});
assert.equal(std.value, "Standard");
assert.ok(
  forwardCollisionLines(std).some((l) =>
    /not an AEB or crash-avoidance/i.test(l),
  ),
);
assert.ok(
  !forwardCollisionLines(std).some((l) =>
    /iihs|aeb included|collision prevention package/i.test(l),
  ),
);

const rows = cardRows({
  ForwardCollisionWarning: "",
  AdaptiveCruiseControl: "Standard",
  PedestrianAutomaticEmergencyBraking: "Standard",
});
assert.ok(
  rows.some(
    (r) =>
      r.label.includes("Forward collision") && r.value === "not provided",
  ),
);
assert.ok(rows.some((r) => r.label.includes("Adaptive cruise")));
assert.ok(rows.some((r) => r.label.includes("Pedestrian AEB")));
assert.ok(!rows.some((r) => /iihs|aeb included/i.test(r.value)));

Review rule: forward-collision modules must not contain AEB-upgrade or crash-avoidance-grade phrases except in forbidding tests. Never upgrade a blank into "Standard."

Takeaway

ForwardCollisionWarning is a catalog token. Display it with clear sourcing, allow "not provided," and never use it as a key into invented AEB claims, IIHS crash-avoidance grades, or "full collision prevention" bundles. Your free VIN UI stays trustworthy when forward-collision data is either a real vPIC value with a modest footnote -- or absent -- and crash-avoidance marketing lives somewhere else, clearly labeled, or not at all.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/showing-forwardcollisionwarning-from-vpic-without-inventing-crash-avoidance-grades-1dj7

This post is about honest display: show SeatBeltType when vPIC provides it, refuse restraint-package inventing, and allow a clean "not provided" state when the field is empty. Keep seat-belt catalog values separate from airbag locations, pretensioner marketing, and crash-test grades. A sourced token is still only a token: it does not prove belts are installed correctly, unmodified, or undamaged on the listed vehicle. (Airbag location honesty is a separate topic; here the focus is SeatBeltType alone.)

What SeatBeltType is (and is not)

SeatBeltType is a catalog attribute associated with the VIN decode. It answers a narrow question: which seat-belt type token did the decode associate with this pattern?

It does not answer:

• Whether the vehicle earned an IIHS or NHTSA star rating
• Whether a dealer "Premium Restraint Package" or OEM suite name is equipped
• Pretensioner health, load-limiter status, or aftermarket belt changes
• Whether belts work today or were replaced after an incident
• A composite "restraint completeness" score built from missing neighboring fields

Empty SeatBeltType does not authorize a default "3-Point" badge, and a positive token does not mean "premium restraint package verified." Do not fill gaps from Make/Model/Year folklore or a chart keyed only by model year.

Normalize empties, do not invent packages

Treat blank, "Not Applicable", "N/A", and similar tokens as missing. Keep a sourced string when present; do not rewrite it into "Premium Restraint Package" or an IIHS-style grade.

const EMPTY = new Set([
  "",
  "not applicable",
  "n/a",
  "na",
  "null",
  "none",
  "unknown",
]);

export type SeatBeltTypeView = {
  value: string | null;
  source: "vpic" | "missing";
};

export function viewSeatBeltType(fields: {
  SeatBeltType?: string | null;
}): SeatBeltTypeView {
  const raw = (fields.SeatBeltType ?? "").trim();
  if (!raw || EMPTY.has(raw.toLowerCase())) {
    return { value: null, source: "missing" };
  }
  return { value: raw, source: "vpic" };
}

export function seatBeltTypeLines(view: SeatBeltTypeView): string[] {
  if (view.source === "missing") {
    return [
      "Seat belt type: not provided by vPIC for this VIN",
    ];
  }
  return [
    `Seat belt type (vPIC): ${view.value}`,
    "Catalog token only -- not a restraint package or crash-grade claim",
  ];
}

The footnote matters. Buyers over-read a belt token as a verified safety suite. Show the sourced value; if blank, say "not provided" -- no greyed "3-Point Standard" and no invented package name.

Forbidden upgrades

Product pressure often asks for:

1. Mapping any non-empty SeatBeltType into "Premium Restraint Package"
2. Inventing IIHS / Euro NCAP / star-equivalent language from belt catalog fields
3. Bundling SeatBeltType with airbag location fields into "Full Restraint Suite"
4. Defaulting blank SeatBeltType to "3-Point" so mid-trim cars look complete
5. Renaming catalog tokens into OEM restraint marketing names you did not source

Refuse those. If you show airbag or other restraint catalog fields from separate sourced keys, show each on its own row. Never invent a package name inside the SeatBeltType mapper.

export function assertNoRestraintPackageInvent(
  moduleSource: string,
): void {
  const banned = [
    /premium restraint/i,
    /restraint package/i,
    /iihs/i,
    /5-star equivalent/i,
    /full restraint suite/i,
    /euro ncap/i,
  ];
  for (const re of banned) {
    if (re.test(moduleSource)) {
      throw new Error(
        `SeatBeltType module must not invent restraint packages: ${re}`,
      );
    }
  }
}

export type CardRow = { label: string; value: string };

export function cardRows(fields: {
  SeatBeltType?: string | null;
  AirBagLocFront?: string | null;
  AirBagLocSide?: string | null;
}): CardRow[] {
  const view = viewSeatBeltType(fields);
  const out: CardRow[] = [];
  if (view.source === "missing") {
    out.push({
      label: "Seat belt type",
      value: "not provided",
    });
  } else {
    out.push({
      label: "Seat belt type",
      value: String(view.value),
    });
  }

  const front = (fields.AirBagLocFront ?? "").trim();
  if (front && !EMPTY.has(front.toLowerCase())) {
    out.push({ label: "Front airbag loc (vPIC)", value: front });
  }
  const side = (fields.AirBagLocSide ?? "").trim();
  if (side && !EMPTY.has(side.toLowerCase())) {
    out.push({ label: "Side airbag loc (vPIC)", value: side });
  }
  return out;
}

Keep airbag locations on their own labeled rows. Never concatenate belts with airbags into "Premium Restraint Package."

UI copy that stays honest

Prefer:

• "Seat belt type (vPIC): Manual"
• "Seat belt type: not provided by vPIC for this VIN"
• A short footnote: catalog token, not a restraint package claim

Avoid:

• "Premium Restraint Package verified"
• "IIHS Good -- belt system complete"
• Grey placeholders that look like real belt data when the field was empty

Quick checks

import assert from "node:assert/strict";

assert.equal(viewSeatBeltType({}).source, "missing");
assert.deepEqual(
  seatBeltTypeLines(viewSeatBeltType({})),
  ["Seat belt type: not provided by vPIC for this VIN"],
);

const manual = viewSeatBeltType({ SeatBeltType: "Manual" });
assert.equal(manual.value, "Manual");
assert.ok(
  seatBeltTypeLines(manual).some((l) =>
    /not a restraint package/i.test(l),
  ),
);
assert.ok(
  !seatBeltTypeLines(manual).some((l) =>
    /premium|iihs|full restraint/i.test(l),
  ),
);

const rows = cardRows({
  SeatBeltType: "",
  AirBagLocFront: "1st Row (Driver and Passenger)",
  AirBagLocSide: "1st Row (Driver and Passenger)",
});
assert.ok(
  rows.some(
    (r) =>
      r.label.includes("Seat belt") && r.value === "not provided",
  ),
);
assert.ok(rows.some((r) => r.label.includes("Front airbag")));
assert.ok(rows.some((r) => r.label.includes("Side airbag")));
assert.ok(!rows.some((r) => /premium restraint|iihs/i.test(r.value)));

Review rule: seat-belt modules must not contain restraint-package marketing phrases except in forbidding tests. Never upgrade a blank into "3-Point."

Takeaway

SeatBeltType is a catalog token. Display it with clear sourcing, allow "not provided," and never use it as a key into invented premium restraint packages, crash grades, or bundled airbag suites. Your free VIN UI stays trustworthy when seat-belt data is either a real vPIC value with a modest footnote -- or absent -- and restraint marketing lives somewhere else, clearly labeled, or not at all.

I maintain VIN Lookup, a free VIN decode based on NHTSA data.

Originally published on DEV: https://dev.to/vin_lookup_8dbd4710f77e9e/displaying-seatbelttype-from-vpic-without-inventing-restraint-package-claims-5dnc