docs(dependency injection): Add a section about ordering providers (#1218)

Co-authored-by: Jochum van der Ploeg <[email protected]>
Co-authored-by: Mayaa-s <[email protected]>
Co-authored-by: Alejandro Santiago <[email protected]>
Co-authored-by: Jochum van der Ploeg <[email protected]>

Author: 5 people

docs/docs/basics/dependency-injection.md

@@ -158,3 +158,100 @@ Middleware cachedAsyncGreetingProvider() {
 ```
 
 With the above implementations, the greeting will only be computed once and the cached value will be used for the duration of the application lifecycle.
+
+### Order matters
+
+In a real life application you will find yourself adding multiple `providers` to your project.
+
+Some `providers` **will depend** on others, as with any application relying on dependency injection.
+
+Let's take the example of a `Car` that depends on a `Wheel`.
+
+We will have two `providers` where the second one depends on the first one for it to work:
+
+1. A first `provider`, called `wheelMiddlewareProvider`, that creates the `Wheel` object
+
+```dart
+final _wheel = Wheel();
+
+/// Provides a [Wheel] instance.
+Middleware wheelMiddlewareProvider() {
+  return provider<Wheel>(
+    (_) => _wheel,
+  );
+}
+```
+
+2. A second `provider`, called `carMiddlewareProvider`, that provides a `Car` object
+
+```dart
+class Car {
+  final Wheel wheel;
+
+  Car({
+    required this.wheel;
+  });
+}
+
+/// Middleware to create the Car object
+Middleware carMiddlewareProvider() {
+  return provider<Car>(
+    (context) => Car(
+      wheel: context.read<Wheel>(),
+    ),
+  );
+}
+```
+
+At this point, it seems clear that `carMiddlewareProvider` depends on `wheelMiddlewareProvider`.
+
+When you try to access the instance of `Car` using `context.read<Car>()`, here is what will happen:
+
+1. _Dart Frog_ will try to create the instance and return it. To do so, it will create a `Car` object and to fulfill its `wheel` parameter
+2. It will "look above" in the dependency graph for a provider of `Wheel`
+3. It will find it with `wheelMiddlewareProvider`, and so on.
+
+This is how dependency injections works, but let's clarify what "look above" means.
+
+We have to tell Dart Frog how to build a `Wheel` **before** it builds a `Car`. We do that by defining the order of the providers.
+
+:::tip
+In Dart Frog, dependencies are resolved from **bottom** to **top**  
+:::
+
+So if provider `B` depends on provider `A`, you will have to declare them as followed:
+
+```dart
+Handler middleware(Handler handler) {
+  return handler
+      .use(B())
+      .use(A())
+}
+```
+
+In the example we gave at the beginning where `carMiddlewareProvider` depends on `wheelMiddlewareProvider` we know it will work when we provided them like so:
+
+```dart
+Handler middleware(Handler handler) {
+  return handler
+      .use(carMiddlewareProvider())
+      .use(wheelMiddlewareProvider())
+}
+```
+
+But if we change the order of the providers it will not work:
+
+```dart
+Handler middleware(Handler handler) {
+  return handler
+      // This won't work because Dart Frog is bottom top
+      .use(wheelMiddlewareProvider())
+      .use(carMiddlewareProvider())
+}
+```
+
+:::note
+Right now, there is an issue about this [fix: Improve dependency injection order #745](https://github.com/VeryGoodOpenSource/dart_frog/issues/745) because some other DI frameworks are working top to bottom and dart_frog is bottom to top.
+
+So you might want to keep that in mind for future releases, but as it would be a breaking change, the release version will reflect this.
+:::