- Refactored and updated pages, router, DI modules, and feature implementations in both example projects:
- client_app: main.dart and my_home_page.dart updated for improved navigation and structure.
- postly: updated DI wiring, presentation pages, repository implementation, and routing logic.
- Applied small improvements and code consistency changes in the examples.
docs: add new documentation assets and benchmarking script
BREAKING CHANGE:
Examples now reflect the latest changes in the DI framework and are ready for Dart 3.8+ and cherrypick_generator element2 API compatibility.
- Fully migrated core cherrypick_generator and submodules to new analyzer element2 system:
- Updated all GeneratorForAnnotation overrides to use Element2, ClassElement2, MethodElement2, FieldElement2 and new annotation/metadata access patterns.
- Migrated signature and bodies for helpers, parsers, annotation validators, meta utils, and type parsers.
- Fixed tests to use readerWriter instead of deprecated reader argument.
- Refactored usage of now-absent 'metadata', 'parameters', 'fields', 'methods', 'source', and similar members to use correct *.firstFragment.* or API alternatives.
- Cleaned up old imports and unused code.
test(generator): update generator integration tests
- Updated test calls to use correct TestReaderWriter type and bring test infra in line with current build_runner/testing API.
build: update dependencies and pubspec to support latest analyzer/build ecosystem
- Raised Dart SDK and package constraints as required for generated code and codegen plugins.
- Updated pubspecs in root/examples as needed by build warnings.
docs: add plots and assets (new files)
BREAKING CHANGE:
- Requires Dart 3.8+ and analyzer that supports element2.
- All downstream codegen/tests depending on Element API must migrate to Element2 signatures and data model.
- Added Netlify deployment status badge to all package README files
- Standardized CI/CD badge formatting across the project
- Improves visibility of deployment status for documentation and examples
- Maintains consistent badge styling with existing Melos + FVM CI badge
- Downgraded lints and test dependencies in multiple packages to ensure consistent analyzer and test ecosystem for Dart 3.2+.
- cherrypick_generator: Bump analyzer to ^7.7.1 and mockito to ^5.4.5 for patch updates and compatibility.
- cherrypick_flutter: Lowered flutter_lints and test to versions compatible with current stable toolchain.
- talker_cherrypick_logger: Lowered lints and test for alignment with mono-repo versions.
- melos.yaml: Added clean_all script for removing generated files and build artifacts repo-wide.
No functional code changes, only dependency and tooling improvements.
- Downgraded Flutter version in .fvmrc from 3.29.3 to 3.27.0 for compatibility with current dependencies
- Raised Dart SDK constraint in benchmark_di/pubspec.yaml from >=3.0.0 <4.0.0 to >=3.2.0 <4.0.0 to align with required package minimums
This change ensures environment compatibility for dependency resolution and build tools. No functional code changes.
- Enhanced description of development approaches in both Russian and English versions
- Clarified distinction between programmatic (imperative) and declarative approaches
- Improved terminology consistency across both language versions
- Fixed code formatting in benchmark_di CLI and adapter files
- Updated pubspec.lock files for benchmark_di, client_app, and postly examples
- Minor formatting improvements in disposable example
- Added Melos + FVM CI badges to all package README.md files
- Standardized badge formatting across all packages
- Improved project visibility with build status indicators
# Release - CherryPick 3.x
> **CherryPick** — a lightweight and modular DI framework for Dart and Flutter that solves dependency injection through strong typing, code generation, and dependency control.
Version **3.x** was recently released with significant improvements.
## Main Changes in 3.x
* **O(1) dependency resolution** — thanks to Map indexing of bindings, performance does not depend on the size of the scope in the DI graph. This provides noticeable speedup in large projects.
* **Protection against circular dependencies** — checking works both within a single scope and across the entire hierarchy. When a cycle is detected, an informative exception with the dependency chain is thrown.
* **Integration with Talker** — all DI events (registration, creation, deletion, errors) are logged and can be displayed in the console or UI.
* **Automatic resource cleanup** — objects implementing `Disposable` are properly released when the scope is closed.
* **Stabilized declarative approach support** — annotations and code generation now work more reliably and are more convenient for use in projects.
## Resource Cleanup Example
```dart
class MyServiceWithSocket implements Disposable {
@override
Future<void> dispose() async {
await socket.close();
print('Socket closed!');
}
}
class AppModule extends Module {
@override
void builder(Scope currentScope) {
// singleton Api
bind<MyServiceWithSocket>()
.toProvide(() => MyServiceWithSocket())
.singleton();
}
}
scope.installModules([AppModule()]);
await CherryPick.closeRootScope(); // will wait for async dispose to complete
```
## Circular Dependency Checking
One of the new features in CherryPick 3.x is built-in cycle protection.
This helps catch situations early where services start depending on each other recursively.
### How to Enable Checking
For checking within a single scope:
```dart
final scope = CherryPick.openRootScope();
scope.enableCycleDetection();
```
For global checking across the entire hierarchy:
```dart
CherryPick.enableGlobalCycleDetection();
CherryPick.enableGlobalCrossScopeCycleDetection();
final rootScope = CherryPick.openRootScope();
```
### How a Cycle Can Occur
Suppose we have two services that depend on each other:
```dart
class UserService {
final OrderService orderService;
UserService(this.orderService);
}
class OrderService {
final UserService userService;
OrderService(this.userService);
}
```
If we register them in the same scope:
```dart
class AppModule extends Module {
@override
void builder(Scope currentScope) {
bind<UserService>().toProvide(() => UserService(scope.resolve()));
bind<OrderService>().toProvide(() => OrderService(scope.resolve()));
}
}
final scope = CherryPick.openRootScope()
..enableCycleDetection()
..installModules([AppModule()]);
scope.resolve<UserService>();
```
Then when trying to resolve the dependency, an exception will be thrown:
```bash
❌ Circular dependency detected for UserService
Dependency chain: UserService -> OrderService -> UserService
```
This way, the error is detected immediately, not "somewhere in runtime".
## Integration with Talker
CherryPick 3.x allows logging all DI events through [Talker](https://pub.dev/packages/talker): registration, object creation, deletion, and errors. This is convenient for debugging and diagnosing the dependency graph.
Connection example:
```dart
final talker = Talker();
final observer = TalkerCherryPickObserver(talker);
CherryPick.setGlobalObserver(observer);
```
After this, DI events will be displayed in the console or UI:
```bash
┌───────────────────────────────────────────────────────────────
│ [info] 9:41:33 | [scope opened][CherryPick] scope_1757054493089_7072
└───────────────────────────────────────────────────────────────
┌───────────────────────────────────────────────────────────────
│ [verbose] 9:41:33 | [diagnostic][CherryPick] Scope created: scope_1757054493089_7072 {type: Scope, name: scope_1757054493089_7072, description: scope created}
└───────────────────────────────────────────────────────────────
```
In the log, you can see when scopes are created, which objects are registered and deleted, and catch errors and cycles in real time.
## Declarative Approach with Annotations
In addition to fully programmatic module descriptions, CherryPick supports **declarative DI style through annotations**.
This allows minimizing manual code and automatically generating modules and mixins for automatic dependency injection.
Example of a declarative module:
```dart
@module()
abstract class AppModule extends Module {
@provide()
@singleton()
Api api() => Api();
@provide()
Repo repo(Api api) => Repo(api);
}
````
After code generation, you can automatically inject dependencies into widgets or services:
```dart
@injectable()
class MyScreen extends StatelessWidget with _$MyScreen {
@inject()
late final Repo repo;
MyScreen() {
_inject(this);
}
}
```
This way you can choose a convenient style: either **purely programmatic** or **declarative with annotations**.
## Who Might Find CherryPick Useful?
* Projects where it's important to guarantee **no cycles in the dependency graph**;
* Teams that want to **minimize manual DI code** and use a declarative style with annotations;
* Applications that require **automatic resource cleanup** (sockets, controllers, streams).
## Useful Links
* 📦 Package: [pub.dev/packages/cherrypick](https://pub.dev/packages/cherrypick)
* 💻 Code: [github.com/pese-git/cherrypick](https://github.com/pese-git/cherrypick)
* 📖 Documentation: [cherrypick-di.netlify.app](https://cherrypick-di.netlify.app/)
- Added // ignore: deprecated_member_use_from_same_package comment
- This suppresses the warning about deprecated toProvideAsync method
- The comment is needed to maintain code quality while keeping backward compatibility
- Added comprehensive release notes for CherryPick 3.x
- Includes new features: O(1) dependency resolution, circular dependency protection
- Added Talker integration and automatic resource cleanup examples
- Added declarative approach with annotations section
- Both Russian and English versions included
- Unified MAJOR.MINOR versioning across all cherrypick ecosystem packages
- Updated cherrypick_annotations from 1.1.2-dev.2 to 3.0.0-dev.0
- Updated cherrypick_generator from 2.0.0-dev.2 to 3.0.0-dev.0
- Updated cherrypick_flutter from 1.1.3-dev.12 to 3.0.0-dev.1
- Updated documentation URLs from .dev to .netlify.app domain
- Maintained semantic versioning consistency for mono-repository management
This change ensures:
- Clear compatibility signaling between interdependent packages
- Simplified dependency management for consumers
- Consistent release versioning across the ecosystem
- Add detailed warning about toInstance usage restrictions in module builders
- Explain singleton behavior with parameterized providers
- Clarify singleton() usage with toInstance() calls
- Update both English and Russian documentation versions
- 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.
- Add an explicit warning and usage examples for .singleton() combined with toProvideWithParams/toProvideAsyncWithParams:
- in API doc-comment for singleton() in binding.dart,
- in README.md and both full tutorials (EN/RU).
- Show correct and incorrect usage/pitfalls for parameterized providers and singleton.
- Help users avoid unintended singleton caching when using providers with parameters.
- Motivation: Prevent common confusion, make advanced DI scenarios safer and more obvious.
- Add an explicit warning and usage pattern examples to the toInstance() method doc-comment.
- Explain why resolving dependencies registered with toInstance inside the same Module.builder does not work.
- Reference safe and unsafe code samples for users navigating via IDE and API documentation.
- Add explicit note for users about the impossibility to use scope.resolve<T>() for just-to-be-registered types inside Module.builder when registering chained dependencies via toInstance.
- Show correct and incorrect usage patterns, functional and anti-pattern Dart examples in RU and EN full tutorials.
- Add the warning to the main README after core concept bindings block, improving discoverability for users starting with the library.
- Motivation: Prevent common misuse and hard-to-debug runtime errors for users who construct chains using toInstance/resolve inside the builder.
- Add detailed English doc comments for all main annotations (inject, injectable, instance, provide, scope, etc)
- Add fully documented example/example.dart illustrating real-world DI scenario
- Clarify stub sections (Module class, generated mixins)
- Aligns package with pub.dev quality and best practice requirements
No breaking changes.
- Updated index.tsx to use <Translate> and translate() for all main texts (title, subtitle, CTA, description) — now fully i18n-ready.
- Added new translation files (code.json, navbar.json, footer.json, etc.) to support Russian language for homepage and UI.
- Enables seamless language switching and correct translations of homepage elements.
- Updated HomepageFeatures/index.tsx to use Docusaurus <Translate> component and unique ids for each feature title and description.
- Enables full i18n support for FeatureList (English & Russian).
- All feature texts are now ready for integration with Docusaurus translation workflow.
- Added the initial Russian localizable version for the documentation introduction section ().
- Makes the first step of the CherryPick documentation available to Russian-speaking users.
- Ensures the /ru/docs/intro route is available and translated.
- Changed docs.editUrl in docusaurus.config.ts to point to the actual GitHub repository (https://github.com/pese-git/cherrypick/tree/website/website).
- Allows users to edit documentation directly in this project's repo via the 'Edit this page' links.
