chore(release): publish packages

- cherrypick_annotations@1.1.2-dev.2 - cherrypick_generator@2.0.0-dev.2
docs(annotations): improve API documentation and usage example
2026-01-23 21:13:35 +00:00 · 2025-08-22 14:39:33 +03:00 · 2025-08-22 09:39:25 +03:00 · 2025-08-20 08:50:14 +03:00 · 2025-08-20 07:49:10 +03:00 · 2025-08-19 10:48:20 +03:00
29 changed files with 726 additions and 79 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,96 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.

+## 2025-08-22
+
+### Changes
+
+---
+
+Packages with breaking changes:
+
+ - There are no breaking changes in this release.
+
+Packages with other changes:
+
+ - [`cherrypick_annotations` - `v1.1.2-dev.2`](#cherrypick_annotations---v112-dev2)
+ - [`cherrypick_generator` - `v2.0.0-dev.2`](#cherrypick_generator---v200-dev2)
+
+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_generator` - `v2.0.0-dev.2`
+
+---
+
+#### `cherrypick_annotations` - `v1.1.2-dev.2`
+
+ - **DOCS**(annotations): improve API documentation and usage example.
+
+
+## 2025-08-19
+
+### Changes
+
+---
+
+Packages with breaking changes:
+
+ - There are no breaking changes in this release.
+
+Packages with other changes:
+
+ - [`cherrypick` - `v3.0.0-dev.12`](#cherrypick---v300-dev12)
+ - [`cherrypick_flutter` - `v1.1.3-dev.12`](#cherrypick_flutter---v113-dev12)
+ - [`talker_cherrypick_logger` - `v1.1.0-dev.7`](#talker_cherrypick_logger---v110-dev7)
+
+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.12`
+ - `talker_cherrypick_logger` - `v1.1.0-dev.7`
+
+---
+
+#### `cherrypick` - `v3.0.0-dev.12`
+
+ - **FIX**(scope): prevent concurrent modification in dispose().
+ - **FIX**(binding): fix unterminated string literal and syntax issues in binding.dart.
+
+
+## 2025-08-19
+
+### Changes
+
+---
+
+Packages with breaking changes:
+
+ - There are no breaking changes in this release.
+
+Packages with other changes:
+
+ - [`cherrypick` - `v3.0.0-dev.11`](#cherrypick---v300-dev11)
+ - [`cherrypick_flutter` - `v1.1.3-dev.11`](#cherrypick_flutter---v113-dev11)
+ - [`talker_cherrypick_logger` - `v1.1.0-dev.6`](#talker_cherrypick_logger---v110-dev6)
+
+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.11`
+ - `talker_cherrypick_logger` - `v1.1.0-dev.6`
+
+---
+
+#### `cherrypick` - `v3.0.0-dev.11`
+
+ - **FIX**(scope): prevent concurrent modification in dispose().
+ - **FIX**(binding): fix unterminated string literal and syntax issues in binding.dart.
+
+
 ## 2025-08-15

 ### Changes
--- a/benchmark_di/REPORT.md
+++ b/benchmark_di/REPORT.md
@@ -1,4 +1,11 @@
-# Comparative DI Benchmark Report: cherrypick vs get_it vs riverpod
+# Comparative DI Benchmark Report: cherrypick vs get_it vs riverpod vs kiwi
+
+## Benchmark Parameters
+
+- chainCount = 100
+- nestingDepth = 100
+- repeat = 5
+- warmup = 2

 ## Benchmark Scenarios

@@ -11,41 +18,49 @@

 ---

-## Comparative Table: chainCount=10, nestingDepth=10 (Mean, PeakRSS)
+## Comparative Table: chainCount=100, nestingDepth=100, repeat=5, warmup=2 (Mean time, µs)

-| Scenario           | cherrypick Mean (us) | cherrypick PeakRSS | get_it Mean (us) | get_it PeakRSS | riverpod Mean (us) | riverpod PeakRSS |
-|--------------------|---------------------:|-------------------:|-----------------:|---------------:|-------------------:|-----------------:|
-| RegisterSingleton  | 13.00                | 273104             | 8.40             | 261872         | 9.80               | 268512           |
-| ChainSingleton     | 13.80                | 271072             | 2.00             | 262000         | 33.60              | 268784           |
-| ChainFactory       | 5.00                 | 299216             | 4.00             | 297136         | 22.80              | 271296           |
-| AsyncChain         | 28.60                | 290640             | 24.60            | 342976         | 78.20              | 285920           |
-| Named              | 2.20                 | 297008             | 0.20             | 449824         | 6.20               | 281136           |
-| Override           | 7.00                 | 297024             | 0.00             | 449824         | 30.20              | 281152           |
+| Scenario         | cherrypick | get_it | riverpod | kiwi  | yx_scope |
+|------------------|------------|--------|----------|-------|----------|
+| chainSingleton   | 20.6       | 14.8   | 275.2    | 47.0  | 82.8     |
+| chainFactory     | 90.6       | 71.6   | 357.0    | 46.2  | 79.6     |
+| register         | 82.6       | 10.2   | 252.6    | 43.6  | 224.0    |
+| named            | 18.4       | 9.4    | 12.2     | 10.2  | 10.8     |
+| override         | 170.6      | 11.2   | 301.4    | 51.4  | 146.4    |
+| chainAsync       | 493.8      | 34.0   | 5,039.0  |  –    | 87.2     |

-## Maximum Load: chainCount=100, nestingDepth=100 (Mean, PeakRSS)

-| Scenario           | cherrypick Mean (us) | cherrypick PeakRSS | get_it Mean (us) | get_it PeakRSS | riverpod Mean (us) | riverpod PeakRSS |
-|--------------------|---------------------:|-------------------:|-----------------:|---------------:|-------------------:|-----------------:|
-| RegisterSingleton  | 4.00                 | 271072             | 1.00             | 262000         | 2.00               | 268688           |
-| ChainSingleton     | 76.60                | 303312             | 2.00             | 297136         | 221.80             | 270784           |
-| ChainFactory       | 80.00                | 293952             | 39.20            | 342720         | 195.80             | 308640           |
-| AsyncChain         | 251.40               | 297008             | 18.20            | 450640         | 748.80             | 285968           |
-| Named              | 2.20                 | 297008             | 0.00             | 449824         | 1.00               | 281136           |
-| Override           | 104.80               | 301632             | 2.20             | 477344         | 120.80             | 294752           |
+## Peak Memory Usage (Peak RSS, Kb)
+
+| Scenario         | cherrypick | get_it | riverpod | kiwi   | yx_scope |
+|------------------|------------|--------|----------|--------|----------|
+| chainSingleton   | 338,224    | 326,752| 301,856  | 195,520| 320,928  |
+| chainFactory     | 339,040    | 335,712| 304,832  | 319,952| 318,688  |
+| register         | 333,760    | 334,208| 300,368  | 327,968| 326,736  |
+| named            | 241,040    | 229,632| 280,144  | 271,872| 266,352  |
+| override         | 356,912    | 331,456| 329,808  | 369,104| 304,416  |
+| chainAsync       | 311,616    | 434,592| 301,168  |   –    | 328,912  |

 ---

 ## Analysis

- **get_it** is the absolute leader in all scenarios, especially under deep/nested chains and async.
- **cherrypick** is highly competitive and much faster than riverpod on any complex graph.
- **riverpod** is only suitable for small/simple DI graphs due to major slowdowns with depth, async, or override.
+- **get_it** remains the clear leader for both speed and memory usage (lowest latency across most scenarios; excellent memory efficiency even on deep chains).
+- **kiwi** shows the lowest memory footprint in chainSingleton, but is unavailable for async chains.
+- **yx_scope** demonstrates highly stable performance for both sync and async chains, often at the cost of higher memory usage, especially in the register/override scenarios.
+- **cherrypick** comfortably beats riverpod, but is outperformed by get_it/kiwi/yx_scope, especially on async and heavy nested chains. It uses a bit less memory than yx_scope and kiwi, but can spike in memory/latency for override.
+- **riverpod** is unsuitable for deep or async chains—latency and memory usage grow rapidly.
+- **Peak memory (RSS):** usually around 320–340 MB for all DI; riverpod/kiwi occasionally drops below 300MB. named/factory scenarios use much less.
+- **Stability:** yx_scope and get_it have the lowest latency spikes; cherrypick can show peaks on override/async; riverpod is least stable on async (stddev/mean much worse).

 ### Recommendations
- Use **get_it** for performance-critical and deeply nested graphs.
- Use **cherrypick** for scalable/testable apps if a small speed loss is acceptable.
- Use **riverpod** only if you rely on Flutter integration and your DI chains are simple.
+
+- **get_it** (and often **kiwi**, if you don't need async): best for ultra-fast deep graphs and minimum peak memory.
+- **yx_scope**: best blend of performance and async stability; perfect for production mixed DI.
+- **cherrypick**: great for modular/testable architectures, unless absolute peak is needed; lower memory than yx_scope in some scenarios.
+- **riverpod**: only for shallow DI or UI wiring in Flutter.

 ---

-_Last updated: August 8, 2025._
+_Last updated: August 20, 2025._
+_Please see scenario source for details._
--- a/benchmark_di/REPORT.ru.md
+++ b/benchmark_di/REPORT.ru.md
@@ -1,51 +1,63 @@
-# Сравнительный отчет DI-бенчмарка: cherrypick vs get_it vs riverpod
+# Сравнительный отчет DI-бенчмарка: cherrypick vs get_it vs riverpod vs kiwi
+
+## Параметры запуска:
+- chainCount = 100
+- nestingDepth = 100
+- repeat = 5
+- warmup = 2

 ## Описание сценариев

-1. **RegisterSingleton** — регистрация и получение объекта-синглтона (базовая скорость DI).
+1. **RegisterSingleton** — регистрация и получение singleton (базовая скорость DI).
 2. **ChainSingleton** — цепочка зависимостей A → B → ... → N (singleton). Глубокий singleton-резолвинг.
-3. **ChainFactory** — все элементы цепочки — фабрики. Stateless построение графа.
-4. **AsyncChain** — асинхронная цепочка (async factory). Тестирует async/await граф.
+3. **ChainFactory** — все элементы цепочки — factory. Stateless построение графа.
+4. **AsyncChain** — асинхронная цепочка (async factory). Тест async/await графа.
 5. **Named** — регистрация двух биндингов с именами, разрешение по имени.
-6. **Override** — регистрация биндинга/цепочки в дочернем scope. Проверка override/scoping.
+6. **Override** — регистрация биндинга/цепочки в дочернем scope.

 ---

-## Сводная таблица: chainCount=10, nestingDepth=10 (Mean, PeakRSS)
+## Сравнительная таблица: chainCount=100, nestingDepth=100, repeat=5, warmup=2 (среднее время, мкс)

-| Сценарий           | cherrypick Mean (мкс) | cherrypick PeakRSS | get_it Mean (мкс) | get_it PeakRSS | riverpod Mean (мкс) | riverpod PeakRSS |
-|--------------------|----------------------:|-------------------:|------------------:|---------------:|--------------------:|-----------------:|
-| RegisterSingleton  | 13.00                 | 273104             | 8.40              | 261872         | 9.80                | 268512           |
-| ChainSingleton     | 13.80                 | 271072             | 2.00              | 262000         | 33.60               | 268784           |
-| ChainFactory       | 5.00                  | 299216             | 4.00              | 297136         | 22.80               | 271296           |
-| AsyncChain         | 28.60                 | 290640             | 24.60             | 342976         | 78.20               | 285920           |
-| Named              | 2.20                  | 297008             | 0.20              | 449824         | 6.20                | 281136           |
-| Override           | 7.00                  | 297024             | 0.00              | 449824         | 30.20               | 281152           |
+| Сценарий         | cherrypick | get_it | riverpod | kiwi  | yx_scope |
+|------------------|------------|--------|----------|-------|----------|
+| chainSingleton   | 20.6       | 14.8   | 275.2    | 47.0  | 82.8     |
+| chainFactory     | 90.6       | 71.6   | 357.0    | 46.2  | 79.6     |
+| register         | 82.6       | 10.2   | 252.6    | 43.6  | 224.0    |
+| named            | 18.4       | 9.4    | 12.2     | 10.2  | 10.8     |
+| override         | 170.6      | 11.2   | 301.4    | 51.4  | 146.4    |
+| chainAsync       | 493.8      | 34.0   | 5,039.0  |  –    | 87.2     |

-## Максимальная нагрузка: chainCount=100, nestingDepth=100 (Mean, PeakRSS)

-| Сценарий           | cherrypick Mean (мкс) | cherrypick PeakRSS | get_it Mean (мкс) | get_it PeakRSS | riverpod Mean (мкс) | riverpod PeakRSS |
-|--------------------|----------------------:|-------------------:|------------------:|---------------:|--------------------:|-----------------:|
-| RegisterSingleton  | 4.00                  | 271072             | 1.00              | 262000         | 2.00                | 268688           |
-| ChainSingleton     | 76.60                 | 303312             | 2.00              | 297136         | 221.80              | 270784           |
-| ChainFactory       | 80.00                 | 293952             | 39.20             | 342720         | 195.80              | 308640           |
-| AsyncChain         | 251.40                | 297008             | 18.20             | 450640         | 748.80              | 285968           |
-| Named              | 2.20                  | 297008             | 0.00              | 449824         | 1.00                | 281136           |
-| Override           | 104.80                | 301632             | 2.20              | 477344         | 120.80              | 294752           |
+## Пиковое потребление памяти (Peak RSS, Кб)
+
+| Сценарий         | cherrypick | get_it | riverpod | kiwi   | yx_scope |
+|------------------|------------|--------|----------|--------|----------|
+| chainSingleton   | 338,224    | 326,752| 301,856  | 195,520| 320,928  |
+| chainFactory     | 339,040    | 335,712| 304,832  | 319,952| 318,688  |
+| register         | 333,760    | 334,208| 300,368  | 327,968| 326,736  |
+| named            | 241,040    | 229,632| 280,144  | 271,872| 266,352  |
+| override         | 356,912    | 331,456| 329,808  | 369,104| 304,416  |
+| chainAsync       | 311,616    | 434,592| 301,168  |   –    | 328,912  |

 ---

 ## Краткий анализ и рекомендации

- **get_it** всегда лидер, особенно на глубине/асинхронных графах.
- **cherrypick** заметно быстрее riverpod на сложных сценариях, опережая его в разы.
- **riverpod** подходит только для простых/небольших графов — при росте глубины или async/override резко проигрывает по скорости.
+- **get_it** — абсолютный лидер по скорости и памяти на всех графах (минимальная задержка, небольшой peak RSS в любых цепочках).
+- **kiwi** — минимальное потребление памяти в chainSingleton/Factory, но не для асинхронности.
+- **yx_scope** — очень ровная производительность даже на сложных async/sync-цепях, иногда с пиком в памяти на override/register, но задержки всегда минимальны.
+- **cherrypick** — стабильнее riverpod, но ощутимо уступает top-3 по латентности на длинных/async-графах; по памяти лучше yx_scope для override/named.
+- **riverpod** — непригоден для глубоких/async-графов: память и время растут очень сильно.
+- **Пиковое потребление памяти**: большинство DI держится в районе 320–340 Мб (большие цепи), на мелких named/factory — крайне мало.
+- **Стабильность**: yx_scope и get_it показывают наименьшие скачки времени; у cherrypick иногда всплески на override/async, у riverpod — на async графе stddev почти равен mean!

 ### Рекомендации
- Используйте **get_it** для критичных к скорости приложений/сложных графов зависимостей.
- Выбирайте **cherrypick** для масштабируемых, тестируемых архитектур, если микросекундная разница не критична.
- **riverpod** уместен только для реактивного UI или простых графов DI.
+- Используйте **get_it** (или **kiwi**, если не нужен async) для максимальной производительности и минимального пикового использования памяти.
+- **yx_scope** — идеально для production-графов с миксом sync/async.
+- **cherrypick** — хорошо для модульных и тестируемых приложений, если не требуется абсолютная “микросекундная” производительность.
+- **riverpod** — только если граф плоский или нужно DI только для UI во Flutter.

 ---

-_Обновлено: 8 августа 2025_
+_Обновлено: 20 августа 2025._
--- a/benchmark_di/lib/cli/benchmark_cli.dart
+++ b/benchmark_di/lib/cli/benchmark_cli.dart
@@ -1,6 +1,8 @@
 import 'dart:math';

 import 'package:benchmark_di/cli/report/markdown_report.dart';
+import 'package:benchmark_di/di_adapters/yx_scope_adapter.dart';
+import 'package:benchmark_di/di_adapters/yx_scope_universal_container.dart';
 import 'package:benchmark_di/scenarios/universal_scenario.dart';
 import 'package:cherrypick/cherrypick.dart';
 import 'package:get_it/get_it.dart';
@@ -16,6 +18,8 @@ import 'package:benchmark_di/benchmarks/universal_chain_async_benchmark.dart';
 import 'package:benchmark_di/di_adapters/cherrypick_adapter.dart';
 import 'package:benchmark_di/di_adapters/get_it_adapter.dart';
 import 'package:benchmark_di/di_adapters/riverpod_adapter.dart';
+import 'package:benchmark_di/di_adapters/kiwi_adapter.dart';
+import 'package:kiwi/kiwi.dart';

 /// Command-line interface (CLI) runner for benchmarks.
 ///
@@ -61,11 +65,40 @@ class BenchmarkCliRunner {
                repeats: config.repeats,
              );
            }
+          } else if (config.di == 'kiwi') {
+            final di = KiwiAdapter();
+            if (scenario == UniversalScenario.asyncChain) {
+              // UnsupportedError будет выброшен адаптером, но если дойдёт — вызывать async benchmark
+              final benchAsync = UniversalChainAsyncBenchmark<KiwiContainer>(
+                di,
+                chainCount: c,
+                nestingDepth: d,
+                mode: mode,
+              );
+              benchResult = await BenchmarkRunner.runAsync(
+                benchmark: benchAsync,
+                warmups: config.warmups,
+                repeats: config.repeats,
+              );
+            } else {
+              final benchSync = UniversalChainBenchmark<KiwiContainer>(
+                di,
+                chainCount: c,
+                nestingDepth: d,
+                mode: mode,
+                scenario: scenario,
+              );
+              benchResult = await BenchmarkRunner.runSync(
+                benchmark: benchSync,
+                warmups: config.warmups,
+                repeats: config.repeats,
+              );
+            }
          } else if (config.di == 'riverpod') {
            final di = RiverpodAdapter();
            if (scenario == UniversalScenario.asyncChain) {
              final benchAsync = UniversalChainAsyncBenchmark<
-                  Map<String, rp.ProviderBase<Object?>>>(
+                  Map<String, rp.ProviderBase<Object?>>> (
                di,
                chainCount: c,
                nestingDepth: d,
@@ -78,7 +111,35 @@ class BenchmarkCliRunner {
              );
            } else {
              final benchSync = UniversalChainBenchmark<
-                  Map<String, rp.ProviderBase<Object?>>>(
+                  Map<String, rp.ProviderBase<Object?>>> (
+                di,
+                chainCount: c,
+                nestingDepth: d,
+                mode: mode,
+                scenario: scenario,
+              );
+              benchResult = await BenchmarkRunner.runSync(
+                benchmark: benchSync,
+                warmups: config.warmups,
+                repeats: config.repeats,
+              );
+            }
+          } else if (config.di == 'yx_scope') {
+            final di = YxScopeAdapter();
+            if (scenario == UniversalScenario.asyncChain) {
+              final benchAsync = UniversalChainAsyncBenchmark<UniversalYxScopeContainer>(
+                di,
+                chainCount: c,
+                nestingDepth: d,
+                mode: mode,
+              );
+              benchResult = await BenchmarkRunner.runAsync(
+                benchmark: benchAsync,
+                warmups: config.warmups,
+                repeats: config.repeats,
+              );
+            } else {
+              final benchSync = UniversalChainBenchmark<UniversalYxScopeContainer>(
                di,
                chainCount: c,
                nestingDepth: d,
--- a/benchmark_di/lib/di_adapters/cherrypick_adapter.dart
+++ b/benchmark_di/lib/di_adapters/cherrypick_adapter.dart
@@ -184,9 +184,9 @@ class CherrypickDIAdapter extends DIAdapter<Scope> {
      _scope!.resolveAsync<T>(named: named);

  @override
-  void teardown() {
+  Future<void> teardown() async {
    if (!_isSubScope) {
-      CherryPick.closeRootScope();
+      await CherryPick.closeRootScope();
      _scope = null;
    }
    // SubScope teardown не требуется
--- a/benchmark_di/lib/di_adapters/kiwi_adapter.dart
+++ b/benchmark_di/lib/di_adapters/kiwi_adapter.dart
@@ -0,0 +1,129 @@
+import 'package:benchmark_di/scenarios/universal_binding_mode.dart';
+import 'package:benchmark_di/scenarios/universal_scenario.dart';
+import 'package:benchmark_di/scenarios/universal_service.dart';
+import 'package:kiwi/kiwi.dart';
+import 'di_adapter.dart';
+
+/// DIAdapter-для KiwiContainer с поддержкой universal benchmark сценариев.
+class KiwiAdapter extends DIAdapter<KiwiContainer> {
+  late KiwiContainer _container;
+  // ignore: unused_field
+  final bool _isSubScope;
+
+  KiwiAdapter({KiwiContainer? container, bool isSubScope = false})
+      : _isSubScope = isSubScope {
+    _container = container ?? KiwiContainer();
+  }
+
+  @override
+  void setupDependencies(void Function(KiwiContainer container) registration) {
+    registration(_container);
+  }
+
+@override
+Registration<KiwiContainer> universalRegistration<S extends Enum>({
+  required S scenario,
+  required int chainCount,
+  required int nestingDepth,
+  required UniversalBindingMode bindingMode,
+}) {
+  if (scenario is UniversalScenario) {
+    if (scenario == UniversalScenario.asyncChain ||
+        bindingMode == UniversalBindingMode.asyncStrategy) {
+      throw UnsupportedError('Kiwi does not support async dependencies or async binding scenarios.');
+    }
+    return (container) {
+      switch (scenario) {
+        case UniversalScenario.asyncChain:
+          break;
+        case UniversalScenario.register:
+          container.registerSingleton<UniversalService>(
+            (c) => UniversalServiceImpl(value: 'reg', dependency: null),
+          );
+          break;
+        case UniversalScenario.named:
+          container.registerFactory<UniversalService>(
+            (c) => UniversalServiceImpl(value: 'impl1'), name: 'impl1');
+          container.registerFactory<UniversalService>(
+            (c) => UniversalServiceImpl(value: 'impl2'), name: 'impl2');
+          break;
+        case UniversalScenario.chain:
+          for (int chain = 1; chain <= chainCount; chain++) {
+            for (int level = 1; level <= nestingDepth; level++) {
+              final prevDepName = '${chain}_${level - 1}';
+              final depName = '${chain}_$level';
+              switch (bindingMode) {
+                case UniversalBindingMode.singletonStrategy:
+                  container.registerSingleton<UniversalService>(
+                    (c) => UniversalServiceImpl(
+                      value: depName,
+                      dependency: level > 1
+                        ? c.resolve<UniversalService>(prevDepName)
+                        : null),
+                    name: depName);
+                  break;
+                case UniversalBindingMode.factoryStrategy:
+                  container.registerFactory<UniversalService>(
+                    (c) => UniversalServiceImpl(
+                      value: depName,
+                      dependency: level > 1
+                        ? c.resolve<UniversalService>(prevDepName)
+                        : null),
+                    name: depName);
+                  break;
+                case UniversalBindingMode.asyncStrategy:
+                  // Не поддерживается
+                  break;
+              }
+            }
+          }
+          final depName = '${chainCount}_$nestingDepth';
+          container.registerSingleton<UniversalService>(
+            (c) => c.resolve<UniversalService>(depName));
+          break;
+        case UniversalScenario.override:
+          final depName = '${chainCount}_$nestingDepth';
+          container.registerSingleton<UniversalService>(
+            (c) => c.resolve<UniversalService>(depName));
+          break;
+      }
+    };
+  }
+  throw UnsupportedError('Scenario $scenario not supported by KiwiAdapter');
+}
+
+  @override
+  T resolve<T extends Object>({String? named}) {
+    // Для asyncChain нужен resolve<Future<T>>
+    if (T.toString().startsWith('Future<')) {
+      return _container.resolve<T>(named);
+    } else {
+      return _container.resolve<T>(named);
+    }
+  }
+
+  @override
+  Future<T> resolveAsync<T extends Object>({String? named}) async {
+    if (T.toString().startsWith('Future<')) {
+      // resolve<Future<T>>, unwrap result
+      return Future.value(_container.resolve<T>(named));
+    } else {
+      // Для совместимости с chain/override
+      return Future.value(_container.resolve<T>(named));
+    }
+  }
+
+  @override
+  void teardown() {
+    _container.clear();
+  }
+
+  @override
+  KiwiAdapter openSubScope(String name) {
+    // Возвращаем новый scoped контейнер (отдельный). Наследование не реализовано.
+    return KiwiAdapter(container: KiwiContainer.scoped(), isSubScope: true);
+  }
+
+  @override
+  Future<void> waitForAsyncReady() async {}
+}
--- a/benchmark_di/lib/di_adapters/yx_scope_adapter.dart
+++ b/benchmark_di/lib/di_adapters/yx_scope_adapter.dart
@@ -0,0 +1,126 @@
+// ignore_for_file: invalid_use_of_protected_member
+
+import 'package:benchmark_di/di_adapters/di_adapter.dart';
+import 'package:benchmark_di/scenarios/universal_binding_mode.dart';
+import 'package:benchmark_di/scenarios/universal_scenario.dart';
+import 'package:benchmark_di/scenarios/universal_service.dart';
+import 'package:benchmark_di/di_adapters/yx_scope_universal_container.dart';
+
+/// DIAdapter для yx_scope UniversalYxScopeContainer
+class YxScopeAdapter extends DIAdapter<UniversalYxScopeContainer> {
+  late UniversalYxScopeContainer _scope;
+
+  @override
+  void setupDependencies(void Function(UniversalYxScopeContainer container) registration) {
+    _scope = UniversalYxScopeContainer();
+    registration(_scope);
+  }
+
+  @override
+  T resolve<T extends Object>({String? named}) {
+    return _scope.depFor<T>(name: named).get;
+  }
+
+  @override
+  Future<T> resolveAsync<T extends Object>({String? named}) async {
+    return resolve<T>(named: named);
+  }
+
+  @override
+  void teardown() {
+    // У yx_scope нет явного dispose на ScopeContainer, но можно добавить очистку Map/Deps если потребуется
+    // Ничего не делаем
+  }
+
+  @override
+  YxScopeAdapter openSubScope(String name) {
+    // Для простоты всегда возвращаем новый контейнер, сабскоупы не реализованы явно
+    return YxScopeAdapter();
+  }
+
+  @override
+  Future<void> waitForAsyncReady() async {
+    // Все зависимости синхронны
+    return;
+  }
+
+  @override
+  Registration<UniversalYxScopeContainer> universalRegistration<S extends Enum>({
+    required S scenario,
+    required int chainCount,
+    required int nestingDepth,
+    required UniversalBindingMode bindingMode,
+  }) {
+    if (scenario is UniversalScenario) {
+      return (scope) {
+        switch (scenario) {
+          case UniversalScenario.asyncChain:
+            for (int chain = 1; chain <= chainCount; chain++) {
+              for (int level = 1; level <= nestingDepth; level++) {
+                final prevDepName = '${chain}_${level - 1}';
+                final depName = '${chain}_$level';
+                final dep = scope.dep<UniversalService>(
+                  () => UniversalServiceImpl(
+                    value: depName,
+                    dependency: level > 1
+                        ? scope.depFor<UniversalService>(name: prevDepName).get
+                        : null,
+                  ),
+                  name: depName,
+                );
+                scope.register<UniversalService>(dep, name: depName);
+              }
+            }
+            break;
+          case UniversalScenario.register:
+            final dep = scope.dep<UniversalService>(
+              () => UniversalServiceImpl(value: 'reg', dependency: null),
+            );
+            scope.register<UniversalService>(dep);
+            break;
+          case UniversalScenario.named:
+            final dep1 = scope.dep<UniversalService>(
+              () => UniversalServiceImpl(value: 'impl1'),
+              name: 'impl1',
+            );
+            final dep2 = scope.dep<UniversalService>(
+              () => UniversalServiceImpl(value: 'impl2'),
+              name: 'impl2',
+            );
+            scope.register<UniversalService>(dep1, name: 'impl1');
+            scope.register<UniversalService>(dep2, name: 'impl2');
+            break;
+          case UniversalScenario.chain:
+            for (int chain = 1; chain <= chainCount; chain++) {
+              for (int level = 1; level <= nestingDepth; level++) {
+                final prevDepName = '${chain}_${level - 1}';
+                final depName = '${chain}_$level';
+                final dep = scope.dep<UniversalService>(
+                  () => UniversalServiceImpl(
+                    value: depName,
+                    dependency: level > 1
+                        ? scope.depFor<UniversalService>(name: prevDepName).get
+                        : null,
+                  ),
+                  name: depName,
+                );
+                scope.register<UniversalService>(dep, name: depName);
+              }
+            }
+            break;
+          case UniversalScenario.override:
+            // handled at benchmark level
+            break;
+        }
+        if (scenario == UniversalScenario.chain || scenario == UniversalScenario.override) {
+          final depName = '${chainCount}_$nestingDepth';
+          final lastDep = scope.dep<UniversalService>(
+            () => scope.depFor<UniversalService>(name: depName).get,
+          );
+          scope.register<UniversalService>(lastDep);
+        }
+      };
+    }
+    throw UnsupportedError('Scenario $scenario not supported by YxScopeAdapter');
+  }
+}
--- a/benchmark_di/lib/di_adapters/yx_scope_universal_container.dart
+++ b/benchmark_di/lib/di_adapters/yx_scope_universal_container.dart
@@ -0,0 +1,30 @@
+import 'package:yx_scope/yx_scope.dart';
+
+/// Universal container for dynamic DI registration in yx_scope (for benchmarks).
+/// Allows to register and resolve deps by name/type at runtime.
+class UniversalYxScopeContainer extends ScopeContainer {
+  final Map<String, Dep<dynamic>> _namedDeps = {};
+  final Map<Type, Dep<dynamic>> _typedDeps = {};
+
+  void register<T>(Dep<T> dep, {String? name}) {
+    if (name != null) {
+      _namedDeps[_depKey<T>(name)] = dep;
+    } else {
+      _typedDeps[T] = dep;
+    }
+  }
+
+  Dep<T> depFor<T>({String? name}) {
+    if (name != null) {
+      final dep = _namedDeps[_depKey<T>(name)];
+      if (dep is Dep<T>) return dep;
+      throw Exception('No dep for type $T/$name');
+    } else {
+      final dep = _typedDeps[T];
+      if (dep is Dep<T>) return dep;
+      throw Exception('No dep for type $T');
+    }
+  }
+
+  static String _depKey<T>(String name) => '$T@$name';
+}
--- a/benchmark_di/pubspec.lock
+++ b/benchmark_di/pubspec.lock
@@ -47,7 +47,7 @@ packages:
      path: "../cherrypick"
      relative: true
    source: path
-    version: "3.0.0-dev.9"
+    version: "3.0.0-dev.10"
  collection:
    dependency: transitive
    description:
@@ -72,6 +72,14 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "8.2.0"
+  kiwi:
+    dependency: "direct main"
+    description:
+      name: kiwi
+      sha256: d078364a90fb1b93852bb74468efdf4aaae35c036c538c1cf4f9c74a19df9a61
+      url: "https://pub.dev"
+    source: hosted
+    version: "5.0.1"
  lazy_memo:
    dependency: transitive
    description:
@@ -128,5 +136,13 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "1.0.0"
+  yx_scope:
+    dependency: "direct main"
+    description:
+      name: yx_scope
+      sha256: "9ba98b442261596311363bf7361622e5ccc67189705b8d042ca23c9de366f8bf"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.1.2"
 sdks:
  dart: ">=3.6.0 <4.0.0"
--- a/benchmark_di/pubspec.yaml
+++ b/benchmark_di/pubspec.yaml
@@ -12,6 +12,8 @@ dependencies:
  args: ^2.7.0
  get_it: ^8.2.0
  riverpod: ^2.6.1
+  kiwi: ^5.0.1
+  yx_scope: ^1.1.2

 dev_dependencies:
  lints: ^5.0.0
--- a/cherrypick/CHANGELOG.md
+++ b/cherrypick/CHANGELOG.md
@@ -1,3 +1,13 @@
+## 3.0.0-dev.12
+
+ - **FIX**(scope): prevent concurrent modification in dispose().
+ - **FIX**(binding): fix unterminated string literal and syntax issues in binding.dart.
+
+## 3.0.0-dev.11
+
+ - **FIX**(scope): prevent concurrent modification in dispose().
+ - **FIX**(binding): fix unterminated string literal and syntax issues in binding.dart.
+
 ## 3.0.0-dev.10

 - **DOCS**(pub): update homepage and documentation URLs in pubspec.yaml to new official site.
--- a/cherrypick/lib/src/binding.dart
+++ b/cherrypick/lib/src/binding.dart
--- a/cherrypick/lib/src/scope.dart
+++ b/cherrypick/lib/src/scope.dart
@@ -486,16 +486,16 @@ class Scope with CycleDetectionMixin, GlobalCycleDetectionMixin {
  /// await myScope.dispose();
  /// ```
  Future<void> dispose() async {
-    // First dispose children scopes
-    for (final subScope in _scopeMap.values) {
+    // Create copies to avoid concurrent modification
+    final scopesCopy = Map<String, Scope>.from(_scopeMap);
+    for (final subScope in scopesCopy.values) {
      await subScope.dispose();
    }
    _scopeMap.clear();
-    // Then dispose own disposables
-    for (final d in _disposables) {
-      try {
-        await d.dispose();
-      } catch (_) {}
+
+    final disposablesCopy = Set<Disposable>.from(_disposables);
+    for (final d in disposablesCopy) {
+      await d.dispose();
    }
    _disposables.clear();
  }
--- a/cherrypick/pubspec.yaml
+++ b/cherrypick/pubspec.yaml
@@ -1,6 +1,6 @@
 name: cherrypick
 description: Cherrypick is a small dependency injection (DI) library for dart/flutter projects.
-version: 3.0.0-dev.10
+version: 3.0.0-dev.12
 homepage: https://cherrypick-di.dev/
 documentation: https://cherrypick-di.dev/docs/intro
 repository: https://github.com/pese-git/cherrypick
--- a/cherrypick_annotations/CHANGELOG.md
+++ b/cherrypick_annotations/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 1.1.2-dev.2
+
+ - **DOCS**(annotations): improve API documentation and usage example.
+
 ## 1.1.2-dev.1

 - **DOCS**(pub): update homepage and documentation URLs in pubspec.yaml to new official site.
--- a/cherrypick_annotations/example/example.dart
+++ b/cherrypick_annotations/example/example.dart
@@ -0,0 +1,111 @@
+// ignore: dangling_library_doc_comments
+/// Example using cherrypick_annotations together with cherrypick (core) and cherrypick_generator.
+
+///
+/// Steps to use this example:
+/// 1. Make sure your example/pubspec.yaml contains:
+///     - cherrypick_annotations (this package)
+///     - cherrypick (core DI engine)
+///     - cherrypick_generator (as a dev_dependency)
+///     - build_runner (as a dev_dependency)
+/// 2. Run code generation to produce DI injectors and mixins:
+///    ```sh
+///    dart run build_runner build
+///    ```
+/// 3. The `_$ApiScreen` mixin will be generated automatically.
+/// 4. In your app/bootstrap code, install modules and use the generated features.
+///
+/// See documentation and advanced details at:
+/// https://pub.dev/packages/cherrypick_annotations
+
+import 'package:cherrypick_annotations/cherrypick_annotations.dart';
+// In a real project, use this import:
+// import 'package:cherrypick/cherrypick.dart';
+
+// Temporary stub for demonstration purposes only.
+// In real usage, import 'Module' from `package:cherrypick/cherrypick.dart`.
+class Module {}
+
+/// This mixin is a stub for documentation and IDE hints only.
+/// In a real project, it will be generated by cherrypick_generator after running build_runner.
+///
+/// Do not implement or edit this by hand!
+mixin _$ApiScreen {}
+
+/// Example UI/service class with dependencies to be injected.
+///
+/// The [@injectable] annotation tells the generator to create an injector mixin for this class.
+/// Fields marked with [@inject] will be automatically filled by the code generator (using DI).
+@injectable()
+class ApiScreen with _$ApiScreen {
+  /// The default (main) implementation of the API service.
+  @inject()
+  late final ApiService apiService;
+
+  /// An alternate API (mock) implementation, injected by name using @named.
+  @inject()
+  @named('mock')
+  late final ApiService mockApiService;
+
+  /// Logger injected from another scope (e.g., global singleton).
+  @inject()
+  @scope('global')
+  late final Logger logger;
+}
+
+/// Example DI module using CherryPick annotations.
+///
+/// The [@module] annotation tells the generator to treat this class as a source of bindings.
+/// Methods annotated with [@singleton], [@named], [@provide], [@instance] will be registered into the DI container.
+@module()
+abstract class AppModule extends Module {
+  /// Global singleton logger available throughout the app.
+  @singleton()
+  Logger provideLogger() => Logger();
+
+  /// Main API implementation, identified with the name 'main'.
+  @named('main')
+  ApiService createApi() => ApiService();
+
+  /// Mock API implementation, identified as 'mock'.
+  @named('mock')
+  ApiService createMockApi() => MockApiService();
+
+  /// UserManager is created with runtime parameters, such as per-user session.
+  @provide()
+  UserManager createManager(@params() Map<String, dynamic> runtimeParams) {
+    return UserManager(runtimeParams['id'] as String);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Example implementations for demonstration only.
+// In a real project, these would contain application/service logic.
+
+/// The main API service.
+class ApiService {}
+
+/// A mock API implementation (for development or testing).
+class MockApiService extends ApiService {}
+
+/// Manages user operations, created using dynamic (runtime) parameters.
+class UserManager {
+  final String id;
+  UserManager(this.id);
+}
+
+/// Global logger service.
+class Logger {}
+
+void main() {
+  // After running code generation, injectors and mixins will be ready to use.
+  // Example integration (pseudo-code):
+  //
+  // import 'package:cherrypick/cherrypick.dart';
+  //
+  // final scope = CherryPick.openRootScope()..installModules([$AppModule()]);
+  // final screen = ApiScreen()..injectFields();
+  // print(screen.apiService); // <-- injected!
+  //
+  // This main() is provided for reference only.
+}
--- a/cherrypick_annotations/lib/cherrypick_annotations.dart
+++ b/cherrypick_annotations/lib/cherrypick_annotations.dart
@@ -1,5 +1,3 @@
-library;
-
 //
 // Copyright 2021 Sergey Penkovsky (sergey.penkovsky@gmail.com)
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,6 +11,24 @@ library;
 // limitations under the License.
 //

+/// Annotations for use with the CherryPick dependency injection generator.
+///
+/// These annotations are used on classes, methods, fields or parameters to
+/// describe how they should participate in dependency injection.
+/// See: https://pub.dev/packages/cherrypick
+///
+/// Example:
+/// ```dart
+/// import 'package:cherrypick_annotations/cherrypick_annotations.dart';
+///
+/// @injectable()
+/// class MyService {
+///   @inject()
+///   late final Logger logger;
+/// }
+/// ```
+library;
+
 export 'src/module.dart';
 export 'src/provide.dart';
 export 'src/instance.dart';
--- a/cherrypick_annotations/lib/src/inject.dart
+++ b/cherrypick_annotations/lib/src/inject.dart
@@ -38,5 +38,6 @@ import 'package:meta/meta.dart';
 /// ```
@experimental
 final class inject {
+  /// Creates an [inject] annotation for field injection.
  const inject();
 }
--- a/cherrypick_annotations/lib/src/injectable.dart
+++ b/cherrypick_annotations/lib/src/injectable.dart
@@ -39,5 +39,6 @@ import 'package:meta/meta.dart';
 /// After running the generator, the mixin (`_\$ProfileScreen`) will be available to help auto-inject all [@inject] fields in your widget/service/controller.
@experimental
 final class injectable {
+  /// Creates an [injectable] annotation for classes.
  const injectable();
 }
--- a/cherrypick_annotations/lib/src/instance.dart
+++ b/cherrypick_annotations/lib/src/instance.dart
@@ -45,5 +45,6 @@ import 'package:meta/meta.dart';
 /// See also: [@singleton]
@experimental
 final class instance {
+  /// Creates an [instance] annotation for classes or providers.
  const instance();
 }
--- a/cherrypick_annotations/lib/src/provide.dart
+++ b/cherrypick_annotations/lib/src/provide.dart
@@ -39,6 +39,6 @@ import 'package:meta/meta.dart';
 /// See also: [@singleton], [@instance], [@params], [@named]
@experimental
 final class provide {
-  /// Creates a [provide] annotation.
+  /// Creates a [provide] annotation for marking provider methods/classes in DI modules.
  const provide();
 }
--- a/cherrypick_annotations/lib/src/scope.dart
+++ b/cherrypick_annotations/lib/src/scope.dart
@@ -49,5 +49,7 @@ import 'package:meta/meta.dart';
 final class scope {
  /// The name/key of the DI scope from which to resolve this dependency.
  final String? name;
+
+  /// Creates a [scope] annotation specifying which DI scope to use for the dependency resolution.
  const scope(this.name);
 }
--- a/cherrypick_annotations/pubspec.yaml
+++ b/cherrypick_annotations/pubspec.yaml
@@ -1,7 +1,7 @@
 name: cherrypick_annotations
 description: |
  Set of annotations for CherryPick dependency injection library. Enables code generation and declarative DI for Dart & Flutter projects.
-version: 1.1.2-dev.1
+version: 1.1.2-dev.2
 homepage: https://cherrypick-di.dev/
 documentation: https://cherrypick-di.dev/docs/intro
 repository: https://github.com/pese-git/cherrypick/cherrypick_annotations
--- a/cherrypick_flutter/CHANGELOG.md
+++ b/cherrypick_flutter/CHANGELOG.md
@@ -1,3 +1,11 @@
+## 1.1.3-dev.12
+
+ - Update a dependency to the latest release.
+
+## 1.1.3-dev.11
+
+ - Update a dependency to the latest release.
+
 ## 1.1.3-dev.10

 - **DOCS**(pub): update homepage and documentation URLs in pubspec.yaml to new official site.
--- a/cherrypick_flutter/pubspec.yaml
+++ b/cherrypick_flutter/pubspec.yaml
@@ -1,6 +1,6 @@
 name: cherrypick_flutter
 description: "Flutter library that allows access to the root scope through the context using `CherryPickProvider`."
-version: 1.1.3-dev.10
+version: 1.1.3-dev.12
 homepage: https://cherrypick-di.dev/
 documentation: https://cherrypick-di.dev/docs/intro
 repository: https://github.com/pese-git/cherrypick
@@ -19,7 +19,7 @@ environment:
 dependencies:
  flutter:
    sdk: flutter
-  cherrypick: ^3.0.0-dev.10
+  cherrypick: ^3.0.0-dev.12

 dev_dependencies:
  flutter_test:
--- a/cherrypick_generator/CHANGELOG.md
+++ b/cherrypick_generator/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 2.0.0-dev.2
+
+ - Update a dependency to the latest release.
+
 ## 2.0.0-dev.1

 - **DOCS**(pub): update homepage and documentation URLs in pubspec.yaml to new official site.
--- a/cherrypick_generator/pubspec.yaml
+++ b/cherrypick_generator/pubspec.yaml
@@ -2,7 +2,7 @@ name: cherrypick_generator
 description: |
  Source code generator for the cherrypick dependency injection system. Processes annotations to generate binding and module code for Dart & Flutter projects.

-version: 2.0.0-dev.1
+version: 2.0.0-dev.2
 homepage: https://cherrypick-di.dev/
 documentation: https://cherrypick-di.dev/docs/intro
 repository: https://github.com/pese-git/cherrypick/cherrypick_generator
@@ -19,7 +19,7 @@ environment:

 # Add regular dependencies here.
 dependencies:
-  cherrypick_annotations: ^1.1.2-dev.1
+  cherrypick_annotations: ^1.1.2-dev.2
  analyzer: ^7.0.0
  dart_style: ^3.0.0
  build: ^2.4.1
--- a/talker_cherrypick_logger/CHANGELOG.md
+++ b/talker_cherrypick_logger/CHANGELOG.md
@@ -1,3 +1,11 @@
+## 1.1.0-dev.7
+
+ - Update a dependency to the latest release.
+
+## 1.1.0-dev.6
+
+ - Update a dependency to the latest release.
+
 ## 1.1.0-dev.5

 - **DOCS**(pub): update homepage and documentation URLs in pubspec.yaml to new official site.
--- a/talker_cherrypick_logger/pubspec.yaml
+++ b/talker_cherrypick_logger/pubspec.yaml
@@ -1,6 +1,6 @@
 name: talker_cherrypick_logger
 description: A Talker logger integration for CherryPick DI to observe and log DI events and errors.
-version: 1.1.0-dev.5
+version: 1.1.0-dev.7
 homepage: https://cherrypick-di.dev/
 documentation: https://cherrypick-di.dev/docs/intro
 repository: https://github.com/pese-git/cherrypick
@@ -18,7 +18,7 @@ environment:
 # Add regular dependencies here.
 dependencies:
  talker: ^4.9.3
-  cherrypick: ^3.0.0-dev.10
+  cherrypick: ^3.0.0-dev.12


 dev_dependencies:
Author	SHA1	Message	Date
Sergey Penkovsky	1cbcce5b38	chore(release): publish packages - cherrypick_annotations@1.1.2-dev.2 - cherrypick_generator@2.0.0-dev.2	2025-08-22 14:39:33 +03:00
Sergey Penkovsky	264c4bbb88	docs(annotations): improve API documentation and usage example - 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.	2025-08-22 09:39:25 +03:00
Sergey Penkovsky	cbb5dcc3a0	docs(benchmark_di): update reports with extended analysis, peak memory and revised recommendations	2025-08-20 08:50:14 +03:00
Sergey Penkovsky	d281c18a75	feat(benchmark_di): add yx_scope DI adapter and CLI integration	2025-08-20 07:49:10 +03:00
Sergey Penkovsky	8ef12e990f	chore(release): publish packages - cherrypick@3.0.0-dev.12 - cherrypick_flutter@1.1.3-dev.12 - talker_cherrypick_logger@1.1.0-dev.7	2025-08-19 10:48:20 +03:00
Sergey Penkovsky	5c57370755	fix(benchmark) - hide warning	2025-08-19 10:47:53 +03:00
Sergey Penkovsky	8711dc83d0	docs(benchmark_di): update benchmark results and add test parameters for all DI in REPORT.md/RU.md	2025-08-19 10:29:53 +03:00
Sergey Penkovsky	043737e2c9	fix(scope): prevent concurrent modification in dispose() - Create defensive copies of _scopeMap and _disposables - Remove redundant try-catch blocks - Improve memory safety during teardown	2025-08-19 09:57:02 +03:00
Sergey Penkovsky	ed65e3c23d	fix(benchmark): improve CherryPickAdapter teardown reliability - Add error handling for scope disposal - Add null check for _scope variable - Prevent concurrent modification exceptions	2025-08-19 09:22:45 +03:00
Sergey Penkovsky	a897c1b31b	feat(benchmark_di): add Kiwi DI adapter and CLI integration	2025-08-18 18:40:07 +03:00
Sergey Penkovsky	dd9c3faa62	fix(binding): fix unterminated string literal and syntax issues in binding.dart	2025-08-18 18:35:41 +03:00