Breaking change introduced in 4.5.5 by changing the default behaviour

[vitorsilvalima]

Bug Description

In previous versions of Zustand (up to version 4.5.4), the default state would automatically persist in the storage (e.g., AsyncStorage in React Native) even if it had never changed. This behavior was crucial in ensuring that the app retained its initial state after a restart, which helped maintain consistency.

However, after updating to version 4.5.5, I've noticed that the default state is no longer persisted at all. Upon app restarts, the default state keeps resetting, causing significant issues in production. This change in the default behavior of Zustand is breaking expected functionality in my React Native application, leading to data inconsistency and unexpected behavior.

I believe this might be an unintended regression or change in the library's persistence mechanism, and I would appreciate any clarification or fix for this issue.

Steps to reproduce:

Use Zustand version 4.5.5 in a React Native app with AsyncStorage for persistence.
Define a default state in the store.
Restart the app without manually changing the state.
Observe that the default state does not persist across restarts.

Expected behavior: The default state should persist in storage, as it did in version 4.5.4 and earlier, unless explicitly modified by the user.

Actual behavior: The default state is not persisted in storage after app restarts, causing it to reset.

Environment:

Zustand version: 4.5.5

Example:

import AsyncStorage from '@react-native-async-storage/async-storage'
import { SafeAreaView, Text } from 'react-native'
import { v4 as uuidv4 } from 'uuid'
import { create } from 'zustand'
import { createJSONStorage, persist } from 'zustand/middleware'

export const useDeviceId = create(
  persist(
    () => ({
      id: uuidv4().toString(),
    }),
    {
      name: 'testing-id',
      storage: createJSONStorage(() => AsyncStorage),
    },
  ),
)

const App = () => {
  const { id } = useDeviceId()

  return (
    <SafeAreaView>
      <Text>current id: {id}</Text>
    </SafeAreaView>
  )
}

export default App

Reproduction Link

4.5.4: https://stackblitz.com/edit/zustand-persist-behavior-4-5-4?file=src%2Fmain.tsx
4.5.5: https://stackblitz.com/edit/zustand-persist-behavior-4-5-5?file=src%2Fmain.tsx

[vitorsilvalima]

version 4.5.4:

Screen.Recording.2024-09-30.at.19.00.24.mov

version 4.5.5:

Screen.Recording.2024-09-30.at.19.00.01.mov

[dai-shi]

Thanks for reporting.
This is an intentional change with #2678 to fix the reported bug in #2663.
It feels like the requirement is conflicting. @double-thinker what do you think?

Meanwhile, to get the previous behavior, I think this workaround would do:
https://stackblitz.com/edit/zustand-persist-behavior-4-5-5-fgvz6e?file=src%2Fmain.tsx

[double-thinker]

Nice catch, @vitorsilvalima!

I did not consider scenarios where the default value needed to be stored. However, I'm not sure if both requirements are conflicting. #2663 could be fixed with another implementation since the problem I was trying to avoid there was persisting an already persisted state. Storing internally a flag to keep track of which values were retrieved and which ones were set should be sufficient to accommodate both requirements, at a cost: default values will always be persisted even when it's not necessary.

Before that, I want to add a few additional thoughts about the semantics that could be considered here before going in any direction. Regarding storage, we can take two approaches:

First, zustand could assume storage transaction cost is negligible (because it's assumed to always be local storage), so my commit could be rolled back and/or storing default values is not a problem.

Alternatively, no property of the storage is assumed, so storage saves should be minimized. Then we can consider: a) implementing another fix like the one I suggested before that reduces some (not all) duplicated saves; b) keeping this as a breaking change. Option b feels wrong to me, and I think breaking changes should be avoided where possible, but this depends on the semantics zustand will follow.

Another consideration is what should be the behavior for impure getters, like this example where a randomized value is initialized? Should we consider them monads/atoms and the getter should be pure/stable so persist should ignore the initial state? I'm no expert on the flux pattern and the ecosystem, but I suggest we mimic what is expected in the "average" mental model of flux.

In my experience with pure atom models, I handle non-pure, randomized values by adding initialization as a separate step, similar to the workaround by @dai-shi . However, zustand's semantics more closely resemble flux/centralized store approaches, so my mental model may not be idea herel. Additionally, always persisting default values could be expensive for non local storage, depending on the use case.

Since, as far as I know, persist lacks an explicit mechanism for defining initial value behavior, I propose another alternative: introduce a new flag, such as persistDefaultValue. This could default to true for backward compatibility or false to optimize storage costs.

I can dedicate some time to this and submit another PR based on what you think is the best approach.

[vitorsilvalima]

As both a developer and a consumer of the library, I agree that breaking changes within the same major version are generally unexpected and can be difficult to diagnose—especially in production environments where debugging is more challenging. In fact, this particular issue initially appeared to be related to AsyncStorage, which caused some confusion before we traced it back to the change in the persist behavior.

Given the importance of maintaining backward compatibility, introducing a persistDefaultValue property seems like an excellent approach. If we default this property to true, it would preserve existing behavior for most users while giving those concerned with storage efficiency the flexibility to opt out. This way, we avoid unnecessary breaking changes and ensure smoother transitions between versions.

[dai-shi]

I'm not sure if both requirements are conflicting.

To me, it is kind of conflicting if a new option is required.

We are about to release v5, so it's a good timing to introducing the breaking change.
We should probably release v4.5.6 reverting #2678, meanwhile. (Or, just add a warning in the release note.)
As for persistDefaultValue, we would like to collect more feedback. (FYI: we don't use true as default, if that's the case, we invert the option.)

[double-thinker]

Makes a lot of sense. When is v5 planned?

To me, it is kind of conflicting if a new option is required.

Sorry, I wasn't clear. The solution that could fix both issues in a non-conflicting way is to keep track of which values are simply retrieved from storage, so persist doesn't save them back again (fixing #2663), and to save the defaults as in 4.5.4 (fixing this bug) without requiring extra configuration.

However, given that the v5 release is approaching, I don't think it's worth developing this solution now. Instead, as you suggested, v5 could implement the breaking change, either by reapplying #2678 or by implementing persistDefaultValue or its inverse.

[dai-shi]

Sorry, I wasn't clear.

Oh, I see.

However, given that the v5 release is approaching, I don't think it's worth developing this solution now.

Okay, I'll add a warning in the 4.5.5 release note, and v5 migration guide. We should be releasing v5 soon.

[KiwiKilian]

Another critical bug caused by this behavior change might be #2827.