flowx-control 1.0.0

package/dist/batch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/batch.ts"],"names":[],"mappings":"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","file":"batch.mjs","sourcesContent":["// ============================================================================\n// FlowX — Types & Error Hierarchy\n// ============================================================================\n\n/** Generic async function signature */\nexport type AsyncFn<TArgs extends any[] = any[], TReturn = any> = (\n  ...args: TArgs\n) => Promise<TReturn>;\n\n/** Backoff strategy for retry/poll operations */\nexport type BackoffStrategy =\n  | 'fixed'\n  | 'linear'\n  | 'exponential'\n  | ((attempt: number, delay: number) => number);\n\n// ── Error Classes ───────────────────────────────────────────────────────────\n\n/** Base error class for all FlowX errors */\nexport class FlowXError extends Error {\n  public readonly code: string;\n  constructor(message: string, code: string) {\n    super(message);\n    this.name = 'FlowXError';\n    this.code = code;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Thrown when a promise exceeds its timeout */\nexport class TimeoutError extends FlowXError {\n  constructor(message = 'Operation timed out') {\n    super(message, 'ERR_TIMEOUT');\n    this.name = 'TimeoutError';\n  }\n}\n\n/** Thrown when a circuit breaker is open */\nexport class CircuitBreakerError extends FlowXError {\n  constructor(message = 'Circuit breaker is open') {\n    super(message, 'ERR_CIRCUIT_OPEN');\n    this.name = 'CircuitBreakerError';\n  }\n}\n\n/** Thrown when a bulkhead rejects due to capacity */\nexport class BulkheadError extends FlowXError {\n  constructor(message = 'Bulkhead capacity exceeded') {\n    super(message, 'ERR_BULKHEAD_FULL');\n    this.name = 'BulkheadError';\n  }\n}\n\n/** Thrown when an operation is aborted */\nexport class AbortError extends FlowXError {\n  constructor(message = 'Operation aborted') {\n    super(message, 'ERR_ABORTED');\n    this.name = 'AbortError';\n  }\n}\n\n/** Thrown when rate limit is exceeded */\nexport class RateLimitError extends FlowXError {\n  constructor(message = 'Rate limit exceeded') {\n    super(message, 'ERR_RATE_LIMIT');\n    this.name = 'RateLimitError';\n  }\n}\n\n// ── Utility Helpers ─────────────────────────────────────────────────────────\n\n/** Sleep for the specified duration, respecting AbortSignal */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new AbortError());\n      return;\n    }\n\n    let onAbort: (() => void) | undefined;\n\n    const timer = setTimeout(() => {\n      if (signal && onAbort) {\n        signal.removeEventListener('abort', onAbort);\n      }\n      resolve();\n    }, ms);\n\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer);\n        reject(new AbortError());\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n    }\n  });\n}\n\n/** Calculate delay based on backoff strategy */\nexport function calculateDelay(\n  attempt: number,\n  baseDelay: number,\n  strategy: BackoffStrategy,\n  jitter: boolean | number = false,\n): number {\n  let delay: number;\n\n  if (typeof strategy === 'function') {\n    delay = strategy(attempt, baseDelay);\n  } else {\n    switch (strategy) {\n      case 'fixed':\n        delay = baseDelay;\n        break;\n      case 'linear':\n        delay = baseDelay * attempt;\n        break;\n      case 'exponential':\n        delay = baseDelay * Math.pow(2, attempt - 1);\n        break;\n    }\n  }\n\n  if (jitter) {\n    const factor = typeof jitter === 'number' ? jitter : 1;\n    delay = delay * (1 - factor * 0.5 + Math.random() * factor);\n  }\n\n  return Math.max(0, Math.floor(delay));\n}\n","// ============================================================================\n// FlowX — Batch Processing with Concurrency\n// ============================================================================\nimport { AbortError } from './types';\n\nexport interface BatchOptions {\n  /** Maximum concurrent batch operations (default: Infinity) */\n  concurrency?: number;\n  /** Number of items per batch (default: 1) */\n  batchSize?: number;\n  /** Progress callback */\n  onProgress?: (completed: number, total: number) => void;\n  /** AbortSignal for cancellation */\n  signal?: AbortSignal;\n}\n\nexport interface BatchResult<T> {\n  /** All results in order */\n  results: T[];\n  /** Total items processed */\n  total: number;\n  /** Number of succeeded items */\n  succeeded: number;\n  /** Number of failed items */\n  failed: number;\n  /** Errors indexed by position */\n  errors: Map<number, Error>;\n}\n\n/**\n * Process an array of items in batches with concurrency control.\n *\n * @example\n * ```ts\n * const results = await batch(\n *   urls,\n *   async (url) => fetch(url).then(r => r.json()),\n *   { concurrency: 5, batchSize: 10 },\n * );\n * ```\n */\nexport async function batch<TItem, TResult>(\n  items: TItem[],\n  fn: (item: TItem, index: number) => Promise<TResult>,\n  options?: BatchOptions,\n): Promise<BatchResult<TResult>> {\n  const { concurrency = Infinity, batchSize = 1, onProgress, signal } = options ?? {};\n\n  if (batchSize < 1) throw new RangeError('batchSize must be >= 1');\n  if (concurrency < 1) throw new RangeError('concurrency must be >= 1');\n\n  const results: TResult[] = new Array(items.length);\n  const errors = new Map<number, Error>();\n  let completed = 0;\n  let succeeded = 0;\n  let failed = 0;\n\n  // Split items into batches\n  const batches: Array<{ items: TItem[]; startIndex: number }> = [];\n  for (let i = 0; i < items.length; i += batchSize) {\n    batches.push({\n      items: items.slice(i, i + batchSize),\n      startIndex: i,\n    });\n  }\n\n  // Process batches with concurrency control\n  let batchIndex = 0;\n\n  async function processBatch(): Promise<void> {\n    while (batchIndex < batches.length) {\n      if (signal?.aborted) throw new AbortError();\n\n      const currentBatch = batches[batchIndex++];\n\n      for (let i = 0; i < currentBatch.items.length; i++) {\n        if (signal?.aborted) throw new AbortError();\n\n        const globalIndex = currentBatch.startIndex + i;\n        try {\n          results[globalIndex] = await fn(currentBatch.items[i], globalIndex);\n          succeeded++;\n        } catch (error) {\n          const err = error instanceof Error ? error : new Error(String(error));\n          errors.set(globalIndex, err);\n          results[globalIndex] = undefined as TResult;\n          failed++;\n        }\n        completed++;\n        onProgress?.(completed, items.length);\n      }\n    }\n  }\n\n  const workers: Promise<void>[] = [];\n  const workerCount = Math.min(concurrency, batches.length);\n\n  for (let i = 0; i < workerCount; i++) {\n    workers.push(processBatch());\n  }\n\n  await Promise.all(workers);\n\n  return {\n    results,\n    total: items.length,\n    succeeded,\n    failed,\n    errors,\n  };\n}\n"]}

package/dist/bulkhead.d.mts

@@ -0,0 +1,30 @@
+interface BulkheadOptions {
+    /** Maximum concurrent executions (default: 10) */
+    concurrency?: number;
+    /** Maximum queue size for waiting tasks (default: 10) */
+    queueSize?: number;
+    /** Timeout in ms for queued tasks (0 = no timeout) */
+    queueTimeout?: number;
+}
+interface Bulkhead {
+    /** Execute a function within the bulkhead */
+    execute: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Current number of active executions */
+    readonly active: number;
+    /** Current number of queued tasks */
+    readonly queued: number;
+    /** Available capacity */
+    readonly available: number;
+}
+/**
+ * Create a bulkhead to isolate concurrent operations and prevent resource exhaustion.
+ *
+ * @example
+ * ```ts
+ * const bulkhead = createBulkhead({ concurrency: 5, queueSize: 10 });
+ * const data = await bulkhead.execute(() => fetch('/api'));
+ * ```
+ */
+declare function createBulkhead(options?: BulkheadOptions): Bulkhead;
+
+export { type Bulkhead, type BulkheadOptions, createBulkhead };

package/dist/bulkhead.d.ts

@@ -0,0 +1,30 @@
+interface BulkheadOptions {
+    /** Maximum concurrent executions (default: 10) */
+    concurrency?: number;
+    /** Maximum queue size for waiting tasks (default: 10) */
+    queueSize?: number;
+    /** Timeout in ms for queued tasks (0 = no timeout) */
+    queueTimeout?: number;
+}
+interface Bulkhead {
+    /** Execute a function within the bulkhead */
+    execute: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Current number of active executions */
+    readonly active: number;
+    /** Current number of queued tasks */
+    readonly queued: number;
+    /** Available capacity */
+    readonly available: number;
+}
+/**
+ * Create a bulkhead to isolate concurrent operations and prevent resource exhaustion.
+ *
+ * @example
+ * ```ts
+ * const bulkhead = createBulkhead({ concurrency: 5, queueSize: 10 });
+ * const data = await bulkhead.execute(() => fetch('/api'));
+ * ```
+ */
+declare function createBulkhead(options?: BulkheadOptions): Bulkhead;
+
+export { type Bulkhead, type BulkheadOptions, createBulkhead };

package/dist/bulkhead.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// src/types.ts
+var FlowXError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "FlowXError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var BulkheadError = class extends FlowXError {
+  constructor(message = "Bulkhead capacity exceeded") {
+    super(message, "ERR_BULKHEAD_FULL");
+    this.name = "BulkheadError";
+  }
+};
+
+// src/bulkhead.ts
+function createBulkhead(options) {
+  const { concurrency = 10, queueSize = 10, queueTimeout = 0 } = options ?? {};
+  if (concurrency < 1) throw new RangeError("concurrency must be >= 1");
+  if (queueSize < 0) throw new RangeError("queueSize must be >= 0");
+  let active = 0;
+  const queue = [];
+  function tryDequeue() {
+    while (queue.length > 0 && active < concurrency) {
+      const item = queue.shift();
+      if (item.timer) clearTimeout(item.timer);
+      run(item);
+    }
+  }
+  async function run(item) {
+    active++;
+    try {
+      const value = await item.fn();
+      active--;
+      tryDequeue();
+      item.resolve(value);
+    } catch (error) {
+      active--;
+      tryDequeue();
+      item.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  function execute(fn) {
+    if (active < concurrency) {
+      return new Promise((resolve, reject) => {
+        run({ fn, resolve, reject });
+      });
+    }
+    if (queue.length >= queueSize) {
+      return Promise.reject(new BulkheadError());
+    }
+    return new Promise((resolve, reject) => {
+      const item = { fn, resolve, reject };
+      if (queueTimeout > 0) {
+        item.timer = setTimeout(() => {
+          const idx = queue.indexOf(item);
+          if (idx !== -1) {
+            queue.splice(idx, 1);
+            reject(new BulkheadError("Bulkhead queue timeout exceeded"));
+          }
+        }, queueTimeout);
+      }
+      queue.push(item);
+    });
+  }
+  return {
+    execute,
+    get active() {
+      return active;
+    },
+    get queued() {
+      return queue.length;
+    },
+    get available() {
+      return Math.max(0, concurrency - active);
+    }
+  };
+}
+
+exports.createBulkhead = createBulkhead;
+//# sourceMappingURL=bulkhead.js.map
+//# sourceMappingURL=bulkhead.js.map

package/dist/bulkhead.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/bulkhead.ts"],"names":[],"mappings":"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","file":"bulkhead.js","sourcesContent":["// ============================================================================\n// FlowX — Types & Error Hierarchy\n// ============================================================================\n\n/** Generic async function signature */\nexport type AsyncFn<TArgs extends any[] = any[], TReturn = any> = (\n  ...args: TArgs\n) => Promise<TReturn>;\n\n/** Backoff strategy for retry/poll operations */\nexport type BackoffStrategy =\n  | 'fixed'\n  | 'linear'\n  | 'exponential'\n  | ((attempt: number, delay: number) => number);\n\n// ── Error Classes ───────────────────────────────────────────────────────────\n\n/** Base error class for all FlowX errors */\nexport class FlowXError extends Error {\n  public readonly code: string;\n  constructor(message: string, code: string) {\n    super(message);\n    this.name = 'FlowXError';\n    this.code = code;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Thrown when a promise exceeds its timeout */\nexport class TimeoutError extends FlowXError {\n  constructor(message = 'Operation timed out') {\n    super(message, 'ERR_TIMEOUT');\n    this.name = 'TimeoutError';\n  }\n}\n\n/** Thrown when a circuit breaker is open */\nexport class CircuitBreakerError extends FlowXError {\n  constructor(message = 'Circuit breaker is open') {\n    super(message, 'ERR_CIRCUIT_OPEN');\n    this.name = 'CircuitBreakerError';\n  }\n}\n\n/** Thrown when a bulkhead rejects due to capacity */\nexport class BulkheadError extends FlowXError {\n  constructor(message = 'Bulkhead capacity exceeded') {\n    super(message, 'ERR_BULKHEAD_FULL');\n    this.name = 'BulkheadError';\n  }\n}\n\n/** Thrown when an operation is aborted */\nexport class AbortError extends FlowXError {\n  constructor(message = 'Operation aborted') {\n    super(message, 'ERR_ABORTED');\n    this.name = 'AbortError';\n  }\n}\n\n/** Thrown when rate limit is exceeded */\nexport class RateLimitError extends FlowXError {\n  constructor(message = 'Rate limit exceeded') {\n    super(message, 'ERR_RATE_LIMIT');\n    this.name = 'RateLimitError';\n  }\n}\n\n// ── Utility Helpers ─────────────────────────────────────────────────────────\n\n/** Sleep for the specified duration, respecting AbortSignal */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new AbortError());\n      return;\n    }\n\n    let onAbort: (() => void) | undefined;\n\n    const timer = setTimeout(() => {\n      if (signal && onAbort) {\n        signal.removeEventListener('abort', onAbort);\n      }\n      resolve();\n    }, ms);\n\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer);\n        reject(new AbortError());\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n    }\n  });\n}\n\n/** Calculate delay based on backoff strategy */\nexport function calculateDelay(\n  attempt: number,\n  baseDelay: number,\n  strategy: BackoffStrategy,\n  jitter: boolean | number = false,\n): number {\n  let delay: number;\n\n  if (typeof strategy === 'function') {\n    delay = strategy(attempt, baseDelay);\n  } else {\n    switch (strategy) {\n      case 'fixed':\n        delay = baseDelay;\n        break;\n      case 'linear':\n        delay = baseDelay * attempt;\n        break;\n      case 'exponential':\n        delay = baseDelay * Math.pow(2, attempt - 1);\n        break;\n    }\n  }\n\n  if (jitter) {\n    const factor = typeof jitter === 'number' ? jitter : 1;\n    delay = delay * (1 - factor * 0.5 + Math.random() * factor);\n  }\n\n  return Math.max(0, Math.floor(delay));\n}\n","// ============================================================================\n// FlowX — Bulkhead Isolation Pattern\n// ============================================================================\nimport { BulkheadError } from './types';\n\nexport interface BulkheadOptions {\n  /** Maximum concurrent executions (default: 10) */\n  concurrency?: number;\n  /** Maximum queue size for waiting tasks (default: 10) */\n  queueSize?: number;\n  /** Timeout in ms for queued tasks (0 = no timeout) */\n  queueTimeout?: number;\n}\n\nexport interface Bulkhead {\n  /** Execute a function within the bulkhead */\n  execute: <T>(fn: () => Promise<T>) => Promise<T>;\n  /** Current number of active executions */\n  readonly active: number;\n  /** Current number of queued tasks */\n  readonly queued: number;\n  /** Available capacity */\n  readonly available: number;\n}\n\ninterface QueueItem<T = any> {\n  fn: () => Promise<T>;\n  resolve: (value: T) => void;\n  reject: (error: Error) => void;\n  timer?: ReturnType<typeof setTimeout>;\n}\n\n/**\n * Create a bulkhead to isolate concurrent operations and prevent resource exhaustion.\n *\n * @example\n * ```ts\n * const bulkhead = createBulkhead({ concurrency: 5, queueSize: 10 });\n * const data = await bulkhead.execute(() => fetch('/api'));\n * ```\n */\nexport function createBulkhead(options?: BulkheadOptions): Bulkhead {\n  const { concurrency = 10, queueSize = 10, queueTimeout = 0 } = options ?? {};\n\n  if (concurrency < 1) throw new RangeError('concurrency must be >= 1');\n  if (queueSize < 0) throw new RangeError('queueSize must be >= 0');\n\n  let active = 0;\n  const queue: QueueItem[] = [];\n\n  function tryDequeue(): void {\n    while (queue.length > 0 && active < concurrency) {\n      const item = queue.shift()!;\n      if (item.timer) clearTimeout(item.timer);\n      run(item);\n    }\n  }\n\n  async function run<T>(item: QueueItem<T>): Promise<void> {\n    active++;\n    try {\n      const value = await item.fn();\n      active--;\n      tryDequeue();\n      item.resolve(value);\n    } catch (error) {\n      active--;\n      tryDequeue();\n      item.reject(error instanceof Error ? error : new Error(String(error)));\n    }\n  }\n\n  function execute<T>(fn: () => Promise<T>): Promise<T> {\n    if (active < concurrency) {\n      return new Promise<T>((resolve, reject) => {\n        run({ fn, resolve, reject });\n      });\n    }\n\n    if (queue.length >= queueSize) {\n      return Promise.reject(new BulkheadError());\n    }\n\n    return new Promise<T>((resolve, reject) => {\n      const item: QueueItem<T> = { fn, resolve, reject };\n\n      if (queueTimeout > 0) {\n        item.timer = setTimeout(() => {\n          const idx = queue.indexOf(item as QueueItem);\n          if (idx !== -1) {\n            queue.splice(idx, 1);\n            reject(new BulkheadError('Bulkhead queue timeout exceeded'));\n          }\n        }, queueTimeout);\n      }\n\n      queue.push(item as QueueItem);\n    });\n  }\n\n  return {\n    execute,\n    get active() {\n      return active;\n    },\n    get queued() {\n      return queue.length;\n    },\n    get available() {\n      return Math.max(0, concurrency - active);\n    },\n  };\n}\n"]}

package/dist/bulkhead.mjs

@@ -0,0 +1,83 @@
+// src/types.ts
+var FlowXError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "FlowXError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var BulkheadError = class extends FlowXError {
+  constructor(message = "Bulkhead capacity exceeded") {
+    super(message, "ERR_BULKHEAD_FULL");
+    this.name = "BulkheadError";
+  }
+};
+
+// src/bulkhead.ts
+function createBulkhead(options) {
+  const { concurrency = 10, queueSize = 10, queueTimeout = 0 } = options ?? {};
+  if (concurrency < 1) throw new RangeError("concurrency must be >= 1");
+  if (queueSize < 0) throw new RangeError("queueSize must be >= 0");
+  let active = 0;
+  const queue = [];
+  function tryDequeue() {
+    while (queue.length > 0 && active < concurrency) {
+      const item = queue.shift();
+      if (item.timer) clearTimeout(item.timer);
+      run(item);
+    }
+  }
+  async function run(item) {
+    active++;
+    try {
+      const value = await item.fn();
+      active--;
+      tryDequeue();
+      item.resolve(value);
+    } catch (error) {
+      active--;
+      tryDequeue();
+      item.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  function execute(fn) {
+    if (active < concurrency) {
+      return new Promise((resolve, reject) => {
+        run({ fn, resolve, reject });
+      });
+    }
+    if (queue.length >= queueSize) {
+      return Promise.reject(new BulkheadError());
+    }
+    return new Promise((resolve, reject) => {
+      const item = { fn, resolve, reject };
+      if (queueTimeout > 0) {
+        item.timer = setTimeout(() => {
+          const idx = queue.indexOf(item);
+          if (idx !== -1) {
+            queue.splice(idx, 1);
+            reject(new BulkheadError("Bulkhead queue timeout exceeded"));
+          }
+        }, queueTimeout);
+      }
+      queue.push(item);
+    });
+  }
+  return {
+    execute,
+    get active() {
+      return active;
+    },
+    get queued() {
+      return queue.length;
+    },
+    get available() {
+      return Math.max(0, concurrency - active);
+    }
+  };
+}
+
+export { createBulkhead };
+//# sourceMappingURL=bulkhead.mjs.map
+//# sourceMappingURL=bulkhead.mjs.map

package/dist/bulkhead.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/bulkhead.ts"],"names":[],"mappings":"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","file":"bulkhead.mjs","sourcesContent":["// ============================================================================\n// FlowX — Types & Error Hierarchy\n// ============================================================================\n\n/** Generic async function signature */\nexport type AsyncFn<TArgs extends any[] = any[], TReturn = any> = (\n  ...args: TArgs\n) => Promise<TReturn>;\n\n/** Backoff strategy for retry/poll operations */\nexport type BackoffStrategy =\n  | 'fixed'\n  | 'linear'\n  | 'exponential'\n  | ((attempt: number, delay: number) => number);\n\n// ── Error Classes ───────────────────────────────────────────────────────────\n\n/** Base error class for all FlowX errors */\nexport class FlowXError extends Error {\n  public readonly code: string;\n  constructor(message: string, code: string) {\n    super(message);\n    this.name = 'FlowXError';\n    this.code = code;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Thrown when a promise exceeds its timeout */\nexport class TimeoutError extends FlowXError {\n  constructor(message = 'Operation timed out') {\n    super(message, 'ERR_TIMEOUT');\n    this.name = 'TimeoutError';\n  }\n}\n\n/** Thrown when a circuit breaker is open */\nexport class CircuitBreakerError extends FlowXError {\n  constructor(message = 'Circuit breaker is open') {\n    super(message, 'ERR_CIRCUIT_OPEN');\n    this.name = 'CircuitBreakerError';\n  }\n}\n\n/** Thrown when a bulkhead rejects due to capacity */\nexport class BulkheadError extends FlowXError {\n  constructor(message = 'Bulkhead capacity exceeded') {\n    super(message, 'ERR_BULKHEAD_FULL');\n    this.name = 'BulkheadError';\n  }\n}\n\n/** Thrown when an operation is aborted */\nexport class AbortError extends FlowXError {\n  constructor(message = 'Operation aborted') {\n    super(message, 'ERR_ABORTED');\n    this.name = 'AbortError';\n  }\n}\n\n/** Thrown when rate limit is exceeded */\nexport class RateLimitError extends FlowXError {\n  constructor(message = 'Rate limit exceeded') {\n    super(message, 'ERR_RATE_LIMIT');\n    this.name = 'RateLimitError';\n  }\n}\n\n// ── Utility Helpers ─────────────────────────────────────────────────────────\n\n/** Sleep for the specified duration, respecting AbortSignal */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new AbortError());\n      return;\n    }\n\n    let onAbort: (() => void) | undefined;\n\n    const timer = setTimeout(() => {\n      if (signal && onAbort) {\n        signal.removeEventListener('abort', onAbort);\n      }\n      resolve();\n    }, ms);\n\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer);\n        reject(new AbortError());\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n    }\n  });\n}\n\n/** Calculate delay based on backoff strategy */\nexport function calculateDelay(\n  attempt: number,\n  baseDelay: number,\n  strategy: BackoffStrategy,\n  jitter: boolean | number = false,\n): number {\n  let delay: number;\n\n  if (typeof strategy === 'function') {\n    delay = strategy(attempt, baseDelay);\n  } else {\n    switch (strategy) {\n      case 'fixed':\n        delay = baseDelay;\n        break;\n      case 'linear':\n        delay = baseDelay * attempt;\n        break;\n      case 'exponential':\n        delay = baseDelay * Math.pow(2, attempt - 1);\n        break;\n    }\n  }\n\n  if (jitter) {\n    const factor = typeof jitter === 'number' ? jitter : 1;\n    delay = delay * (1 - factor * 0.5 + Math.random() * factor);\n  }\n\n  return Math.max(0, Math.floor(delay));\n}\n","// ============================================================================\n// FlowX — Bulkhead Isolation Pattern\n// ============================================================================\nimport { BulkheadError } from './types';\n\nexport interface BulkheadOptions {\n  /** Maximum concurrent executions (default: 10) */\n  concurrency?: number;\n  /** Maximum queue size for waiting tasks (default: 10) */\n  queueSize?: number;\n  /** Timeout in ms for queued tasks (0 = no timeout) */\n  queueTimeout?: number;\n}\n\nexport interface Bulkhead {\n  /** Execute a function within the bulkhead */\n  execute: <T>(fn: () => Promise<T>) => Promise<T>;\n  /** Current number of active executions */\n  readonly active: number;\n  /** Current number of queued tasks */\n  readonly queued: number;\n  /** Available capacity */\n  readonly available: number;\n}\n\ninterface QueueItem<T = any> {\n  fn: () => Promise<T>;\n  resolve: (value: T) => void;\n  reject: (error: Error) => void;\n  timer?: ReturnType<typeof setTimeout>;\n}\n\n/**\n * Create a bulkhead to isolate concurrent operations and prevent resource exhaustion.\n *\n * @example\n * ```ts\n * const bulkhead = createBulkhead({ concurrency: 5, queueSize: 10 });\n * const data = await bulkhead.execute(() => fetch('/api'));\n * ```\n */\nexport function createBulkhead(options?: BulkheadOptions): Bulkhead {\n  const { concurrency = 10, queueSize = 10, queueTimeout = 0 } = options ?? {};\n\n  if (concurrency < 1) throw new RangeError('concurrency must be >= 1');\n  if (queueSize < 0) throw new RangeError('queueSize must be >= 0');\n\n  let active = 0;\n  const queue: QueueItem[] = [];\n\n  function tryDequeue(): void {\n    while (queue.length > 0 && active < concurrency) {\n      const item = queue.shift()!;\n      if (item.timer) clearTimeout(item.timer);\n      run(item);\n    }\n  }\n\n  async function run<T>(item: QueueItem<T>): Promise<void> {\n    active++;\n    try {\n      const value = await item.fn();\n      active--;\n      tryDequeue();\n      item.resolve(value);\n    } catch (error) {\n      active--;\n      tryDequeue();\n      item.reject(error instanceof Error ? error : new Error(String(error)));\n    }\n  }\n\n  function execute<T>(fn: () => Promise<T>): Promise<T> {\n    if (active < concurrency) {\n      return new Promise<T>((resolve, reject) => {\n        run({ fn, resolve, reject });\n      });\n    }\n\n    if (queue.length >= queueSize) {\n      return Promise.reject(new BulkheadError());\n    }\n\n    return new Promise<T>((resolve, reject) => {\n      const item: QueueItem<T> = { fn, resolve, reject };\n\n      if (queueTimeout > 0) {\n        item.timer = setTimeout(() => {\n          const idx = queue.indexOf(item as QueueItem);\n          if (idx !== -1) {\n            queue.splice(idx, 1);\n            reject(new BulkheadError('Bulkhead queue timeout exceeded'));\n          }\n        }, queueTimeout);\n      }\n\n      queue.push(item as QueueItem);\n    });\n  }\n\n  return {\n    execute,\n    get active() {\n      return active;\n    },\n    get queued() {\n      return queue.length;\n    },\n    get available() {\n      return Math.max(0, concurrency - active);\n    },\n  };\n}\n"]}

package/dist/circuit-breaker.d.mts

@@ -0,0 +1,44 @@
+type CircuitState = 'closed' | 'open' | 'half-open';
+interface CircuitBreakerOptions {
+    /** Number of failures before opening the circuit (default: 5) */
+    failureThreshold?: number;
+    /** Time in ms before attempting half-open (default: 30000) */
+    resetTimeout?: number;
+    /** Max concurrent calls in half-open state (default: 1) */
+    halfOpenLimit?: number;
+    /** Custom predicate to decide if an error should count as a failure */
+    shouldTrip?: (error: Error) => boolean;
+    /** Callback fired on state changes */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+    /** Number of successes in half-open to close the circuit (default: 1) */
+    successThreshold?: number;
+}
+interface CircuitBreaker<TArgs extends any[], TReturn> {
+    /** Execute the protected function */
+    fire: (...args: TArgs) => Promise<TReturn>;
+    /** Get the current circuit state */
+    readonly state: CircuitState;
+    /** Get the current failure count */
+    readonly failureCount: number;
+    /** Get the current success count (in half-open) */
+    readonly successCount: number;
+    /** Manually reset the circuit to closed */
+    reset: () => void;
+    /** Manually open the circuit */
+    open: () => void;
+}
+/**
+ * Create a circuit breaker to protect against cascading failures.
+ *
+ * @example
+ * ```ts
+ * const breaker = createCircuitBreaker(callExternalApi, {
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000,
+ * });
+ * const data = await breaker.fire('arg1');
+ * ```
+ */
+declare function createCircuitBreaker<TArgs extends any[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options?: CircuitBreakerOptions): CircuitBreaker<TArgs, TReturn>;
+
+export { type CircuitBreaker, type CircuitBreakerOptions, type CircuitState, createCircuitBreaker };

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,44 @@
+type CircuitState = 'closed' | 'open' | 'half-open';
+interface CircuitBreakerOptions {
+    /** Number of failures before opening the circuit (default: 5) */
+    failureThreshold?: number;
+    /** Time in ms before attempting half-open (default: 30000) */
+    resetTimeout?: number;
+    /** Max concurrent calls in half-open state (default: 1) */
+    halfOpenLimit?: number;
+    /** Custom predicate to decide if an error should count as a failure */
+    shouldTrip?: (error: Error) => boolean;
+    /** Callback fired on state changes */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+    /** Number of successes in half-open to close the circuit (default: 1) */
+    successThreshold?: number;
+}
+interface CircuitBreaker<TArgs extends any[], TReturn> {
+    /** Execute the protected function */
+    fire: (...args: TArgs) => Promise<TReturn>;
+    /** Get the current circuit state */
+    readonly state: CircuitState;
+    /** Get the current failure count */
+    readonly failureCount: number;
+    /** Get the current success count (in half-open) */
+    readonly successCount: number;
+    /** Manually reset the circuit to closed */
+    reset: () => void;
+    /** Manually open the circuit */
+    open: () => void;
+}
+/**
+ * Create a circuit breaker to protect against cascading failures.
+ *
+ * @example
+ * ```ts
+ * const breaker = createCircuitBreaker(callExternalApi, {
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000,
+ * });
+ * const data = await breaker.fire('arg1');
+ * ```
+ */
+declare function createCircuitBreaker<TArgs extends any[], TReturn>(fn: (...args: TArgs) => Promise<TReturn>, options?: CircuitBreakerOptions): CircuitBreaker<TArgs, TReturn>;
+
+export { type CircuitBreaker, type CircuitBreakerOptions, type CircuitState, createCircuitBreaker };

package/dist/circuit-breaker.js

@@ -0,0 +1,132 @@
+'use strict';
+
+// src/types.ts
+var FlowXError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "FlowXError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var CircuitBreakerError = class extends FlowXError {
+  constructor(message = "Circuit breaker is open") {
+    super(message, "ERR_CIRCUIT_OPEN");
+    this.name = "CircuitBreakerError";
+  }
+};
+
+// src/circuit-breaker.ts
+function createCircuitBreaker(fn, options) {
+  const {
+    failureThreshold = 5,
+    resetTimeout = 3e4,
+    halfOpenLimit = 1,
+    shouldTrip,
+    onStateChange,
+    successThreshold = 1
+  } = options ?? {};
+  let state = "closed";
+  let failureCount = 0;
+  let successCount = 0;
+  let halfOpenActive = 0;
+  let resetTimer = null;
+  function transition(to) {
+    if (state === to) return;
+    const from = state;
+    state = to;
+    onStateChange?.(from, to);
+  }
+  function scheduleReset() {
+    if (resetTimer) clearTimeout(resetTimer);
+    resetTimer = setTimeout(() => {
+      resetTimer = null;
+      transition("half-open");
+      halfOpenActive = 0;
+      successCount = 0;
+    }, resetTimeout);
+  }
+  function reset() {
+    if (resetTimer) {
+      clearTimeout(resetTimer);
+      resetTimer = null;
+    }
+    failureCount = 0;
+    successCount = 0;
+    halfOpenActive = 0;
+    transition("closed");
+  }
+  function manualOpen() {
+    if (resetTimer) {
+      clearTimeout(resetTimer);
+      resetTimer = null;
+    }
+    failureCount = 0;
+    successCount = 0;
+    halfOpenActive = 0;
+    transition("open");
+    scheduleReset();
+  }
+  async function fire(...args) {
+    if (state === "open") {
+      throw new CircuitBreakerError();
+    }
+    if (state === "half-open" && halfOpenActive >= halfOpenLimit) {
+      throw new CircuitBreakerError("Circuit breaker is half-open \u2014 limit reached");
+    }
+    if (state === "half-open") {
+      halfOpenActive++;
+    }
+    try {
+      const result = await fn(...args);
+      if (state === "half-open") {
+        successCount++;
+        halfOpenActive--;
+        if (successCount >= successThreshold) {
+          reset();
+        }
+      } else {
+        failureCount = 0;
+      }
+      return result;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      if (shouldTrip && !shouldTrip(err)) {
+        if (state === "half-open") {
+          halfOpenActive--;
+        }
+        throw err;
+      }
+      if (state === "half-open") {
+        halfOpenActive--;
+        transition("open");
+        scheduleReset();
+      } else {
+        failureCount++;
+        if (failureCount >= failureThreshold) {
+          transition("open");
+          scheduleReset();
+        }
+      }
+      throw err;
+    }
+  }
+  return {
+    fire,
+    get state() {
+      return state;
+    },
+    get failureCount() {
+      return failureCount;
+    },
+    get successCount() {
+      return successCount;
+    },
+    reset,
+    open: manualOpen
+  };
+}
+
+exports.createCircuitBreaker = createCircuitBreaker;
+//# sourceMappingURL=circuit-breaker.js.map
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/circuit-breaker.ts"],"names":[],"mappings":"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","file":"circuit-breaker.js","sourcesContent":["// ============================================================================\n// FlowX — Types & Error Hierarchy\n// ============================================================================\n\n/** Generic async function signature */\nexport type AsyncFn<TArgs extends any[] = any[], TReturn = any> = (\n  ...args: TArgs\n) => Promise<TReturn>;\n\n/** Backoff strategy for retry/poll operations */\nexport type BackoffStrategy =\n  | 'fixed'\n  | 'linear'\n  | 'exponential'\n  | ((attempt: number, delay: number) => number);\n\n// ── Error Classes ───────────────────────────────────────────────────────────\n\n/** Base error class for all FlowX errors */\nexport class FlowXError extends Error {\n  public readonly code: string;\n  constructor(message: string, code: string) {\n    super(message);\n    this.name = 'FlowXError';\n    this.code = code;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Thrown when a promise exceeds its timeout */\nexport class TimeoutError extends FlowXError {\n  constructor(message = 'Operation timed out') {\n    super(message, 'ERR_TIMEOUT');\n    this.name = 'TimeoutError';\n  }\n}\n\n/** Thrown when a circuit breaker is open */\nexport class CircuitBreakerError extends FlowXError {\n  constructor(message = 'Circuit breaker is open') {\n    super(message, 'ERR_CIRCUIT_OPEN');\n    this.name = 'CircuitBreakerError';\n  }\n}\n\n/** Thrown when a bulkhead rejects due to capacity */\nexport class BulkheadError extends FlowXError {\n  constructor(message = 'Bulkhead capacity exceeded') {\n    super(message, 'ERR_BULKHEAD_FULL');\n    this.name = 'BulkheadError';\n  }\n}\n\n/** Thrown when an operation is aborted */\nexport class AbortError extends FlowXError {\n  constructor(message = 'Operation aborted') {\n    super(message, 'ERR_ABORTED');\n    this.name = 'AbortError';\n  }\n}\n\n/** Thrown when rate limit is exceeded */\nexport class RateLimitError extends FlowXError {\n  constructor(message = 'Rate limit exceeded') {\n    super(message, 'ERR_RATE_LIMIT');\n    this.name = 'RateLimitError';\n  }\n}\n\n// ── Utility Helpers ─────────────────────────────────────────────────────────\n\n/** Sleep for the specified duration, respecting AbortSignal */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new AbortError());\n      return;\n    }\n\n    let onAbort: (() => void) | undefined;\n\n    const timer = setTimeout(() => {\n      if (signal && onAbort) {\n        signal.removeEventListener('abort', onAbort);\n      }\n      resolve();\n    }, ms);\n\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer);\n        reject(new AbortError());\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n    }\n  });\n}\n\n/** Calculate delay based on backoff strategy */\nexport function calculateDelay(\n  attempt: number,\n  baseDelay: number,\n  strategy: BackoffStrategy,\n  jitter: boolean | number = false,\n): number {\n  let delay: number;\n\n  if (typeof strategy === 'function') {\n    delay = strategy(attempt, baseDelay);\n  } else {\n    switch (strategy) {\n      case 'fixed':\n        delay = baseDelay;\n        break;\n      case 'linear':\n        delay = baseDelay * attempt;\n        break;\n      case 'exponential':\n        delay = baseDelay * Math.pow(2, attempt - 1);\n        break;\n    }\n  }\n\n  if (jitter) {\n    const factor = typeof jitter === 'number' ? jitter : 1;\n    delay = delay * (1 - factor * 0.5 + Math.random() * factor);\n  }\n\n  return Math.max(0, Math.floor(delay));\n}\n","// ============================================================================\n// FlowX — Circuit Breaker Pattern\n// ============================================================================\nimport { CircuitBreakerError } from './types';\n\nexport type CircuitState = 'closed' | 'open' | 'half-open';\n\nexport interface CircuitBreakerOptions {\n  /** Number of failures before opening the circuit (default: 5) */\n  failureThreshold?: number;\n  /** Time in ms before attempting half-open (default: 30000) */\n  resetTimeout?: number;\n  /** Max concurrent calls in half-open state (default: 1) */\n  halfOpenLimit?: number;\n  /** Custom predicate to decide if an error should count as a failure */\n  shouldTrip?: (error: Error) => boolean;\n  /** Callback fired on state changes */\n  onStateChange?: (from: CircuitState, to: CircuitState) => void;\n  /** Number of successes in half-open to close the circuit (default: 1) */\n  successThreshold?: number;\n}\n\nexport interface CircuitBreaker<TArgs extends any[], TReturn> {\n  /** Execute the protected function */\n  fire: (...args: TArgs) => Promise<TReturn>;\n  /** Get the current circuit state */\n  readonly state: CircuitState;\n  /** Get the current failure count */\n  readonly failureCount: number;\n  /** Get the current success count (in half-open) */\n  readonly successCount: number;\n  /** Manually reset the circuit to closed */\n  reset: () => void;\n  /** Manually open the circuit */\n  open: () => void;\n}\n\n/**\n * Create a circuit breaker to protect against cascading failures.\n *\n * @example\n * ```ts\n * const breaker = createCircuitBreaker(callExternalApi, {\n *   failureThreshold: 5,\n *   resetTimeout: 30000,\n * });\n * const data = await breaker.fire('arg1');\n * ```\n */\nexport function createCircuitBreaker<TArgs extends any[], TReturn>(\n  fn: (...args: TArgs) => Promise<TReturn>,\n  options?: CircuitBreakerOptions,\n): CircuitBreaker<TArgs, TReturn> {\n  const {\n    failureThreshold = 5,\n    resetTimeout = 30000,\n    halfOpenLimit = 1,\n    shouldTrip,\n    onStateChange,\n    successThreshold = 1,\n  } = options ?? {};\n\n  let state: CircuitState = 'closed';\n  let failureCount = 0;\n  let successCount = 0;\n  let halfOpenActive = 0;\n  let resetTimer: ReturnType<typeof setTimeout> | null = null;\n\n  function transition(to: CircuitState): void {\n    if (state === to) return;\n    const from = state;\n    state = to;\n    onStateChange?.(from, to);\n  }\n\n  function scheduleReset(): void {\n    /* istanbul ignore next -- defensive guard; timer always fires before reschedule in normal flow */\n    if (resetTimer) clearTimeout(resetTimer);\n    resetTimer = setTimeout(() => {\n      resetTimer = null;\n      transition('half-open');\n      halfOpenActive = 0;\n      successCount = 0;\n    }, resetTimeout);\n  }\n\n  function reset(): void {\n    if (resetTimer) {\n      clearTimeout(resetTimer);\n      resetTimer = null;\n    }\n    failureCount = 0;\n    successCount = 0;\n    halfOpenActive = 0;\n    transition('closed');\n  }\n\n  function manualOpen(): void {\n    if (resetTimer) {\n      clearTimeout(resetTimer);\n      resetTimer = null;\n    }\n    failureCount = 0;\n    successCount = 0;\n    halfOpenActive = 0;\n    transition('open');\n    scheduleReset();\n  }\n\n  async function fire(...args: TArgs): Promise<TReturn> {\n    if (state === 'open') {\n      throw new CircuitBreakerError();\n    }\n\n    if (state === 'half-open' && halfOpenActive >= halfOpenLimit) {\n      throw new CircuitBreakerError('Circuit breaker is half-open — limit reached');\n    }\n\n    if (state === 'half-open') {\n      halfOpenActive++;\n    }\n\n    try {\n      const result = await fn(...args);\n\n      if (state === 'half-open') {\n        successCount++;\n        halfOpenActive--;\n        if (successCount >= successThreshold) {\n          reset();\n        }\n      } else {\n        // In closed state, reset failure count on success\n        failureCount = 0;\n      }\n\n      return result;\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error(String(error));\n\n      if (shouldTrip && !shouldTrip(err)) {\n        if (state === 'half-open') {\n          halfOpenActive--;\n        }\n        throw err;\n      }\n\n      if (state === 'half-open') {\n        halfOpenActive--;\n        transition('open');\n        scheduleReset();\n      } else {\n        failureCount++;\n        if (failureCount >= failureThreshold) {\n          transition('open');\n          scheduleReset();\n        }\n      }\n\n      throw err;\n    }\n  }\n\n  return {\n    fire,\n    get state() {\n      return state;\n    },\n    get failureCount() {\n      return failureCount;\n    },\n    get successCount() {\n      return successCount;\n    },\n    reset,\n    open: manualOpen,\n  };\n}\n"]}