watchable 6.0.2

Production-ready, type-safe state management for Flutter. 10x performance improvement with advanced memory management and comprehensive error handling.

Changelog

All notable changes to the watchable package will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

6.0.2 - 2025-12-12

Changed

• Removed USAGE.md and TEST_CASES.md (documentation cleanup)

Documentation

• Removed benchmark comparison table with other libraries from README

6.0.1 - 2025-12-12

Documentation

• Fixed version in README (^5.0.0 → ^6.0.0)
• Updated README to reflect v6.0.0 changes: replaced deep equality section with identical() comparison explanation
• Updated benchmarks table and "Why Switch" section

6.0.0 - 2025-12-12

BREAKING CHANGES

• Removed const constructor - Watchable no longer supports const construction
• Removed WatchableConfig - Fast mode is now the default and only mode
• Removed FastWatchable - Optimizations merged into Watchable class
• Removed .fastWatchable extension - Use .watchable instead
• Removed collection dependency - Deep equality no longer used

Performance (6x Faster)

• Direct field storage for notifier (no static Map lookup)
• O(1) equality using identical() only
• @pragma('vm:prefer-inline') for hot paths
• Benchmarks: ~10.6M ops/sec with 100 listeners (vs ~1.8M in v5.0.0)

Migration Guide

// Before (v5.x)
const counter = Watchable<int>(0);  // No longer supported

// After (v6.0.0)
final counter = Watchable<int>(0);  // Works
final counter = 0.watchable;        // Works

All other APIs unchanged: value, emit(), refresh(), alwaysNotify(), .watchable, WatchableBuilder, tuple extensions, Watch.build2()-Watch.build6().

5.0.0 - 2025-09-13

Added

• Deep collection equality - Comprehensive collection comparison using DeepCollectionEquality from collection package
• Advanced error handling - Graceful degradation for comparison operations with try-catch safety
• Bulletproof test coverage - 152 comprehensive tests covering all edge cases and failure scenarios
• Threading and concurrency tests - Comprehensive concurrent access validation and thread safety
• Extension method edge case handling - Robust error handling for all extension operations
• Widget integration stress testing - High-load UI scenarios with rapid state changes

Fixed

• Deep equality for nested collections - Lists, Maps, and Sets now properly compared using deep equality
• Collection comparison infinite loops - Protected against circular references and excessive nesting
• Transformation failure recovery - All transformation operations now handle exceptions gracefully
• Widget exception handling - Proper Flutter framework exception capture in tests
• Concurrent modification safety - Thread-safe operations for high-concurrency scenarios

Enhanced

• Production-ready reliability - 100% test success rate across 152 comprehensive test cases
• Memory management - Advanced leak prevention and resource cleanup
• Performance optimization - Efficient deep equality checking with fallback mechanisms
• Type safety - Enhanced compile-time safety for all operations
• Developer experience - Better error messages and exception handling

Quality Assurance

• 152 comprehensive tests - Complete coverage of all functionality including edge cases
• 100% test success rate - Zero failing tests across all scenarios
• Deep collection testing - Extensive validation of List, Map, Set equality operations
• Concurrency validation - Thread safety confirmed under high-load conditions
• Widget lifecycle testing - Complete Flutter integration validation
• Error handling coverage - All exception scenarios properly tested and handled

Technical Improvements

• DeepCollectionEquality integration - Proper deep comparison for all collection types
• Static _areEqual method - Centralized equality checking with graceful error handling
• Enhanced value setter - Intelligent comparison with fallback to standard equality
• Exception safety - All operations protected against comparison failures
• Memory efficiency - Optimized comparison operations without performance impact

4.1.2 - 2025-09-12

Fixed

• Static analysis warnings - Removed all @Deprecated annotations to eliminate deprecation warnings
• Clean codebase - No more internal deprecation warnings when using WatchableBuilder and WatchableConsumer
• Example app warnings - Fixed withOpacity deprecation in example app

Developer Experience

• Zero analysis issues - Perfect static analysis score with no errors, warnings, or lints
• Cleaner development - No more noisy deprecation warnings during development
• Better IDE experience - Improved code completion and error highlighting

4.1.1 - 2025-09-12

Fixed

• Documentation cleanup - Removed all emojis from README.md and USAGE.md for cleaner, professional appearance
• Code warnings - Fixed unused parameter warning in example app

Documentation

• Cleaner presentation - All section headers and content now emoji-free
• Professional appearance - Improved readability and accessibility
• Consistent formatting - Standardized documentation style across all markdown files

4.1.0 - 2025-09-12

Added

• Direct value assignment - Revolutionary .value setter for ultimate simplicity
• Universal type support - Works seamlessly with primitives, collections, custom objects, and nullable types
• Compound operations - Full support for +=, -=, *=, ++, -- operators
• Zero boilerplate updates - From counter.emit(counter.value + 1) to counter.value++

Developer Experience Improvements

• 80% reduction in update code - Direct assignment replaces verbose emit() calls
• Natural syntax - Code reads like standard Dart: name.value = 'John', items.value.add(newItem)
• Type-safe operations - All Dart operators work naturally with watchable values
• Unified pattern - Single .watch + .value approach for all state management needs

Examples

// Before (v4.0)
counter.emit(counter.value + 1);
items.emit([...items.value, newItem]);
user.emit(user.value.copyWith(name: 'John'));

// After (v4.1) 
counter.value++;
items.value = [...items.value, newItem];
user.value = user.value.copyWith(name: 'John');

Compatibility

• Fully backward compatible - All existing .emit() code continues to work unchanged
• Gradual adoption - Mix .value and .emit() approaches as needed
• Zero performance impact - .value setter internally calls .emit() with same efficiency

4.0.0 - 2025-09-06

BREAKING CHANGES

• Updated to major version 4.0.0 to reflect significant API enhancements
• No actual breaking changes to existing code - full backward compatibility maintained

Added

• Extension-based API - Revolutionary .watch syntax for 70% less boilerplate code
• Type-specific extensions - 0.watch (WInt), 'text'.watch (WString), false.watch (WBool)
• Shorter type aliases - W<T>, WInt, WString, WBool, WDouble, WList<T>, WMap<K,V>
• Widget shortcuts - .build() method for StateWatchable, .consume() for event streams
• Event stream alias - WEvent<T> for cleaner event handling
• Combiner extensions - Tuple-based multi-watchable combining with (a, b).combine() and (a, b).build()
• 2-6 item support - Full support for combining 2 to 6 watchables with type safety
• Watch utility class - Watch.build2() through Watch.build6() for explicit multi-watchable operations
• Custom class support - Full support for combining custom classes and complex types
• Developer-focused documentation - Comprehensive README focused on extension API usage
• Real-world examples - Complex form validation and state management patterns

Developer Experience Improvements

• 70% reduction in boilerplate code - From MutableStateWatchable<int>(0) to 0.watch
• Better type inference - No more explicit generic type declarations needed
• Intuitive syntax - Code reads like natural language (counter.build, name.watch)
• Backward compatibility - All existing code continues to work unchanged
• Gradual migration - Mix old and new APIs as needed

Performance

• Zero overhead - Extensions compile to identical bytecode as traditional API
• Same memory safety - All existing memory leak prevention remains intact
• Identical performance - 10x faster operations maintained

Migration Support

• Complete migration guide - Step-by-step instructions in README
• Code comparison examples - Before/after examples for common patterns
• Non-breaking changes - Additive API improvements only

3.0.0 - 2025-01-06

BREAKING CHANGES

• Fixed replay buffer initialization in MutableStateWatchable - initial values now always available via replay
• Improved type safety in combiners may require minor type adjustments in some use cases

Added

• Type-safe combiners - Complete rewrite of from2, from3, from4, from5 methods with compile-time type safety
• Comprehensive error handling - All user callbacks now wrapped with graceful error handling and debug logging
• Advanced memory management - Enhanced disposal patterns and leak prevention mechanisms
• Production debugging support - Debug logging in development mode, silent operation in production
• Extensive test coverage - Added 47 new test cases covering edge cases, memory management, and error scenarios
• Performance monitoring - Built-in safeguards for high-load scenarios and concurrent operations

Fixed

• Critical type safety bug - Eliminated unsafe type casting that could cause runtime crashes
• State consistency issue - Fixed widget state update inconsistency in WatchableBuilder
• Memory leak prevention - Fixed replay buffer not being populated for MutableStateWatchable
• Performance bottleneck - Replaced O(n) List operations with O(1) Set operations (10x performance improvement)
• Concurrent modification issues - Added proper synchronization for watcher collections
• Resource cleanup - Enhanced disposal mechanisms to prevent memory leaks in complex scenarios

Changed

• Watcher storage - Migrated from List<Function(T)> to Set<Function(T)> for better performance
• Error handling strategy - Non-breaking error recovery with debug information
• Initial value handling - MutableStateWatchable now guarantees initial value availability via replay buffer
• Dependencies - Updated flutter_lints to version 6.0.0 for latest linting standards

Performance Improvements

• 10x faster watcher operations - Set-based add/remove operations
• Reduced memory footprint - Optimized disposal and cleanup patterns
• Improved UI responsiveness - Fixed state update consistency issues
• Better concurrency handling - Thread-safe operations for multi-threaded scenarios

Quality Assurance

• 106 comprehensive tests (expanded from 59) covering all functionality
• Zero analysis warnings - Clean, lint-perfect codebase
• Memory leak testing - Stress testing with 1000+ watchers and rapid operations
• Concurrency testing - Validation of thread-safe operations
• Error handling validation - Comprehensive exception scenario testing
• Integration testing - Complex widget lifecycle and state management scenarios

Documentation

• Enhanced README - Added performance comparisons and migration guides
• API documentation - Complete inline documentation for all public APIs
• Migration examples - Step-by-step migration from GetX and Provider
• Best practices guide - Production-ready usage patterns and recommendations

2.0.5 2024-06-XX

• Documentation updated

2.0.4

• For controlled access to its state mutability added
• MutableStateWatchable added
• MutableWatchable added

2.0.3

• Example updated

2.0.2

• Readme update

2.0.1

• Readme update

2.0.0

• StateWatchable class for mutable state management
• Watchable class for event stream management
• WatchableBuilder widget for efficient UI updates
• WatchableConsumer widget for handling event streams

1.0.5

• Issues fixed with List, Map
• Readme updated

1.0.4

• Issues fixed with List, Map
• Added compare function to support custom object check

1.0.3

• Readme updated

1.0.2

• Selector added in WatchableBuilder to control rebuild with conditions

1.0.1

• Static Analysis Fix

1.0.0

• Initial release of the watchable package
• Watchable<T> class for wrapping values and notifying listeners of changes
• WatchableBuilder widget for efficiently rebuilding UI when state changes
• Static methods in WatchableBuilder for combining multiple Watchable instances:
  • fromList
  • from2
  • from3
  • from4
  • from5
• Basic documentation and examples