[RFC]: Unified syntax for providers, without code-generation

[rrousselGit]

With the death of macros, I've been thinking a lot on the future of Riverpod.

There are two common complaints with Riverpod:

• Too many options
• or it requires codegen

Those are two sides of the same coin. Many users aren't satisfied with the API.
The API issue impacts other areas too. For example, documentations are in a bad state in large part because there are too many things to cover.
With that in mind, I've been experimenting on how to solve this issue over the years. And I think I'm ready to share a possible new syntax for Riverpod.

The problems

Before showing the new syntax, I'd like to list a few problems that we're trying to solve here. If you think one of them is missing, make sure to leave a comment!

1. There are too many types of providers.
   No need to explain anything. We all know what this is about.

2. family's syntax without code-generation is bad.
   We are currently limited with a single required positional parameter. No optional ones. No default values. No named parameters. No generics.
   Codegen fixes this. But codegen is slow.

3. Updating a provider is needlessly complex.
   We currently have to write ref.read(provider.notifier).method(). We can probably do simpler.

4. We need a way to define "mutations" without codegen
   Support query mutation #1660 was implemented some time, but it requires code-generation. It was a good decision at the time. But that assumed we'd be getting macros.
   We should be able to use the feature without codegen.

5. Rebuilding an asynchronous provider can cause a pointless "loading" frame.
   A common question is "how to skip loading during a rebuild".
   Believe it or not, this is a Dart issue. It is caused by the async keyword and relying on future.then.

Dart lacks a way to have an async function that synchronously emits a value. Flutter has SynchronousFuture as workaround, but it's full of bugs (since Dart's compiler is definitely not expecting that!)

There are some solutions though ; by changing the syntax around async a bit.

6. family required passing parameters everywhere, and this gets tedious.
   One common complaint with family is having to pass the args all the time. We can use scoping to solve this, but scoping is way too hard!

Which leads us to:
7) Scoping is too hard!
Having to specify dependencies is too much. And more often than not, it's just used to inject a few values anyway.

Proposal: A single Provider class

Here's a cheatsheet of the new syntax

Simple synchronous provider

This is unchanged

final repositoryProvider = Provider((ref) => UserRepository());
...
UserRepository repo = ref.watch(repositoryProvider);

Simple asynchronous provider

This is the equivalent to FutureProvider

final currentUser = AsyncProvider((ref) async {
  final user = /* fetch from http */
  return user;
});
...
AsyncValue<User> user = ref.watch(currentUser);
Future<User> user = ref.watch(currentUser.future);

Emitting a stream instead of a Future

The old "StreamProvider" is fused with "FutureProvider"

final currentUser = AsyncProvider((ref) async {
  Stream<User> user = /* use websockets */
  ref.emit(user); // A way to emit Streams
});
...
AsyncValue<User> user = ref.watch(currentUser);
Future<User> user = ref.watch(currentUser.future);

Note: The async keyword is optional.
Note: async* is not supported anymore. We are not returning a Stream.
This is by design. async* as always been problematic in Riverpod anyway. It is one of the main cause of unnecessary AsyncLoading.

Making a provider mutable.

The concept of "notifier" is gone. Instead, we rely on "Mutations" from #1660.
Custom providers can now be made by subclassing Provider<T>.
We could rewrite the previous examples as so:

class RepositoryProvider with Provider<UserRepository> {
  @override
  UserRepository build(ref) => UserRepository();
}
final repositoryProvider = RepositoryProvider();

...
UserRepository repo = ref.watch(repositoryProvider);

class UserProvider with AsyncProvider<User> {
  @override
  Future<User> build(ref) async {
    final user = /* fetch from http */
    return user;
  }
}
final currentUser = UserProvider();

...
AsyncValue<User> user = ref.watch(currentUser);
Future<User> user = ref.watch(currentUser.future);

Once that's done, we can add mutations as properties of our provider:

class UserProvider with AsyncProvider<User?> {
  // A simple function which renames the user
  Call<Future<void>> rename({String? firstName}) =>
      run((ref) async {
          /* call `ref.state = AsyncData(...)` as usual */
      });

  /* define build like in the previous snippets */
}
final currentUser = UserProvider();
...
Future<void> result = ref.invoke(currentUser.rename(firstName: 'John'));

As you can see:

• We can define functions inside providers ; which can modify the current state
• Since those functions aren't in a notifier anymore, we don't need a redundant .notifier to access the function

Note:
Calling currentUser.rename(...) without passing the result to ref.invoke does nothing.
The run callback only executes when using ref.invoke.
Note:
run is @protected. As such, you shouldn't be able to mutate providers in a way they don't intend without a warning in the IDE.

Listening to side-effects in the UI

We've only shown how to update providers.
For #1660, we need something extra: The ability to listen to side-effects

For that, we can slightly tweak the previous example:

class UserProvider with AsyncProvider<User?> {
  // We define some "key" in the provider for side-effects ; which the UI can listen to.
  late final renameMut = mutation<void>();
  Call<Future<void>> rename({String? firstName}) =>
      // Instead of `run((ref) => ...)` we use `mutate(mutation, (ref) => ...)`
      mutate(renameMut, (ref) async {
        /* update the user as usual */
      });

  /* define build as usual */
}
final currentUser = UserProvider();
...
// Calling `rename()` hasn't changed:
Future<void> result = ref.invoke(currentUser.rename(firstName: 'John'));
// We can now listen to `rename` side-effects with:
MutationState<void> rename = ref.watch(currentUser.renameMut);
switch (mutationState) {
  case IdleMutationState():
  case PendingMutationState():
  case ErrorMutationState(:final error):
  case SuccessMutationState(:final result);
}

Family / Passing arguments to our provider

There's no more a distinction between family and normal providers.
Instead, we keep subclassing Provider, and we pass parameters to our class constructor:

class ProductProvider with AsyncProvider<List<Product>> {
  ProductProvider({this.search = ''});
  final String search;

   // When passing arguments, we need to override `args` and list them.
  // This is similar to overriding == on the provider.
  @override
  Record get args => (search,);

  // We can still define mutations/methods.
  // When defining mutations, we have to pass a unique symbol
  late final addAllToCartMut = mutation<void>(#addAllToCart);
  Call<Future<void>> addAllToCart() => /* same as before */  

  @override
  Future<List<Product>> build(ref) async {
    final response = await http.get('https://my-api.com?search=$search');
    /* decode response */
  }
}
...
AsyncValue<List<Product>> homeProducts = ref.watch(ProductProvider());
AsyncValue<List<Product>> searchedProducts = ref.watch(ProductProvider(search: 'jeans'));

// We can update providers using the same syntax as before:
ref.invoke(ProductProvider().addAllToCart());
ref.invoke(ProductProvider(search: '').addAllToCart());

// We can listen to mutations too:
MutationState<void> addAllToCart = ref.watch(ProductProvider(...).addAllToCartMut);

Note:
All kinds of parameters work. And you can pass as many as you want. Just make sure to list them in args.
Note:
A lint rule will be offered to warn in case a property is defined and args doesn't list it.

Note:
If your app is using code-generation, you can use your typical data-class package to override == instead of writing args.
As such, you could do:

@freezed
class ProductProvider with AsyncProvider<...>, _$ProductProvider {
  ProductProvider({this.search = ''});
  final String search;
  // no need to override `args`
}

Passing around parameter providers

We still rely on scoping here. But scoping is revised!

class ProductProvider with AsyncProvider<List<Product>> {
  // We define a way to scope the provider
  static final fallback = Scope.required<ProductProvider>();
  /* same as before */
}


// The UI can override said scope:
ProviderScope(
  overrides: [
    ProductProvider.fallback.overrideWithValue(ProductProvider(search: 'food')),
  ],
);


// Widgets can now listen to the provider without having to specify args:
@override
Widget build(BuildContext context, WidgetRef ref) {
  final productProvider = ref.watch(ProductProvider.fallback);
  AsyncValue<List<Product>> products = ref.watch(productProvider);
  // Of course, we could listen/start mutations too!
}

Note:
Scope can only be listened inside Consumer. Providers cannot listen to Scope, and ref.watch(P.fallback) will then result in a compilation error.

About the new syntax

That's a lot of new information, I know.

The TL:DR is:

• We only have a single Provider
• It supports both sync and async code
• Provider can be subclassed to define methods/properties
• family is now just as simple as defining a constructor on our Provider subclass.
  This enables support for default values, named parameters, ...
• Updating the state of our provider is done by defining methods in our Provider subclass.
• The UI now has a way to listen to side-effects
• None of this requires code-generation.
• ref.read(provider.notifier).method() is simplified to ref.invoke(provider.method())
• Scoping providers is significantly dumbed down. Providers can't be scoped anymore, and we instead have to use a Scope object.

And most importantly:
A migration tool will be provided. I need one to migrate my codebases anyway 😛
And the new syntax will be shipped as a 2.x.0 version, alongside the old syntax, in a non-breaking way. So both syntaxes can coexist while you migrate.

This should solve most concerns with Riverpod's syntax.

There are still some small inconveniences, like having to override args when specifying parameters on a provider. Or having to pass #myMutation to mutation(...) when the provider receives parameters.

These should be minor inconveniences though.

• Overriding args is similar to what you'd do using Equatable for ==.
• The #myMutation symbol is a very small amount of boilerplate, and the linter + asserts will catch any mistake.

Still, some question remains:

• Would you be satisfied with this syntax?
• Is this in your opinion a big enough improvement to warrant the breaking change?
• Would it be acceptable to ask codegen users to migrate to this new syntax too?

[benthillerkus]

Looks nice, especially ref.read(provider.notifier).method() -> ref.invoke(provider.method()) is clean.

But I need some help understanding:

class UserProvider with Provider<AsyncValue<User>> {
  @override
  late final create = async((ref) async {
    final user = /* fetch from http */
    return ref.setData(user);
  });
}

Why are these defined as late member variables instead of as methods? What is this working around :) ?

And what does the return do? Does it return some metadata coming from ref.setData? Or is it an alternative way of setting state?

I'm also curious why the mutation keys are needed. What's happening internally that requires this?

[EmixamZ]

Hi @rrousselGit ,
Many thanks for your work on Riverpod.
I think this is going the right way...

I don't know if it's intentional but it looks more and more like TanStack Query, which is a good thing IMO.

[rrousselGit]

@benthillerkus

Why are these defined as late member variables instead of as methods? What is this working around :) ?

create is a variable instead of a method because of sync vs async having a different prototype.
We'd need SyncProvider vs AsyncProvider otherwise.
Which then requires SyncRef vs AsyncRef. And which then requires a new generic on Mutation and other interfaces to specify the Ref.

Things would be simpler if providers were always asynchronous 🤷

And what does the return do? Does it return some metadata coming from ref.setData? Or is it an alternative way of setting state?

The sole purpose of return is there to require you to initialise your provider.
Otherwise you could forget to setup a data. Besides this, the return value is useless.

The main goal of using ref.setData() is that it solves the "unnecessary isLoading" by making mutations execute synchronously instead of having to wait for Future.then.

It's the most "optional" part of the proposal. We could easily stick to the same syntax as with FutureProvider.
We'd keep the problem with redundant isLoading though.

[rrousselGit]

For create, one alternative I looked into was:

class Foo with Provider<int> {
  @override
  ProviderHandle<int> create() =>
     async((ref) => ...);
}

That's pretty much the same thing as what's in the issue, but as a method instead of a field.

The main challenge is that this enables folks to write code before Riverpod converts errors into AsyncErrors:

class Foo with Provider<int> {
  @override
  ProviderHandle<int> create() {
    throw Exception("Oopsy, I'm not caught by Riverpod");
    return ProviderHandle.async((ref) => throw Exception('Here is safe though!'));
  }
}

Using late final create = async((ref) => ...) solves the issue. And it's a small amount of boilerplate reduction, which is nice (but the syntax is a bit odd though)

[saavy1]

FWIW as a codegen user

Would you be satisfied with this syntax?

yes, it'd make my ilfe with defining custom mixins so much easier, like SupabaseMixin and AuthMixin

Is this in your opinion a big enough improvement to warrant the breaking change?

also yes, especially if a migration tool launches with it

Would it be acceptable to ask codegen users to migrate to this new syntax too?

I can't speak for others, but I wouldn't have an issue with a migration for this

[dhafinrayhan]

Would it be possible to unify ProviderCall and MutationCall? This way, we will always define the method in the "mutation way", except if the user doesn't want to use mutation, he can simply not use it

[GP4cK]

Love the fact that we would have only one provider and unlimited parameters for families.

1. What about autoDispose? Is it correct to assume that it would be something like Provider.autoDispose.sync(...)?
2. What's the difference between IdleMutationState and PendingMutationState?

[maxfrees]

How will the notifier change?

[toufeeqahamedns]

Is it possible to hold ref in create variable and just do, create.setData() ? If possible, this would be more simpler.

class RepositoryProvider with Provider<UserRepository> {
  @override
  late final ref = sync((ref) => UserRepository());

  // A simple function which renames the user
  ProviderCall<Future<void>> rename({String? firstName}) {
      if (firstName != null) {
        var user = await ref.future; // We get the current state, like we'd do in Riverpod today. 
        user = user.copyWith(firstName: first Name);
        ref.setData(user); // We update the state. This is equivalent to `ref.state = AsyncData(user)`.
      }
  }
}

[tbm98]

Personally I find it too cumbersome and unnecessarily difficult for beginners. It should be simple and I accept build-runner