diff --git a/cherrypick/lib/src/binding.dart b/cherrypick/lib/src/binding.dart index c0e7e7e..c29011b 100644 --- a/cherrypick/lib/src/binding.dart +++ b/cherrypick/lib/src/binding.dart @@ -160,6 +160,38 @@ class Binding { /// ```dart /// bind().toInstance(ApiMock()); /// ``` + /// + /// **Important limitation:** + /// If you register several dependencies via [toInstance] inside a [`Module.builder`], + /// do _not_ use `scope.resolve()` to get objects that are also being registered during the _same_ builder execution. + /// All [toInstance] bindings are applied sequentially, and at the point of registration, + /// earlier objects are not yet available for resolve. + /// + /// **Correct:** + /// ```dart + /// void builder(Scope scope) { + /// final a = A(); + /// final b = B(a); + /// bind().toInstance(a); + /// bind().toInstance(b); + /// } + /// ``` + /// **Wrong:** + /// ```dart + /// void builder(Scope scope) { + /// bind().toInstance(A()); + /// bind().toInstance(B(scope.resolve())); // Error! A is not available yet. + /// } + /// ``` + /// **Wrong:** + /// ```dart + /// void builder(Scope scope) { + /// bind().toProvide(() => A()); + /// bind().toInstance(B(scope.resolve())); // Error! A is not available yet. + /// } + /// ``` + /// This restriction only applies to [toInstance] bindings. + /// With [toProvide]/[toProvideAsync] you may freely use `scope.resolve()` in the builder or provider function. Binding toInstance(Instance value) { _resolver = InstanceResolver(value); return this;