Migrate legacy values to Zustand

[davor-bauk-sh]

It would be nice if the migrate handler in the persist middleware allowed migrating legacy values into a new Zustand store.

Let's say my app state depends on the following two values in AsyncStorage:

• foo: string
• bar: string

... and I set up a new store:

type AppStoreState = {
  readonly foo: string;
  readonly bar: string;
};

type AppStoreActions = {
  readonly setFoo: (foo: string) => void;
  readonly setBar: (bar: string) => void;
}

type AppStore = AppStoreState & AppStoreActions;

const INITIAL_APP_STATE: AppStoreState = {
  foo: 'Hello',
  bar: 'World',
};

I assumed that I could use the migrate handler to pull in legacy values into the store. In fact, this was suggested by both Claude and GPT.

However, the migrate handler only gets called if there is an existing stored state with a version different than the current one.
Also, the state doesn't seems to be saved to storage until it is mutated.

It would be cool if we could do something like this:

const useAppStore = create<AppStore>()(
  persist((set) => {
    ...INITIAL_APP_STATE,
    setFoo: (foo: string) => { set({ foo }); };
    setBar: (bar: string) => { set({ bar }); };
  }, {
    name: 'app-state',
    storage: createJSONStorage(() => AsyncStorage),
    version: 1,
    migrate: async (persistedState: unknown, version: number | undefined) => {
      if (version === undefined) {
        const legacyKeys = ['foo', 'bar'];

        const [fooPair, barPair] = await AsyncStorage.multiGet(legacyKeys); // returns ReadonlyArray<[string, string | null]>;
        await AsyncStorage.multiRemove(legacyKeys);

        const [_, foo] = fooPair;
        const [_, bar] = barPair;

        return {
          ...INITIAL_APP_STATE,
          ...(foo !== null ? { foo } : {}),
          ...(bar !== null ? { bar } : {}),
        } satisfies AppStoreState;
      }

      return persistedState;
    },
  });
);

I'm able to make it work with this patch:

diff --git a/node_modules/zustand/esm/middleware/persist.d.mts b/node_modules/zustand/esm/middleware/persist.d.mts
index 69da8d6..0c03cae 100644
--- a/node_modules/zustand/esm/middleware/persist.d.mts
+++ b/node_modules/zustand/esm/middleware/persist.d.mts
@@ -51,7 +51,7 @@ export interface PersistOptions<S, PersistedState = S, PersistReturn = unknown>
      * A function to perform persisted state migration.
      * This function will be called when persisted state versions mismatch with the one specified here.
      */
-    migrate?: (persistedState: unknown, version: number) => PersistedState | Promise<PersistedState>;
+    migrate?: (persistedState: unknown, version: number | undefined) => PersistedState | Promise<PersistedState>;
     /**
      * A function to perform custom hydration merges when combining the stored state with the current one.
      * By default, this function does a shallow merge.
diff --git a/node_modules/zustand/middleware.js b/node_modules/zustand/middleware.js
index 8c89320..74d426a 100644
--- a/node_modules/zustand/middleware.js
+++ b/node_modules/zustand/middleware.js
@@ -404,6 +404,13 @@ const persistImpl = (config, baseOptions) => (set, get, api) => {
           return [false, deserializedStorageValue.state];
         }
       }
+      if (options.migrate) {
+        const migration = options.migrate(undefined, undefined);
+        if (migration instanceof Promise) {
+          return migration.then((result) => [true, result]);
+        }
+        return [true, migration];
+      }
       return [false, void 0];
     }).then((migrationResult) => {
       var _a2;
diff --git a/node_modules/zustand/middleware/persist.d.ts b/node_modules/zustand/middleware/persist.d.ts
index 9bebf1a..14dbbf0 100644
--- a/node_modules/zustand/middleware/persist.d.ts
+++ b/node_modules/zustand/middleware/persist.d.ts
@@ -51,7 +51,7 @@ export interface PersistOptions<S, PersistedState = S, PersistReturn = unknown>
      * A function to perform persisted state migration.
      * This function will be called when persisted state versions mismatch with the one specified here.
      */
-    migrate?: (persistedState: unknown, version: number) => PersistedState | Promise<PersistedState>;
+    migrate?: (persistedState: unknown, version: number | undefined) => PersistedState | Promise<PersistedState>;
     /**
      * A function to perform custom hydration merges when combining the stored state with the current one.
      * By default, this function does a shallow merge.

If there is currently a better way to do this, I'd love to know about it!

[dai-shi]

Hi, thanks for reporting.

I wonder if this patch works for your case:

diff --git a/src/middleware/persist.ts b/src/middleware/persist.ts
index 5a2dfe5..8219646 100644
--- a/src/middleware/persist.ts
+++ b/src/middleware/persist.ts
@@ -101,7 +101,7 @@ export interface PersistOptions<
    */
   migrate?: (
     persistedState: unknown,
-    version: number,
+    version: number | undefined,
   ) => PersistedState | Promise<PersistedState>
   /**
    * A function to perform custom hydration merges when combining the stored state with the current one.
@@ -266,7 +266,7 @@ const persistImpl: PersistImpl = (config, baseOptions) => (set, get, api) => {
       .then((deserializedStorageValue) => {
         if (deserializedStorageValue) {
           if (
-            typeof deserializedStorageValue.version === 'number' &&
+            typeof options.version === 'number' &&
             deserializedStorageValue.version !== options.version
           ) {
             if (options.migrate) {