flutter_event_limiter 1.2.1

flutter_event_limiter: ^1.2.1 copied to clipboard

Topics Optimization 🏷️

Changed #

• ✅ Optimized pub.flutter-io.cn topics for better discoverability
  • Replaced generic topics (performance, widget, button) with specific pain points
  • Added problem-focused keywords: anti-spam, race-condition, loading-state
  • Added use-case keywords: async, form, search
  • Better alignment with user search intent and common problems

New topics (max 5 on pub.flutter-io.cn):

1. throttle - Core function
2. debounce - Core function
3. anti-spam - Pain point: prevent double-clicks
4. async - Feature: AsyncThrottler, async operations
5. loading-state - Unique: auto loading state management

This improves package visibility for developers searching for solutions to specific problems like preventing double-clicks, fixing race conditions, or handling loading states.

---

Advanced Concurrency Control 🚀

This major feature release adds powerful concurrency control strategies for async operations, giving you fine-grained control over how multiple async calls are handled.

Added #

Concurrency Modes (NEW)

• ✅ 4 execution strategies for handling concurrent async operations:

  • Drop (default): Ignore new calls while busy - perfect for preventing double-clicks
  • Enqueue: Queue all calls and execute sequentially (FIFO) - perfect for chat apps
  • Replace: Cancel current execution and start new one - perfect for search queries
  • Keep Latest: Execute current + latest only - perfect for auto-save

• ✅ New ConcurrencyMode enum with rich documentation and helper methods:

  enum ConcurrencyMode {
    drop,        // Ignore new calls (default)
    enqueue,     // Queue and execute all
    replace,     // Cancel and replace
    keepLatest,  // Execute current + latest
  }
  

New Controller: ConcurrentAsyncThrottler

• ✅ Advanced async throttler with concurrency control strategies
• ✅ Wraps AsyncThrottler with additional concurrency logic
• ✅ Queue management for enqueue mode (~60 bytes per queued operation)
• ✅ ID-based cancellation for replace mode
• ✅ Smart pending call tracking for keepLatest mode
• ✅ Exposes pendingCount, queueSize, and hasPendingCalls properties
• ✅ Full debug mode support with detailed logging
• Example:

  final chatSender = ConcurrentAsyncThrottler(
    mode: ConcurrencyMode.enqueue,
    maxDuration: Duration(seconds: 30),
    debugMode: true,
  );
  
  // All messages sent in order
  chatSender.call(() async => await api.send('Hello'));
  chatSender.call(() async => await api.send('World'));
  

New Widget: ConcurrentAsyncThrottledBuilder

• ✅ Widget wrapper for ConcurrentAsyncThrottler
• ✅ Automatic loading state tracking
• ✅ Pending operations count for queue display
• ✅ Safe mounted checks in async operations
• ✅ Auto-dispose - no manual cleanup needed
• ✅ onError and onSuccess callbacks
• Example:

  ConcurrentAsyncThrottledBuilder(
    mode: ConcurrencyMode.enqueue,
    onPressed: () async => await api.sendMessage(text),
    builder: (context, callback, isLoading, pendingCount) {
      return ElevatedButton(
        onPressed: isLoading ? null : callback,
        child: Text(pendingCount > 0
          ? 'Sending ($pendingCount)...'
          : 'Send'),
      );
    },
  )
  

Tests #

• ✅ 25 comprehensive unit tests for concurrency logic:

  • Drop mode tests (default behavior)
  • Enqueue mode tests (queue management)
  • Replace mode tests (cancellation)
  • Keep latest mode tests (smart buffering)
  • Real-world scenarios (chat, search, auto-save)
  • Edge cases and error handling

• ✅ 8 widget tests for ConcurrentAsyncThrottledBuilder:

  • Loading state management
  • Error handling with callbacks
  • Success callbacks
  • Null safety handling
  • Proper disposal
  • Debug mode support

• ✅ Total: 128 tests passing (up from 95)

Examples #

• ✅ Interactive demo app (example/concurrency_demo.dart):
  • Live demonstrations of all 4 concurrency modes
  • Visual event logs showing execution order
  • Practical use cases (payment, chat, search, auto-save)
  • Pending count visualization

Documentation #

• ✅ Comprehensive inline documentation for all concurrency features
• ✅ Real-world use case examples in each mode
• ✅ Performance notes and memory overhead details
• ✅ Migration guide from AsyncThrottler

Performance #

• ✅ Zero overhead for drop mode (direct AsyncThrottler passthrough)
• ✅ Minimal memory: ~60 bytes per queued operation (enqueue mode)
• ✅ Minimal memory: ~40 bytes overhead (replace/keepLatest modes)

---

Documentation Fix 📝

Changed #

• Fixed overly promotional README marketing claims
• Removed unverified user count claims
• Made feature descriptions more accurate and professional

---

Enhanced Test Coverage & Documentation 📚

This release significantly improves test coverage and updates documentation for 2025.

Added #

• ✅ 23 new comprehensive test cases covering:
  • Stress tests with 100+ rapid calls
  • Multiple instance independence tests
  • Edge cases with extreme durations (very short/long)
  • Real-world scenarios (e-commerce, search, chat, form validation, gaming)
  • Performance benchmarks (1000+ operations)
  • Total tests: 95 passing (up from 78)

Changed #

• 📝 Updated README with modern marketing content
  • Updated for 2025 best practices
  • Enhanced feature descriptions
  • Better performance metrics
  • Updated test badge to show 95 passing tests
  • More compelling value propositions

Fixed #

• 🐛 Improved timing reliability in async tests
• 🐛 Better edge case handling in stress scenarios

---

Phase 1: Foundation & Growth - Community Feedback & Polish 🚀

This release adds powerful debugging, monitoring, and control features based on community feedback.

Added #

Debug Mode (P1)

• ✅ Added debugMode parameter to all controllers (Throttler, Debouncer, AsyncDebouncer, AsyncThrottler)
• ✅ Added name parameter for controller identification in logs
• ✅ Automatic timestamped logging of throttle/debounce events
• Example:

  Throttler(
    debugMode: true,
    name: 'submit-button',
  )
  // Logs: "[submit-button] Throttle executed at 2025-12-08T10:30:45.123"
  

Performance Metrics (P2)

• ✅ Added onMetrics callback to track execution time and state
• ✅ Throttler: Tracks execution time and whether calls were executed or blocked
• ✅ Debouncer: Tracks wait time and whether calls were cancelled
• ✅ AsyncDebouncer: Tracks async operation duration and cancellations
• ✅ AsyncThrottler: Tracks async operation duration and lock state
• Example:

  Throttler(
    onMetrics: (duration, executed) {
      print('Execution time: $duration, executed: $executed');
    },
  )
  

Conditional Throttling/Debouncing (P1)

• ✅ Added enabled parameter to all controllers
• ✅ When enabled = false, controllers bypass throttle/debounce logic entirely
• ✅ Useful for VIP users, admin modes, or testing
• Example:

  Throttler(
    enabled: !isVipUser, // VIP users skip throttle
  )
  

Custom Cooldown per Call (P2)

• ✅ Added callWithDuration() method to Throttler and Debouncer
• ✅ Override default duration for specific calls
• Example:

  final throttler = Throttler(duration: Duration(seconds: 1));
  throttler.callWithDuration(() => normalAction(), Duration(milliseconds: 500));
  throttler.callWithDuration(() => criticalAction(), Duration(seconds: 2));
  

Reset on Error (P2)

• ✅ Added resetOnError parameter to all controllers
• ✅ Automatically resets controller state when callbacks throw exceptions
• ✅ Prevents users from being locked out after errors
• Example:

  Throttler(
    resetOnError: true, // Auto-resets after exceptions
  )
  

Batch Execution (P2)

• ✅ New BatchThrottler class for collecting and executing multiple actions as one batch
• ✅ Useful for analytics tracking, batched API calls, or optimizing state updates
• ✅ Includes flush(), clear(), and pendingCount for control
• Example:

  final batcher = BatchThrottler(
    duration: Duration(milliseconds: 500),
    onBatchExecute: (actions) {
      for (final action in actions) {
        action();
      }
    },
    debugMode: true,
    name: 'analytics-batch',
  );
  
  // Multiple rapid calls
  batcher.add(() => trackEvent('click1'));
  batcher.add(() => trackEvent('click2'));
  batcher.add(() => trackEvent('click3'));
  // After 500ms, all 3 events execute as one batch
  

Changed #

• ⚠️ Minor Breaking Change: Debouncer error handling - Errors in debounced callbacks are now swallowed (logged in debug mode) instead of being rethrown. This is consistent with Timer callback behavior and prevents uncaught exceptions in async scenarios.

Fixed #

• ✅ Improved edge case handling for dispose during async execution
• ✅ Better hot reload support with proper cleanup
• ✅ Fixed rapid rebuild scenarios
• ✅ Fixed unused variable warning in Debouncer.flush()

Tests #

• ✅ Added comprehensive test suite for all v1.1.0 features
• ✅ 78 total tests passing (all existing + 29 new v1.1.0 tests)
• ✅ Test coverage for debug mode, metrics, conditional execution, custom durations, error handling, and batch execution

Documentation #

• ✅ Updated all controller documentation with v1.1.0 feature examples
• ✅ Added inline examples for each new feature
• ✅ Maintained backward compatibility for all existing APIs

---

Documentation Improvements 📚

Changes #

• ✅ Improved README - More concise and professional

  • Reduced length from 1,175 to 745 lines (37% reduction)
  • Added compelling 30-second demo with Before/After comparison
  • Replaced aggressive comparisons with professional feature table
  • Improved structure with clear sections and visual hierarchy
  • Added real-world scenarios with problem statements

• ✅ Added .pubignore - Cleaner package distribution

  • Excluded internal documentation and marketing materials
  • Excluded build artifacts
  • Reduced package size from 93 KB to 25 KB

SEO & Market Positioning Release 🚀

Major Enhancements #

Documentation & Marketing

• ✅ Comprehensive competitor analysis - Added detailed comparison with 6 major competitors:

  • flutter_smart_debouncer (hard-coded widgets approach)
  • flutter_throttle_debounce (basic utility approach)
  • easy_debounce_throttle (stream-based approach)
  • easy_debounce (manual ID approach)
  • rxdart (over-engineering approach)
  • Plus existing comparison with industry standards

• ✅ Enhanced README with "Why Different?" section explaining three common library traps:

  • The "Basic Utility" Trap (manual lifecycle)
  • The "Hard-Coded Widget" Trap (no flexibility)
  • The "Over-Engineering" Trap (unnecessary complexity)

• ✅ Expanded comparison table - Now includes all 6 competitors with 11 comparison categories

• ✅ Real-world code comparisons - Side-by-side examples showing 80% code reduction

• ✅ Complete use-case catalog - Added 5 production scenarios:

  • E-Commerce: Prevent double checkout
  • Search: Auto-cancel old requests
  • Form Submit: Loading state & error handling
  • Chat App: Prevent message spam
  • Game: High-frequency input throttling

• ✅ Migration guides - Detailed guides from all 3 main competitor categories

• ✅ FAQ section - 7 common questions with SEO-optimized answers

SEO Optimizations

• ✅ Updated description - Highlights unique value propositions:

  • "Complete event management framework" (not just utility)
  • "Universal Builders for ANY widget" (flexibility)
  • "Perfect 160/160 pub points" (quality badge)

• ✅ Enhanced topics - Maintains 8 high-traffic keywords:

  • throttle, debounce, anti-spam, button, widget
  • race-condition, loading-state, double-click

• ✅ Competitive positioning - Clear differentiation from all competitors

• ✅ Trust signals - Added pub points badge and test count prominently

Analysis Documents

• ✅ Created COMPETITOR_DEEP_ANALYSIS.md - 30+ page deep dive covering:

  • Detailed analysis of each competitor's strengths/weaknesses
  • Feature matrices and comparison tables
  • Marketing positioning strategies
  • Attack strategies for each competitor category

• ✅ Created SEO_MARKETING_STRATEGY.md - Comprehensive 21-page strategy

• ✅ Created SEO_CHANGES_SUMMARY.md - Executive summary of all changes

Key Differentiators Highlighted #

1. Universal Builders - Only library supporting ANY widget (not hard-coded)
2. Built-in Loading State - Only library with automatic isLoading management
3. Auto Safety - Only library with auto mounted check + auto-dispose
4. Perfect Score - Only throttle/debounce library with 160/160 pub points
5. Production Ready - Only library with 48 comprehensive tests

Metrics #

• Code Reduction: 80% less code vs competitors for common tasks
• Pub Points: 160/160 (best in category)
• Test Coverage: 48 comprehensive tests
• Competitor Wins: 9 out of 10 comparison categories

---

Pub.dev optimization release 📦

Changes #

• ✅ Fixed package description length (reduced to 144 chars for pub.flutter-io.cn compliance)
• ✅ Formatted all Dart code with dart format for 50/50 static analysis points
• ✅ Removed unnecessary documentation files for cleaner package
• ✅ Package now scores 160/160 pub points (perfect score!)

Removed Files #

• Development documentation (FINAL_CHECKLIST.md, FINAL_REVIEW.md, etc.)
• Setup scripts (setup_github.sh, setup_github.bat)
• Publishing guides (moved to separate repository)

---

Initial release 🎉

Features #

Core Controllers

• Throttler: Prevents spam clicks with time-based blocking
• Debouncer: Delays execution until pause
• AsyncDebouncer: Async debouncing with auto-cancel for race condition prevention
• AsyncThrottler: Process-based throttling with automatic timeout
• HighFrequencyThrottler: DateTime-based throttling for 60fps events
• ThrottleDebouncer: Combined leading + trailing execution (rare use case)

Wrapper Widgets

• ThrottledInkWell: Throttled InkWell with onTap, onDoubleTap, onLongPress support
• ThrottledTapWidget: Throttled GestureDetector without ripple
• ThrottledCallback: Generic throttled callback wrapper
• DebouncedTapWidget: Debounced tap widget
• DebouncedCallback: Generic debounced callback wrapper

Text Controllers

• DebouncedTextController: TextField controller with debouncing
• AsyncDebouncedTextController: TextField controller with async debouncing, loading state, and error handling

Builder Widgets (Universal - work with ANY widget)

• ThrottledBuilder: Universal throttle builder
• DebouncedBuilder: Universal debounce builder
• AsyncThrottledBuilder: Universal async throttle builder
• AsyncDebouncedBuilder: Universal async debounce builder

Enhanced Builders (with loading state and error handling)

• AsyncThrottledCallbackBuilder: Form submission with auto loading state
• AsyncDebouncedCallbackBuilder: Search API with auto loading state

Safety Features #

• ✅ Automatic mounted check in builder widgets with loading state
• ✅ Automatic disposal of all controllers
• ✅ Memory leak prevention with proper cleanup
• ✅ Race condition prevention with ID-based cancellation
• ✅ Stack trace capture in error handling

Bug Fixes #

• Fixed hanging futures when AsyncDebouncer timer is cancelled
• Fixed loading state flicker when debounced calls are cancelled
• Fixed potential memory leak in TextController constructors
• Added assert to prevent controller + initialValue conflict

Documentation #

• Comprehensive README with usage examples
• Inline documentation for all classes and methods
• Common pitfalls section
• Migration guide from manual Timer usage

Testing #

• 48 comprehensive unit tests covering all core functionality
• 100% core logic coverage (all controllers, widgets, and edge cases)
• Production-ready code (zero known bugs)
• Tested in real-world applications

---

Future Releases #

See Roadmap for planned features.