Add combining_request page

website/docs/essentials/combining_requests.mdx

@@ -1,30 +1,135 @@
 ---
-title: Combining requests (WIP)
+title: Combining requests
 version: 1
 ---
 
-:::note
-This page is a work in progress
+import { Link } from "../../src/components/Link";
+import { AutoSnippet } from "../../src/components/CodeSnippet";
+import functionalRef from "./combining_requests/functional_ref";
+import notifierRef from "./combining_requests/notifier_ref";
+import watchExample from "./combining_requests/watch_example";
+import watchPlacement from "./combining_requests/watch_placement";
+import listenExample from "./combining_requests/listen_example";
+import readExample from './combining_requests/read_example'
+
+Up till now, we've only seens cases were requests are independent from each
+other. But a common use-case is to have to trigger a request based on the
+result of another request.
+
+We _could_ be using the <Link documentID="essentials/passing_args" /> mechanism to
+do that, by passing the result of a provider as parameter to another a provider.
+
+But this approach has a few downsides:
+
+- This leaks implementation details.
+  Now, your UI needs to know about all the providers that are used
+  your other provider.
+- Whenever the parameter change, a brand new state will be made.
+  By passing parameters, there are no way to keep the previous state
+  when the parameter changes.
+- It makes combining requests harder.
+- This makes tooling less useful. A devtool wouldn't
+  know about the relationship between providers.
+
+To improve this, Riverpod offers a different approach to combine requests.
+
+## The basics: Obtaining a "ref"
+
+All possible ways of combining requests have one thing in common:
+They are all based on the `Ref` object.
+
+The `Ref` object is an object which all providers have access to.
+It grants them access to various life-cycle listeners, but also
+various methods to combine providers.
+
+The place where `Ref` can be obtained depends on the type of provider.
+
+In functional providers, the `Ref` is passed as parameter to the
+provider's function:
+
+<AutoSnippet {...functionalRef} />
+
+In class variants, the `Ref` is a property of the Notifier class:
+
+<AutoSnippet {...notifierRef} />
+
+## Using ref to read a provider.
+
+## The `ref.watch` method.
+
+Now that we've obtained a `Ref`, we can use it to combine requests.
+The main way to do so is by using `ref.watch`.  
+It is generally recommended to architecture your code such that you
+can use `ref.watch` over other options, as it is generally easier to maintain.
+
+The `ref.watch` method takes a provider, and returns its current state.
+Then, whenever the listened provider changes, our provider will be
+invalidated and rebuilt next frame or on next read.
+
+By using `ref.watch`, your logic becomes both "reactive" and "declarative".  
+Meaning that your logic will automatically recompute when needed.
+And that the update mechanism doesn't rely on side-effects, such as an "on change".
+This is similar to how StatelessWidgets behave.
+
+As an example, we could define a provider that listens to the user's location.
+Then, we could use this location to fetch the list of restaurants near the user.
+
+<AutoSnippet {...watchExample} />
+
+:::info
+When the listened provider changes and our request recomputes, the previous
+state is kept until the new request completes.  
+At the same time, while the request is pending, the "isLoading" and "isReloading"
+flags will be set.
+
+This enables UI to either show the previous state, or a loading indicator,
+or even both.
 :::
 
-- [ ] Mention that some network requests may depend on the result of
-      other requests. For example, a request to get the list of cities
-      near the user would depend on a request to get the user's location.
+:::caution
+It is considered bad practice to call `ref.watch` inside code that is executed
+"imperatively". Meaning any code that is possibly not executed during the build
+phase of the provider. This includes "listener" callbacks or methods on Notifiers:
+
+<AutoSnippet {...watchPlacement} />
+:::
+
+## The `ref.listen`/`listenSelf` methods.
+
+The `ref.listen` method is an alternative to `ref.watch`.  
+It is similar to your traditional "listen"/"addListener" method. It takes a provider
+and a callback, and will invoke said callback whenever the content of the provider
+changes.
 
-- [ ] Mention that there are two primary ways to combine requests:
+Refactoring your code such thar you can use `ref.watch` instead of `ref.listen`
+is generally recommended, as the latter is more error-prone due to its imperative nature.  
+But `ref.listen` can be helpful to add some quick logic without having to do
+significant refactor.
 
-  - [ ] `ref.watch` - declarative approach, will automatically recompute the request on change
-    - [ ] Mention that this is the recommended approach due to simplified error handling
-          & automatic recomputation.
-  - [ ] `ref.listen` - imperative approach, will invoke a listener when the result changes.
-        It is then up to the listener to perform changes, such as maybe calling `ref.state=`.
-    - [ ] Link Provider migration guide, to showcase how using ref.listen
-          can be used to migrate ProxyProviders to Riverpod
+We could rewrite the `ref.watch` example to use `ref.listen` instead
 
-- [ ] A `ref` is always available when defining a provider:
-  - it is either passed as parameter to the provider's function
-  - or it is a property of the Notifier class.
+<AutoSnippet {...listenExample} />
 
-- Explain how if an async provider refreshes with ref.watch, its previous state is kept
-  until the new state is available, but under "isReloading: true".
-  If the provider rebuildt with ref.invalidate/refresh, then isRefreshing will be true instead.
+:::info
+It is entirely safe to use `ref.listen` during the build phase of a provider.
+If the provider somehow is recomputed, previous listeners will be removed.
+
+Alternatively, you can use the return value of `ref.listen` to remove the listener
+manually when you wish.
+:::
+
+## The `ref.read` method.
+
+The last option available is `ref.read`.
+It is similar to `ref.watch` in that it returns the current state of a provider.
+But unlike `ref.watch`, it doesn't listen to the provider.
+
+As such, `ref.read` should be only be used in placed where you can't use
+`ref.watch`, such as inside methods of Notifiers.
+
+<AutoSnippet {...readExample} />
+
+:::caution
+Be careful when using `ref.read` on a provider as, since it doesn't listen to the
+provider, said provider may decide to destroy its state if it isn't listened.
+:::

website/docs/essentials/combining_requests/functional_ref/codegen.dart

@@ -0,0 +1,18 @@
+// ignore_for_file: unused_local_variable
+
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+part 'codegen.g.dart';
+
+@riverpod
+int other(OtherRef ref) => 0;
+
+/* SNIPPET START */
+@riverpod
+int example(ExampleRef ref) {
+  // "Ref" can be used here to read other providers
+  final otherValue = ref.watch(otherProvider);
+
+  return 0;
+}
+/* SNIPPET END */

website/docs/essentials/combining_requests/functional_ref/index.ts

@@ -0,0 +1,4 @@
+import raw from '!!raw-loader!./raw.dart';
+import codegen from '!!raw-loader!./codegen.dart';
+
+export default { raw, codegen };

website/docs/essentials/combining_requests/functional_ref/raw.dart

@@ -0,0 +1,14 @@
+// ignore_for_file: unused_local_variable
+
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+final otherProvider = Provider<int>((ref) => 0);
+
+/* SNIPPET START */
+final provider = Provider<int>((ref) {
+  // "Ref" can be used here to read other providers
+  final otherValue = ref.watch(otherProvider);
+
+  return 0;
+});
+/* SNIPPET END */

website/docs/essentials/combining_requests/listen_example/codegen.dart

@@ -0,0 +1,17 @@
+// ignore_for_file: unused_local_variable, avoid_print
+
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+part 'codegen.g.dart';
+
+final otherProvider = Provider<int>((ref) => 0);
+
+/* SNIPPET START */
+@riverpod
+int example(ExampleRef ref) {
+  ref.listen(otherProvider, (previous, next) {
+    print('Changed from: $previous, next: $next');
+  });
+
+  return 0;
+}

website/docs/essentials/combining_requests/listen_example/index.ts

@@ -0,0 +1,4 @@
+import raw from '!!raw-loader!./raw.dart';
+import codegen from '!!raw-loader!./codegen.dart';
+
+export default { raw, codegen };

website/docs/essentials/combining_requests/listen_example/raw.dart

@@ -0,0 +1,13 @@
+// ignore_for_file: unused_local_variable, avoid_print
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+final otherProvider = Provider<int>((ref) => 0);
+
+/* SNIPPET START */
+final provider = Provider<int>((ref) {
+  ref.listen(otherProvider, (previous, next) {
+    print('Changed from: $previous, next: $next');
+  });
+
+  return 0;
+});

website/docs/essentials/combining_requests/notifier_ref/codegen.dart

@@ -0,0 +1,21 @@
+// ignore_for_file: unused_local_variable
+
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+part 'codegen.g.dart';
+
+@riverpod
+int other(OtherRef ref) => 0;
+
+/* SNIPPET START */
+@riverpod
+class Example extends _$Example {
+  @override
+  int build() {
+    // "Ref" can be used here to read other providers
+    final otherValue = ref.watch(otherProvider);
+
+    return 0;
+  }
+}
+/* SNIPPET END */

website/docs/essentials/combining_requests/notifier_ref/index.ts

@@ -0,0 +1,4 @@
+import raw from '!!raw-loader!./raw.dart';
+import codegen from '!!raw-loader!./codegen.dart';
+
+export default { raw, codegen };

website/docs/essentials/combining_requests/notifier_ref/raw.dart

@@ -0,0 +1,19 @@
+// ignore_for_file: unused_local_variable
+
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+final otherProvider = Provider<int>((ref) => 0);
+
+/* SNIPPET START */
+final provider = NotifierProvider<MyNotifier, int>(MyNotifier.new);
+
+class MyNotifier extends Notifier<int> {
+  @override
+  int build() {
+    // "Ref" can be used here to read other providers
+    final otherValue = ref.watch(otherProvider);
+
+    return 0;
+  }
+}
+/* SNIPPET END */