@fortify-ts/bulkhead

@fortify-ts/bulkhead

Bulkhead (concurrency limiter) pattern for the Fortify-TS resilience library.

Installation

npm install @fortify-ts/bulkhead
# or
pnpm add @fortify-ts/bulkhead

Features

• Concurrency Limiting: Control maximum parallel executions
• Request Queueing: Queue excess requests with optional timeout
• Rejection Handling: Reject when at capacity
• Metrics: Track active and queued requests

Usage

Basic Usage

import { Bulkhead } from '@fortify-ts/bulkhead';

const bulkhead = new Bulkhead<Response>({
  maxConcurrent: 10,
});

try {
  const result = await bulkhead.execute(async (signal) => {
    return fetch('/api/data', { signal });
  });
} catch (error) {
  if (error instanceof BulkheadFullError) {
    console.log('Too many concurrent requests');
  }
}

With Queueing

const bulkhead = new Bulkhead<Response>({
  maxConcurrent: 10,
  maxQueue: 100,        // Queue up to 100 requests
  queueTimeout: 5000,   // 5 second queue timeout
});

Configuration Options

const bulkhead = new Bulkhead<Response>({
  // Maximum concurrent executions
  maxConcurrent: 10,

  // Maximum queued requests (0 = no queue)
  maxQueue: 100,

  // Queue timeout in milliseconds
  queueTimeout: 5000,

  // Rejection callback
  onRejected: (activeCount, queuedCount) => {
    console.log(`Rejected: ${activeCount} active, ${queuedCount} queued`);
  },

  // Optional logger
  logger: myLogger,
});

Checking Status

// Get current counts
const activeCount = bulkhead.getActiveCount();
const queuedCount = bulkhead.getQueuedCount();

// Check if at capacity
const isFull = activeCount >= config.maxConcurrent;

Resource Cleanup

// Close bulkhead (rejects queued requests)
await bulkhead.close();

Configuration Reference

Option	Type	Default	Description
maxConcurrent	number	10	Max parallel executions
maxQueue	number	0	Max queued requests
queueTimeout	number	-	Queue timeout (ms)
onRejected	function	-	Rejection callback
logger	FortifyLogger	-	Optional logger

Error Types

Error	Description
BulkheadFullError	Bulkhead and queue at capacity
BulkheadClosedError	Bulkhead has been closed

License

MIT