persist: Dexie migration Promises silently overwrite saved state with defaults

[Tnalxmsk]

Bug Description

In zustand@5.0.15, returning a Dexie Promise directly from persist's migrate callback can overwrite saved data with the initial defaults, even when the migration resolves successfully.

Steps to reproduce

1. Persist a state containing one draft at version 1.
2. Create the store with version 2, an initial state of { drafts: [] }, and partialize configured to persist drafts.
3. In migrate, return a Dexie database operation's Promise that resolves to the saved state.
4. Let automatic hydration run, then inspect storage and recreate the store.

Actual behavior

The stored record changes from:

{ "state": { "drafts": [{ "id": "1", "text": "My saved draft" }] }, "version": 1 }

to:

{ "state": { "drafts": [] }, "version": 2 }

Hydration reports no error. Because the version has advanced, recreating the store does not rerun the migration. No user edits or additional setState calls are needed to trigger the overwrite.

Expected behavior

Await the migration result before merging and persisting it. If migration rejects, preserve the original stored data and version and report the error.

Investigation

The migration branch checks migration instanceof Promise. Dexie Promises do not pass that check, so the unresolved Promise is treated as the migrated state. Wrapping the same operation in native Promise.resolve(...) preserves the data.

Dexie's PromiseExtended<T> extends Promise<T>, and this callback type-checks against Zustand's migrate type without a cast. A native Promise from another realm reproduces the same failure.

I verified this with dexie@4.4.5, including a real browser using IndexedDB and localStorage. The linked Node reproduction uses fake-indexeddb and fails an assertion on the published Zustand version.

Related context: #1505 discussed native Promise assumptions in a React Native mocking report, and #2827 covered an older ordinary async-migration regression. This reproduction demonstrates the Dexie/cross-realm data-loss path in 5.0.15; same-realm native Promises work correctly.

Fix prepared

I have prepared a fix and regression tests on this branch:

https://github.com/Tnalxmsk/zustand/tree/fix/persist-promise-migration

The fix preserves native Promise detection and recognizes other migration results through the fuller Promise interface (then, catch, finally, and a string Symbol.toStringTag) before awaiting them. It remains scoped to migration results.

The regression tests cover successful and rejected migrations, storage/version preservation, store recreation, and synchronous states containing ordinary actions named then, catch, or finally. Those synchronous states still hydrate immediately without invoking their actions. All 233 tests, type checks, lint, formatting, and build pass locally. I also verified the fix with actual Dexie operations in a browser using IndexedDB and localStorage.

One design trade-off for review: structural checks cannot distinguish a Promise from a state object that deliberately exposes the entire checked interface. This change does not add support for arbitrary then-only objects or change the other Promise checks in storage handling.

Since PR creation is currently limited to collaborators, could a maintainer open a PR from this branch? I'm happy to address review feedback.

Reproduction Link

https://github.com/Tnalxmsk/zustand/tree/e3f3c106dd60c1ee7a8d8bd7128cdc756345eb10/reproductions/persist-promise-migration

[dbritto-dev]

I feel that's on userland which means you need a custom storage

[Tnalxmsk]

Thanks for taking a look! To clarify, the reproduction uses synchronous storage through createJSONStorage. The Dexie Promise is returned only from migrate, not from a storage method.

In this reproduction, returning it directly overwrites saved data with defaults, while wrapping the same operation in native Promise.resolve(...) preserves the data.
Would handling this in userland mean wrapping the migration result, rather than providing custom storage?

[dai-shi]

I'm actually fine to use isPromiseLike instead of instanceof Promise, if that helps.
https://github.com/pmndrs/jotai/blob/89d4fddd1949628e50952fc8ac1b09786248dfca/src/vanilla/utils/atomWithStorage.ts#L5-L6

[Tnalxmsk]

Thanks! I verified that the Jotai-style check fixes the reported Dexie and cross-realm cases, and I'd be happy to simplify the patch to match.

One compatibility detail I wanted to check: a synchronous migrate returning { drafts, then: () => {} } currently hydrates normally, but the then-only check calls that action and leaves hydration pending.

My branch currently uses a stricter check to preserve that behavior, though it doesn't fully resolve the ambiguity. Would it be reasonable to treat any migration result with a callable then as a thenable here as well?

[dai-shi]

Sorry for the delay. Yes, as I understand, the contract of PromiseLike (or Thenable) is to treat an object having then function as a promise. So migrate returning { drafts, then: () => {} } is violating that contract. I think it's fair and more straightforward than arbitrary strict checks.

Could you update your branch?

[Tnalxmsk]

Updated the branch to use the Jotai-style isPromiseLike check for migration results, while keeping Promise.resolve for thenable assimilation. All tests and checks pass locally.

Thanks for clarifying the intended behavior!

[dai-shi]

#3583 is open