packages/riverpod/CHANGELOG.md (1)

9-10: Clarify API change with signature and snippet

Recommend documenting the exact signature change and a tiny example for discoverability.

Apply this diff:

-- Made `Mutation.call` generic.
-  This allows for better compatibility with generic-returning functions (thanks to @TekExplorer)
+- Made `Mutation.call` generic: `call<ChangedT extends ResultT>(Object? key) -> Mutation<ChangedT>`.
+  This enables refining a mutation's result type at the call site (thanks to @TekExplorer).
+  Example:
+  ```dart
+  final save = Mutation<Object?>();
+  // Narrow the result type for this keyed usage:
+  final saveUser = save.call<User>(userId);
+  ```

packages/riverpod/lib/src/core/mutations.dart (3)

336-346: Doc grammar fix (“These are”)

Minor wording polish.

-  /// This are passed using [call].
+  /// These are passed using [call].

---

599-601: Doc typo (“You can also”)

Minor typo.

-/// You cam also manually reset a mutation to its initial state using
+/// You can also manually reset a mutation to its initial state using

---

411-413: Soundness of _key parent type is fine given covariance, but add an assertion

At runtime, a mismatched parent would be catastrophic. Add a debug assert to ensure this is the parent when creating keyed instances.

 MutationImpl<ChangedT> call<ChangedT extends ResultT>(Object? key) {
-  return MutationImpl<ChangedT>._keyed((key, this), label: label);
+  assert(() {
+    // Sanity: parent must be `this`.
+    final parent = this;
+    return parent is Mutation<Object?>;
+  }());
+  return MutationImpl<ChangedT>._keyed((key, this), label: label);
 }

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/riverpod/test/feature/mutation_test.dart (2)

41-44: Close subscriptions to avoid lingering listeners.

Not required for correctness here, but closing them is cleaner and mirrors typical usage.

Apply this diff after the last expect:

@@
-    expect(subDouble.read(), isMutationSuccess<double>(3.14));
+    expect(subDouble.read(), isMutationSuccess<double>(3.14));
+    sub.close();
+    subInt.close();
+    subDouble.close();

---

35-38: Tighten the comment wording.

Clarify intent: it’s about instance equality when generic and key match.

Apply this diff:

-    // shows that using the same generic
-    // with the same key will get the correct value
+    // Using the same generic and the same key yields the same mutation instance

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/riverpod/lib/src/core/mutations.dart (1)

519-526: Equality currently blocks cross-generic keyed equality; consider ignoring type parameter in == for keyed instances

As written, operator == requires other is MutationImpl<ResultT> and _matchesT, so two keyed mutations with the same (parent, key) but different ChangedT won’t be equal. This undermines the idea of “refining” the same keyed mutation across types (e.g., mut<num>('k') vs mut<int>('k')), and may fragment caches/observers keyed by the mutation.

Proposed change (keyed instances equal by (parent,key) regardless of generic; unkeyed fallback remains identity):

-  bool _matchesT(Mutation<Object?> other) => other is Mutation<ResultT>;
+  // No longer needed if equality ignores generic for keyed instances.

   @override
   bool operator ==(Object other) {
-    if (other is! MutationImpl<ResultT> || !other._matchesT(this)) return false;
-    if (_key != null) return _key == other._key;
+    if (identical(this, other)) return true;
+    if (other is! MutationImpl) return false;
+    if (_key != null) return _key == (other as MutationImpl)._key;
 
     return super == other;
   }

No change needed to hashCode since it already derives from _key when present.

Note: To fully share provider instances across refined generics, _MutationProvider.operator == may also need to drop its generic constraint:

-  @override
-  bool operator ==(Object other) {
-    return other is _MutationProvider<ValueT> && mutation == other.mutation;
-  }
+  @override
+  bool operator ==(Object other) {
+    return other is _MutationProvider && mutation == other.mutation;
+  }

If the intended design is to keep refined generics distinct, please confirm and we can drop this suggestion and add docs/tests clarifying the behavior.

website/docs/concepts2/mutations.mdx (3)

40-48: Keyed mutation example: consider showing the watch/run flow

The snippet defines a keyed mutation instance but doesn’t illustrate how to listen/run it. Adding one line clarifies usage.

 final removeTodo = Mutation<void>();
-final removeTodoWithId = removeTodo(todo.id);
+final removeTodoWithId = removeTodo(todo.id);
+// Later in a widget:
+final state = ref.watch(removeTodoWithId);
+// And when triggering:
+removeTodoWithId.run(ref, (tsx) async { /* ... */ });

---

50-61: Grammar and casing tweaks; tighten example prose

• “api” → “API”
• “such as if” → “such as when”

-Sometimes, these mutations have a generic return type,
-such as if an api response may have different response types
+Sometimes, these mutations have a generic return type,
+such as when an API response may have different response types
 based on the input parameters.

---

65-68: Wording nit: “our choice” → “your choice”

Minor tone fix in user-facing docs.

-For this, we will need a <Link documentID="concepts2/refs" /> and pick a listening method of our choice
+For this, we will need a <Link documentID="concepts2/refs" /> and pick a listening method of your choice
 (typically [Ref.watch]).

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

website/docs/concepts2/mutations.mdx (1)

52-52: Nice: snippet extracted and inlined via raw-loader

This addresses the prior request to externalize code samples for compilation safety.

website/docs/concepts2/mutations/listening.dart (1)

24-27: Verify WidgetStatePropertyAll vs MaterialStatePropertyAll compatibility

WidgetStatePropertyAll requires newer Flutter. If your min Flutter SDK is older, ButtonStyle.backgroundColor expects MaterialStateProperty<Color?>. Consider this fallback.

-            backgroundColor: switch (addTodoState) {
-              MutationError() => const WidgetStatePropertyAll(Colors.red),
-              _ => null,
-            },
+            backgroundColor: switch (addTodoState) {
+              MutationError() => const MaterialStatePropertyAll(Colors.red),
+              _ => null,
+            },

website/docs/concepts2/mutations.mdx (4)

18-25: Polish punctuation and stray character

Remove the extra “!” and fix spacing before the semicolon.

-![Submit progress indicator](/img/concepts2/mutations/spinner.gif)!
+![Submit progress indicator](/img/concepts2/mutations/spinner.gif)

-...with UI concerns ; and it involves a lot of boilerplate code
+...with UI concerns; and it involves a lot of boilerplate code

---

69-72: Tighten wording and capitalization

Use API (caps) and avoid the duplicated “such as”.

-Sometimes, these mutations have a generic return type,
-such as if an api response may have different response types
-based on the input parameters, such as with deserialization.
+Sometimes, these mutations have a generic return type,
+for example when an API response varies based on input parameters,
+such as during deserialization.

---

87-89: Clarify: run is an instance method

The narrative suggests passing a mutation to a static function. It’s invoked on the instance.

-To trigger a mutation, we can use [Mutation.run], pass our mutation, and provide an asynchronous callback
+To trigger a mutation, call [Mutation.run] on your instance (e.g., addTodo.run) and provide an asynchronous callback

---

153-161: Confirm doc version pinning

All API links are pinned to 3.0.0‑dev.17. If the dev tag bumps, these will stale. Consider using latest or a shared version constant if that matches project conventions.

-[MutationPending]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/experimental_mutation/MutationPending-class.html
+[MutationPending]: https://pub.dev/documentation/riverpod/latest/experimental_mutation/MutationPending-class.html
...
-[Ref.watch]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/riverpod/Ref/watch.html
+[Ref.watch]: https://pub.dev/documentation/riverpod/latest/riverpod/Ref/watch.html

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

website/docs/concepts2/mutations.mdx (1)

5-12: Snippets extracted and imported correctly; listener path fix looks good

The raw-loader imports point to dedicated .dart snippets, and the previous listener.dart → listening.dart issue is resolved.

Run to verify snippet files exist and imports match:

#!/bin/bash
set -euo pipefail
base="website/docs/concepts2/mutations"
for f in listening.dart keyed.dart generic.dart triggering.dart switching.dart resetting.dart; do
  test -f "$base/$f" || { echo "Missing: $base/$f"; exit 1; }
done
# Ensure imports reference the exact filenames
rg -nP $'^import\\s+\\w+\\s+from\\s+\\\'raw-loader!\\./mutations/(listening|keyed|generic|triggering|switching|resetting)\\.dart\\\';$' website/docs/concepts2/mutations.mdx

website/docs/concepts2/mutations/triggering.dart (2)

45-45: Fix typo in comment.

-          // We perform a perform request using a Notifier.
+          // We perform a request using a Notifier.

---

35-54: Optionally await run to avoid re-entrancy and surface errors.

Making onPressed async and awaiting run helps prevent double-taps during pending and propagates exceptions to Flutter’s error handler.

-    return ElevatedButton(
-      onPressed: () {
+    return ElevatedButton(
+      onPressed: () async {
         // Trigger the mutation, and run the callback.
         // During the callback, we obtain a MutationTransaction (tsx) object
         // which we can use to access providers and perform operations.
-        addTodo.run(ref, (tsx) async {
+        await addTodo.run(ref, (tsx) async {
           // We use tsx.get to access providers within mutations.
           // This will keep the provider alive for the duration of the operation.
           final todoNotifier = tsx.get(todoNotifierProvider.notifier);
 
-          // We perform a perform request using a Notifier.
+          // We perform a request using a Notifier.
           final createdTodo = await todoNotifier.addTodo('Eat a cookie');
 
           // We return the created todo. This enables our UI to show information
           // about the created todo, such as its ID/creation date/etc.
           return createdTodo;
         });
       },

website/docs/concepts2/mutations/generic.dart (1)

42-48: Return the created value to showcase generic return types.

Returning the CreatedResponse from executeCreateTodo better demonstrates the new generic capability.

-Future<void> executeCreateTodo(MutationTarget ref) async {
-  await createTodo.run(ref, (tsx) async {
+Future<CreatedResponse<Todo>> executeCreateTodo(MutationTarget ref) async {
+  return await createTodo.run(ref, (tsx) async {
     final client = tsx.get(apiProvider);
     final response = client.post('/todos', data: {'title': 'Eat a cookie'});
     return CreatedResponse<Todo>.fromJson(response.data, Todo.fromJson);
   });
 }

website/docs/concepts2/mutations.mdx (5)

57-57: Specify code language for proper syntax highlighting

Add language="dart" to CodeBlock.

-<CodeBlock>{trimSnippet(listener)}</CodeBlock>
+<CodeBlock language="dart">{trimSnippet(listener)}</CodeBlock>

---

59-76: Tighten phrasing, fix capitalization, and add code language; minor copyedits

• Capitalize “API”.
• Remove repetition (“such as … such as”).
• Minor grammar/punctuation.
• Add language="dart" to CodeBlock elements.

-### Scoping a mutation
+### Scoping a mutation
@@
-Sometimes, you may want to have multiple instances of the same mutation.
+Sometimes, you may want multiple instances of the same mutation.
@@
-This can include things like an id, or any other parameter that makes the mutation unique.
+This can include an ID or any other parameter that makes the mutation unique.
@@
-This is useful if you want to have multiple instances of the same mutation,
-such as deleting a specific item in a list
+This is useful when you want multiple instances of the same mutation,
+such as deleting a specific item in a list.
@@
-Simply call the mutation with the unique key:
+Call the mutation with a unique key:
@@
-<CodeBlock>{trimSnippet(keyed)}</CodeBlock>
+<CodeBlock language="dart">{trimSnippet(keyed)}</CodeBlock>
@@
-Sometimes, these mutations have a generic return type,
-such as if an api response may have different response types
-based on the input parameters, such as with deserialization.
+Sometimes, mutations have a generic return type. For example, an API response
+may deserialize into different types based on the input parameters.
@@
-<CodeBlock>{trimSnippet(generic)}</CodeBlock>
+<CodeBlock language="dart">{trimSnippet(generic)}</CodeBlock>

---

85-85: Add language to CodeBlock

Consistent highlighting across snippets.

-<CodeBlock>{trimSnippet(triggering)}</CodeBlock>
+<CodeBlock language="dart">{trimSnippet(triggering)}</CodeBlock>

---

97-97: Add language to CodeBlock

-<CodeBlock>{trimSnippet(switching)}</CodeBlock>
+<CodeBlock language="dart">{trimSnippet(switching)}</CodeBlock>

---

110-110: Add language to CodeBlock

-<CodeBlock>{trimSnippet(resetting)}</CodeBlock>
+<CodeBlock language="dart">{trimSnippet(resetting)}</CodeBlock>

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

website/docs/concepts2/mutations.mdx (2)

5-12: Snippets extracted and imports wired correctly.

Raw-loader imports match the new .dart snippets. This addresses the earlier ask to extract snippets to dedicated files.

---

59-66: Good: new dedicated “Scoping a mutation” section placed under Listening.

This implements the earlier suggestion to move this content into its own section under “Listening to mutations.”

website/docs/concepts2/mutations.mdx (4)

23-24: Trailing “!” after image and awkward phrasing.

Remove the extra exclamation and tighten the sentence.

-In short, mutations are to achieve effects such as this:
-![Submit progress indicator](/img/concepts2/mutations/spinner.gif)!
+In short, mutations are used to achieve effects like this:
+![Submit progress indicator](/img/concepts2/mutations/spinner.gif)

---

27-29: Fix punctuation spacing.

There should be no space before a semicolon.

-state of your provider with UI concerns ; and it involves a lot of boilerplate code
+state of your provider with UI concerns; and it involves a lot of boilerplate code

---

72-75: Clarify wording and capitalize API; reduce repetition.

“Simplify” the sentence and reflect the new ability to refine generics at call-site.

-Sometimes, these mutations have a generic return type,
-such as if an api response may have different response types
-based on the input parameters, such as with deserialization.
+Sometimes, these mutations have a generic return type. For example, an API response may vary based on input parameters (deserialization), and you can refine the mutation’s generic at the call-site accordingly.

---

112-120: Prefer /latest docs links and add a link for Mutation.call.

Hardcoding dev.17 makes the page stale quickly. Switch to /latest and add the missing [Mutation.call] reference to match the new feature.

-[MutationPending]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/experimental_mutation/MutationPending-class.html
-[MutationError]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/experimental_mutation/MutationError-class.html
-[MutationSuccess]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/experimental_mutation/MutationSuccess-class.html
-[MutationIdle]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/experimental_mutation/MutationIdle-class.html
-[Mutation.reset]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/experimental_mutation/Mutation/reset.html
-[Mutation.run]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/experimental_mutation/Mutation/run.html
-[Mutation]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/experimental_mutation/Mutation-class.html
-[Notifier]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/riverpod/Notifier-class.html
-[Ref.watch]: https://pub.dev/documentation/riverpod/3.0.0-dev.17/riverpod/Ref/watch.html
+[MutationPending]: https://pub.dev/documentation/riverpod/latest/experimental_mutation/MutationPending-class.html
+[MutationError]: https://pub.dev/documentation/riverpod/latest/experimental_mutation/MutationError-class.html
+[MutationSuccess]: https://pub.dev/documentation/riverpod/latest/experimental_mutation/MutationSuccess-class.html
+[MutationIdle]: https://pub.dev/documentation/riverpod/latest/experimental_mutation/MutationIdle-class.html
+[Mutation.reset]: https://pub.dev/documentation/riverpod/latest/experimental_mutation/Mutation/reset.html
+[Mutation.run]: https://pub.dev/documentation/riverpod/latest/experimental_mutation/Mutation/run.html
+[Mutation.call]: https://pub.dev/documentation/riverpod/latest/experimental_mutation/Mutation/call.html
+[Mutation]: https://pub.dev/documentation/riverpod/latest/experimental_mutation/Mutation-class.html
+[Notifier]: https://pub.dev/documentation/riverpod/latest/riverpod/Notifier-class.html
+[Ref.watch]: https://pub.dev/documentation/riverpod/latest/riverpod/Ref/watch.html

Run a quick docs-link check to ensure /latest works across the site before merging.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.