Better docs about whether 'operator==' is necessary

[wujek-srujek]

As I was implementing reacting to partial state changes (see #564), I wrote a provider like this:

final timerStatusProvider =
    Provider.autoDispose.family<TimerStatus, Duration>(
  (ref, interval) => ref.watch(timerNotifierProvider(interval)).status,
);

and it all worked, i.e. my UI is rebuilt only the the status field changes. Nice, but at the same time, I was surprised (partially because it is so darn easy) - because I didn't have to do anything special, no filtering on my own. It turns out all of this is because operator== is involved, and status being an enum gets it for free.

I got back to the docs and couldn't find details anywhere, the next best thing is this sentence on watch:

Obtains the state of a provider and cause the state to be re-evaluated when that provider emits a new value.

But it isn't documented anywhere what a new value is, apparently it is something that returns false from operator==, but it is not explained, so it could be a new reference (to an otherwise structurally identical object). At the same time, it is explicitly stated that family parameters must implement operator==.

On the same note, I'm also using StateNotifier and as far as I know it also doesn't state what is required for a state change to be discovered. The next best thing is

Updating this variable will synchronously call all the listeners.

documented on the state property, but it fails to explain what 'updating' really means - just setting the property (even if the same reference), or setting it to a new reference, or setting to something that returns false for operator== (seriously, I don't even know the answer to this question, I will need to go back to my code and experiment).
(EDIT: in StateNotifier, it seems like setting the state property to anything, even the same reference, triggers a notification. This makes it pretty confusing as StateNotifier.state and states returned by Provider are on the opposite spectrum - set to anything, even the same reference vs set to something where operator== == false)

The answers to these questions may be obvious to someone with experience with StateNotifier and Riverpod, but maybe it is worth considering being very, very explicit in the documentation?

[larssn]

Hey 👋

(I realize this thread is a bit old).

I'm not sure what your question is exactly, but I can address this bit of confusion here:

Obtains the state of a provider and cause the state to be re-evaluated when that provider emits a new value.
But it isn't documented anywhere what a new value is

Remember that providers emit immutable values. If you have a Provider<SomeClass>, it will emit a new instance of that class. It will never emit the same instance, meaning you might need a custom equality check for that class. This is the new value mentioned. Providers behave similarly to Streams/Observables in that you listen to them, and expect them to sometimes emit a new value.

Your classes could implement Comparable, if you want transparent equality checks.

But yeah, not much documentation about it, it is briefly mentioned at the bottom of: https://riverpod.dev/docs/concepts/reading

[wujek-srujek]

I forgot what my question was about, but I guess it was about whether identity check (if it is the same instance) or operator == is used. There is a difference, albeit a minor one.