dart_debounce_throttle

The Traffic Control System for Dart

Debounce, throttle, rate limit (Token Bucket), and batch — for Dart servers, CLI tools, and shared business logic. Zero external dependencies.

---

🚀 Honest API — No Silent Failures

Most libraries return void, causing "silent failures" where dropped operations appear to succeed. This library introduces ThrottlerResult and DebounceResult so the compiler forces you to handle every outcome.

// ✅ compiler forces handling of both branches
final result = await throttler.call(() async => await processPayment(order));

result.when(
  onExecuted: () => sendConfirmationEmail(order),
  onDropped:  () => log.warn('Request dropped — server busy'),
);

---

5-Second Start

// Rate limit outbound API calls (Token Bucket)
final limiter = RateLimiter(maxTokens: 10, refillRate: 2);
if (limiter.tryAcquire()) await callExpensiveAPI();

// Batch database writes (1000 calls → 10 DB writes)
final batcher = BatchThrottler(
  duration: 1.seconds,
  maxBatchSize: 100,
  onBatchExecute: (items) => db.insertBatch(items),
);
batcher(() => logEntry);

// Debounce with leading edge (cache stampede protection)
final debouncer = Debouncer(duration: 5.seconds, leading: true);
debouncer(() => refreshCache());

---

Complete Toolkit

Class	Use Case
RateLimiter	Token Bucket algorithm — API cost control
BatchThrottler	Batch operations — 100x fewer DB writes
Throttler	Basic rate limiting — one call per interval
Debouncer	Wait for pause (leading/trailing edge)
AsyncDebouncer	Auto-cancel stale async calls
AsyncThrottler	Async operations with timeout
ConcurrentAsyncThrottler	4 concurrency modes
DistributedRateLimiter	Multi-server rate limiting (Redis/Memcached)
HighFrequencyThrottler	High-freq events — no Timer overhead
Stream Extensions	rxdart-style .debounce() / .throttle()

---

Features

• Token Bucket Rate Limiting: Professional-grade outbound call control.
• Distributed Rate Limiting: Sync across Redis/Memcached (perfect for Dart Frog/Serverpod).
• Concurrency Control: 4 modes (drop, replace, enqueue, keepLatest) for async tasks.
• Batch Processing: Automatically group high-frequency items into single operations.
• Memory Safety: Auto-cleanup of unused limiters and verified zero leaks.

---

Installation

dependencies:
  dart_debounce_throttle: ^2.4.6

---

Quality Assurance

Guarantee	How
570+ tests	Unit, integration, security, performance & stress tests
Zero dependencies	Only meta package in production
Type-safe	No dynamic, full generics
Compile-time safety	when() forces exhaustive handling of results

---

GitHub · FAQ · API Reference

Made with craftsmanship by Brewkits