mirror of
https://github.com/pese-git/cherrypick.git
synced 2026-01-24 05:25:19 +00:00
Compare commits
20 Commits
cherrypick
...
cherrypick
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
900cd68663 | ||
|
|
57e4196b95 | ||
|
|
358da8f96b | ||
|
|
ea2b6687f4 | ||
|
|
df00a2a5d2 | ||
|
|
d5983a4a0b | ||
|
|
125bccfa5a | ||
|
|
12b97c9368 | ||
|
|
424aaa3e22 | ||
|
|
2ec3a86a2f | ||
|
|
efed72cc39 | ||
|
|
4dc9e269cd | ||
|
|
d153ab4255 | ||
|
|
6924ccd07b | ||
|
|
26b843f791 | ||
|
|
8eafba4e4b | ||
|
|
ad6e9bbc3d | ||
|
|
bea8affcab | ||
|
|
1d7b9a9166 | ||
|
|
016c212063 |
2
.gitignore
vendored
2
.gitignore
vendored
@@ -18,5 +18,7 @@ pubspec_overrides.yaml
|
|||||||
melos_cherrypick.iml
|
melos_cherrypick.iml
|
||||||
melos_cherrypick_workspace.iml
|
melos_cherrypick_workspace.iml
|
||||||
melos_cherrypick_flutter.iml
|
melos_cherrypick_flutter.iml
|
||||||
|
melos_benchmark_di.iml
|
||||||
|
melos_talker_cherrypick_logger.iml
|
||||||
|
|
||||||
coverage
|
coverage
|
||||||
35
CHANGELOG.md
35
CHANGELOG.md
@@ -3,6 +3,41 @@
|
|||||||
All notable changes to this project will be documented in this file.
|
All notable changes to this project will be documented in this file.
|
||||||
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
||||||
|
|
||||||
|
## 2025-08-12
|
||||||
|
|
||||||
|
### Changes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Packages with breaking changes:
|
||||||
|
|
||||||
|
- There are no breaking changes in this release.
|
||||||
|
|
||||||
|
Packages with other changes:
|
||||||
|
|
||||||
|
- [`cherrypick` - `v3.0.0-dev.8`](#cherrypick---v300-dev8)
|
||||||
|
- [`cherrypick_flutter` - `v1.1.3-dev.8`](#cherrypick_flutter---v113-dev8)
|
||||||
|
|
||||||
|
Packages with dependency updates only:
|
||||||
|
|
||||||
|
> Packages listed below depend on other packages in this workspace that have had changes. Their versions have been incremented to bump the minimum dependency versions of the packages they depend upon in this project.
|
||||||
|
|
||||||
|
- `cherrypick_flutter` - `v1.1.3-dev.8`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### `cherrypick` - `v3.0.0-dev.8`
|
||||||
|
|
||||||
|
- **REFACTOR**(tests): replace MockLogger with MockObserver in scope tests to align with updated observer API.
|
||||||
|
- **FIX**(doc): remove hide symbol.
|
||||||
|
- **FEAT**(core): add full DI lifecycle observability via onInstanceDisposed.
|
||||||
|
- **DOCS**(logging): update Logging section in README with modern Observer usage and Talker integration examples.
|
||||||
|
- **DOCS**(observer): improve documentation, translate all comments to English, add usage examples.
|
||||||
|
- **DOCS**(README): add section with overview table for additional modules.
|
||||||
|
- **DOCS**(README): refactor structure and improve clarity of advanced features.
|
||||||
|
- **DOCS**(README): add 'Hierarchical Subscopes' section and update structure for advanced features clarity.
|
||||||
|
|
||||||
|
|
||||||
## 2025-08-11
|
## 2025-08-11
|
||||||
|
|
||||||
### Changes
|
### Changes
|
||||||
|
|||||||
@@ -47,7 +47,7 @@ packages:
|
|||||||
path: "../cherrypick"
|
path: "../cherrypick"
|
||||||
relative: true
|
relative: true
|
||||||
source: path
|
source: path
|
||||||
version: "3.0.0-dev.5"
|
version: "3.0.0-dev.7"
|
||||||
collection:
|
collection:
|
||||||
dependency: transitive
|
dependency: transitive
|
||||||
description:
|
description:
|
||||||
|
|||||||
@@ -1,3 +1,14 @@
|
|||||||
|
## 3.0.0-dev.8
|
||||||
|
|
||||||
|
- **REFACTOR**(tests): replace MockLogger with MockObserver in scope tests to align with updated observer API.
|
||||||
|
- **FIX**(doc): remove hide symbol.
|
||||||
|
- **FEAT**(core): add full DI lifecycle observability via onInstanceDisposed.
|
||||||
|
- **DOCS**(logging): update Logging section in README with modern Observer usage and Talker integration examples.
|
||||||
|
- **DOCS**(observer): improve documentation, translate all comments to English, add usage examples.
|
||||||
|
- **DOCS**(README): add section with overview table for additional modules.
|
||||||
|
- **DOCS**(README): refactor structure and improve clarity of advanced features.
|
||||||
|
- **DOCS**(README): add 'Hierarchical Subscopes' section and update structure for advanced features clarity.
|
||||||
|
|
||||||
## 3.0.0-dev.7
|
## 3.0.0-dev.7
|
||||||
|
|
||||||
> Note: This release has breaking changes.
|
> Note: This release has breaking changes.
|
||||||
|
|||||||
@@ -13,7 +13,7 @@ It provides an easy-to-use system for registering, scoping, and resolving depend
|
|||||||
- [Binding](#binding)
|
- [Binding](#binding)
|
||||||
- [Module](#module)
|
- [Module](#module)
|
||||||
- [Scope](#scope)
|
- [Scope](#scope)
|
||||||
- [Automatic Resource Cleanup with Disposable](#automatic-resource-cleanup-with-disposable)
|
- [Disposable](#disposable)
|
||||||
- [Dependency Resolution API](#dependency-resolution-api)
|
- [Dependency Resolution API](#dependency-resolution-api)
|
||||||
- [Using Annotations & Code Generation](#using-annotations--code-generation)
|
- [Using Annotations & Code Generation](#using-annotations--code-generation)
|
||||||
- [Advanced Features](#advanced-features)
|
- [Advanced Features](#advanced-features)
|
||||||
@@ -24,6 +24,7 @@ It provides an easy-to-use system for registering, scoping, and resolving depend
|
|||||||
- [Example Application](#example-application)
|
- [Example Application](#example-application)
|
||||||
- [FAQ](#faq)
|
- [FAQ](#faq)
|
||||||
- [Documentation Links](#documentation-links)
|
- [Documentation Links](#documentation-links)
|
||||||
|
- [Additional Modules](#additional-modules)
|
||||||
- [Contributing](#contributing)
|
- [Contributing](#contributing)
|
||||||
- [License](#license)
|
- [License](#license)
|
||||||
|
|
||||||
@@ -50,13 +51,14 @@ Add to your `pubspec.yaml`:
|
|||||||
```yaml
|
```yaml
|
||||||
dependencies:
|
dependencies:
|
||||||
cherrypick: ^<latest_version>
|
cherrypick: ^<latest_version>
|
||||||
```
|
````
|
||||||
|
|
||||||
Then run:
|
Then run:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
dart pub get
|
dart pub get
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Getting Started
|
## Getting Started
|
||||||
@@ -66,7 +68,6 @@ Here is a minimal example that registers and resolves a dependency:
|
|||||||
```dart
|
```dart
|
||||||
import 'package:cherrypick/cherrypick.dart';
|
import 'package:cherrypick/cherrypick.dart';
|
||||||
|
|
||||||
|
|
||||||
class AppModule extends Module {
|
class AppModule extends Module {
|
||||||
@override
|
@override
|
||||||
void builder(Scope currentScope) {
|
void builder(Scope currentScope) {
|
||||||
@@ -92,11 +93,11 @@ await CherryPick.closeRootScope();
|
|||||||
|
|
||||||
A **Binding** acts as a configuration for how to create or provide a particular dependency. Bindings support:
|
A **Binding** acts as a configuration for how to create or provide a particular dependency. Bindings support:
|
||||||
|
|
||||||
- Direct instance assignment (`toInstance()`, `toInstanceAsync()`)
|
* Direct instance assignment (`toInstance()`, `toInstanceAsync()`)
|
||||||
- Lazy providers (sync/async functions)
|
* Lazy providers (sync/async functions)
|
||||||
- Provider functions supporting dynamic parameters
|
* Provider functions supporting dynamic parameters
|
||||||
- Named instances for resolving by string key
|
* Named instances for resolving by string key
|
||||||
- Optional singleton lifecycle
|
* Optional singleton lifecycle
|
||||||
|
|
||||||
#### Example
|
#### Example
|
||||||
|
|
||||||
@@ -172,7 +173,7 @@ await CherryPick.closeRootScope();
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Automatic Resource Cleanup with Disposable
|
### Disposable
|
||||||
|
|
||||||
CherryPick can automatically clean up any dependency that implements the `Disposable` interface. This makes resource management (for controllers, streams, sockets, files, etc.) easy and reliable—especially when scopes or the app are shut down.
|
CherryPick can automatically clean up any dependency that implements the `Disposable` interface. This makes resource management (for controllers, streams, sockets, files, etc.) easy and reliable—especially when scopes or the app are shut down.
|
||||||
|
|
||||||
@@ -223,67 +224,17 @@ await CherryPick.closeRootScope(); // awaits async disposal
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Automatic resource management (`Disposable`, `dispose`)
|
## Dependency Resolution API
|
||||||
|
|
||||||
CherryPick automatically manages the lifecycle of any object registered via DI that implements the `Disposable` interface.
|
- `resolve<T>()` — Locates a dependency instance or throws if missing.
|
||||||
|
- `resolveAsync<T>()` — Async variant for dependencies requiring async binding.
|
||||||
|
- `tryResolve<T>()` — Returns `null` if not found (sync).
|
||||||
|
- `tryResolveAsync<T>()` — Returns `null` async if not found.
|
||||||
|
|
||||||
**Best practice:**
|
Supports:
|
||||||
Always finish your work with `await CherryPick.closeRootScope()` (for the root scope) or `await scope.closeSubScope('key')` (for subscopes).
|
- Synchronous and asynchronous dependencies
|
||||||
These methods will automatically await `dispose()` on all resolved objects (e.g., singletons) that implement `Disposable`, ensuring proper and complete resource cleanup—sync or async.
|
- Named dependencies
|
||||||
|
- Provider functions with and without runtime parameters
|
||||||
Manual `await scope.dispose()` may be useful if you manually manage custom scopes.
|
|
||||||
|
|
||||||
#### Example
|
|
||||||
|
|
||||||
```dart
|
|
||||||
class MyService implements Disposable {
|
|
||||||
@override
|
|
||||||
FutureOr<void> dispose() async {
|
|
||||||
// release resources, close streams, perform async shutdown, etc.
|
|
||||||
print('MyService disposed!');
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
final scope = openRootScope();
|
|
||||||
scope.installModules([
|
|
||||||
ModuleImpl(),
|
|
||||||
]);
|
|
||||||
|
|
||||||
final service = scope.resolve<MyService>();
|
|
||||||
|
|
||||||
// ... use service
|
|
||||||
|
|
||||||
// Recommended completion:
|
|
||||||
await CherryPick.closeRootScope(); // will print: MyService disposed!
|
|
||||||
|
|
||||||
// Or, to close and clean up a subscope and its resources:
|
|
||||||
await scope.closeSubScope('feature');
|
|
||||||
|
|
||||||
class ModuleImpl extends Module {
|
|
||||||
@override
|
|
||||||
void builder(Scope scope) {
|
|
||||||
bind<MyService>().toProvide(() => MyService()).singleton();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Working with Subscopes
|
|
||||||
|
|
||||||
```dart
|
|
||||||
// Open a named child scope (e.g., for a feature/module)
|
|
||||||
final subScope = rootScope.openSubScope('featureScope')
|
|
||||||
..installModules([FeatureModule()]);
|
|
||||||
|
|
||||||
// Resolve from subScope, with fallback to parents if missing
|
|
||||||
final dataBloc = await subScope.resolveAsync<DataBloc>();
|
|
||||||
```
|
|
||||||
|
|
||||||
### Fast Dependency Lookup (Performance Improvement)
|
|
||||||
|
|
||||||
> **Performance Note:**
|
|
||||||
> **Starting from version 3.0.0**, CherryPick uses a Map-based resolver index for dependency lookup. This means calls to `resolve<T>()` and related methods are now O(1) operations, regardless of the number of modules or bindings in your scope. Previously, the library had to iterate over all modules and bindings to locate the requested dependency, which could impact performance as your project grew.
|
|
||||||
>
|
|
||||||
> This optimization is internal and does not change any library APIs or usage patterns, but it significantly improves resolution speed in larger applications.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -337,7 +288,7 @@ class ProfilePage with _\$ProfilePage {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
- After running build_runner, the mixin `_ | |||||||