@julr/tenace 1.0.0-next.0 → 1.0.0-next.1

package/README.md

@@ -1,6 +1,6 @@
 # Tenace
 
-A fluent resilience library for Node.js. Make any async operation resilient with timeout, retry, circuit breaker, bulkhead, and more.
+Resilience library for Node.js. Timeout, retry, circuit breaker, bulkhead, caching, rate limiting, and more.
 
 ## Installation
 
@@ -30,10 +30,6 @@ import type { CacheAdapter, RateLimiterAdapter, LockAdapter } from '@julr/tenace
 ```ts
 import { Tenace } from '@julr/tenace'
 
-// Without Tenace: hope for the best
-const user = await fetch('/api/users/1')
-
-// With Tenace: be resilient
 const user = await Tenace.call(() => fetch('/api/users/1'))
   .withTimeout('5s')
   .withRetry({ times: 3 })
@@ -41,70 +37,37 @@ const user = await Tenace.call(() => fetch('/api/users/1'))
   .execute()
 ```
 
-## Understanding the Pipeline
-
-Tenace uses a **pipeline** system for policies. **The order you add policies = the order errors flow through them.**
-
-### The Golden Rule
-
-> **First added = Innermost layer (handles errors first)**
-> **Last added = Outermost layer (catches errors last)**
+## Pipeline
 
-Think of it like a pipeline: `fn → timeout → retry → fallback`
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  .withFallback()     ← 4th: Catches ALL errors (outermost) │
-│  ┌───────────────────────────────────────────────────────┐  │
-│  │  .withRetry()     ← 3rd: Retries timeout errors       │  │
-│  │  ┌─────────────────────────────────────────────────┐  │  │
-│  │  │  .withTimeout()  ← 2nd: Timeout per attempt     │  │  │
-│  │  │  ┌───────────────────────────────────────────┐  │  │  │
-│  │  │  │  .withCircuitBreaker()  ← 1st: Tracks     │  │  │  │
-│  │  │  │  ┌─────────────────────────────────────┐  │  │  │  │
-│  │  │  │  │                                     │  │  │  │  │
-│  │  │  │  │          YOUR FUNCTION              │  │  │  │  │
-│  │  │  │  │                                     │  │  │  │  │
-│  │  │  │  └─────────────────────────────────────┘  │  │  │  │
-│  │  │  └───────────────────────────────────────────┘  │  │  │
-│  │  └─────────────────────────────────────────────────┘  │  │
-│  └───────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
+The order you add policies matters. First added = innermost layer (closest to your function). Last added = outermost layer.
 
-### Order Matters: Common Patterns
-
-#### Pattern 1: Timeout per attempt vs total timeout
+### Timeout per attempt vs total timeout
 
 ```ts
-// ✅ 5s timeout PER attempt
-// timeout is inner (first), retry is outer (second)
+// 5s timeout PER attempt
 Tenace.call(fn)
   .withTimeout('5s')
   .withRetry({ times: 5 })
   .execute()
 
-// ⚠️ TOTAL timeout of 5s for ALL retries combined
-// retry is inner (first), timeout is outer (second)
+// TOTAL timeout of 5s for ALL retries combined
 Tenace.call(fn)
   .withRetry({ times: 5 })
   .withTimeout('5s')
   .execute()
 ```
 
-#### Pattern 2: Where to place fallback
+### Where to place fallback
 
 ```ts
-// ✅ Fallback catches EVERYTHING (recommended)
-// retry first (inner) → fallback second (outer)
+// Fallback catches everything (recommended)
 Tenace.call(fn)
   .withRetry({ times: 3 })
   .withTimeout('5s')
   .withFallback(() => defaultValue)
   .execute()
 
-// ⚠️ Fallback only catches fn errors, not retry/timeout
-// fallback is inner, retry is outer
+// Fallback only catches fn errors, not retry/timeout errors
 Tenace.call(fn)
   .withFallback(() => defaultValue)
   .withRetry({ times: 3 })
@@ -112,56 +75,41 @@ Tenace.call(fn)
   .execute()
 ```
 
-#### Pattern 3: Circuit breaker placement
+### Circuit breaker placement
 
 ```ts
-// ✅ RECOMMENDED: Circuit breaker inside retry
-// CB first (inner) → retry second (outer)
-// Each retry attempt is tracked separately
+// Circuit breaker inside retry = each attempt is tracked separately
 Tenace.call(fn)
   .withCircuitBreaker({ failureThreshold: 5, halfOpenAfter: '30s' })
   .withRetry({ times: 3 })
   .execute()
 
-// ⚠️ Circuit breaker outside retry
-// retry is inner, CB is outer
-// Only the final result (after all retries) is tracked
+// Circuit breaker outside retry = only the final result is tracked
 Tenace.call(fn)
   .withRetry({ times: 3 })
   .withCircuitBreaker({ failureThreshold: 5, halfOpenAfter: '30s' })
   .execute()
 ```
 
-### Recommended Order
-
-For most use cases (reading order = error handling order):
+### Recommended order
 
 ```ts
 Tenace.call(fn)
   .withCircuitBreaker(...)            // 1. Failure tracking (innermost)
   .withTimeout('5s')                  // 2. Timeout per attempt
   .withRetry({ times: 3 })            // 3. Retry on timeout/error
-  .withFallback(() => defaultValue)   // 4. Catch-all safety net (outermost)
+  .withFallback(() => defaultValue)   // 4. Catch-all (outermost)
   .execute()
 ```
 
-### Errors That Stop Retries
-
-The retry policy will **NOT** retry these errors (fail-fast behavior):
+### Errors that stop retries
 
-| Error               | Reason                                        |
-| ------------------- | --------------------------------------------- |
-| `CircuitOpenError`  | Circuit breaker is open, no point retrying    |
-| `BulkheadFullError` | System is overloaded, retrying makes it worse |
-
-All other errors (including `TimeoutError`) **will** be retried.
+`CircuitOpenError` and `BulkheadFullError` are never retried. All other errors (including `TimeoutError`) will be retried.
 
 ## Policies
 
 ### Timeout
 
-Set a maximum execution time. Supports two strategies:
-
 ```ts
 // Cooperative (default): Passes AbortSignal, function should respect it
 Tenace.call(({ signal }) => fetch('/api', { signal }))
@@ -176,10 +124,7 @@ Tenace.call(() => slowOperation())
 
 ### Retry
 
-Retry failed operations with configurable backoff:
-
 ```ts
-// Simple retry
 Tenace.call(fn)
   .withRetry({ times: 3 })
   .execute()
@@ -218,9 +163,7 @@ Tenace.call(fn)
   .execute()
 ```
 
-#### Backoff Presets
-
-Use the `backoff` helper for common backoff patterns:
+#### Backoff presets
 
 ```ts
 import { Tenace, backoff } from '@julr/tenace'
@@ -248,20 +191,16 @@ Tenace.call(fn)
 
 Available presets:
 
-| Preset                                | Description                 | Options                                  |
-| ------------------------------------- | --------------------------- | ---------------------------------------- |
-| `backoff.constant(delay)`             | Fixed delay between retries | `Duration`                               |
-| `backoff.exponential(opts)`           | Doubles each time (default) | `{ initial?, max?, exponent? }`          |
-| `backoff.exponentialWithJitter(opts)` | Exponential + randomization | `{ initial?, max?, exponent?, jitter? }` |
-| `backoff.linear(opts)`                | Increases by fixed step     | `{ initial?, step?, max? }`              |
+- `backoff.constant(delay)` - Fixed delay between retries
+- `backoff.exponential({ initial?, max?, exponent? })` - Doubles each time
+- `backoff.exponentialWithJitter({ initial?, max?, exponent?, jitter? })` - Exponential + randomization
+- `backoff.linear({ initial?, step?, max? })` - Increases by fixed step
 
-Jitter strategies for `exponentialWithJitter`:
-- `'full'` (default): Random delay between 0 and calculated delay
-- `'decorrelated'`: AWS-style decorrelated jitter ([recommended](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/))
+Jitter strategies: `'full'` (default) or `'decorrelated'` (AWS-style)
 
 ### Circuit Breaker
 
-Stop calling a failing service. After N failures, the circuit "opens" and all calls fail immediately with `CircuitOpenError`.
+After N consecutive failures, the circuit opens and all calls fail immediately with `CircuitOpenError`.
 
 ```ts
 const policy = Tenace.policy()
@@ -288,20 +227,17 @@ handle?.dispose() // Release isolation
 
 ### Bulkhead
 
-Limit concurrent executions to protect downstream services:
+Limit concurrent executions. Throws `BulkheadFullError` if the queue is full.
 
 ```ts
 const policy = Tenace.policy()
   .withBulkhead(10, 100) // max 10 concurrent, 100 in queue
 
 await policy.call(() => heavyOperation()).execute()
-// Throws BulkheadFullError if queue is also full
 ```
 
 ### Fallback
 
-Return a default value when everything fails:
-
 ```ts
 const user = await Tenace.call(() => fetchUser(id))
   .withFallback(() => ({ id, name: 'Unknown', cached: true }))
@@ -317,38 +253,32 @@ const user = await Tenace.call(() => fetchUser(id))
 
 ## Adapters
 
-Cache, Rate Limiter, and Distributed Lock are **integrated into the pipeline**. Order matters - just like other policies!
+Cache, Rate Limiter, and Distributed Lock follow the same pipeline rules.
 
 ### Cache
 
-Cache successful results to avoid redundant calls:
-
 ```ts
-// Basic caching
 const user = await Tenace.call(() => fetchUser(id))
-  .withCache({ key: `user:${id}`, ttl: 60_000 }) // 1 minute TTL
+  .withCache({ key: `user:${id}`, ttl: 60_000 })
   .execute()
 ```
 
-#### Order patterns for cache
+#### Order patterns
 
 ```ts
-// ✅ Fallback BEFORE cache = fallback values ARE cached
-// fallback (inner) → cache (outer) = cache stores fallback result
+// Fallback BEFORE cache = fallback values are cached
 Tenace.call(fn)
   .withFallback(() => defaultValue)
   .withCache({ key: 'x', ttl: 60_000 })
   .execute()
 
-// ⚠️ Cache BEFORE fallback = fallback values NOT cached
-// cache (inner) → fallback (outer) = cache doesn't see fallback result
+// Cache BEFORE fallback = fallback values not cached
 Tenace.call(fn)
   .withCache({ key: 'x', ttl: 60_000 })
   .withFallback(() => defaultValue)
   .execute()
 
-// ✅ RateLimit BEFORE cache = no token consumed on cache hit
-// rateLimit (inner) → cache (outer) = cache checks first
+// RateLimit BEFORE cache = no token consumed on cache hit
 Tenace.call(fn)
   .withRateLimit({ key: 'api', maxCalls: 100, windowMs: 60_000 })
   .withCache({ key: 'x', ttl: 60_000 })
@@ -358,13 +288,13 @@ Tenace.call(fn)
 #### Graceful degradation
 
 ```ts
-// If Redis is down, continue without cache (don't fail the request)
+// If the adapter is down, continue without cache
 await Tenace.call(fn)
   .withCache({ key: 'x', ttl: 60_000, optional: true })
   .execute()
 ```
 
-**Built-in adapter**: `MemoryCacheAdapter` (uses Bentocache under the hood)
+**Built-in adapter**: `MemoryCacheAdapter` (uses Bentocache)
 
 ```ts
 import { MemoryCacheAdapter } from '@julr/tenace/adapters'
@@ -382,7 +312,7 @@ await Tenace.call(fn)
   .execute()
 ```
 
-**Custom adapter**: Implement `CacheAdapter` interface
+**Custom adapter**: Implement `CacheAdapter`
 
 ```ts
 import type { CacheAdapter } from '@julr/tenace/adapters'
@@ -397,10 +327,9 @@ class RedisCacheAdapter implements CacheAdapter {
 
 ### Rate Limiter
 
-Limit call frequency to protect APIs or respect external rate limits:
+Throws `RateLimitError` when limit is exceeded (includes `retryAfterMs`).
 
 ```ts
-// 100 calls per minute
 const result = await Tenace.call(() => callExternalApi())
   .withRateLimit({
     key: 'external-api',
@@ -410,28 +339,51 @@ const result = await Tenace.call(() => callExternalApi())
   .execute()
 ```
 
-Throws `RateLimitError` when limit is exceeded. The error includes `retryAfterMs`.
+#### Queue mode
+
+By default, requests exceeding the rate limit are rejected immediately. Enable queue mode to wait for tokens to become available instead:
+
+```ts
+// Requests wait in queue instead of being rejected
+const result = await Tenace.call(() => callExternalApi())
+  .withRateLimit({
+    key: 'external-api',
+    maxCalls: 10,
+    windowMs: 1000,
+    queue: {},  // Enable queue with default settings
+  })
+  .execute()
+
+// Limit queue size to prevent unbounded memory usage
+const result = await Tenace.call(() => callExternalApi())
+  .withRateLimit({
+    key: 'external-api',
+    maxCalls: 10,
+    windowMs: 1000,
+    queue: { maxSize: 100 },  // Max 100 requests in queue
+  })
+  .execute()
+```
+
+Throws `RateLimitQueueFullError` when the queue is full.
 
-#### Order patterns for rate limit
+#### Order patterns
 
 ```ts
-// ✅ RateLimit BEFORE fallback = fallback catches RateLimitError
-// rateLimit (inner) → fallback (outer)
+// RateLimit BEFORE fallback = fallback catches RateLimitError
 Tenace.call(fn)
   .withRateLimit({ key: 'api', maxCalls: 100, windowMs: 60_000 })
   .withFallback(() => defaultValue)
   .execute()
 
-// ⚠️ Fallback BEFORE rateLimit = RateLimitError NOT caught by fallback
-// fallback (inner) → rateLimit (outer)
+// Fallback BEFORE rateLimit = RateLimitError not caught by fallback
 Tenace.call(fn)
   .withFallback(() => defaultValue)
   .withRateLimit({ key: 'api', maxCalls: 100, windowMs: 60_000 })
   .execute()
 
-// ✅ Retry with error-based delay for rate limit handling
+// Retry with error-based delay for rate limit handling
 await Tenace.call(fn)
-  .withFallback(() => defaultValue)
   .withRetry({
     times: 3,
     delay: (attempt, error) => {
@@ -446,13 +398,13 @@ await Tenace.call(fn)
 #### Graceful degradation
 
 ```ts
-// If Redis is down, allow the call through (don't enforce rate limit)
+// If the adapter is down, allow the call through
 await Tenace.call(fn)
   .withRateLimit({ key: 'api', maxCalls: 100, windowMs: 60_000, optional: true })
   .execute()
 ```
 
-**Built-in adapter**: `MemoryRateLimiterAdapter` (uses rate-limiter-flexible)
+**Built-in adapter**: `MemoryRateLimiterAdapter`
 
 ```ts
 import { MemoryRateLimiterAdapter } from '@julr/tenace/adapters'
@@ -463,13 +415,14 @@ configStore.configure({
 })
 ```
 
-**Custom adapter**: Implement `RateLimiterAdapter` interface
+**Custom adapter**: Implement `RateLimiterAdapter`
 
 ```ts
-import type { RateLimiterAdapter, RateLimitConfig, RateLimitResult, RateLimitState } from '@julr/tenace/adapters'
+import type { RateLimiterAdapter, RateLimitConfig, RateLimitResult, RateLimitState, RateLimitQueueConfig } from '@julr/tenace/adapters'
 
 class RedisRateLimiterAdapter implements RateLimiterAdapter {
   async acquire(key: string, options: RateLimitConfig): Promise<RateLimitResult> { /* ... */ }
+  async removeTokens(options: { key: string; tokens: number; config: RateLimitConfig; queue?: RateLimitQueueConfig }): Promise<number> { /* ... */ }
   async getState(key: string): Promise<RateLimitState> { /* ... */ }
   async reset(key: string): Promise<void> { /* ... */ }
 }
@@ -477,46 +430,40 @@ class RedisRateLimiterAdapter implements RateLimiterAdapter {
 
 ### Distributed Lock
 
-Ensure only one process executes a critical section at a time (useful for distributed systems):
+Throws `LockNotAcquiredError` if the lock cannot be acquired.
 
 ```ts
-// Process payment with distributed lock
 const result = await Tenace.call(() => processPayment(orderId))
   .withDistributedLock({
     key: `payment:${orderId}`,
-    ttl: 30_000,  // Lock expires after 30s (prevents deadlocks)
+    ttl: 30_000,
   })
   .execute()
 ```
 
-Throws `LockNotAcquiredError` if the lock cannot be acquired.
-
-#### Order patterns for lock
+#### Order patterns
 
 ```ts
-// ✅ Retry BEFORE lock = lock held during ALL retries (atomicity)
-// retry (inner) → lock (outer) = lock acquired once, held during all retries
+// Retry BEFORE lock = lock held during all retries
 Tenace.call(fn)
   .withRetry({ times: 3 })
   .withDistributedLock({ key: 'payment', ttl: 30_000 })
   .execute()
 
-// ⚠️ Lock BEFORE retry = each retry acquires its own lock
-// lock (inner) → retry (outer) = lock released between retries
+// Lock BEFORE retry = each retry acquires its own lock
 Tenace.call(fn)
   .withDistributedLock({ key: 'payment', ttl: 10_000 })
   .withRetry({ times: 3 })
   .execute()
 
-// ✅ Lock BEFORE fallback = fallback catches LockNotAcquiredError
-// lock (inner) → fallback (outer)
+// Lock BEFORE fallback = fallback catches LockNotAcquiredError
 Tenace.call(fn)
   .withDistributedLock({ key: 'payment', ttl: 30_000 })
   .withFallback(() => defaultValue)
   .execute()
 ```
 
-**No built-in adapter** - You must provide one (e.g., using [@verrou/core](https://github.com/Julien-R44/verrou)):
+**No built-in adapter** - provide your own (e.g., using [@verrou/core](https://github.com/Julien-R44/verrou)):
 
 ```ts
 import { Verrou } from '@verrou/core'
@@ -536,7 +483,7 @@ class VerrouLockAdapter implements LockAdapter {
 configStore.configure({ lock: new VerrouLockAdapter() })
 ```
 
-**With retry** for lock acquisition:
+With retry for lock acquisition:
 
 ```ts
 await Tenace.call(fn)
@@ -554,7 +501,7 @@ await Tenace.call(fn)
 
 ## Reusable Policies
 
-Create a policy once, reuse everywhere. **Circuit breaker and bulkhead states are shared across calls.**
+Circuit breaker and bulkhead states are shared across calls.
 
 ```ts
 const apiPolicy = Tenace.policy()
@@ -562,14 +509,11 @@ const apiPolicy = Tenace.policy()
   .withRetry({ times: 3, delay: (attempt) => 100 * 2 ** attempt })
   .withCircuitBreaker({ failureThreshold: 5, halfOpenAfter: '30s' })
 
-// All calls share the same circuit breaker state!
 await apiPolicy.call(() => fetch('/api/users')).execute()
 await apiPolicy.call(() => fetch('/api/posts')).execute()
-
-// If 5 total failures occur, ALL calls will fail with CircuitOpenError
 ```
 
-### Health Check Example
+### Health check example
 
 ```ts
 class UserService {
@@ -592,15 +536,13 @@ class UserService {
 
 ## Batch Operations
 
-### Process items with concurrency control
-
 ```ts
 const userIds = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 
 const users = await Tenace.map(userIds, (id) => fetchUser(id))
-  .withConcurrency(3)          // max 3 parallel requests
-  .withRetryPerTask(2)         // retry each task up to 2 times
-  .withTimeoutPerTask('5s')    // 5s timeout per task
+  .withConcurrency(3)
+  .withRetryPerTask(2)
+  .withTimeoutPerTask('5s')
   .execute()
 ```
 
@@ -621,7 +563,7 @@ const [users, posts, config] = await Tenace.all([
 ```ts
 const results = await Tenace.map(urls, (url) => fetch(url))
   .withConcurrency(5)
-  .settle() // Never throws
+  .settle()
 
 for (const result of results) {
   if (result.status === 'fulfilled') {
@@ -651,21 +593,16 @@ await Tenace.map(files, (file) => uploadFile(file))
 
 ## Semaphore
 
-Low-level concurrency control:
-
 ```ts
 import { Semaphore } from '@julr/tenace'
 
-const sem = new Semaphore(5) // max 5 concurrent
+const sem = new Semaphore(5)
 
-// Run with automatic acquire/release
 await sem.run(() => doWork())
 
-// Wrap a function
 const limitedFetch = sem.wrap(fetch)
 await limitedFetch('/api/data')
 
-// Map with concurrency
 const results = await sem.map(items, (item) => process(item))
 
 // Manual acquire/release
@@ -679,16 +616,14 @@ try {
 
 ## Waiting for Conditions
 
-Poll until a condition becomes true. Useful for waiting on eventual consistency or service readiness.
+Poll until a condition becomes true.
 
 ```ts
-// Wait for a service to be healthy
 await Tenace.waitFor(() => isServiceHealthy(), {
   interval: '1s',
   timeout: '30s',
 })
 
-// Wait for a database connection
 await Tenace.waitFor(async () => {
   try {
     await db.ping()
@@ -697,13 +632,6 @@ await Tenace.waitFor(async () => {
     return false
   }
 }, { interval: '500ms', timeout: '1m' })
-
-// Wait for eventual consistency
-await orderApi.create(order)
-await Tenace.waitFor(
-  () => orderApi.exists(order.id),
-  { interval: '100ms', timeout: '5s' }
-)
 ```
 
 Options:
@@ -715,35 +643,24 @@ Options:
 
 ## Chaos Engineering
 
-Test your resilience patterns by injecting failures and latency.
-
-### Global Chaos
+Inject failures and latency for testing.
 
-Enable chaos globally to affect all Tenace calls:
+### Global chaos
 
 ```ts
-import { Tenace } from '@julr/tenace'
+Tenace.chaos.enable({ fault: 1 })       // 100% failure rate
+Tenace.chaos.enable({ latency: 500 })   // 500ms latency
 
-// Enable 100% failure rate
-Tenace.chaos.enable({ fault: 1 })
-
-// Enable 500ms latency
-Tenace.chaos.enable({ latency: 500 })
-
-// Combined with configuration
 Tenace.chaos.enable({
   fault: { rate: 0.1, error: new Error('Random failure') },
   latency: { rate: 0.2, delay: { min: 100, max: 2000 } },
 })
 
-// Disable
 Tenace.chaos.disable()
-
-// Check status
 Tenace.chaos.isEnabled()
 ```
 
-### Testing Example
+### Testing example
 
 ```ts
 import { test } from 'vitest'
@@ -900,16 +817,17 @@ All errors extend `TenaceError`:
 
 ```ts
 import {
-  TenaceError,           // Base class
-  TimeoutError,          // Operation timed out
-  CancelledError,        // Operation cancelled via AbortSignal
-  CircuitOpenError,      // Circuit breaker is open
-  CircuitIsolatedError,  // Circuit breaker manually isolated
-  BulkheadFullError,     // Bulkhead capacity exceeded
-  AbortError,            // AbortSignal triggered
-  RateLimitError,        // Rate limit exceeded (has retryAfterMs)
-  LockNotAcquiredError,  // Distributed lock not acquired
-  WaitForTimeoutError,   // waitFor() timed out
+  TenaceError,              // Base class
+  TimeoutError,             // Operation timed out
+  CancelledError,           // Operation cancelled via AbortSignal
+  CircuitOpenError,         // Circuit breaker is open
+  CircuitIsolatedError,     // Circuit breaker manually isolated
+  BulkheadFullError,        // Bulkhead capacity exceeded
+  AbortError,               // AbortSignal triggered
+  RateLimitError,           // Rate limit exceeded (has retryAfterMs)
+  RateLimitQueueFullError,  // Rate limit queue is full
+  LockNotAcquiredError,     // Distributed lock not acquired
+  WaitForTimeoutError,      // waitFor() timed out
 } from '@julr/tenace/errors'
 ```
 
@@ -958,7 +876,7 @@ Tenace.call(fn)
   .withBulkhead(limit, queue?)          // Concurrency limiter
   .withFallback(fn)                     // Default value on failure
   .withCache(options)                   // { key, ttl, adapter? }
-  .withRateLimit(options)               // { key, maxCalls, windowMs, adapter? }
+  .withRateLimit(options)               // { key, maxCalls, windowMs, queue?, adapter? }
   .withDistributedLock(options)         // { key, timeout?, adapter? }
   .withSpan(name, attributes?)          // OpenTelemetry tracing
   .withChaosFault(options)              // { rate, error?, errors? }

package/build/src/adapters/rate_limiter/memory.d.ts

@@ -1,9 +1,15 @@
-import type { RateLimiterAdapter, RateLimitConfig, RateLimitResult, RateLimitState } from './types.ts';
+import type { RateLimiterAdapter, RateLimitConfig, RateLimitQueueConfig, RateLimitResult, RateLimitState } from './types.ts';
 /**
  * In-memory rate limiter adapter using rate-limiter-flexible.
  */
 export declare class MemoryRateLimiterAdapter implements RateLimiterAdapter {
     #private;
+    removeTokens(options: {
+        key: string;
+        tokens: number;
+        config: RateLimitConfig;
+        queue?: RateLimitQueueConfig;
+    }): Promise<number>;
     acquire(key: string, options: RateLimitConfig): Promise<RateLimitResult>;
     getState(key: string): Promise<RateLimitState>;
     reset(key: string): Promise<void>;

package/build/src/adapters/rate_limiter/memory.js

@@ -1,2 +1,3 @@
-import { t as MemoryRateLimiterAdapter } from "../../memory-DXkg8s6y.js";
+import "../../errors-TCLFVbwO.js";
+import { t as MemoryRateLimiterAdapter } from "../../memory-BKGDbMrk.js";
 export { MemoryRateLimiterAdapter };

package/build/src/adapters/rate_limiter/types.d.ts

@@ -7,6 +7,17 @@ export interface RateLimiterAdapter {
      * Try to acquire a permit. Returns true if allowed, false if rate limited.
      */
     acquire(key: string, options: RateLimitConfig): Promise<RateLimitResult>;
+    /**
+     * Remove tokens from the rate limiter, waiting in queue if necessary.
+     * Returns the number of remaining tokens after removal.
+     * Throws RateLimiterQueueError if queue is full or tokens requested exceed limit.
+     */
+    removeTokens(options: {
+        key: string;
+        tokens: number;
+        config: RateLimitConfig;
+        queue?: RateLimitQueueConfig;
+    }): Promise<number>;
     /**
      * Get current state for a key
      */
@@ -74,6 +85,16 @@ export interface RateLimitState {
      */
     resetInMs: number;
 }
+/**
+ * Queue configuration for rate limiting
+ */
+export interface RateLimitQueueConfig {
+    /**
+     * Maximum number of requests that can be queued.
+     * @default 4294967295 (2^32 - 1)
+     */
+    maxSize?: number;
+}
 /**
  * Options for rate limiting behavior
  */
@@ -92,7 +113,12 @@ export interface RateLimitOptions extends RateLimitConfig {
      */
     optional?: boolean;
     /**
-     * Called when rate limit is exceeded
+     * Queue configuration. When enabled, requests that exceed the rate limit
+     * will be queued instead of rejected, and executed when tokens become available.
+     */
+    queue?: RateLimitQueueConfig;
+    /**
+     * Called when rate limit is exceeded (only when queue is not enabled)
      */
     onRejected?: (event: {
         key: string;

package/build/src/errors/errors.d.ts

@@ -77,3 +77,13 @@ export declare class LockNotAcquiredError extends TenaceError {
 export declare class WaitForTimeoutError extends TenaceError {
     constructor(message?: string);
 }
+/**
+ * Thrown when rate limit queue is full and cannot accept more requests
+ */
+export declare class RateLimitQueueFullError extends TenaceError {
+    key: string;
+    constructor(options: {
+        key: string;
+        message?: string;
+    });
+}

package/build/src/errors/main.d.ts

@@ -1 +1 @@
-export { TenaceError, TimeoutError, CancelledError, CircuitOpenError, CircuitIsolatedError, BulkheadFullError, AbortError, RateLimitError, LockNotAcquiredError, WaitForTimeoutError, } from './errors.ts';
+export { TenaceError, TimeoutError, CancelledError, CircuitOpenError, CircuitIsolatedError, BulkheadFullError, AbortError, RateLimitError, RateLimitQueueFullError, LockNotAcquiredError, WaitForTimeoutError, } from './errors.ts';

package/build/src/errors/main.js

@@ -1,2 +1,2 @@
-import { a as CircuitOpenError, c as TenaceError, i as CircuitIsolatedError, l as TimeoutError, n as BulkheadFullError, o as LockNotAcquiredError, r as CancelledError, s as RateLimitError, t as AbortError, u as WaitForTimeoutError } from "../errors-BODHnryv.js";
-export { AbortError, BulkheadFullError, CancelledError, CircuitIsolatedError, CircuitOpenError, LockNotAcquiredError, RateLimitError, TenaceError, TimeoutError, WaitForTimeoutError };
+import { a as CircuitOpenError, c as RateLimitQueueFullError, d as WaitForTimeoutError, i as CircuitIsolatedError, l as TenaceError, n as BulkheadFullError, o as LockNotAcquiredError, r as CancelledError, s as RateLimitError, t as AbortError, u as TimeoutError } from "../errors-TCLFVbwO.js";
+export { AbortError, BulkheadFullError, CancelledError, CircuitIsolatedError, CircuitOpenError, LockNotAcquiredError, RateLimitError, RateLimitQueueFullError, TenaceError, TimeoutError, WaitForTimeoutError };

package/build/src/{errors-BODHnryv.js → errors-TCLFVbwO.js}

@@ -64,4 +64,12 @@ var WaitForTimeoutError = class extends TenaceError {
 		this.name = "WaitForTimeoutError";
 	}
 };
-export { CircuitOpenError as a, TenaceError as c, CircuitIsolatedError as i, TimeoutError as l, BulkheadFullError as n, LockNotAcquiredError as o, CancelledError as r, RateLimitError as s, AbortError as t, WaitForTimeoutError as u };
+var RateLimitQueueFullError = class extends TenaceError {
+	key;
+	constructor(options) {
+		super(options.message ?? `Rate limit queue is full for key "${options.key}"`);
+		this.name = "RateLimitQueueFullError";
+		this.key = options.key;
+	}
+};
+export { CircuitOpenError as a, RateLimitQueueFullError as c, WaitForTimeoutError as d, CircuitIsolatedError as i, TenaceError as l, BulkheadFullError as n, LockNotAcquiredError as o, CancelledError as r, RateLimitError as s, AbortError as t, TimeoutError as u };

package/build/src/internal/adapter_policies.d.ts

@@ -20,7 +20,7 @@ export declare function createCachePolicy<T>(options: CachePolicyOptions): IPoli
 /**
  * Creates a rate limit policy that integrates into the cockatiel pipeline.
  * - Check rate limit before execution
- * - Throw RateLimitError if exceeded
+ * - Throw RateLimitError if exceeded (or queue if configured)
  */
 export declare function createRateLimitPolicy<T>(options: RateLimitPolicyOptions): IPolicy;
 /**

package/build/src/main.js

@@ -1,5 +1,5 @@
-import { a as CircuitOpenError, i as CircuitIsolatedError, l as TimeoutError$1, n as BulkheadFullError, o as LockNotAcquiredError, r as CancelledError, s as RateLimitError, u as WaitForTimeoutError } from "./errors-BODHnryv.js";
-import { t as MemoryRateLimiterAdapter } from "./memory-DXkg8s6y.js";
+import { a as CircuitOpenError, c as RateLimitQueueFullError, d as WaitForTimeoutError, i as CircuitIsolatedError, n as BulkheadFullError, o as LockNotAcquiredError, r as CancelledError, s as RateLimitError, u as TimeoutError$1 } from "./errors-TCLFVbwO.js";
+import { t as MemoryRateLimiterAdapter } from "./memory-BKGDbMrk.js";
 import { t as MemoryCacheAdapter } from "./memory-DWyezb1O.js";
 import pWaitFor, { TimeoutError } from "p-wait-for";
 import { ms } from "@julr/utils/string/ms";
@@ -422,33 +422,46 @@ function createRateLimitPolicy(options) {
 	const adapter = options.adapter ?? configStore.getRateLimiter();
 	return { execute: async (fn, signal) => {
 		try {
-			const result = await adapter.acquire(options.key, {
-				maxCalls: options.maxCalls,
-				windowMs: options.windowMs,
-				...options.strategy !== void 0 && { strategy: options.strategy }
+			if (options.queue) await adapter.removeTokens({
+				key: options.key,
+				tokens: 1,
+				config: {
+					maxCalls: options.maxCalls,
+					windowMs: options.windowMs,
+					...options.strategy !== void 0 && { strategy: options.strategy }
+				},
+				queue: options.queue
 			});
-			if (!result.allowed) {
-				emitEvent(TelemetryEvents.RATE_LIMIT_REJECTED, {
-					key: options.key,
-					retry_after_ms: result.retryAfterMs ?? 0
-				});
-				notifyPlugins("onRateLimitRejected", {
-					key: options.key,
-					retryAfterMs: result.retryAfterMs
-				});
-				if (result.retryAfterMs !== void 0) options.onRejected?.({
-					key: options.key,
-					retryAfterMs: result.retryAfterMs
-				});
-				else options.onRejected?.({ key: options.key });
-				throw new RateLimitError({
-					message: `Rate limit exceeded for key "${options.key}". Retry after ${result.retryAfterMs}ms`,
-					retryAfterMs: result.retryAfterMs ?? 0,
-					remaining: result.remaining
+			else {
+				const result = await adapter.acquire(options.key, {
+					maxCalls: options.maxCalls,
+					windowMs: options.windowMs,
+					...options.strategy !== void 0 && { strategy: options.strategy }
 				});
+				if (!result.allowed) {
+					emitEvent(TelemetryEvents.RATE_LIMIT_REJECTED, {
+						key: options.key,
+						retry_after_ms: result.retryAfterMs ?? 0
+					});
+					notifyPlugins("onRateLimitRejected", {
+						key: options.key,
+						retryAfterMs: result.retryAfterMs
+					});
+					if (result.retryAfterMs !== void 0) options.onRejected?.({
+						key: options.key,
+						retryAfterMs: result.retryAfterMs
+					});
+					else options.onRejected?.({ key: options.key });
+					throw new RateLimitError({
+						message: `Rate limit exceeded for key "${options.key}". Retry after ${result.retryAfterMs}ms`,
+						retryAfterMs: result.retryAfterMs ?? 0,
+						remaining: result.remaining
+					});
+				}
 			}
 		} catch (error) {
 			if (error instanceof RateLimitError) throw error;
+			if (error instanceof RateLimitQueueFullError) throw error;
 			if (!options.optional) throw error;
 		}
 		return fn({

package/build/src/{memory-DXkg8s6y.js → memory-BKGDbMrk.js}

@@ -1,6 +1,8 @@
-import { RateLimiterMemory } from "rate-limiter-flexible";
+import { c as RateLimitQueueFullError } from "./errors-TCLFVbwO.js";
+import { RateLimiterMemory, RateLimiterQueue, RateLimiterQueueError } from "rate-limiter-flexible";
 var MemoryRateLimiterAdapter = class {
 	#limiters = /* @__PURE__ */ new Map();
+	#queues = /* @__PURE__ */ new Map();
 	#getLimiter(options) {
 		const cacheKey = `${options.key}:${options.config.maxCalls}:${options.config.windowMs}`;
 		let limiter = this.#limiters.get(cacheKey);
@@ -13,6 +15,35 @@ var MemoryRateLimiterAdapter = class {
 		}
 		return limiter;
 	}
+	#getQueue(options) {
+		const maxSize = options.queue.maxSize ?? 4294967295;
+		const cacheKey = `${options.key}:${options.config.maxCalls}:${options.config.windowMs}:${maxSize}`;
+		let queue = this.#queues.get(cacheKey);
+		if (!queue) {
+			queue = new RateLimiterQueue(this.#getLimiter({
+				key: options.key,
+				config: options.config
+			}), { maxQueueSize: maxSize });
+			this.#queues.set(cacheKey, queue);
+		}
+		return queue;
+	}
+	async removeTokens(options) {
+		const queue = this.#getQueue({
+			key: options.key,
+			config: options.config,
+			queue: options.queue ?? {}
+		});
+		try {
+			return await queue.removeTokens(options.tokens, options.key);
+		} catch (error) {
+			if (error instanceof RateLimiterQueueError) throw new RateLimitQueueFullError({
+				key: options.key,
+				message: error.message
+			});
+			throw error;
+		}
+	}
 	async acquire(key, options) {
 		const limiter = this.#getLimiter({
 			key,
@@ -55,6 +86,7 @@ var MemoryRateLimiterAdapter = class {
 	}
 	clear() {
 		this.#limiters.clear();
+		this.#queues.clear();
 	}
 };
 export { MemoryRateLimiterAdapter as t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@julr/tenace",
   "type": "module",
-  "version": "1.0.0-next.0",
+  "version": "1.0.0-next.1",
   "packageManager": "pnpm@10.24.0",
   "description": "A Node.js library to make any call resilient with a fluent and simple API",
   "author": "Julien Ripouteau <julien@ripouteau.com>",