FlowX

Production-grade resilience & async flow control for TypeScript/JavaScript.

Stop shipping fragile async code. FlowX gives you battle-tested patterns — retry, circuit breaker, rate limiter, bulkhead, queue, and 12 more — in a single, zero-dependency, tree-shakable package with 100% test coverage.

Why FlowX?

| | FlowX | Others | |--|-------|--------| | Dependencies | 0 | 3–15+ | | Test Coverage | 100% statements, branches, functions, lines | Partial | | TypeScript | Native .d.ts + .d.mts | Bolted-on types | | Tree-shaking | Per-module deep imports | Monolithic bundle | | Module Support | ESM + CJS + Types | Usually one | | Patterns | 17 resilience & flow primitives | 2–5 |

Install

npm install flowx-control
yarn add flowx-control
pnpm add flowx-control

Quick Start

import { retry, createCircuitBreaker, withTimeout, rateLimit } from 'flowx-control';

// Retry with exponential backoff
const data = await retry(() => fetch('/api/data'), {
  maxAttempts: 5,
  delay: 1000,
  backoff: 'exponential',
});

// Circuit breaker
const breaker = createCircuitBreaker(fetchUser, {
  failureThreshold: 5,
  resetTimeout: 30_000,
});
const user = await breaker.fire(userId);

// Timeout
const result = await withTimeout(() => fetch('/slow'), 5000, {
  fallback: () => cachedResponse,
});

// Rate limiter
const limiter = createRateLimiter({ limit: 10, interval: 1000 });
await limiter.execute(() => callExternalApi());

All 17 Modules

🛡️ Resilience

• retry — Exponential backoff, jitter, abort signal, custom retry predicates
• circuitBreaker — Closed/Open/Half-open state machine, trip hooks
• fallback — Graceful degradation with fallback chains
• timeout — Hard deadline + optional fallback value

🚦 Concurrency

• bulkhead — Max concurrent + max queue isolation
• queue — Priority async task queue with concurrency
• semaphore — Counting resource lock (acquire/release)
• mutex — Mutual exclusion for critical sections

🎛️ Flow Control

• rateLimit — Token bucket with queue/reject strategies
• throttle — Leading/trailing edge, cancellable
• debounce — maxWait support, flush/cancel
• batch — Process collections in chunks with progress
• pipeline — Compose sync/async operations

🛠️ Utilities

• poll — Repeated polling with backoff until condition
• hedge — Speculative parallel requests
• memo — Async memoization with TTL + max size
• deferred — Externally resolvable promise

Error Hierarchy

| Error | Code | Thrown by | |-------|------|----------| | TimeoutError | ERR_TIMEOUT | withTimeout | | CircuitBreakerError | ERR_CIRCUIT_OPEN | circuitBreaker | | BulkheadError | ERR_BULKHEAD_FULL | bulkhead | | AbortError | ERR_ABORTED | poll, batch, timeout | | RateLimitError | ERR_RATE_LIMIT | rateLimit |

Compatibility

| Environment | Support | |-------------|---------| | Node.js | ≥ 16 | | Bun | ✅ | | Deno | ✅ | | Browsers | ✅ (ESM) | | TypeScript | ≥ 4.7 |

Contributing

git clone https://github.com/Avinashvelu03/flowx-control.git
cd flowx-control && npm install
npm test
npm run build

License

MIT © Avinash

⚡ Fuel the Flow

  · · · · · · · · · · · · · · · · · · · · · · · ·
  ·                                       ·
  ·   FlowX handles your retries,          ·
  ·   your circuit breakers,               ·
  ·   your race conditions,                ·
  ·   and your 3 AM production fires.      ·
  ·                                       ·
  ·   If it earned your trust — fuel it.   ·
  ·                                       ·
  · · · · · · · · · · · · · · · · · · · · · · · ·

No budget? No problem:

• ⭐ Star FlowX — boosts discovery
• 🐛 Open an issue — shape the roadmap
• 🗣️ Tell a dev who ships async code

Built solo, shipped free — by Avinash Velu