zenify 2.2.0

Complete state management for Flutter — hierarchical dependency injection, intelligent async caching, and offline-first resilience. Zero boilerplate, automatic cleanup.

2.2.0

Added

• Global Query & Mutation Hooks (Zen.isFetching, Zen.isMutating): Added top-level reactive getters and counters to Zen for effortless global status indicators:
  • Zen.isFetching & Zen.activeFetches (RxInt): Reactive hooks to detect in-flight queries across the app (ideal for top-level progress bars or app bar spinners).
  • Zen.isMutating & Zen.activeMutations (RxInt): Reactive hooks to detect in-flight mutations across the app (ideal for disabling action buttons or showing save overlays).
  • ZenMutation.isMutatingKey(key) & ZenMutation.activeMutationsForKey(key): Query active in-flight mutation status for specific mutation keys.
  • ZenQueryCache.isFetching(...) & ZenQueryCache.isFetchingCount(...): Filter active query fetch status by queryKey, tag, or custom predicate.
• Memory-Bounded Infinite Queries (ZenInfiniteQuery.maxPages): Added maxPages parameter to ZenInfiniteQuery to prevent unbounded memory growth during long scroll sessions. Automatically evicts oldest pages from the head during forward pagination or newest pages from the tail during backward pagination, while maintaining cursor continuity for seamless bidirectional refetching.

---

2.1.1

Fixed

• Sequential Offline Mutation Replay: Enforced strict FIFO ordering and stop-on-failure execution during offline mutation queue replay in ZenMutationQueue. Prevents out-of-order execution in order-sensitive workloads (such as chat sequences and transactions) when network connectivity drops or errors occur.
• ZenQueryConsumer Instance Sharing: Introduced reference-counted query instance resolution in ZenQueryConsumer. Multiple consumer widgets mounted with the exact same queryKey now share a single active ZenQuery instance, completely eliminating duplicate queries and transient dual in-flight fetches.
• Cancellable Retry Delays: Implemented Completer-based delay cancellation in ZenQuery and ZenMutation. Disposing or resetting a query/mutation during an active backoff window cancels the delay immediately. dispose() halts retrying and frees resources; reset() halts retrying and leaves the mutation in idle state, fully reusable.
• ZenMutationQueue Subscription Leak: setNetworkStream now stores and cancels the previous StreamSubscription before subscribing to a new stream. Calling setNetworkStream more than once (e.g. after a hot-restart or test re-init) no longer accumulates duplicate connectivity listeners.

---

2.1.0

Added

• keepPreviousData parameter added to ZenQueryConsumer to prevent loading flashes during pagination.
• ZenQueryCache.prefetch now returns a Future<T?> allowing awaiting of prefetch results.

Fixed

• Stack Overflow Fix: Replaced recursive retries in ZenMutation and ZenQuery with iterative while loops to prevent stack overflow errors under high retry counts or spotty networks.
• Retry Delay Reliability: _calculateRetryDelay now correctly requires a non-nullable error parameter, eliminating a bug where retryDelayFn could receive the wrong exception fallback.
• State Cleanups: Removed orphaned internal state (e.g. _retryAttempt fields) for safer concurrent fetches.

---

2.0.0 — V2 Architecture

This release completes the architectural shift to fully tree-bound dependency injection. Every controller access is now resolved via BuildContext — the same model Flutter uses for Theme, MediaQuery, and Navigator. The result is multi-instance safety by construction, perfect test isolation with zero global teardown, and a mental model that transfers directly to how Flutter works.

Migration: See migration_v2_0_0.md for the full guide.
The mechanical change is adding a controller parameter to every ZenView.build() override.

Breaking Changes

Architecture & lifecycle

• ZenRouteObserver removed. The V1 NavigatorObserver-based controller disposal has been removed. Use ZenRoute instead — it disposes its scope automatically when the widget leaves the tree, with zero manual registration required.
• ZenController.autoDispose and limited workers removed. These were trivially composable using ever() and once().
• getResourceStats()['memory_overhead_estimate'] removed. The hardcoded estimate was misleading without a real heap profiler.
• ZenService now extends ZenController. The standalone duplicate lifecycle implementation has been replaced. ZenService is now abstract class ZenService extends ZenController {}. Consumer code (class MyService extends ZenService) is unchanged. Removed: ZenService.disposeAllServices(), ZenService.activeServiceCount, ZenService.getActiveServiceTypes(), ZenService._activeServices, ensureInitialized(). Services now benefit from full Rx tracking and worker auto-disposal via the ZenController base. Use Zen.reset() in tests instead of ZenService.disposeAllServices().

---

The Three-Step Mental Model

REGISTER  →  Zen.registerModules([AppModule()])      app services — live for app lifetime
              ZenRoute(moduleBuilder: () => M())      route-level — standard for real apps
              ↳ scope.put<T>(T())  inside ZenModule   where controllers are actually created
              ZenProvider.create<T>(create: ...)      simple routes without a module

CONSUME   →  ZenView<T>                 extend — controller injected into build()
              ZenConsumer<T>            compose — inline builder, no inheritance
              context.controller<T>()  imperative — from any widget or callback

REACT     →  ZenObserver               Rx<T> — auto-rebuild on value change
              ZenUpdater<T>             update() — manual, ID-targeted rebuilds
              ZenQuery<T>               async — caching, loading, error, refetch

Key rule: ZenView resolves from the nearest scope automatically. It doesn't matter whether the controller was registered via ZenRoute, ZenProvider, or Zen.put — consumption is always the same zero-boilerplate pattern.

---

Global API cleanup

Removed	Replacement
Zen.currentScope / setCurrentScope / resetCurrentScope	context.zenScope (widget tree) or Zen.rootScope
Zen.get<T>()	Zen.find<T>()
Zen.has<T>()	Zen.exists<T>()
Zen.remove<T>()	Zen.delete<T>()
Obx widget	ZenObserver

Ref<T> is removed entirely. It was a thin wrapper over scope.find() with no additional value.

ZenWorkerHandle renamed to ZenWorker

The handle returned by all ZenWorkers.* factory methods and ZenController.* worker methods is now named ZenWorker. Update any type annotations in your code:

// ❌ V1-style name (removed)
ZenWorkerHandle handle = ZenWorkers.ever(count, (_) => update());

// ✅ V2
ZenWorker worker = ZenWorkers.ever(count, (_) => update());

ZenWorkerGroup is unchanged.

ZenDependencyAnalyzer — REMOVED

ZenDependencyAnalyzer is removed. It contained only stubbed, non-functional implementations. There is no replacement.

ZenConfig — two flags removed

Removed field	Reason
checkForCircularDependencies	No runtime implementation existed — the flag had no effect
enableDependencyVisualization	No runtime implementation existed — the flag had no effect

The corresponding configure() parameters circularDependencyCheck: and dependencyVisualization: are also removed.

ZenMetrics — instrumentation methods and fields removed

The following methods were never called by the library itself (the counters they wrote to were always zero):

Removed method	Removed field
recordRxCreation()	totalRxValues
recordStateUpdate()	totalStateUpdates
recordProviderCreation()	totalProviders
recordEffectSuccess()	totalEffectRuns, totalEffectSuccesses, effectSuccessCounts
recordEffectFailure()	totalEffectFailures, effectFailureCounts

getReport() no longer includes a state or effects block (both were always zeros). The remaining API — incrementCounter, recordCounterValue, startTiming, stopTiming, getAverageDuration, getReport, startPeriodicLogging, stopPeriodicLogging, reset — is unchanged.

ZenRoute — scope resolution bug fixed

ZenRoute no longer mutates a global Zen.currentScope pointer on every push. Scope resolution is now:

1. Explicit parentScope: parameter
2. Nearest ZenProvider ancestor in the widget tree (context.zenScope)
3. Zen.rootScope — stable fallback for top-level routes

Sibling routes pushed via Navigator.push no longer silently inherit each other's scopes.

---

ZenView.build() — explicit controller parameter (required)

V1 provided the controller via a magic controller getter backed by a global static registry. V2 injects it as an explicit parameter — resolved from the nearest ZenProvider ancestor by the framework.

// ❌ V1 — magic getter, global registry
class CartPage extends ZenView<CartController> {
  @override
  Widget build(BuildContext context) {
    return Text('${controller.totalItems}');
  }
}

// ✅ V2 — explicit injection, compiler-enforced
class CartPage extends ZenView<CartController> {
  const CartPage({super.key});

  @override
  Widget build(BuildContext context, CartController controller) {
    return Text('${controller.totalItems}');
  }
}

The migration is mechanical: add , CartController controller to every ZenView.build() override.

ZenScopeWidget renamed to ZenProvider

The canonical provider widget is now ZenProvider. All usages of ZenScopeWidget must be renamed.

// ❌ V1
ZenScopeWidget.create<CartController>(create: () => CartController(), child: ...)

// ✅ V2
ZenProvider.create<CartController>(create: () => CartController(), child: ...)

ZenControllerScope — REMOVED (not deprecated)

ZenControllerScope conflated widget lifecycle with DI lifecycle — two concerns that must be kept separate. It is removed entirely in V2. Replace with ZenProvider.create:

// ❌ V1 — removed
ZenControllerScope<MyController>(
  create: () => MyController(),
  child: MyView(),
)

// ✅ V2
ZenProvider.create<MyController>(
  create: () => MyController(),
  child: const MyView(),
)

initController on ZenView — REMOVED

Per-instance self-owned controller via initController is removed. It tightly coupled widget and DI concerns. Use ZenProvider.create at the callsite instead:

// ❌ V1 — initController override (removed)
class ChatBubble extends ZenView<ChatBubbleController> {
  final String messageId;
  @override
  ChatBubbleController Function() get initController =>
      () => ChatBubbleController(messageId: messageId);
  ...
}

// ✅ V2 — provide at callsite
ZenProvider.create<ChatBubbleController>(
  create: () => ChatBubbleController(messageId: messageId),
  child: const ChatBubble(),
)

_ZenViewRegistry — deleted

The global Map<Type, List<ZenController>> static registry is gone entirely. There is nothing to migrate.

ZenView.scope property — removed

Scope association is done exclusively via ZenProvider in the widget tree.

context.controller<T>() — no global fallback

The global Zen.findOrNull<T>() fallback has been removed from context.controller<T>(). Resolution is strictly tree-bound. If no ZenProvider ancestor provides the type, ZenControllerNotFoundException is thrown with an actionable message.

---

Controller Resolution (V2)

ZenView resolves its controller in this order:

1. Nearest ZenProvider ancestor — O(1) InheritedWidget lookup.
2. ZenControllerNotFoundException — thrown with a clear, actionable message if not found.

There is no global fallback. This is intentional — silent fallbacks to global state hide architectural mistakes.

---

New

ZenProvider.create<T> — single-controller shorthand

The most common pattern (one controller per route) now has a dedicated constructor:

ZenProvider.create<CartController>(
  create: () => CartController(),
  child: const CartPage(),
)

ZenUpdater<T> — renamed from ZenBuilder<T>

ZenBuilder<T> is now ZenUpdater<T>. The name communicates the purpose: this widget rebuilds when controller.update() is called. ZenBuilder is fully removed — any remaining usage is a compile error.

ZenConsumer<T> — fixed and production-ready

ZenConsumer previously used global DI only. V2 fixes it to resolve via context.controller<T>() in didChangeDependencies() — proper InheritedWidget subscription semantics, scope-bound, fails fast.

---

Performance

• No global registry — resolution is O(1) via Flutter's native InheritedWidget hash map.
• Fewer allocations — ZenView uses ComponentElement instead of StatefulWidget. Each view allocates 2 objects (Widget + Element) instead of 3 (Widget + Element + State).
• ZenUpdater listener churn fixed — didChangeDependencies() uses an identical() guard to avoid re-attaching listeners when the resolved controller hasn't changed.

---

Bug Fixes

• ZenUpdater silent failures — now stores resolution errors and rethrows in build(), routing to onError if provided.
• ZenProvider async init — module init errors now surface via FlutterError.reportError() instead of being silently logged.
• ZenConsumer fail-fast — throws clearly when controller not found instead of silently degrading.

---

Tests

2,082 tests, all passing. Test suite fully migrated to V2 patterns — no global Zen.put for UI controllers in any widget test.

---

Migration Checklist

# Find all ZenView.build() overrides that need updating:
grep -rn "Widget build(BuildContext context)" lib/ --include="*.dart"

1. Add , T controller parameter to every ZenView.build() override
2. Replace ZenScopeWidget → ZenProvider (and ZenScopeWidget.create → ZenProvider.create)
3. Replace ZenControllerScope → ZenProvider.create (removed, must migrate)
4. Remove initController overrides → move controller creation to ZenProvider.create at callsite
5. Replace ZenBuilder → ZenUpdater (required — ZenBuilder is fully removed, will not compile)
6. dart analyze → confirm 0 errors
7. flutter test → confirm all tests pass

Full migration guide →

---

1.11.0

Fixed

• ZenView multi-instance registry — replaced the flat Map<Type, ZenController> registry with a stack-based registry (Map<Type, List<ZenController>>). Each ZenView instance now pushes its controller on mount and pops on dispose. The controller getter uses peek() to always return the innermost (most recently mounted) instance — analogous to Flutter's own InheritedWidget nearest-ancestor semantics. This fixes state-bleed when navigating between multiple instances of the same page type (e.g., navigating to CartPage twice in the back stack).

• ZenRoute scope unification — ZenRoute previously maintained its own private _ZenScopeProvider InheritedWidget alongside the canonical one in ZenScopeWidget. These are now unified: ZenRoute uses the shared ZenScopeProvider and context.zenScope extension from zen_scope_widget.dart. Eliminates a source of duplicate scope discovery logic.

• ZenBuilder import — fixed import in zen_builder.dart which was incorrectly depending on zen_route.dart's private scope provider rather than the canonical zen_scope_widget.dart.

• context.controller<T>() resolution — the ZenViewContextExtensions.controller<T>() method previously had a redundant step that looked up the internal _ZenViewRegistry. Removed. Resolution is now purely widget-tree-bound: nearest ZenScope → global Zen.findOrNull<T>(). This makes context.controller<T>() 100% multi-instance safe with no global registry involved.

Improved

• ZenScopeProvider — moved from public export to implementation-internal. It was always an implementation detail (the InheritedWidget backing ZenScope) and was never documented for direct use. Users who need it can still access it via a direct import but it is no longer part of the default package surface.

• doc/v2_architecture_design.md — added architectural design document capturing the rationale for current V1.x fixes and the full V2 breaking-change roadmap (ZenView injected build, ZenConsumer<T>, ZenScopeWidget-as-canonical-provider). Serves as the reference for V2 development.

---

1.10.4

Added

• RxList.assignAll() — convenience method to replace all elements in a reactive list in a single call. Also adds tryAssignAll() for explicit error-handling.

Improved

• ZenStorage documentation — clarified that write()/read() pass a plain Map<String, dynamic>, not a JSON-encoded string. Added a copy-paste Drift/SQLite adapter recipe alongside the existing SharedPreferences example.
• ZenQueryConfig.fromJson / toJson documentation — clarified that these work with Map<String, dynamic> directly, making Drift's toMap()/fromMap() plug in without any extra JSON encoding step.

---

1.10.3

Added

• ZenQueryConfig.retryWhenOnline — network-aware retry pausing. When true, a query that exhausts all its retry attempts while the device is offline (or goes offline mid-retry) enters paused (fetchStatus = ZenQueryFetchStatus.paused) instead of the usual error state. It is automatically registered in an internal retry queue and restarts a fresh, full retry cycle (with exponential backoff) the moment connectivity returns — no manual invalidate() or refetch() required.

  // Query silently waits for connectivity and self-heals on reconnect
  final query = ZenQuery<User>(
    queryKey: 'user:me',
    fetcher: (_) => api.getMe(),
    config: ZenQueryConfig(
      retryCount: 3,
      retryWhenOnline: true, // NEW
    ),
  );
  

  Key behaviours:

  • Stale cache preserved: if the query already has data, it returns the cached value while paused.
  • Multiple queries: all queued queries are drained atomically when connectivity returns.
  • Disabled queries: skipped at drain time if enabled = false.
  • Dispose safety: disposed queries are automatically cleaned up from the queue.
  • Off by default: retryWhenOnline: false preserves the existing error-on-exhaustion behaviour.

---

1.10.2

Added

• ZenInfiniteQuery.maxPages — memory safety limit for infinite scrolling. Automatically evicts older pages from RAM when users scroll deeply, while preserving the exact cursors needed for seamless bi-directional refetching.
• ZenMutation.anyMutating & ZenMutation.activeMutations — global tracking hooks. Perfect for showing universal loading indicators or disabling navigation while mutations are actively in-flight anywhere in the app.

---

1.10.1

Added

• scope.require<T>({String? tag}) — idiomatic throwing dependency lookup on ZenScope. This is the one genuinely new addition. scope.find<T>() is nullable (returns T?), which means scope.find<T>()! is a silent footgun. scope.require<T>() is the non-nullable, throwing form that surfaces a ZenDependencyNotFoundException with the missing type name, scope name, tag, and a copy-paste registration suggestion.

  // ❌ Before — NPE crash, no diagnostic context
  final svc = scope.find<AuthService>()!;
  
  // ✅ After — ZenDependencyNotFoundException with actionable message
  final svc = scope.require<AuthService>();
  

  Note: Zen.find<T>() (global API) already throws when missing — it behaves like Get.find<T>(). The new require<T>() is only on ZenScope where find is nullable.

• ZenQueryConsumer<T> — self-contained widget that creates, fetches, and renders a ZenQuery with no controller or module boilerplate. The useQuery equivalent for Zenify.

  // No controller. No module. One widget.
  ZenQueryConsumer<User>(
    queryKey: 'user:123',
    fetcher: (_) => api.getUser(123),
    data: (user) => UserProfile(user),
    loading: () => const CircularProgressIndicator(),
    error: (err, retry) => ErrorView(err, onRetry: retry),
  )
  

  Supports all ZenQueryBuilder features: initialData, config, showStaleData, autoFetch, and dynamic queryKey changes (disposes the old query, creates a new one).

Docs Updated

• doc/hierarchical_scopes_guide.md — ZenModule.register examples updated to scope.require<T>().
• doc/real_world_patterns.md — NetworkModule and AuthModule examples updated to scope.require<T>().
• doc/migration_guide.md — DI section clarifies that Zen.find<T>() already throws like Get.find<T>(), and introduces findOrNull<T>() as the explicit nullable escape hatch.

Tests

• test/di/zen_require_test.dart — 21 tests: scope.require<T>() happy path (untagged, tagged, hierarchical, lazy), error path (exception type, type name, scope name, tag, suggestion), parity with findRequired<T>(), disposed scope, and Zen.find<T>() throwing behaviour.
• test/widgets/zen_query_consumer_test.dart — 14 widget tests: happy path, initialData, loading state (custom + default), error state (custom + default + retry), idle state, queryKey change, disposal, config passthrough, typed generics, and barrel export smoke test.

---

1.10.0

Added

• ZenInfiniteQuery.when() — declarative builder for infinite-scroll UI. Handles all states (loading, error, data, loadingMore, empty) with optional footer slot for a "load more" trigger.
• ZenMutation.when() — reactive mutation state builder using AnimatedBuilder + Listenable.merge. Covers idle, loading, success, and error states with full type parameters.
• doc/gorouter_guide.md — comprehensive guide for integrating ZenRoute with GoRouter, covering nested routes, auth guards, and scope lifecycle.
• Codecov badge in README.

Bug Fixes

These bugs were uncovered through the new test suite ("coverage-driven debugging"). All are fixed in this release.

• RxTransformations.skip() never updated after creation — the closure returned null without accessing value, so the source Rx was never registered as a dependency. The computed was permanently dead and would never re-evaluate when the source changed. Fixed by always accessing value before branching.
• RxTransformations.take() lost its dependency after exhaustion — same root cause. Fixed for consistency.
• RxTimingExtensions.take/skip caused API-wide ambiguity — RxTimingExtensions defined callback-style take(int, callback) and skip(int, callback) on Rx<T>, conflicting with RxTransformations.take(int) and .skip(int). Dart could not resolve either name. Renamed to takeFirst / skipFirst — consistent with Flutter's firstWhere/firstOrNull pattern.
• RxTimingExtensions.map/where caused API-wide ambiguity — RxTimingExtensions defined callback-style map(transformer, callback) and where(condition, callback) on Rx<T>, conflicting with RxComputedExtensions.map / .where which both return computed values. Renamed to listenMapped(transformer, callback) and listenWhere(condition, callback) — the listen* prefix makes the side-effect callback intent explicit and unambiguous.
• RxMapExtensions.update() was unreachable dead code — Rx<T> has a class-level update(T Function(T) updater) that always shadows the extension method update(K key, V Function(V), ...). Users could never call the map-keyed version. Removed; use tryUpdate(key, fn) directly.
• RxTransformations.whereNotNull() caused ambiguity for nullable types — conflicted with RxNullableTransformations.whereNotNull(). Removed from RxTransformations<T>; RxNullableTransformations<T>.whereNotNull() is the correct location.
• ZenTestMode.mockAll() silently registers under dynamic (breaking change documented) — calling Zen.put(instance) where instance is typed as dynamic loses the generic type parameter T to type erasure. All mocks were registered under dynamic instead of the intended interface type, making Zen.find<T>() always return null regardless of what was mocked. Deprecated with a clear runtime warning explaining the bug. Use chained .mock<T>() calls instead.
• ZenModuleRegistry dead code removed — the missing-dependency guard in registerModules was unreachable because _collectAllDependencies() already recursively resolves all transitive dependencies before the check was reached. Removed to prevent misleading error messages.
• ZenController.autoDispose<T>() did not dispose handle on error — if the callback threw an exception, the handle was orphaned. It now calls handle.dispose() in the catch block, consistent with the no-leak guarantee.
• ZenController.limited<T>() did not dispose handle on error — same issue. Now disposes on callback exception.

Tests

• Comprehensive Test Coverage: Over 2,120+ unit and widget tests validating core logic, widget interactions, garbage collection, and strict state invariants. Line test coverage has reached >95.0% overall!

Big Fixes & Minor Tweaks

• Fixed Lifecycle Hook Warnings: Resolved mustCallSuper lint warnings within ZenController's onInit and onReady hooks, ensuring developers properly chain initialization methods.
• Widget Testing Stability: Fixed pending timer exceptions during test disposal by ensuring immediate flush of garbage collection timers within Widget tests affecting ZenQueryBuilder, ZenInfiniteQuery.when(), and cache operations.

Dead Code Audit

As part of the final push for test coverage, we removed/ignored non-reachable safety pathways:

• Scope clearAll fallback: // coverage:ignore-line added to the error catch inside clearAll since dispose completely swallows exceptions within ZenScope's controller array cleanup phase.
• ControllerScope key update: Standard Flutter validation (Widget.canUpdate verifies identical keys) effectively prevents instances with different keys from executing didUpdateWidget. Thus, key differences trigger complete teardowns via widget replacement rather than widget updates. This redundant internal key check inside ZenControllerScope.didUpdateWidget has been marked with // coverage:ignore.

---

1.9.1

Added

• ZenQuery.when() — declarative shorthand for ZenQueryBuilder. Supports data, loading, error, and idle builders.
• tool/migrate_from_getx.dart — migration script that auto-converts GetX code to Zenify (imports, controllers, .obs → .obs(), DI calls, widgets, permanent: → isPermanent:). Flags navigation, workers, and other patterns for manual review.
• GitHub Actions CI workflow (flutter test, dart analyze, format check)
• GetX migration guide (doc/migration_guide.md) complete rewrite with verified API examples
• README callout for GetX developers linking to the migration guide

---

1.9.0

Added

• tags parameter on ZenQuery for group-based cache management
• ZenQueryCache.invalidateQueriesByTag(tag) and refetchQueriesByTag(tag)
• ZenQueryCache.invalidateQueriesByPattern(pattern) and refetchQueriesByPattern(pattern) — supports glob-style * wildcards
• ZenQueryCache.getQueriesByTag(tag) and getKeysByTag(tag) for tag inspection
• InMemoryStorage — a built-in zero-dependency ZenStorage adapter for testing and ephemeral storage
• Warning log when a wildcard pattern matches all queries (e.g. '*')

---

1.8.0

Breaking Changes

• Removed ZenInspectorOverlay widget. Remove the wrapper from your app — Zen.init(registerDevTools: true) continues to work as before.

// Before
runApp(ZenInspectorOverlay(child: MyApp()));

// After
runApp(MyApp()); // DevTools integration unchanged

Changed

• DevTools UI moved to a separate optional package: zenify_devtools_extension
• Core package is ~25MB smaller as a result

---

1.7.0

Added

• Flutter DevTools extension with 3-tab inspector: Scope Inspector, Query Cache Viewer, Metrics Dashboard
• ZenServiceExtensions class for VM Service Protocol integration
• Automatic service extension registration via Zen.init(registerDevTools: true) in debug builds
• Zero performance impact in release builds

---

1.6.6

Added

• ZenException base class with compact (default) and verbose (ZenConfig.verboseErrors = true) error formatting
• Specific exception types: ZenDependencyNotFoundException, ZenCircularDependencyException, ZenDisposedScopeException, ZenScopeNotFoundException, ZenControllerNotFoundException, ZenControllerDisposedException, ZenOfflineException, ZenQueryException, ZenMutationException, ZenModuleException, ZenLifecycleException, ZenRouteException
• ZenLogger.logException(e) for formatted exception output
• ZenConfig.verboseErrors toggle

---

1.6.5

Added

• "Pending Mutations" card in DevTools Stats View
• ZenMutationQueue.pendingCount and pendingJobs for debugging
• Visual offline queue status indicator in DevTools

---

1.6.4

Added

• ZenObserver — alias for Obx widget
• scope.get<T>() — alias for scope.find<T>()
• scope.remove<T>() — alias for scope.delete<T>()
• scope.has<T>() — alias for scope.exists<T>()

---

1.6.3

Added

• Zen.get<T>() — alias for Zen.find<T>()
• Zen.remove<T>() — alias for Zen.delete<T>()
• Zen.has<T>() — alias for Zen.exists<T>()
• Zen.queryCache — shorthand for ZenQueryCache.instance

---

1.6.2

Breaking Changes

• OptimisticMutation renamed to ZenMutation (helpers are now static methods)
• listAdd → listPut, listUpdate → listSet, add → put, update → set

// Before
OptimisticMutation.listAdd<Post>(queryKey: 'posts', mutationKey: 'create', mutationFn: ...)

// After
ZenMutation.listPut<Post>(queryKey: 'posts', mutationFn: ...) // mutationKey auto-generated

Changed

• mutationKey is now optional; auto-generated from queryKey if omitted

---

1.6.1

Added

• ZenMutation.listPut<T>, listSet<T>, listRemove<T> — optimistic list helpers with automatic rollback
• ZenMutation.put<T>, set<T>, remove() — optimistic single-value helpers

---

1.6.0

Added

• ZenStorage interface for pluggable persistence backends (SharedPreferences, Hive, SQLite, etc.)
• Auto-hydration: queries load cached data from storage on startup
• Offline mutation queue: mutations triggered while offline are queued and replayed on reconnect
• ZenQueryCache.setQueryData() for function-based optimistic cache updates
• NetworkMode enum: online, offlineFirst, always
• example/zen_offline — full offline-first example app

---

1.5.0

Breaking Changes

• refetchOnMount, refetchOnFocus, refetchOnReconnect changed from bool to RefetchBehavior enum

// Before
ZenQueryConfig(refetchOnMount: true)

// After
ZenQueryConfig(refetchOnMount: RefetchBehavior.ifStale)
// New option: RefetchBehavior.always — force refetch regardless of staleness

Added

• RefetchBehavior.always for real-time/critical data use cases
• ZenQueryConfig.retryDelayFn — custom function for error-aware retry delays

---

1.4.4

Fixed

• ZenInspectorOverlay crashes when used without a Scaffold — replaced ScaffoldMessenger with internal toast system
• Layout overflows and data preview scrolling in inspector

---

1.4.3

Fixed

• invalidate() now automatically refetches active queries (previously only marked stale)

---

1.4.2

Changed

• Removed unnecessary type parameter from ZenQueryClient.getQueryDefaults()

---

1.4.1

Added

• ZenQueryClient and ZenQueryClientOptions for managing global query defaults
• ZenQueryConfig.copyWith() for partial config overrides

---

1.4.0

Added

• pause() and resume() methods on ZenQuery and ZenStreamQuery
• ZenQueryConfig.autoPauseOnBackground and refetchOnResume
• ZenQueryCache.getAllQueries() for lifecycle management
• Exponential backoff: maxRetryDelay, retryBackoffMultiplier, retryWithJitter

Breaking Changes

• ZenStreamQuery now defaults to autoPauseOnBackground: false (was true in 1.3.x)

// To restore previous behavior
ZenStreamQuery(config: ZenQueryConfig(autoPauseOnBackground: true))

---

1.3.6

Fixed

• Zen.reset() no longer requires testWidgets() — works in plain test() blocks
• ZenLifecycleManager handles missing WidgetsBinding in test environments gracefully

---

1.3.5

Changed

• Restructured README and documentation for clarity
• Added doc/real_world_patterns.md

---

1.3.4

Changed

• Fixed createController syntax in all documentation
• Rewrote state_management_patterns.md with clearer examples

---

1.3.3

Fixed

• 1-pixel RenderFlex overflow in ZenInspectorOverlay on iOS/Android with no dependencies
• Improved overlay positioning with explicit Positioned.fill

---

1.3.2

Added

• ZenInspectorOverlay — in-app debug overlay with real-time scope hierarchy, query cache, and performance stats

---

1.3.1

Added

• Automatic query tracking: queries created in onInit() are automatically disposed when the controller closes — no onClose() boilerplate required

---

1.3.0

Changed

• Internal architecture refactoring: replaced ZenScopeManager (541 lines) and ZenScopeStackTracker with a single Zen.currentScope navigation bridge (~80% reduction in scope management code)
• ZenRoute reduced from 526 to 336 lines

Added

• parentScope parameter on ZenRoute for explicit scope control

Breaking Changes

• None. All public APIs unchanged.

---

1.2.3

Fixed

• ZenStreamQuery now pauses on inactive and hidden app states (web tab switching)
• Lifecycle events (onPause, onResume) now fire correctly when query is not registered in DI

---

1.2.2

Changed

• Expanded zen_query example app with additional features

---

1.2.1

Added

• ZenInfiniteQuery.getPreviousPageParam() and fetchPreviousPage() for bidirectional pagination
• hasPreviousPage and isFetchingPreviousPage reactive properties
• Call-time callbacks on mutate(): onSuccess, onError, onSettled
• placeholderData in ZenQueryConfig — temporary initial data that doesn't persist to cache
• keepPreviousData on ZenQueryBuilder and ZenStreamQueryBuilder to prevent flash-of-loading on key changes

---

1.2.0

Added

• ZenStreamQuery — reactive wrapper for Stream<T> with lifecycle management and optimistic updates
• ZenStreamQueryBuilder widget

Changed

• Folder restructure: builders moved to lib/widgets/builders/, query internals to lib/query/core|logic|extensions/
• import 'package:zenify/zenify.dart' is unaffected

---

1.1.9

Added

• ZenStorage interface (foundation for 1.6.0 offline engine)
• persist, fromJson, toJson, storage options on ZenQueryConfig
• Auto-hydration from storage on query initialization

---

1.1.8

Breaking Changes

• Fetcher signature now requires a ZenCancelToken parameter

// Before
fetcher: () => api.getData()

// After
fetcher: (_) => api.getData()

Added

• ZenCancelToken for platform-agnostic request cancellation
• Automatic cancel on dispose and on re-trigger (prevents stale data race conditions)

---

1.1.7

Added

• Smart refetching: stale queries auto-refetch on app resume and network reconnect
• ZenQueryConfig.refetchOnFocus and refetchOnReconnect
• Zen.setNetworkStream() for connectivity integration

Changed

• App lifecycle observation centralized to ZenLifecycleManager (single observer)

---

1.1.6

Added

• enabled parameter and RxBool enabled property on ZenQuery for dependent queries
• ZenQueryCache.instance.prefetch() for pre-loading data without creating listeners

---

1.1.5

Added

• ZenQuery.select() — derived queries that only update when specific data changes

---

1.1.4

Added

• ZenInfiniteQuery for paginated lists and infinite scrolling
• queryKey now accepts Object (including List) in addition to String

---

1.1.3

Added

• ZenMutation for reactive write operations (create, update, delete)
• Lifecycle hooks: onMutate, onSuccess, onError, onSettled
• ZenQueryCache.invalidateQuery() integration pattern

---

1.1.2

Added

• ZenScopeQueryExtension: scope.putQuery<T>() and scope.putCachedQuery<T>()

---

1.1.1

Added

• scope parameter on ZenQuery for automatic disposal with scope lifecycle
• ZenQueryCache.invalidateScope(), refetchScope(), clearScope(), getScopeQueries(), getScopeStats()

---

1.1.0

Added

• ZenQuery — async state management with caching, deduplication, retries, and background refetch
• ZenQueryBuilder — reactive widget with loading/error/success states and SWR pattern
• ZenQueryCache — global cache manager with invalidation and memory management

---

1.0.1

Added

• doc/testing_guide.md

Changed

• Removed Zen.putFactory() — use Zen.putLazy(..., alwaysNew: true) instead
• Route and controller lifecycle events now use logInfo() level

Fixed

• ZenScope.put() default parameter handling
• Factory cleanup logic in scope disposal

---

1.0.0

Breaking Changes

• EagerRef, LazyRef, ControllerRef, ZenRef replaced by a single Ref<T>
• .put(), .asRef(), .register() extension methods removed — use Zen.put()
• Zen.putFactory() removed — use Zen.putLazy(..., isPermanent: false)
• Debug methods moved to ZenDebug class: ZenDebug.dumpScopes() etc.

Added

• Ref<T> universal reference with call() shorthand
• Improved ZenBuilder with proper DI cleanup and ownership tracking

---

0.6.3

Added

• ZenEnvironment.productionVerbose environment preset
• ZenConfig.shouldLogRoutes and shouldLogNavigation helpers

---

0.6.2

Fixed

• Inverted logic in shouldLog() causing logs to appear when suppressed
• Rx tracking logs now respect ZenConfig.enableRxTracking

---

0.6.1

Breaking Changes

• enableDebugLogs replaced by ZenLogLevel enum: none, error, warning, info, debug, trace

Added

• ZenEnvironment enum for type-safe environment configuration: production, staging, development, debug, trace, test

---

0.6.0

Breaking Changes

• ZenController.onDispose() → onClose()
• ZenService.onDelete() → onClose()
• ZenScope.put() parameter permanent → isPermanent

Added

• Automatic ZenService disposal when its scope disposes

---

0.5.5

Added

• ZenService base class with onInit and onClose lifecycle hooks

---

0.5.4

Changed

• Updated pub.dev example application

---

0.5.3

Fixed

• Linting, formatting, and analysis issues for pub.dev score compliance

---

0.5.2

Changed

• Updated package topics for better pub.dev discoverability

---

0.5.1

Fixed

• Deprecated RadioListTile API usage — migrated to RadioGroup widget

---

0.5.0

Initial pub.dev release.

---

0.4.1

Changed

• README and package metadata improvements for pub.dev

Fixed

• const keyword consistency across codebase
• Documentation path corrections (docs/ → doc/)

---

0.4.0

Breaking Changes

• ZenModulePage renamed to ZenRoute

Added

• ZenModule base class and comprehensive module system
• ZenRoute widget for module-based dependency injection
• ZenConsumer widget for dependency access without rebuild
• Stack-based scope tracking and automatic lifecycle management

---

0.3.0

Added

• RxResult<T> for success/failure error handling patterns
• RxComputed for automatic dependency tracking
• RxFuture for reactive async operations
• Circuit breaker pattern for resilient reactive operations
• Batch operations and bulk updates for collections

---

0.2.0

Added

• ZenConsumer widget with automatic caching

---

0.1.9

Added

• Memory leak detection test suite
• Dependency resolution benchmark suite

---

0.1.8

Added

• ZenView base class for automatic controller management in pages

---

0.1.7

Changed

• lookup renamed to find

Added

• findOrNull() for non-throwing dependency lookup
• EagerRef and LazyRef reference types

---

0.1.6

Added

• ZenLogger system with debug, warning, error levels
• Comprehensive DI test suite

---

0.1.5

Added

• Hierarchical scope system
• Circular dependency detection
• Module/binding system for organized registration
• Lazy initialization support

---

0.1.4

Added

• Generic type constraints on RxList<E>, RxMap<K,V>, RxSet<E>
• ControllerRef<T> typed provider references

---

0.1.3

Added

• ZenEffect for async operations with loading states
• Worker compatibility improvements

---

0.1.2

Fixed

• Minimum Dart SDK updated to 2.19.0
• Deprecated IndexError usage
• Collection type safety in RxList, RxMap, RxSet

---

0.1.1

Initial release — reactive state, controller lifecycle management, route-based disposal.