persist clearStorage can be followed by stale async hydration

[teamleaderleo]

Bug Description

With async storage, clearStorage() can run while rehydrate() is still pending. The item gets removed, but the older read can finish afterward and apply the value that was just cleared.

rehydrate() already uses hydrationVersion to discard stale hydration work. It seems like clearStorage() should advance that same generation.

Reproduction Link

https://github.com/teamleaderleo/zustand/blob/f3e46bdeef229ae00ea1dae1e2e9193e8b7ec1df/tests/persistClearStorageHydrationGeneration.test.ts#L18-L43

[latent-9]

Confirmed, this is a real race, and your diagnosis is exactly right. clearStorage() doesn't advance hydrationVersion, so an in-flight rehydrate() never gets invalidated and re-applies the value you just cleared.

Walking through src/middleware/persist.ts on main:

• hydrate() opens with const currentVersion = ++hydrationVersion, then reads storage asynchronously. Every continuation after the await guards itself with if (currentVersion !== hydrationVersion) return, which is the mechanism that lets a newer rehydrate() cancel an older, still-pending one.
• clearStorage() is only:

  clearStorage: () => {
    storage?.removeItem(options.name)
  },

  It removes the item but leaves hydrationVersion untouched.

So with async storage the interleaving is:

1. rehydrate() runs: currentVersion = N, hydrationVersion = N, and getItem() is in flight and has already read the old value.
2. clearStorage() runs: the item is removed from storage, but hydrationVersion stays N.
3. The in-flight getItem() resolves with the old value. The guard checks N !== N, which is false, so it does not bail and calls set(merge(oldValue, ...)), re-applying the cleared state in memory.

The one-line fix is to make clearStorage() bump the generation, mirroring what hydrate() already does:

clearStorage: () => {
  ++hydrationVersion // invalidate any in-flight rehydrate
  storage?.removeItem(options.name)
},

After that, any hydration that was already running hits its next currentVersion !== hydrationVersion check and bails, so it can't overwrite the cleared state.

Two notes: this only affects async storage, since with synchronous storage the getItem() resolves before clearStorage() can interleave, so there's no window. And it's the in-memory store state that gets re-applied; the storage entry itself is genuinely removed. The change matches the existing invalidation pattern, so it'd make a clean PR.

[dai-shi]

Thanks! Could you check #3555?

[teamleaderleo]

I think package-lock.json was accidentally committed? Other than that, LGTM! 💸

[latent-9]

Yes, that is the fix. Bumping hydrationVersion inside clearStorage makes the pending rehydrate see the newer version and discard its result, so the stale async read no longer writes the cleared value back. The test covers the race nicely. Looks good to me.

[dai-shi]

Thank you guys! Nice catch about package-lock.json.

[latent-9]

Looks correct to me. It lands exactly where the race is: clearStorage() now advances hydrationVersion, so any rehydrate() that is already past its getItem() await hits currentVersion !== hydrationVersion on its next check and bails instead of writing the cleared value back.

Two details the PR gets right that are easy to miss:

• The bump happens before removeItem, so an in-flight hydration is still invalidated even if removeItem throws. The removal-throws test covers that ordering directly.
• It also invalidates the async migrate() continuation, not only the getItem() one, since both go through the same version guard.

Test coverage looks solid: stale getItem, stale migrate, removeItem throwing, clear-after-hydration leaving live state intact, and the onRehydrateStorage/onFinishHydration suppression. Nothing else reads hydrationVersion, so bumping it here has no other side effects.

LGTM.