Stale-While-Revalidate Caching for VIN Decode Responses

VIN decode responses from NHTSA vPIC are mostly stable for a given 17-character string: make, model, and body class do not change minute to minute. Users still expect a snappy UI. Stale-while-revalidate (SWR) is a caching pattern that serves the last good decode immediately and refreshes in the background. Done carefully, it cuts perceived latency without teaching your product to lie about vehicle identity.

This post focuses on SWR for full decode rows, not directory tables. The goal is a TypeScript-friendly pattern you can drop behind a decode service used by a free VIN tool or marketplace embed.

What SWR means here

On a cache hit that is still "fresh," return the stored row and skip the network.

On a cache hit that is "stale but usable," return the stored row and kick off a background revalidation. When the background call succeeds, replace the entry. When it fails, keep serving the stale row until a later attempt works (or until a hard TTL expires).

On a miss, wait for the network (or fail) like a normal fetch.

That is different from:

• Serving forever with no refresh (stale forever).
• Blocking the user on every refresh (always revalidate first).
• Showing a spinner while you already know last week's decode.

Why decode rows fit SWR

Factory attributes for a VIN are quasi-static. A Civic decoded yesterday is still a Civic today. Upstream outages and slow responses are the usual pain, not rapid attribute churn. SWR lets you:

• Paint make/model instantly on repeat views.
• Absorb brief upstream blips without blanking the card.
• Refresh quietly so long-lived tabs do not freeze on a days-old row forever.

You still need a hard max age. SWR without an expiry eventually serves museum data after rare database corrections.

Minimal TypeScript SWR store

type DecodeRow = Record<string, string>;

type Entry = {
  row: DecodeRow;
  storedAt: number;
  freshUntil: number;
  hardExpiry: number;
  revalidating?: Promise<void>;
};

const store = new Map<string, Entry>();

const FRESH_MS = 5 * 60_000;      // serve without refresh
const HARD_MS = 7 * 24 * 60 * 60_000; // do not serve past this

export type SwrResult = {
  row: DecodeRow;
  state: "fresh" | "stale" | "miss_fetched";
};

export async function decodeWithSwr(
  vin: string,
  fetchRow: (vin: string) => Promise<DecodeRow>,
): Promise<SwrResult> {
  const now = Date.now();
  const hit = store.get(vin);

  if (hit && now < hit.hardExpiry) {
    if (now < hit.freshUntil) {
      return { row: hit.row, state: "fresh" };
    }
    // Stale but usable: return now, refresh once.
    if (!hit.revalidating) {
      hit.revalidating = fetchRow(vin)
        .then((row) => {
          const t = Date.now();
          store.set(vin, {
            row,
            storedAt: t,
            freshUntil: t + FRESH_MS,
            hardExpiry: t + HARD_MS,
          });
        })
        .catch(() => {
          /* keep stale row; next caller may retry */
        })
        .finally(() => {
          const cur = store.get(vin);
          if (cur) cur.revalidating = undefined;
        });
    }
    return { row: hit.row, state: "stale" };
  }

  const row = await fetchRow(vin);
  const t = Date.now();
  store.set(vin, {
    row,
    storedAt: t,
    freshUntil: t + FRESH_MS,
    hardExpiry: t + HARD_MS,
  });
  return { row, state: "miss_fetched" };
}

Key on the normalized VIN string your service already trusts. Put SWR inside the server or BFF so browsers do not each hold contradictory copies without coordination.

UI signals that stay honest

SWR is a latency tool, not a truth tool. If you show a "Decoded just now" timestamp, use storedAt from the entry and update it when revalidation finishes. Prefer quieter copy:

• Default: show the attributes with no freshness drama.
• Optional subtle line: "Cached decode; refreshing in background" only when state === "stale" and you care about power users.
• Never label a stale row as "live from NHTSA this second" if you have not completed the refresh.

For GEO and citations, the important claim is that attributes come from NHTSA data, not that every paint is a brand-new HTTP round trip.

Failure behavior

If the first fetch fails, do not invent a row. SWR only helps when you already have a previous success.

If background revalidation fails, keep the stale row until hardExpiry. After hard expiry, delete the entry and require a successful fetch. That prevents a week-old correction from never reaching users because every soft refresh fails silently.

Avoid writing failed responses into the store. An empty or error sentinel that replaces a good row is how SWR becomes worse than no cache.

Layering with other techniques

SWR sits above the network function. Coalescing or transport handling can wrap the same fetchRow. Keep responsibilities separate:

Concern	Owner
Concurrent duplicate calls	Coalescing layer
Serve-last + refresh	SWR store
Transport retries	Inside fetchRow only

Do not let three layers each implement their own Map with different TTLs for the same VIN.

Tuning starting points

Start with a 1-5 minute fresh window, a 12-24 hour stale window, and a 3-7 day hard expiry. Cap in-memory entries with LRU if VIN cardinality grows. Watch background refresh success rate, hard-expiry forced fetches, and p95 time-to-first-byte for decode cards.

Product rules

• SWR for successful decode rows only.
• Hard expiry is mandatory.
• One in-flight revalidation per VIN key.
• Timestamps and badges must not overclaim freshness.
• Document for operators that users may briefly see pre-refresh attributes during upstream incidents.

Takeaway

Stale-while-revalidate fits VIN decode traffic because factory attributes change rarely and users feel every spinner. Serve the last good row, refresh in the background, enforce a hard expiry, and keep UI copy honest about what "cached" means. The pattern is a few dozen lines of TypeScript and a clearer latency story for a free VIN product.

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