chore(release): publish packages

- cherrypick_generator@1.1.0-dev.2

CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## 2025-05-23
+
+### Changes
+
+---
+
+Packages with breaking changes:
+
+ - There are no breaking changes in this release.
+
+Packages with other changes:
+
+ - [`cherrypick_generator` - `v1.1.0-dev.2`](#cherrypick_generator---v110-dev2)
+
+---
+
+#### `cherrypick_generator` - `v1.1.0-dev.2`
+
+ - **FIX**: update instance generator code.
+
+
 ## 2025-05-22
 
 ### Changes

cherrypick_annotations/lib/src/instance.dart

@@ -11,11 +11,12 @@
 // limitations under the License.
 //
 
-/// An annotation to specify that a method or class provides a new instance
-/// each time it is requested.
+/// ENGLISH:
+/// Annotation to specify that a new instance should be provided on each request.
 ///
-/// This is typically used to indicate that the annotated binding should
-/// not be a singleton and a new object is created for every injection.
+/// Use the `@instance()` annotation for methods or classes in your DI module
+/// to declare that the DI container must create a new object every time
+/// the dependency is injected (i.e., no singleton behavior).
 ///
 /// Example:
 /// ```dart
@@ -35,6 +36,32 @@
 ///   }
 /// }
 /// ```
+///
+/// RUSSIAN (Русский):
+/// Аннотация для создания нового экземпляра при каждом запросе.
+///
+/// Используйте `@instance()` для методов или классов в DI-модуле,
+/// чтобы указать, что контейнер внедрения зависимостей должен создавать
+/// новый объект при каждом обращении к зависимости (то есть, не синглтон).
+///
+/// Пример:
+/// ```dart
+/// @module()
+/// abstract class AppModule extends Module {
+///   @instance()
+///   Foo foo() => Foo();
+/// }
+/// ```
+///
+/// Будет сгенерирован следующий код:
+/// ```dart
+/// final class $AppModule extends AppModule {
+///   @override
+///   void builder(Scope currentScope) {
+///     bind<Foo>().toInstance(() => foo());
+///   }
+/// }
+/// ```
 // ignore: camel_case_types
 final class instance {
   const instance();

cherrypick_annotations/lib/src/module.dart

@@ -11,25 +11,57 @@
 // limitations under the License.
 //
 
-/// An annotation used to mark a Dart class or library as a module.
+/// ENGLISH:
+/// Annotation for marking Dart classes or libraries as modules.
 ///
-/// This annotation can be used for tooling, code generation,
-/// or to provide additional metadata about the module.
+/// Use the `@module()` annotation on abstract classes (or on a library)
+/// to indicate that the class represents a DI (Dependency Injection) module.
+/// This is commonly used in code generation tools to automatically register
+/// and configure dependencies defined within the module.
 ///
 /// Example:
 /// ```dart
 /// @module()
 /// abstract class AppModule extends Module {
+///   // Dependency definitions go here.
 /// }
 /// ```
-/// Сгенерирует код:
+///
+/// Generates code like:
 /// ```dart
 /// final class $AppModule extends AppModule {
 ///   @override
 ///   void builder(Scope currentScope) {
+///     // Dependency registration...
+///   }
+/// }
+/// ```
 ///
+/// RUSSIAN (Русский):
+/// Аннотация для пометки классов или библиотек Dart как модуля.
+///
+/// Используйте `@module()` для абстрактных классов (или библиотек), чтобы
+/// показать, что класс реализует DI-модуль (Dependency Injection).
+/// Обычно используется генераторами кода для автоматической регистрации
+/// и конфигурирования зависимостей, определённых в модуле.
+///
+/// Пример:
+/// ```dart
+/// @module()
+/// abstract class AppModule extends Module {
+///   // Определения зависимостей
+/// }
+/// ```
+///
+/// Будет сгенерирован код:
+/// ```dart
+/// final class $AppModule extends AppModule {
+///   @override
+///   void builder(Scope currentScope) {
+///     // Регистрация зависимостей...
 ///   }
 /// }
+/// ```
 // ignore: camel_case_types
 final class module {
   /// Creates a [module] annotation.

cherrypick_annotations/lib/src/named.dart

@@ -11,10 +11,13 @@
 // limitations under the License.
 //
 
-/// An annotation to assign a name or identifier to a class, method, or other element.
+/// ENGLISH:
+/// Annotation to assign a name or identifier to a class, method, or other element.
 ///
-/// This can be useful for code generation, dependency injection,
-/// or providing metadata within a framework.
+/// The `@named('value')` annotation allows you to specify a string name
+/// for a dependency, factory, or injectable. This is useful for distinguishing
+/// between multiple registrations of the same type in dependency injection,
+/// code generation, and for providing human-readable metadata.
 ///
 /// Example:
 /// ```dart
@@ -25,7 +28,33 @@
 /// }
 /// ```
 ///
-/// Сгенерирует код:
+/// This will generate:
+/// ```dart
+/// final class $AppModule extends AppModule {
+///   @override
+///   void builder(Scope currentScope) {
+///     bind<Dio>().toProvide(() => dio()).withName('dio').singleton();
+///   }
+/// }
+/// ```
+///
+/// RUSSIAN (Русский):
+/// Аннотация для задания имени или идентификатора классу, методу или другому элементу.
+///
+/// Аннотация `@named('значение')` позволяет указать строковое имя для зависимости,
+/// фабрики или внедряемого значения. Это удобно для различения нескольких
+/// регистраций одного типа в DI, генерации кода.
+///
+/// Пример:
+/// ```dart
+/// @module()
+/// abstract class AppModule extends Module {
+///   @named('dio')
+///   Dio dio() => Dio();
+/// }
+/// ```
+///
+/// Будет сгенерирован следующий код:
 /// ```dart
 /// final class $AppModule extends AppModule {
 ///   @override
@@ -36,9 +65,13 @@
 /// ```
 // ignore: camel_case_types
 final class named {
-  /// The assigned name or identifier.
+  /// EN: The assigned name or identifier for the element.
+  ///
+  /// RU: Назначенное имя или идентификатор для элемента.
   final String value;
 
-  /// Creates a [named] annotation with the given [value].
+  /// EN: Creates a [named] annotation with the given [value].
+  ///
+  /// RU: Создаёт аннотацию [named] с заданным значением [value].
   const named(this.value);
 }

cherrypick_annotations/lib/src/params.dart

@@ -11,11 +11,14 @@
 // limitations under the License.
 //
 
-/// An annotation to indicate that a parameter is to be injected with run-time provided arguments.
+/// ENGLISH:
+/// Annotation to mark a method parameter for injection with run-time arguments.
 ///
-/// Use this annotation to mark a method parameter that should receive arguments
-/// passed during the resolution of a dependency (for example, through the
-/// `.withParams(...)` method in the generated code).
+/// Use the `@params()` annotation to specify that a particular parameter of a
+/// provider method should be assigned a value supplied at resolution time,
+/// rather than during static dependency graph creation. This is useful in DI
+/// when a dependency must receive dynamic data passed by the consumer
+/// (via `.withParams(...)` in the generated code).
 ///
 /// Example:
 /// ```dart
@@ -27,6 +30,26 @@
 /// ```dart
 /// bind<String>().toProvideWithParams((args) => greet(args));
 /// ```
+///
+/// RUSSIAN (Русский):
+/// Аннотация для пометки параметра метода, который будет внедряться со значением во время выполнения.
+///
+/// Используйте `@params()` чтобы указать, что конкретный параметр метода-провайдера
+/// должен получать значение, передаваемое в момент обращения к зависимости,
+/// а не на этапе построения графа зависимостей. Это полезно, если зависимость
+/// должна получать данные динамически от пользователя или другого процесса
+/// через `.withParams(...)` в сгенерированном коде.
+///
+/// Пример:
+/// ```dart
+/// @provide()
+/// String greet(@params() dynamic params) => 'Hello $params';
+/// ```
+///
+/// Будет сгенерировано:
+/// ```dart
+/// bind<String>().toProvideWithParams((args) => greet(args));
+/// ```
 // ignore: camel_case_types
 final class params {
   const params();

cherrypick_annotations/lib/src/provide.dart

@@ -11,28 +11,56 @@
 // limitations under the License.
 //
 
-/// An annotation to indicate that a method provides a dependency to the module.
+/// ENGLISH:
+/// Annotation to declare a factory/provider method or class as a singleton.
 ///
-/// This annotation is typically used in conjunction with dependency injection,
-/// marking methods whose return value should be registered as a provider.
-/// The annotated method can optionally declare dependencies as parameters,
-/// which will be resolved and injected automatically.
+/// Use the `@singleton()` annotation on methods in your DI module to specify
+/// that only one instance of the resulting object should be created and shared
+/// for all consumers. This is especially useful in dependency injection
+/// frameworks and service locators.
 ///
 /// Example:
 /// ```dart
 /// @module()
 /// abstract class AppModule extends Module {
-///   @provide()
-///   Foo foo(Bar bar) => Foo(bar);
+///   @singleton()
+///   Dio dio() => Dio();
 /// }
 /// ```
 ///
-/// This will generate:
+/// This generates the following code:
 /// ```dart
 /// final class $AppModule extends AppModule {
 ///   @override
 ///   void builder(Scope currentScope) {
-///     bind<Foo>().toProvide(() => foo(currentScope.resolve<Bar>()));
+///     bind<Dio>().toProvide(() => dio()).singleton();
+///   }
+/// }
+/// ```
+///
+/// RUSSIAN (Русский):
+/// Аннотация для объявления фабричного/провайдерного метода или класса синглтоном.
+///
+/// Используйте `@singleton()` для методов внутри DI-модуля, чтобы указать,
+/// что соответствующий объект (экземпляр класса) должен быть создан только один раз
+/// и использоваться всеми компонентами приложения (единый общий экземпляр).
+/// Это характерно для систем внедрения зависимостей и сервис-локаторов.
+///
+/// Пример:
+/// ```dart
+/// @module()
+/// abstract class AppModule extends Module {
+///   @singleton()
+///   Dio dio() => Dio();
+/// }
+/// ```
+///
+/// Будет сгенерирован следующий код:
+/// ```dart
+/// final class $AppModule extends AppModule {
+///   @override
+///   void builder(Scope currentScope) {
+///     bind<Dio>().toProvide(() => dio()).singleton();
 ///   }
 /// }
 /// ```

cherrypick_annotations/lib/src/singleton.dart

@@ -11,11 +11,14 @@
 // limitations under the License.
 //
 
-/// An annotation to declare a class as a singleton.
+/// ENGLISH:
+/// Annotation to declare a dependency as a singleton.
 ///
-/// This can be used to indicate that only one instance of the class
-/// should be created, which is often useful in dependency injection
-/// frameworks or service locators.
+/// Use the `@singleton()` annotation on provider methods inside a module
+/// to indicate that only a single instance of this dependency should be
+/// created and shared throughout the application's lifecycle. This is
+/// typically used in dependency injection frameworks or service locators
+/// to guarantee a single shared instance.
 ///
 /// Example:
 /// ```dart
@@ -25,7 +28,36 @@
 ///   Dio dio() => Dio();
 /// }
 /// ```
-/// Сгенерирует код:
+///
+/// This will generate code like:
+/// ```dart
+/// final class $AppModule extends AppModule {
+///   @override
+///   void builder(Scope currentScope) {
+///     bind<Dio>().toProvide(() => dio()).singleton();
+///   }
+/// }
+/// ```
+///
+/// RUSSIAN (Русский):
+/// Аннотация для объявления зависимости как синглтона.
+///
+/// Используйте `@singleton()` для методов-провайдеров внутри модуля,
+/// чтобы указать, что соответствующий объект должен быть создан
+/// единожды и использоваться во всём приложении (общий синглтон).
+/// Это характерно для систем внедрения зависимостей и сервис-локаторов,
+/// чтобы гарантировать один общий экземпляр.
+///
+/// Пример:
+/// ```dart
+/// @module()
+/// abstract class AppModule extends Module {
+///   @singleton()
+///   Dio dio() => Dio();
+/// }
+/// ```
+///
+/// Будет сгенерирован следующий код:
 /// ```dart
 /// final class $AppModule extends AppModule {
 ///   @override

cherrypick_annotations/pubspec.yaml

@@ -1,8 +1,9 @@
 name: cherrypick_annotations
-description: Collection annotations.
+description: |
+  Set of annotations for CherryPick dependency injection library. Enables code generation and declarative DI for Dart & Flutter projects.
 version: 1.1.0-dev.0
 documentation: https://github.com/pese-git/cherrypick/wiki
-repository: https://github.com/pese-git/cherrypick
+repository: https://github.com/pese-git/cherrypick/cherrypick_annotations
 issue_tracker: https://github.com/pese-git/cherrypick/issues
 
 environment:

cherrypick_generator/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.1.0-dev.2
+
+ - **FIX**: update instance generator code.
+
 ## 1.1.0-dev.1
 
  - **FIX**: optimize code.

cherrypick_generator/lib/src/bind_spec.dart

@@ -125,9 +125,11 @@ class BindSpec {
     final multiLine = fnArgs.length > 60 || fnArgs.contains('\n');
     switch (bindingType) {
       case BindingType.instance:
-        return isAsyncInstance
-            ? '.toInstanceAsync(($fnArgs) => $methodName($fnArgs))'
-            : '.toInstance(($fnArgs) => $methodName($fnArgs))';
+        throw StateError(
+            'Internal error: _generateWithParamsProvideClause called for @instance binding with @params.');
+      //return isAsyncInstance
+      //    ? '.toInstanceAsync(($fnArgs) => $methodName($fnArgs))'
+      //    : '.toInstance(($fnArgs) => $methodName($fnArgs))';
       case BindingType.provide:
       default:
         if (isAsyncProvide) {
@@ -218,6 +220,15 @@ class BindSpec {
     final bindingType =
         hasInstance ? BindingType.instance : BindingType.provide;
 
+    // PROHIBIT @params with @instance bindings!
+    if (bindingType == BindingType.instance && hasParams) {
+      throw InvalidGenerationSourceError(
+        '@params() (runtime arguments) cannot be used together with @instance() on method $methodName. '
+        'Use @provide() instead if you want runtime arguments.',
+        element: method,
+      );
+    }
+
     // -- Extract inner type for Future<T> and set async flags.
     bool isAsyncInstance = false;
     bool isAsyncProvide = false;

cherrypick_generator/pubspec.yaml

@@ -1,8 +1,10 @@
 name: cherrypick_generator
-description: Code generator for cherrypick annotations
-version: 1.1.0-dev.1
+description: |
+  Source code generator for the cherrypick dependency injection system. Processes annotations to generate binding and module code for Dart & Flutter projects.
+
+version: 1.1.0-dev.2
 documentation: https://github.com/pese-git/cherrypick/wiki
-repository: https://github.com/pese-git/cherrypick
+repository: https://github.com/pese-git/cherrypick/cherrypick_generator
 issue_tracker: https://github.com/pese-git/cherrypick/issues
 
 environment:

examples/client_app/pubspec.lock

@@ -132,7 +132,7 @@ packages:
       path: "../../cherrypick"
       relative: true
     source: path
-    version: "2.2.0-dev.0"
+    version: "2.2.0-dev.1"
   cherrypick_annotations:
     dependency: "direct main"
     description:
@@ -146,14 +146,14 @@ packages:
       path: "../../cherrypick_flutter"
       relative: true
     source: path
-    version: "1.1.2-dev.0"
+    version: "1.1.2-dev.1"
   cherrypick_generator:
     dependency: "direct dev"
     description:
       path: "../../cherrypick_generator"
       relative: true
     source: path
-    version: "1.1.0-dev.0"
+    version: "1.1.0-dev.1"
   clock:
     dependency: transitive
     description:

examples/client_app/pubspec.yaml

@@ -24,7 +24,7 @@ dev_dependencies:
 
   flutter_lints: ^5.0.0
 
-  cherrypick_generator: ^1.1.0-dev.1
+  cherrypick_generator: ^1.1.0-dev.2
   build_runner: ^2.4.13
 
 # For information on the generic Dart part of this file, see the

examples/postly/pubspec.lock

@@ -156,7 +156,7 @@ packages:
       path: "../../cherrypick"
       relative: true
     source: path
-    version: "2.2.0-dev.0"
+    version: "2.2.0-dev.1"
   cherrypick_annotations:
     dependency: "direct main"
     description:
@@ -170,7 +170,7 @@ packages:
       path: "../../cherrypick_generator"
       relative: true
     source: path
-    version: "1.1.0-dev.0"
+    version: "1.1.0-dev.1"
   clock:
     dependency: transitive
     description:

examples/postly/pubspec.yaml

@@ -30,7 +30,7 @@ dev_dependencies:
 
   flutter_lints: ^5.0.0
 
-  cherrypick_generator: ^1.1.0-dev.1
+  cherrypick_generator: ^1.1.0-dev.2
   build_runner: 2.4.13
   
   retrofit_generator: ^9.1.5