Three caches answer a barcode scan, and the only one with an expiry has nothing to do with speed
Scanning is the one thing in Munchable that has to feel instant. You are standing in a shop holding a packet, you point the camera at the barcode, and the answer about whether that product suits you should already be the
Scanning is the one thing in Munchable that has to feel instant. You are standing in a shop holding a packet, you point the camera at the barcode, and the answer about whether that product suits you should already be there. Everything else in the app can take a moment. This cannot.
So the scan path has three caches and a de-duplicator in front of one network call. They look like one optimisation. They are four different decisions, and only the first is about speed.
Layer 1: a Map, read synchronously
Products resolved during this session live in a plain Map, and the scan path peeks at it synchronously. No await, no storage round trip, no state update. Scan the same packet twice while comparing two brands on a shelf and the second scan costs nothing at all.
The peek has one rule that took a bug to find:
export function peekProduct(barcode: string): ResolvedProduct | undefined {
const hit = resolved.get(barcode) ?? resolved.get(normalizeBarcode(barcode));
if (!hit || hit.source === 'session') return undefined;
return hit;
}
Entries marked source: 'session' are deliberately invisible here. They come from a label the server could not save: the result screen can still show you what it read, but Munchable does not have that product. Scanning that barcode again has to go back to the server, get a 404, and send you to the camera for a fresh capture.
The first version of the peek returned those entries, so rescanning a pack whose capture had just failed to save landed on the stale device-only result instead of the "we do not have this one yet" flow. A cache that holds something the system does not consider real is worse than no cache, because the user cannot tell the difference and the app can.
It also never falls back to the bundled sample catalog that exists for local development, because the scan path has to behave identically in development and in production. A sample barcode colliding with a real pack must not shadow a real lookup.
Layer 2: the device cache, and the only expiry in the system
The app keeps resolved products in storage, originally so the Recent list survived a restart. Answering a scan out of that store is a different promise, and it is the only place in this codebase with a time limit:
const SCAN_CACHE_MAX_AGE_MS = 60 * 60 * 1000;
That hour is not a performance number. Removing it would make the app faster, not slower.
It is there because Munchable's data is corrected continuously. An unbounded device cache means a row that has since been fixed, or withdrawn, keeps being served forever on any device that scanned that barcode once. The hour is a ceiling on how long a correction can go unseen: one hour of use, not one install.
The round trip is also the only thing that carries the data version header, which is how a device learns its ingredient knowledge is behind. I wrote about that version in our data version is one number. A scan that never asks is a scan that never finds out it is stale, so an infinite cache would quietly freeze a device's knowledge as well as its data.
And one class of row is never served from this layer at all. Community-contributed rows carry a trust status that other people's reports can demote between one scan and the next, so those always go back to the server. Serving a withheld row out of a device cache is precisely the failure that withholding exists to prevent. Rows that are curated data, which does not move between scans, are the ones this layer answers, and the tap-to-open screen was already serving them from the same store, so reading them here adds no trust surface the app did not already have.
Picking an hour is also sized against what this layer is actually for. Repeat scans inside one session are already free from layer 1. All this layer adds is the person who restarts the app partway through a shop and rescans the same pack. An hour covers that comfortably.
Layer 3: single flight, and why it is not just a Map of promises
A camera does not read a barcode once. It reads it on every frame it can, so a steady hand on one packet produces a burst of identical reads. Without de-duplication that is one request per frame.
const scanLookups = singleFlight<ResolvedProduct | null>();
The implementation is about thirty lines and three of its decisions are load-bearing:
const tracked = work.finally(() => {
if (inFlight.get(key) === tracked) inFlight.delete(key);
});
inFlight.set(key, tracked);
return tracked;
The tracked promise is what goes in the map and what callers get, not the raw one. Every joiner then waits on the same promise the cleanup is attached to, so there is no window where one caller holds a promise that has already been forgotten.
The slot is only cleared if it is still this run's. Nothing in the app replaces a live entry today. A future caller that wanted to restart a run would, and the alternative to that identity check is a de-duplicator that silently stops de-duplicating, which is the worst kind of bug in this file: everything works, just N times.
A synchronous throw out of the start function never enters the map. It was never in flight, so there is nothing to register and nothing to clean up.
The fourth decision: speculating, with a cap of three
The scanner arms a code before the user has confirmed anything, and the app starts the lookup right then. The confirmed scan later joins that exact promise, which is the whole trick: a stability hold followed by a round trip becomes a stability hold with the round trip running underneath it.
The speculative path is allowed exactly one effect, and the comment says so:
Fire and forget by design: the ONLY effect it is allowed to have is that
`scanProduct` for the same code answers faster.
It does not count a scan, does not read or spend quota, and does not navigate. All of those live in one confirm path that runs once per confirmed product. A prefetch that lands after the user has walked away has filled a cache entry nobody reads, which costs nothing.
There is a cap of three in flight, and the reason is the device rather than the server:
const MAX_SPECULATIVE_LOOKUPS = 3;
Panning a camera across a shelf arms a different code every time the scanner catches one, and each would speculate. React Native's fetch shares a small connection pool, so a dozen requests nobody asked for sit ahead of the one for the pack the user is actually holding, and the optimisation becomes a regression. Three covers the realistic case of a code re-armed once or twice while somebody steadies their hand.
One last line that looks like noise and is not:
void scanLookups.run(code, () => resolveForScan(code)).catch(() => {});
Nothing awaits a prefetch, and every joiner of a rejected single-flight run is handed the rejection. Without that catch, a dropped connection in a shop with bad signal surfaces as an unhandled rejection warning for a request the user never made.
What the layers add up to
Written out as the order a scan actually travels:
- session map, synchronous, free, ignores anything not considered real,
- single-flight map, so a burst of frames and the speculative prefetch are one request,
- device cache, for rows that do not move, up to an hour old,
- the server.
Four layers, and three of them exist for correctness rather than latency. That ratio surprised me when I wrote it down. The instinct with a cache is to ask how much time it saves; most of the work here went into deciding what each layer is not allowed to answer, because a wrong answer delivered instantly is worse than a right answer after 300ms when the subject is whether a food is going to make somebody ill.
The app is at munchable.app, the plain-English version of how it decides anything is at munchable.app/about under "How a verdict is decided", and the conditions it covers are at munchable.app/conditions. The web pages at munchable.app/answers answer the same questions for people who are reading at home rather than standing in an aisle, which is the one case where none of this plumbing matters at all.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.