mirror of
https://github.com/pese-git/cherrypick.git
synced 2026-01-23 21:13:35 +00:00
doc: update readme
This commit is contained in:
Sergey Penkovsky
253
README.md
253
README.md
@@ -1,184 +1,145 @@
|
|||||||
# CherryPick Workspace
|
# CherryPick Workspace
|
||||||
|
|
||||||
CherryPick Workspace is a modular ecosystem for declarative, type-safe dependency injection in Dart and Flutter applications. It brings together core dependency management, advanced code generation, annotation-driven DI, and seamless Flutter integration for stateful, testable, and scalable app architectures.
|
CherryPick Workspace is a modular, open-source dependency injection ecosystem for Dart and Flutter, designed to offer lightweight, flexible, and scalable DI suitable for both backend and frontend (Flutter) development. This monorepo contains the main DI runtime library, annotation helpers, code generation for modular bindings, and seamless Flutter integration.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Overview
|
## Packages Overview
|
||||||
|
|
||||||
CherryPick Workspace includes the following packages:
|
- **[`cherrypick`](./cherrypick)**
|
||||||
|
The core dependency injection library. Supports modular bindings, hierarchical scopes, named and singleton bindings, provider functions (sync/async), runtime parameters, and test-friendly composition.
|
||||||
|
_Intended for use in pure Dart and Flutter projects._
|
||||||
|
|
||||||
- **`cherrypick`** – Core dependency injection engine for Dart: bindings, modules, scopes, and runtime resolution.
|
- **[`cherrypick_annotations`](./cherrypick_annotations)**
|
||||||
- **`cherrypick_annotations`** – Lightweight annotation library (`@module`, `@singleton`, `@named`) for injectable code and code generation.
|
A set of Dart annotations (`@module`, `@singleton`, `@instance`, `@provide`, `@named`, `@params`) enabling concise, declarative DI modules and providers, primarily for use with code generation tools.
|
||||||
- **`cherrypick_generator`** – Code generator that produces DI module boilerplate from annotated Dart classes, using `cherrypick_annotations`.
|
|
||||||
- **`cherrypick_flutter`** – Flutter integration providing scope-aware dependency resolution via `CherryPickProvider` in the widget tree.
|
- **[`cherrypick_generator`](./cherrypick_generator)**
|
||||||
|
A [source_gen](https://pub.dev/packages/source_gen)-based code generator that automatically converts your annotated modules and providers into ready-to-use boilerplate for registration and resolution within your app.
|
||||||
|
_Reduces manual wiring and errors; compatible with build_runner._
|
||||||
|
|
||||||
|
- **[`cherrypick_flutter`](./cherrypick_flutter)**
|
||||||
|
Adds Flutter-native integration, exposing DI scopes and modules to the widget tree through `CherryPickProvider` and enabling dependency management throughout your Flutter app.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Repository Structure
|
## Why CherryPick?
|
||||||
|
|
||||||
- `cherrypick/` – Core DI library (bindings, modules, scopes, runtime resolution)
|
- **Zero-overhead and intuitive API:**
|
||||||
- `cherrypick_annotations/` – DI annotations for use with generators
|
Clean, minimal syntax, strong typing, powerful binding lifecycle control.
|
||||||
- `cherrypick_generator/` – Source-gen implementation for codegen of modules and bindings
|
- **High testability:**
|
||||||
- `cherrypick_flutter/` – Flutter tools to provide DI in widget subtree via `CherryPickProvider`
|
Supports overriding and hierarchical scope trees.
|
||||||
- `examples/` – Sample Flutter projects demonstrating patterns
|
- **Both Sync & Async support:**
|
||||||
|
Register and resolve async providers, factories, and dependencies.
|
||||||
|
- **Seamless code generation:**
|
||||||
|
Effortless setup with annotations + generator—skip boilerplate!
|
||||||
|
- **Works with or without Flutter.**
|
||||||
|
- **Production ready:**
|
||||||
|
Robust enough for apps, packages, and server-side Dart.
|
||||||
|
- **Extensible & Modular:**
|
||||||
|
Add bindings at runtime, use sub-modules, or integrate via codegen.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Quick Start Guide
|
## Get Started
|
||||||
|
|
||||||
### Installation
|
### 1. Add dependencies
|
||||||
|
|
||||||
Add the desired packages to your `pubspec.yaml` (pick what you need):
|
In your `pubspec.yaml`:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
dependencies:
|
dependencies:
|
||||||
cherrypick: ^latest
|
cherrypick: ^<latest-version>
|
||||||
cherrypick_annotations: ^latest
|
cherrypick_annotations: ^<latest-version>
|
||||||
cherrypick_flutter: ^latest
|
|
||||||
|
|
||||||
dev_dependencies:
|
dev_dependencies:
|
||||||
cherrypick_generator: ^latest
|
build_runner: ^<latest>
|
||||||
build_runner: ^latest
|
cherrypick_generator: ^<latest-version>
|
||||||
```
|
```
|
||||||
|
|
||||||
Run `flutter pub get` or `dart pub get` to fetch dependencies.
|
For Flutter projects, add:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
dependencies:
|
||||||
|
cherrypick_flutter: ^<latest-version>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Write a DI Module (with annotations)
|
||||||
|
|
||||||
|
```dart
|
||||||
|
import 'package:cherrypick_annotations/cherrypick_annotations.dart';
|
||||||
|
import 'package:cherrypick/cherrypick.dart';
|
||||||
|
|
||||||
|
@module()
|
||||||
|
abstract class MyModule extends Module {
|
||||||
|
@singleton()
|
||||||
|
ApiClient apiClient() => ApiClient();
|
||||||
|
|
||||||
|
@provide()
|
||||||
|
DataRepository dataRepo(ApiClient client) => DataRepository(client);
|
||||||
|
|
||||||
|
@provide()
|
||||||
|
String greeting(@params() String name) => 'Hello, $name!';
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Generate the bindings
|
||||||
|
|
||||||
|
```sh
|
||||||
|
dart run build_runner build
|
||||||
|
# or for Flutter:
|
||||||
|
flutter pub run build_runner build
|
||||||
|
```
|
||||||
|
|
||||||
|
The generator will create a `$MyModule` class with binding code.
|
||||||
|
|
||||||
|
### 4. Install and Resolve
|
||||||
|
|
||||||
|
```dart
|
||||||
|
final scope = CherryPick.openRootScope()
|
||||||
|
..installModules([$MyModule()]);
|
||||||
|
|
||||||
|
final repo = scope.resolve<DataRepository>();
|
||||||
|
final greeting = scope.resolveWithParams<String>('John'); // 'Hello, John!'
|
||||||
|
```
|
||||||
|
|
||||||
|
_For Flutter, wrap your app with `CherryPickProvider` for DI scopes in the widget tree:_
|
||||||
|
|
||||||
|
```dart
|
||||||
|
void main() {
|
||||||
|
runApp(
|
||||||
|
CherryPickProvider(child: MyApp()),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Usage
|
## Features at a Glance
|
||||||
|
|
||||||
#### Core DI (`cherrypick`)
|
- ⚡ **Fast, lightweight DI** for any Dart/Flutter project
|
||||||
|
- 🧩 **Modular & hierarchical scopes** (root, subscopes)
|
||||||
- **Bind dependencies:**
|
- 🔖 **Named/bound/singleton instances** out of the box
|
||||||
|
- 🔄 **Sync and async provider support**
|
||||||
```dart
|
- ✏️ **Runtime parameters for dynamic factory methods**
|
||||||
Binding<String>().toInstance("hello world");
|
- 🏷️ **Code generator** for annotation-based DI setup (`cherrypick_generator`)
|
||||||
Binding<ApiClient>().toProvide(() => ApiClientImpl()).singleton();
|
- 🕹️ **Deep Flutter integration** via `CherryPickProvider`
|
||||||
```
|
|
||||||
|
|
||||||
- **Module definition:**
|
|
||||||
|
|
||||||
```dart
|
|
||||||
class AppModule extends Module {
|
|
||||||
@override
|
|
||||||
void builder(Scope currentScope) {
|
|
||||||
bind<ApiClient>().toInstance(ApiClientMock());
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- **Scope management:**
|
|
||||||
|
|
||||||
```dart
|
|
||||||
final rootScope = CherryPick.openRootScope();
|
|
||||||
rootScope.installModules([AppModule()]);
|
|
||||||
final client = rootScope.resolve<ApiClient>();
|
|
||||||
```
|
|
||||||
|
|
||||||
You can create sub-scopes for feature isolation as needed:
|
|
||||||
|
|
||||||
```dart
|
|
||||||
final featureScope = rootScope.openSubScope("feature");
|
|
||||||
featureScope.installModules([FeatureModule()]);
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Annotation & Code Generation (`cherrypick_annotations`, `cherrypick_generator`)
|
|
||||||
|
|
||||||
- **Annotate your DI modules:**
|
|
||||||
|
|
||||||
```dart
|
|
||||||
import 'package:cherrypick_annotations/cherrypick_annotations.dart';
|
|
||||||
import 'package:cherrypick/cherrypick.dart';
|
|
||||||
|
|
||||||
part 'app_module.cherrypick.g.dart';
|
|
||||||
|
|
||||||
@module()
|
|
||||||
abstract class AppModule extends Module {
|
|
||||||
@singleton()
|
|
||||||
ApiClient client() => ApiClientImpl();
|
|
||||||
|
|
||||||
@named('apiBaseUrl')
|
|
||||||
String baseUrl() => 'https://api.example.com';
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- **Generate code:**
|
|
||||||
|
|
||||||
Run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
dart run build_runner build
|
|
||||||
```
|
|
||||||
|
|
||||||
This will generate efficient registration code for your modules.
|
|
||||||
|
|
||||||
#### Flutter Integration (`cherrypick_flutter`)
|
|
||||||
|
|
||||||
- **Setup `CherryPickProvider` in your widget tree:**
|
|
||||||
|
|
||||||
```dart
|
|
||||||
void main() {
|
|
||||||
runApp(
|
|
||||||
CherryPickProvider(
|
|
||||||
child: MyApp(),
|
|
||||||
),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- **Access DI scopes anywhere in Flutter:**
|
|
||||||
|
|
||||||
```dart
|
|
||||||
class MyWidget extends StatelessWidget {
|
|
||||||
@override
|
|
||||||
Widget build(BuildContext context) {
|
|
||||||
final cherryPick = CherryPickProvider.of(context);
|
|
||||||
final rootScope = cherryPick.openRootScope();
|
|
||||||
|
|
||||||
final repo = rootScope.resolve<MyRepository>();
|
|
||||||
// use repo as needed...
|
|
||||||
|
|
||||||
return Text('Dependency resolved!');
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Features
|
## Example Usage
|
||||||
|
|
||||||
- [x] Module-based configuration & composition
|
Please see:
|
||||||
- [x] Flexible scopes (main/root/subscopes)
|
- [`cherrypick/README.md`](./cherrypick/README.md) for core DI features and examples
|
||||||
- [x] Named and singleton bindings
|
- [`cherrypick_flutter/README.md`](./cherrypick_flutter/README.md) for Flutter-specific usage
|
||||||
- [x] Async binding and parameter injection
|
- [`cherrypick_annotations/README.md`](./cherrypick_annotations/README.md) and [`cherrypick_generator/README.md`](./cherrypick_generator/README.md) for codegen and annotations
|
||||||
- [x] Annotations (`@module`, `@singleton`, `@named`) for concise setup
|
|
||||||
- [x] Code generation for efficient, boilerplate-free DI modules
|
|
||||||
- [x] Seamless integration with Flutter via InheritedWidget (`CherryPickProvider`)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Example Projects
|
## Contribution & License
|
||||||
|
|
||||||
See the [`examples/`](examples/) directory for real-world usage patterns, including synchronous, asynchronous, and named injection in Flutter apps.
|
- **Contributions:** PRs, issues, and feedback are welcome on [GitHub](https://github.com/pese-git/cherrypick).
|
||||||
|
- **License:** Apache 2.0 for all packages in this workspace.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Contributing
|
**Happy Cherry Picking! 🍒**
|
||||||
|
|
||||||
Community feedback, bug reports, and PRs are welcome! Please file issues and suggestions on the [GitHub issues page](https://github.com/pese-git/cherrypick/issues).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
CherryPick Workspace is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Links
|
|
||||||
|
|
||||||
- [CherryPick GitHub Repository](https://github.com/pese-git/cherrypick)
|
|
||||||
- [cherrypick_flutter on pub.dev](https://pub.dev/packages/cherrypick_flutter)
|
|
||||||
- [cherrypick_generator on pub.dev](https://pub.dev/packages/cherrypick_generator)
|
|
||||||
- [cherrypick_annotations on pub.dev](https://pub.dev/packages/cherrypick_annotations)
|
|
||||||
Reference in New Issue
Block a user