Flutter Event Limiter 🛡️

Production-ready throttle and debounce for Flutter apps.

Stop wrestling with Timer boilerplate, race conditions, and setState crashes. Handle button spam, search debouncing, and async operations with 3 lines of code instead of 15+.

⚡ Quick Start

Problem: Manual Throttling (15+ lines, error-prone)

Timer? _timer;
bool _loading = false;

void onSearch(String text) {
  _timer?.cancel();
  _timer = Timer(Duration(milliseconds: 300), () async {
    setState(() => _loading = true);
    try {
      final result = await api.search(text);
      if (!mounted) return; // Easy to forget!
      setState(() => _result = result);
    } finally {
      if (mounted) setState(() => _loading = false);
    }
  });
}

@override
void dispose() {
  _timer?.cancel(); // Easy to forget!
  super.dispose();
}

Solution: flutter_event_limiter (3 lines, safe)

AsyncDebouncedTextController(
  onChanged: (text) async => await api.search(text),
  onSuccess: (result) => setState(() => _result = result),
  onLoadingChanged: (loading) => setState(() => _loading = loading),
)

Result: 80% less code. Auto-dispose. Auto mounted checks. Auto loading state.

✨ Why This Library?

Built for production use:

✅ 160/160 pub points - Perfect score, actively maintained
✅ 128 comprehensive tests - Edge cases covered, battle-tested
✅ Zero dependencies - No bloat, no conflicts

Saves development time:

✅ 3 lines vs 15+ - Eliminates boilerplate
✅ Auto-safety - No setState crashes, no memory leaks
✅ Works with any widget - Material, Cupertino, custom widgets

Unique features:

✅ Built-in loading state - No manual bool isLoading = false needed
✅ Race condition prevention - Auto-cancels stale API calls
✅ Universal builders - Not locked into specific widgets

See detailed comparison with alternatives →

🚀 Common Use Cases

1. Prevent Button Double-Clicks

ThrottledInkWell(
  onTap: () => submitOrder(), // Only executes once per 500ms
  child: Text("Submit Order"),
)

See E-Commerce example →

2. Smart Search Bar

AsyncDebouncedTextController(
  duration: Duration(milliseconds: 300),
  onChanged: (text) async => await api.search(text),
  onSuccess: (products) => setState(() => _products = products),
  onLoadingChanged: (isLoading) => setState(() => _loading = isLoading),
)

See Search example →

3. Form Submission with Loading UI

AsyncThrottledCallbackBuilder(
  onPressed: () async => await uploadFile(),
  builder: (context, callback, isLoading) {
    return ElevatedButton(
      onPressed: isLoading ? null : callback,
      child: isLoading ? CircularProgressIndicator() : Text("Upload"),
    );
  },
)

See Form example →

4. Advanced Concurrency Control (NEW in v1.2.0)

Control how multiple async operations are handled with 4 powerful modes:

// Chat App: Queue messages and send in order
ConcurrentAsyncThrottledBuilder(
  mode: ConcurrencyMode.enqueue,
  onPressed: () async => await api.sendMessage(text),
  builder: (context, callback, isLoading, pendingCount) {
    return ElevatedButton(
      onPressed: callback,
      child: Text(pendingCount > 0 ? 'Sending ($pendingCount)...' : 'Send'),
    );
  },
)

// Search: Cancel old queries, only run latest
ConcurrentAsyncThrottledBuilder(
  mode: ConcurrencyMode.replace,
  onPressed: () async => await api.search(query),
  builder: (context, callback, isLoading, _) {
    return SearchBar(
      onChanged: (q) { query = q; callback?.call(); },
      trailing: isLoading ? CircularProgressIndicator() : null,
    );
  },
)

// Auto-save: Save current + latest only
ConcurrentAsyncThrottledBuilder(
  mode: ConcurrencyMode.keepLatest,
  onPressed: () async => await api.saveDraft(content),
  builder: (context, callback, isLoading, _) {
    return TextField(
      onChanged: (text) { content = text; callback?.call(); },
      decoration: InputDecoration(
        suffixIcon: isLoading ? CircularProgressIndicator() : Icon(Icons.check),
      ),
    );
  },
)

4 Concurrency Modes:

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

See interactive demo →

🎨 Universal Builder Pattern

The power of flexibility: Works with any Flutter widget.

ThrottledBuilder(
  duration: Duration(seconds: 1),
  builder: (context, throttle) {
    return FloatingActionButton(
      onPressed: throttle(() => saveData()),
      child: Icon(Icons.save),
    );
  },
)

Use with:

✅ Material Design (ElevatedButton, FloatingActionButton, InkWell)
✅ Cupertino (CupertinoButton, CupertinoTextField)
✅ Custom widgets from any package
✅ Third-party UI libraries

Unlike other libraries that lock you into specific widgets, flutter_event_limiter adapts to your UI framework.

📊 Throttle vs Debounce: Which One?

Throttle (Anti-Spam)

Fires immediately, then blocks for duration.

User clicks: ▼     ▼   ▼▼▼       ▼
Executes:    ✓     X   X X       ✓
             |<-500ms->|         |<-500ms->|

Use for: Button clicks, refresh actions, preventing spam

Debounce (Wait for Pause)

Waits for pause in events, then fires.

User types:  a  b  c  d ... (pause) ... e  f  g
Executes:                   ✓                   ✓
             |<--300ms wait-->|     |<--300ms wait-->|

Use for: Search input, auto-save, slider changes

AsyncDebouncer (Debounce + Auto-Cancel)

Waits for pause and cancels previous async operations.

User types:  a    b    c  (API starts) ... d
API calls:   X    X    ▼ (running...)   X (cancelled)
Result used:                            ✓ (only 'd')

Use for: Search APIs, autocomplete, async validation

Learn more about timing strategies →

📚 Complete Widget Reference

Throttling (Anti-Spam Buttons)

Widget	Use Case
`ThrottledInkWell`	Material buttons with ripple
`ThrottledBuilder`	Universal - Any widget
`AsyncThrottledCallbackBuilder`	Async with auto loading state
`Throttler`	Direct class (advanced)

Debouncing (Search, Auto-save)

Widget	Use Case
`DebouncedTextController`	Basic text input
`AsyncDebouncedTextController`	Search API with loading
`DebouncedBuilder`	Universal - Any widget
`Debouncer`	Direct class (advanced)

High-Frequency Events

Widget	Use Case
`HighFrequencyThrottler`	Scroll, mouse, resize (60fps)

View full API documentation →

🛠 Installation

flutter pub add flutter_event_limiter

Or add to pubspec.yaml:

dependencies:
  flutter_event_limiter: ^1.1.2

Then import:

import 'package:flutter_event_limiter/flutter_event_limiter.dart';

📖 Documentation

Getting Started

Examples

Migration Guides

From easy_debounce - Stop managing IDs manually
From flutter_smart_debouncer - Unlock from fixed widgets
From rxdart - Simpler API for UI events

Advanced

🎯 Features

Core Capabilities:

⏱️ Throttle - Execute immediately, block duplicates
⏳ Debounce - Wait for pause, then execute
🔄 Async Support - Built-in for async operations
🏃 High Frequency - Optimized for scroll/mouse events (60fps)
🎭 Combo - ThrottleDebouncer (leading + trailing)

Safety & Reliability:

🛡️ Auto Dispose - Zero memory leaks
✅ Auto Mounted Checks - No setState crashes
🏁 Race Condition Prevention - Auto-cancel stale calls
📦 Batch Execution - Group multiple operations

Developer Experience:

🎨 Universal Builders - Works with any widget
📊 Built-in Loading State - No manual flags
🐛 Debug Mode - Log throttle/debounce events
📈 Performance Metrics - Track execution time
⚙️ Conditional Execution - Enable/disable dynamically

🧪 Testing

Works seamlessly with Flutter's test framework:

testWidgets('throttle blocks rapid clicks', (tester) async {
  int clickCount = 0;

  await tester.pumpWidget(
    MaterialApp(
      home: ThrottledInkWell(
        duration: Duration(milliseconds: 500),
        onTap: () => clickCount++,
        child: Text('Tap'),
      ),
    ),
  );

  await tester.tap(find.text('Tap'));
  expect(clickCount, 1);

  await tester.tap(find.text('Tap')); // Blocked
  expect(clickCount, 1);

  await tester.pumpAndSettle(Duration(milliseconds: 500));
  await tester.tap(find.text('Tap')); // Works again
  expect(clickCount, 2);
});

See more testing examples in FAQ →

🔧 Advanced Features (v1.1.0+)

Debug Mode

Throttler(
  debugMode: true,
  name: 'submit-button',
  onMetrics: (duration, executed) {
    print('Throttle took: $duration, executed: $executed');
  },
)

Conditional Throttling

ThrottledBuilder(
  enabled: !isVipUser, // VIP users skip throttle
  builder: (context, throttle) => ElevatedButton(...),
)

Custom Duration per Call

final throttler = Throttler();

throttler.callWithDuration(
  () => criticalAction(),
  duration: Duration(seconds: 2), // Override default
);

Manual Reset

final throttler = Throttler();
throttler.call(() => action());
throttler.reset(); // Clear throttle state
throttler.call(() => action()); // Executes immediately

See all advanced features →

💡 Integration with State Management

Works with all state management solutions:

GetX:

ThrottledInkWell(
  onTap: () => Get.find<MyController>().submit(),
  child: Text("Submit"),
)

Riverpod:

AsyncDebouncedTextController(
  onChanged: (text) async {
    return await ref.read(searchProvider.notifier).search(text);
  },
  onSuccess: (results) {
    // Update state
  },
)

Bloc:

ThrottledBuilder(
  builder: (context, throttle) {
    return ElevatedButton(
      onPressed: throttle(() => context.read<MyBloc>().add(SubmitEvent())),
      child: Text("Submit"),
    );
  },
)

Provider:

ThrottledInkWell(
  onTap: () => context.read<CounterProvider>().increment(),
  child: Text("Increment"),
)

See more state management examples →

⚡ Performance

Near-zero overhead:

Metric	Performance
Throttle/Debounce	~0.01ms per call
High-Frequency Throttler	~0.001ms (100x faster)
Memory	~40 bytes per controller

Benchmarked: Handles 1000+ concurrent operations without frame drops.

See performance benchmarks →

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Add tests for new features
Submit a pull request

See CONTRIBUTING.md for guidelines.

📄 License

MIT License - See LICENSE file for details.

📮 Support

💬 Questions: FAQ · GitHub Discussions
🐛 Bugs: GitHub Issues
⭐ Like it? Star this repo!

Made with ❤️ for the Flutter community

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
docs		docs
example		example
lib		lib
test		test
.gitignore		.gitignore
.pubignore		.pubignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
analysis_options.yaml		analysis_options.yaml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

License

vietnguyentuan2019/flutter_event_limiter

Folders and files

Latest commit

History

Repository files navigation