Suppose an AI assistant hands you a patch that swaps a value cache for a promise cache. Its summary promises three things: concurrent callers now share one read, failed reads are dropped so callers can retry, and invalidation forces a fresh read. The code is short and looks like code you’ve seen many times. It still breaks when events happen in one particular order.
Write down what the cache should do
“Improve caching” leaves every detail to whoever writes the code. For this review, the cache should follow five rules:
- Calls for the same key share one pending read.
- A successful result stays cached until it’s invalidated.
- A failed read doesn’t stick; the next call can try again.
- Invalidation removes the current entry, so the next call starts a new read.
- When an old, already-removed read finishes, it can’t remove or replace a newer entry.
Rule 4 only affects future lookups. It doesn’t cancel a read in progress or take back a value a caller is already waiting for. If your product needs every caller to see the newest data, this cache isn’t enough even with no bugs at all.
The cache key also has to include everything that changes the result. A file path may be enough for a local file loader; an HTTP cache might also need the user, their permissions, the query, or a revision.
The patch
If you cache the value only after await read(key), two calls that arrive together both miss and both read. Caching the in-flight promise fixes that. Add cleanup for failed reads and you get something like this:
function load(key) {
if (entries.has(key)) return entries.get(key);
const pending = Promise.resolve().then(() => read(key));
entries.set(key, pending);
void pending.catch(() => {
entries.delete(key);
});
return pending;
}
function invalidate(key) {
entries.delete(key);
}
The promise is stored before the read starts, so a second caller can share it. When the read fails, the handler deletes the key. But it deletes whatever is in that slot now, which isn’t necessarily the promise that failed.
Notice that invalidate didn’t change in this patch. Unchanged code is easy to skip in a review, and without it the new cleanup looks like routine error handling. The bug only shows up when you read the two functions together.
The order that breaks it
Call two reads of the same key A and B:
| Step | Event | Cache entry |
|---|---|---|
| 1 | First load(key) starts read A |
promise A |
| 2 | invalidate(key) runs |
absent |
| 3 | Second load(key) starts read B |
promise B |
| 4 | A fails; its cleanup deletes key |
absent |
| 5 | Third load(key) runs while B is pending |
promise C; duplicate read |
At step 4, the failed read deletes an entry that now belongs to B. In this example the visible damage is extra work: B and C read the same key at the same time. Don’t call it data corruption unless the real reader’s side effects could actually corrupt something.
The table also shows exactly what it takes to trigger the bug: an invalidation while a read is pending, a new lookup, and then the old read failing. A test that loads, invalidates, and loads again after everything has finished will never hit it.
The fix: check that the entry is still yours
Before deleting, check that the slot still holds the promise that failed:
export function createCache(read) {
const entries = new Map();
return {
load(key) {
if (entries.has(key)) return entries.get(key);
const pending = Promise.resolve().then(() => read(key));
entries.set(key, pending);
void pending.catch(() => {
if (entries.get(key) === pending) entries.delete(key);
});
return pending;
},
invalidate(key) {
entries.delete(key);
},
};
}
The identity check is the whole fix. A key being present doesn’t mean the entry is still yours; a newer request may have taken the slot. Checking entries.has(key) in the handler would still be wrong.
Two smaller details are worth knowing. Promise.resolve().then(() => read(key)) turns a synchronous throw from read into a rejected promise, and it guarantees the entry is stored before read runs. If your read is always async you can write this differently, but decide on purpose how sync errors and re-entrant calls should behave. Also, the cleanup hangs off a separate .catch(), so callers still get the original promise and still see the rejection. Turning failures into a fallback value would change the API, and that’s a separate decision.
Test it while the promises are pending
Control when each read settles with deferred promises instead of timers. This is the regression test that matters:
const old = cache.load('file');
const rejected = assert.rejects(old, /old read failed/);
await Promise.resolve(); // Let the injected reader start A.
cache.invalidate('file');
const current = cache.load('file');
await Promise.resolve(); // Let the injected reader start B.
a.reject(new Error('old read failed'));
await rejected;
const next = cache.load('file');
assert.equal(next, current);
a controls the first read; the full example also has a b for the second read and resolves it at the end. assert.rejects is attached before A is rejected, so the test doesn’t cause an unhandled rejection of its own.
Comparing promise identity works for this implementation, but count the underlying reads as well. Two wrapper promises can share one read, and two separate reads can return equal values. The rules ask for one read, not for one particular promise object.
Then cover the states around it:
| Test | What to assert |
|---|---|
| Two calls before completion | One underlying read; both callers receive the value |
| A later call after success | Cached value; no extra read |
| A failure followed by a new call | New read can succeed |
| Old failure after invalidation | Replacement remains cached |
| Old success after invalidation | Original caller gets old data; future callers keep new data |
| Synchronous reader failure | Rejection reaches the caller; retry remains possible |
The old-success row deserves a second look. This cache never writes to the map on success, so an invalidated read can’t put itself back when it resolves. Its own caller still receives the old value, though. Make sure that’s what you want.
Write a comment the author can check
A review comment for this bug might say:
The rejection handler deletes by key without checking whether the entry is still the promise that failed. If read A is invalidated while pending, read B gets cached, and then A rejects, A’s cleanup removes B. The next lookup starts a third read while B is still running, which breaks “one read per current entry.” Compare promise identity before deleting; the invalidate-then-reject test reproduces it.
It names the location, the trigger, the effect, and a test. How serious it is depends on the real callers: duplicate local file reads are a performance problem, while duplicate calls to a paid API cost money. Find out which before you assign a severity.
Also look at the base revision. If something was already broken before this patch, report it separately instead of blaming the new cleanup. And if the AI patch also reformatted files or bumped dependencies, ask why. Unrelated changes make the real behavior change harder to see.
For a local review, Yenpo’s Git diff viewer for Mac keeps a chosen commit or branch comparison available while you inspect the code around the patch.
Run it yourself
Download promise-cache.mjs and run it with Node.js 22 or later:
node --test promise-cache.mjs
One of the six tests is a reproduction: it passes when the unsafe version shows the bug. The other five check the fixed cache. The example keeps everything in memory and has no eviction, cross-process coordination, or cancellation. For a real patch you’d check those as well, along with the callers that build keys and call invalidate.
With Yenpo’s AI Reader, open a Git comparison and click “Ask AI to review this comparison.” Check the attached comparison, then replace the draft with a focused request:
Review this cache change. Find callers that can invalidate a pending read and start a replacement. Check whether the old read’s success or failure can affect the replacement entry. Cite the relevant code, show the triggering call order, and separate pre-existing issues from regressions.
Check that the callers can trigger the proposed order, then run the test in your terminal.
If a patch also edits the tests, review the assertions that changed alongside the implementation. A green result can hide a caller regression when an error check is replaced with a weaker condition.