docs(binding,docs): clarify .singleton() with .toInstance() behavior in docs and API

- Add an explicit note and warning about the effect (or lack thereof) of calling `.singleton()` after `.toInstance()`:
  - in singleton() API doc-comment in binding.dart,
  - in README.md (after all binding usage patterns),
  - in full_tutorial_en.md and full_tutorial_ru.md.
- Explain that `.singleton()` has no effect on objects registered with `.toInstance()` — they are always single instance.
- Recommend `.singleton()` only for providers (toProvide/toProvideAsync), not direct instances.
- Improves clarity and prevents misuse/confusion for end users and future maintainers.
This commit is contained in:
Sergey Penkovsky
2025-09-08 10:46:20 +03:00
parent b5b672765e
commit 484061148d
4 changed files with 35 additions and 0 deletions

View File

@@ -107,6 +107,14 @@ final api = scope.resolve<ApiClient>(named: 'mock');
- `.singleton()` — single instance per Scope lifetime
- By default, every resolve creates a new object
> **Note about `.singleton()` and `.toInstance()`:**
>
> Calling `.singleton()` after `.toInstance()` does **not** change the bindings behavior: the object passed with `toInstance()` is already a single, constant instance that will be always returned for every resolve.
>
> It is not necessary to use `.singleton()` with an existing object—this call has no effect.
>
> `.singleton()` is only meaningful with providers (such as `toProvide`/`toProvideAsync`), to ensure only one instance is created by the factory.
### Parameterized bindings
Allows you to create dependencies with runtime parameters, e.g., a service for a user with a given ID: