watch_it 2.1.0

watch_it: ^2.1.0 copied to clipboard

Improvements #

• Better Error Messages: Watch ordering violations now show a helpful error message instead of cryptic type errors. When conditional watch calls are placed incorrectly, you'll see clear guidance on how to fix it with BAD/GOOD examples.
• Enhanced Documentation: Added "Watch Ordering and Conditional Watches" section to README with visual examples explaining why conditional watches must be at the end of build methods.
• Improved Test Coverage: Test coverage increased to 93.3%.

Maintenance #

• Updated get_it dependency to ^9.0.0
• Added GitHub Actions workflow for CI/CD with automated testing and code coverage
• Improved README header with logo and better formatting to match flutter_it ecosystem style
• Added package logo to pub.dev screenshots

Breaking Changes #

• BREAKING: Replaced dependency functional_listener ^4.0.0 with listen_it ^5.1.0. This is a breaking change as functional_listener has been renamed and restructured into listen_it. If you use functional_listener operators in your code, update your imports from package:functional_listener/functional_listener.dart to package:listen_it/listen_it.dart.
• BREAKING: watchValue() and registerHandler() now default to allowObservableChange: false for better performance and memory leak prevention. This means the selector function is only called once on first build. If you need to dynamically switch observables (e.g., condition ? obsA : obsB), set allowObservableChange: true. This prevents common memory leaks from inline chain creation like watchValue((m) => m.source.map(...)).

New Features #

• Added callAfterFirstBuild() function that executes a callback once after the first frame has been rendered. This is useful for operations that require the widget tree to be fully built and laid out, such as showing dialogs, accessing widget dimensions, scrolling to positions, or starting animations that depend on final widget sizes. This replaces the common pattern of using WidgetsBinding.instance.addPostFrameCallback in initState().
• Added callAfterEveryBuild() function that executes a callback after every frame has been rendered. This is useful for operations that need to run after each rebuild, such as updating scroll positions, repositioning overlays, or performing measurements. The callback includes a cancel() function to stop future invocations when needed.

Performance Improvements #

• watchValue() and registerHandler() now have zero overhead on rebuilds with default settings - selectors are only called once instead of on every build
• Added helpful StateError messages when observables change unexpectedly with allowObservableChange: false, guiding users to the correct fix

Bug Fixes #

• Fixed createOnceAsync test isolation issue by properly resetting testCompleter in setUp
• Internal refactoring: Renamed parameters for better clarity (target → parentOrListenable, etc.)

• PR by @timmaffett imrproving the markdown of the readme
• adding topics to pubspec

• adding sl alias for di
• adding createOnce to the readme

• fixing an exception in Streambuilder during loading state if you don't provide an inital value

• Fix for https://github.com/escamoteur/watch_it/issues/42

• fixing linter warnings

• Adding createOnce and createOnceAsync

• fix for https://github.com/escamoteur/watch_it/issues/28

• thanks to the pr https://github.com/escamoteur/watch_it/pull/27 by @jefflongo pushScope now accepts the isFinal parameter that the underlying get_it function does for some time now.

• added executeHandlerOnlyOnce to registerFutureHandler, allReady and allReadyHandler
• added new functions: callOnce and onDispose. See readme for details

• thanks to the PR from @smjxpro https://github.com/escamoteur/watch_it/pull/22 you now can register handlers for pure Listenable/ChangeNotifiers too

• https://github.com/fluttercommunity/get_it/issues/345 allReady() will now throw a correct error if an exception is thrown in one of the factory functions that allReady() checks

• Typo fixes by PRs from @mym0404 @elitree @florentmx

• updates Discord invite link

• added some more asserts to provide better error messages in case you forgot to use the WatchItMixin

• bumped get_it version

• thanks for PR by @yangsfang https://github.com/escamoteur/watch_it/pull/10

• small change in documentation

• fix for https://github.com/escamoteur/watch_it/issues/8
• improved comments thanks to PR by @kevlar700

• added safety checks in case _element gets null but still a handler might get called

• improving readme

• fix typo

• First beta release

• This is currently just a placeholder for the new version of the get_it_mixin