async-bulkhead-ts 0.1.0 → 0.2.0

package/README.md

@@ -11,6 +11,9 @@ Designed for services that prefer **rejecting work early** over queueing and deg
 - ✅ **Fail-fast by default** (no hidden queues)
 - ✅ Simple **bulkhead / concurrency limits**
 - ✅ Explicit admission + release lifecycle
+- ✅ `bulkhead.run(fn)` helper for safe execution
+- ✅ Optional cancellation via `AbortSignal`
+- ✅ Lightweight lifecycle hooks for metrics
 - ✅ Zero dependencies
 - ✅ ESM + CJS support
 - ✅ Node.js **20+**
@@ -19,7 +22,7 @@ Non-goals (by design):
 - ❌ No background workers
 - ❌ No retry logic
 - ❌ No distributed coordination
-- ❌ No metrics backend (hooks later)
+- ❌ No built-in metrics backend (hooks only)
 
 ---
 
@@ -29,7 +32,7 @@ Non-goals (by design):
 npm install async-bulkhead-ts
 ```
 
-## Basic Usage
+## Basic Usage (Manual)
 
 ```ts
 import { createBulkhead } from 'async-bulkhead-ts';
@@ -39,28 +42,69 @@ const admission = bulkhead.admit();
 
 if (!admission.ok) {
   // Fail fast — shed load, return 503, etc.
-  throw new Error('Service overloaded');
+  throw admission.error;
 }
 
 try {
-  // Do async work
   await doWork();
 } finally {
   admission.release();
 }
 ```
 
+You must call `release()` exactly once if admission succeeds.
+Failing to release permanently reduces capacity.
+
+## Convenience Helper
+
+For most use cases, prefer `bulkhead.run(fn)`:
+
+```ts
+await bulkhead.run(async () => {
+  await doWork();
+});
+```
+
+Behavior:
+
+* Admission + release handled automatically
+* Still fail-fast
+* Admission failures throw typed errors
+* Supports cancellation via AbortSignal
+
 ## With a Queue (Optional)
 
 Queues are opt-in and bounded.
- ```ts
+
+```ts
 const bulkhead = createBulkhead({
   maxConcurrent: 10,
   maxQueue: 20,
 });
 ```
 
-If both concurrency and queue limits are exceeded, admission fails immediately.
+When both concurrency and queue limits are exceeded, admission fails immediately.
+
+Queue ordering is FIFO.
+
+## Cancellation
+
+Bulkhead operations can be bound to an `AbortSignal`:
+
+```ts
+await bulkhead.run(
+  async () => {
+    await doWork();
+  },
+  { signal }
+);
+```
+
+Cancellation guarantees:
+
+* Queued work can be cancelled before execution
+* In-flight work observes the signal but is not forcibly terminated
+* Capacity is always released correctly
 
 ## API
 
@@ -75,9 +119,10 @@ type BulkheadOptions = {
 
 Returns:
 
-```json
+```ts
 {
   admit(): AdmitResult;
+  run<T>(fn: () => Promise<T>, options?): Promise<T>;
   stats(): {
     inFlight: number;
     queued: number;
@@ -92,37 +137,40 @@ Returns:
 ```ts
 type AdmitResult =
   | { ok: true; release: () => void }
-  | { ok: false; reason: 'concurrency_limit' | 'queue_limit' };
+  | { ok: false; error: BulkheadError };
 ```
 
-You must call `release()` exactly once if admission succeeds.
+Admission failures are returned as typed errors, not strings.
+
+## Metrics Hooks
+
+Optional lifecycle hooks allow integration with metrics systems:
 
-Failing to release will permanently reduce capacity.
+* admission accepted
+* queued
+* execution started
+* released
+* rejected
+
+Hooks are synchronous and side-effect–free by design.
 
 ## Design Philosophy
 
 This library is intentionally small.
 
-It exists to enforce **backpressure at the boundary** of your system:
+It exists to enforce backpressure at the boundary of your system:
 
 * before request fan-out
 * before hitting downstream dependencies
 * before saturation cascades
 
-If you need retries, buffering, scheduling, or persistence—compose those *around* this, not inside it.
+If you need retries, buffering, scheduling, or persistence—compose those around this, not inside it.
 
 ## Compatibility
 
 * Node.js: 20+ (24 LTS recommended)
 * Module formats: ESM and CommonJS
 
-## Roadmap (Short)
-
-* `bulkhead.run(fn)` helper
-* Structured metrics hooks
-* `AbortSignal` / cancellation support
-* Optional time-based admission windows
-
 ## License
 
 MIT © 2026

package/dist/index.cjs

@@ -20,59 +20,164 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BulkheadRejectedError: () => BulkheadRejectedError,
   createBulkhead: () => createBulkhead
 });
 module.exports = __toCommonJS(index_exports);
+var BulkheadRejectedError = class extends Error {
+  constructor(reason) {
+    super(`Bulkhead rejected: ${reason}`);
+    this.reason = reason;
+    this.name = "BulkheadRejectedError";
+  }
+  code = "BULKHEAD_REJECTED";
+};
 function createBulkhead(opts) {
   if (!Number.isInteger(opts.maxConcurrent) || opts.maxConcurrent <= 0) {
     throw new Error("maxConcurrent must be a positive integer");
   }
   const maxQueue = opts.maxQueue ?? 0;
+  if (!Number.isInteger(maxQueue) || maxQueue < 0) {
+    throw new Error("maxQueue must be an integer >= 0");
+  }
   let inFlight = 0;
-  const queue = [];
-  const tryStartNext = () => {
-    while (inFlight < opts.maxConcurrent && queue.length > 0) {
-      const start = queue.shift();
+  const q = [];
+  let qHead = 0;
+  let aborted = 0;
+  let timedOut = 0;
+  let rejected = 0;
+  let doubleRelease = 0;
+  const pendingCount = () => q.length - qHead;
+  const makeToken = () => {
+    let released = false;
+    return {
+      release() {
+        if (released) {
+          doubleRelease++;
+          return;
+        }
+        released = true;
+        inFlight--;
+        if (inFlight < 0) inFlight = 0;
+        drain();
+      }
+    };
+  };
+  const cleanupWaiter = (w) => {
+    if (w.abortListener) w.abortListener();
+    if (w.timeoutId) clearTimeout(w.timeoutId);
+    w.abortListener = void 0;
+    w.timeoutId = void 0;
+  };
+  const drain = () => {
+    while (inFlight < opts.maxConcurrent && pendingCount() > 0) {
+      const w = q[qHead++];
+      if (w.cancelled) {
+        cleanupWaiter(w);
+        continue;
+      }
       inFlight++;
-      start();
+      cleanupWaiter(w);
+      w.resolve({ ok: true, token: makeToken() });
+    }
+    if (qHead > 1024 && qHead * 2 > q.length) {
+      q.splice(0, qHead);
+      qHead = 0;
     }
   };
-  const release = () => {
-    inFlight = Math.max(0, inFlight - 1);
-    tryStartNext();
+  const tryAcquire = () => {
+    if (inFlight < opts.maxConcurrent) {
+      inFlight++;
+      return { ok: true, token: makeToken() };
+    }
+    if (maxQueue > 0 && pendingCount() >= maxQueue) {
+      rejected++;
+      return { ok: false, reason: "queue_limit" };
+    }
+    rejected++;
+    return { ok: false, reason: maxQueue > 0 ? "queue_limit" : "concurrency_limit" };
   };
-  const admit = () => {
+  const acquire = (ao = {}) => {
     if (inFlight < opts.maxConcurrent) {
       inFlight++;
-      return { ok: true, release };
+      return Promise.resolve({ ok: true, token: makeToken() });
+    }
+    if (maxQueue === 0) {
+      rejected++;
+      return Promise.resolve({ ok: false, reason: "concurrency_limit" });
+    }
+    if (pendingCount() >= maxQueue) {
+      rejected++;
+      return Promise.resolve({ ok: false, reason: "queue_limit" });
     }
-    if (maxQueue > 0 && queue.length < maxQueue) {
-      let started = false;
-      const gate = () => {
-        started = true;
+    return new Promise((resolve) => {
+      const w = {
+        resolve,
+        cancelled: false,
+        abortListener: void 0,
+        timeoutId: void 0
       };
-      queue.push(gate);
-      return {
-        ok: true,
-        release: () => {
-          if (!started) {
-            const idx = queue.indexOf(gate);
-            if (idx >= 0) queue.splice(idx, 1);
-          } else {
-            release();
+      if (ao.signal) {
+        if (ao.signal.aborted) {
+          aborted++;
+          resolve({ ok: false, reason: "aborted" });
+          return;
+        }
+        const onAbort = () => {
+          if (!w.cancelled) {
+            w.cancelled = true;
+            aborted++;
+            cleanupWaiter(w);
+            resolve({ ok: false, reason: "aborted" });
           }
+        };
+        ao.signal.addEventListener("abort", onAbort, { once: true });
+        w.abortListener = () => ao.signal.removeEventListener("abort", onAbort);
+      }
+      if (ao.timeoutMs != null) {
+        if (!Number.isFinite(ao.timeoutMs) || ao.timeoutMs < 0) {
+          timedOut++;
+          resolve({ ok: false, reason: "timeout" });
+          return;
         }
-      };
-    }
-    return { ok: false, reason: maxQueue > 0 ? "queue_limit" : "concurrency_limit" };
+        w.timeoutId = setTimeout(() => {
+          if (!w.cancelled) {
+            w.cancelled = true;
+            timedOut++;
+            cleanupWaiter(w);
+            resolve({ ok: false, reason: "timeout" });
+          }
+        }, ao.timeoutMs);
+      }
+      q.push(w);
+    });
   };
-  return {
-    admit,
-    stats: () => ({ inFlight, queued: queue.length, maxConcurrent: opts.maxConcurrent, maxQueue })
+  const run = async (fn, ao = {}) => {
+    const r = await acquire(ao);
+    if (!r.ok) {
+      throw new BulkheadRejectedError(r.reason);
+    }
+    try {
+      return await fn(ao.signal);
+    } finally {
+      r.token.release();
+    }
   };
+  const stats = () => ({
+    inFlight,
+    pending: pendingCount(),
+    maxConcurrent: opts.maxConcurrent,
+    maxQueue,
+    aborted,
+    timedOut,
+    rejected,
+    doubleRelease
+  });
+  return { tryAcquire, acquire, run, stats };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BulkheadRejectedError,
   createBulkhead
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export type BulkheadOptions = {\n  maxConcurrent: number;\n  maxQueue?: number; // if undefined => no queue (fail fast)\n};\n\nexport type AdmitResult =\n  | { ok: true; release: () => void }\n  | { ok: false; reason: \"concurrency_limit\" | \"queue_limit\" };\n\nexport function createBulkhead(opts: BulkheadOptions) {\n  if (!Number.isInteger(opts.maxConcurrent) || opts.maxConcurrent <= 0) {\n    throw new Error(\"maxConcurrent must be a positive integer\");\n  }\n  const maxQueue = opts.maxQueue ?? 0;\n\n  let inFlight = 0;\n  const queue: Array<() => void> = [];\n\n  const tryStartNext = () => {\n    while (inFlight < opts.maxConcurrent && queue.length > 0) {\n      const start = queue.shift()!;\n      inFlight++;\n      start();\n    }\n  };\n\n  const release = () => {\n    inFlight = Math.max(0, inFlight - 1);\n    tryStartNext();\n  };\n\n  const admit = (): AdmitResult => {\n    if (inFlight < opts.maxConcurrent) {\n      inFlight++;\n      return { ok: true, release };\n    }\n    if (maxQueue > 0 && queue.length < maxQueue) {\n      let started = false;\n      const gate = () => {\n        started = true;\n      };\n      queue.push(gate);\n\n      return {\n        ok: true,\n        release: () => {\n          // If not started yet, remove from queue and free slot reserved by queue entry.\n          if (!started) {\n            const idx = queue.indexOf(gate);\n            if (idx >= 0) queue.splice(idx, 1);\n          } else {\n            release();\n          }\n        }\n      };\n    }\n    return { ok: false, reason: maxQueue > 0 ? \"queue_limit\" : \"concurrency_limit\" };\n  };\n\n  return {\n    admit,\n    stats: () => ({ inFlight, queued: queue.length, maxConcurrent: opts.maxConcurrent, maxQueue })\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AASO,SAAS,eAAe,MAAuB;AACpD,MAAI,CAAC,OAAO,UAAU,KAAK,aAAa,KAAK,KAAK,iBAAiB,GAAG;AACpE,UAAM,IAAI,MAAM,0CAA0C;AAAA,EAC5D;AACA,QAAM,WAAW,KAAK,YAAY;AAElC,MAAI,WAAW;AACf,QAAM,QAA2B,CAAC;AAElC,QAAM,eAAe,MAAM;AACzB,WAAO,WAAW,KAAK,iBAAiB,MAAM,SAAS,GAAG;AACxD,YAAM,QAAQ,MAAM,MAAM;AAC1B;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAEA,QAAM,UAAU,MAAM;AACpB,eAAW,KAAK,IAAI,GAAG,WAAW,CAAC;AACnC,iBAAa;AAAA,EACf;AAEA,QAAM,QAAQ,MAAmB;AAC/B,QAAI,WAAW,KAAK,eAAe;AACjC;AACA,aAAO,EAAE,IAAI,MAAM,QAAQ;AAAA,IAC7B;AACA,QAAI,WAAW,KAAK,MAAM,SAAS,UAAU;AAC3C,UAAI,UAAU;AACd,YAAM,OAAO,MAAM;AACjB,kBAAU;AAAA,MACZ;AACA,YAAM,KAAK,IAAI;AAEf,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,SAAS,MAAM;AAEb,cAAI,CAAC,SAAS;AACZ,kBAAM,MAAM,MAAM,QAAQ,IAAI;AAC9B,gBAAI,OAAO,EAAG,OAAM,OAAO,KAAK,CAAC;AAAA,UACnC,OAAO;AACL,oBAAQ;AAAA,UACV;AAAA,QACF;AAAA,MACF;AAAA,IACF;AACA,WAAO,EAAE,IAAI,OAAO,QAAQ,WAAW,IAAI,gBAAgB,oBAAoB;AAAA,EACjF;AAEA,SAAO;AAAA,IACL;AAAA,IACA,OAAO,OAAO,EAAE,UAAU,QAAQ,MAAM,QAAQ,eAAe,KAAK,eAAe,SAAS;AAAA,EAC9F;AACF;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export type BulkheadOptions = {\n  maxConcurrent: number;\n  maxQueue?: number; // pending waiters allowed (0 => no waiting)\n};\n\nexport type AcquireOptions = {\n  signal?: AbortSignal;\n  timeoutMs?: number; // waiting timeout only\n};\n\nexport type Stats = {\n  inFlight: number;\n  pending: number;\n  maxConcurrent: number;\n  maxQueue: number;\n  // optional debug counters:\n  aborted?: number;\n  timedOut?: number;\n  rejected?: number;\n  doubleRelease?: number;\n};\n\nexport type Token = { release(): void };\n\nexport type TryAcquireResult =\n  | { ok: true; token: Token }\n  | { ok: false; reason: 'concurrency_limit' | 'queue_limit' };\n\nexport type AcquireResult =\n  | { ok: true; token: Token }\n  | { ok: false; reason: 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted' };\n\ntype Waiter = {\n  resolve: (r: AcquireResult) => void;\n  cancelled: boolean;\n\n  abortListener: (() => void) | undefined;\n  timeoutId: ReturnType<typeof setTimeout> | undefined;\n};\n\nexport type RejectReason = 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted';\n\nexport class BulkheadRejectedError extends Error {\n  readonly code = 'BULKHEAD_REJECTED' as const;\n\n  constructor(readonly reason: RejectReason) {\n    super(`Bulkhead rejected: ${reason}`);\n    this.name = 'BulkheadRejectedError';\n  }\n}\n\nexport function createBulkhead(opts: BulkheadOptions) {\n  // ---- validate ----\n  if (!Number.isInteger(opts.maxConcurrent) || opts.maxConcurrent <= 0) {\n    throw new Error('maxConcurrent must be a positive integer');\n  }\n  const maxQueue = opts.maxQueue ?? 0;\n  if (!Number.isInteger(maxQueue) || maxQueue < 0) {\n    throw new Error('maxQueue must be an integer >= 0');\n  }\n\n  // ---- state ----\n  let inFlight = 0;\n\n  // FIFO queue as array with head index (cheap shift)\n  const q: Waiter[] = [];\n  let qHead = 0;\n\n  // optional counters\n  let aborted = 0;\n  let timedOut = 0;\n  let rejected = 0;\n  let doubleRelease = 0;\n\n  const pendingCount = () => q.length - qHead;\n\n  // ---- token factory ----\n  const makeToken = (): Token => {\n    let released = false;\n    return {\n      release() {\n        if (released) {\n          doubleRelease++;\n          return; // idempotent; consider throw in dev builds if you prefer\n        }\n        released = true;\n        inFlight--;\n        if (inFlight < 0) inFlight = 0; // defensive, should never happen\n        drain();\n      },\n    };\n  };\n\n  const cleanupWaiter = (w: Waiter) => {\n    if (w.abortListener) w.abortListener();\n    if (w.timeoutId) clearTimeout(w.timeoutId);\n    w.abortListener = undefined;\n    w.timeoutId = undefined;\n  };\n\n  // ---- drain algorithm ----\n  const drain = () => {\n    while (inFlight < opts.maxConcurrent && pendingCount() > 0) {\n      const w = q[qHead++]!;\n      // skip cancelled waiters\n      if (w.cancelled) {\n        cleanupWaiter(w);\n        continue;\n      }\n\n      // grant slot\n      inFlight++;\n      cleanupWaiter(w);\n      w.resolve({ ok: true, token: makeToken() });\n    }\n\n    // occasional compaction to avoid unbounded growth\n    if (qHead > 1024 && qHead * 2 > q.length) {\n      q.splice(0, qHead);\n      qHead = 0;\n    }\n  };\n\n  // ---- public APIs ----\n\n  const tryAcquire = (): TryAcquireResult => {\n    if (inFlight < opts.maxConcurrent) {\n      inFlight++;\n      return { ok: true, token: makeToken() };\n    }\n    // tryAcquire never waits; queue_limit matters only if maxQueue configured\n    if (maxQueue > 0 && pendingCount() >= maxQueue) {\n      rejected++;\n      return { ok: false, reason: 'queue_limit' };\n    }\n    rejected++;\n    return { ok: false, reason: maxQueue > 0 ? 'queue_limit' : 'concurrency_limit' };\n  };\n\n  const acquire = (ao: AcquireOptions = {}): Promise<AcquireResult> => {\n    // immediate fast path\n    if (inFlight < opts.maxConcurrent) {\n      inFlight++;\n      return Promise.resolve({ ok: true, token: makeToken() });\n    }\n\n    // no waiting allowed\n    if (maxQueue === 0) {\n      rejected++;\n      return Promise.resolve({ ok: false, reason: 'concurrency_limit' });\n    }\n\n    // bounded waiting\n    if (pendingCount() >= maxQueue) {\n      rejected++;\n      return Promise.resolve({ ok: false, reason: 'queue_limit' });\n    }\n\n    // enqueue\n    return new Promise<AcquireResult>((resolve) => {\n      const w: Waiter = {\n        resolve,\n        cancelled: false,\n        abortListener: undefined,\n        timeoutId: undefined,\n      };\n\n      // abort support\n      if (ao.signal) {\n        if (ao.signal.aborted) {\n          aborted++;\n          resolve({ ok: false, reason: 'aborted' });\n          return;\n        }\n        const onAbort = () => {\n          // mark cancelled; drain() will skip it\n          if (!w.cancelled) {\n            w.cancelled = true;\n            aborted++;\n            cleanupWaiter(w);\n            resolve({ ok: false, reason: 'aborted' });\n          }\n        };\n        ao.signal.addEventListener('abort', onAbort, { once: true });\n        w.abortListener = () => ao.signal!.removeEventListener('abort', onAbort);\n      }\n\n      // timeout support (waiting only)\n      if (ao.timeoutMs != null) {\n        if (!Number.isFinite(ao.timeoutMs) || ao.timeoutMs < 0) {\n          // invalid => treat as immediate timeout\n          timedOut++;\n          resolve({ ok: false, reason: 'timeout' });\n          return;\n        }\n        w.timeoutId = setTimeout(() => {\n          if (!w.cancelled) {\n            w.cancelled = true;\n            timedOut++;\n            cleanupWaiter(w);\n            resolve({ ok: false, reason: 'timeout' });\n          }\n        }, ao.timeoutMs);\n      }\n\n      q.push(w);\n      // NOTE: we do NOT reserve capacity here.\n      // A slot is consumed only when drain() grants a token.\n\n      // No need to call drain() here because we already know we’re at capacity,\n      // but it doesn’t hurt if you want (for races with release).\n    });\n  };\n\n  const run = async <T>(\n    fn: (signal?: AbortSignal) => Promise<T>,\n    ao: AcquireOptions = {},\n  ): Promise<T> => {\n    const r = await acquire(ao);\n    if (!r.ok) {\n      throw new BulkheadRejectedError(r.reason);\n    }\n    try {\n      return await fn(ao.signal);\n    } finally {\n      r.token.release();\n    }\n  };\n\n  const stats = (): Stats => ({\n    inFlight,\n    pending: pendingCount(),\n    maxConcurrent: opts.maxConcurrent,\n    maxQueue,\n    aborted,\n    timedOut,\n    rejected,\n    doubleRelease,\n  });\n\n  return { tryAcquire, acquire, run, stats };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -2,21 +2,48 @@ type BulkheadOptions = {
     maxConcurrent: number;
     maxQueue?: number;
 };
-type AdmitResult = {
+type AcquireOptions = {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+type Stats = {
+    inFlight: number;
+    pending: number;
+    maxConcurrent: number;
+    maxQueue: number;
+    aborted?: number;
+    timedOut?: number;
+    rejected?: number;
+    doubleRelease?: number;
+};
+type Token = {
+    release(): void;
+};
+type TryAcquireResult = {
+    ok: true;
+    token: Token;
+} | {
+    ok: false;
+    reason: 'concurrency_limit' | 'queue_limit';
+};
+type AcquireResult = {
     ok: true;
-    release: () => void;
+    token: Token;
 } | {
     ok: false;
-    reason: "concurrency_limit" | "queue_limit";
+    reason: 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted';
 };
+type RejectReason = 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted';
+declare class BulkheadRejectedError extends Error {
+    readonly reason: RejectReason;
+    readonly code: "BULKHEAD_REJECTED";
+    constructor(reason: RejectReason);
+}
 declare function createBulkhead(opts: BulkheadOptions): {
-    admit: () => AdmitResult;
-    stats: () => {
-        inFlight: number;
-        queued: number;
-        maxConcurrent: number;
-        maxQueue: number;
-    };
+    tryAcquire: () => TryAcquireResult;
+    acquire: (ao?: AcquireOptions) => Promise<AcquireResult>;
+    run: <T>(fn: (signal?: AbortSignal) => Promise<T>, ao?: AcquireOptions) => Promise<T>;
+    stats: () => Stats;
 };
 
-export { type AdmitResult, type BulkheadOptions, createBulkhead };
+export { type AcquireOptions, type AcquireResult, type BulkheadOptions, BulkheadRejectedError, type RejectReason, type Stats, type Token, type TryAcquireResult, createBulkhead };

package/dist/index.d.ts

@@ -2,21 +2,48 @@ type BulkheadOptions = {
     maxConcurrent: number;
     maxQueue?: number;
 };
-type AdmitResult = {
+type AcquireOptions = {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+type Stats = {
+    inFlight: number;
+    pending: number;
+    maxConcurrent: number;
+    maxQueue: number;
+    aborted?: number;
+    timedOut?: number;
+    rejected?: number;
+    doubleRelease?: number;
+};
+type Token = {
+    release(): void;
+};
+type TryAcquireResult = {
+    ok: true;
+    token: Token;
+} | {
+    ok: false;
+    reason: 'concurrency_limit' | 'queue_limit';
+};
+type AcquireResult = {
     ok: true;
-    release: () => void;
+    token: Token;
 } | {
     ok: false;
-    reason: "concurrency_limit" | "queue_limit";
+    reason: 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted';
 };
+type RejectReason = 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted';
+declare class BulkheadRejectedError extends Error {
+    readonly reason: RejectReason;
+    readonly code: "BULKHEAD_REJECTED";
+    constructor(reason: RejectReason);
+}
 declare function createBulkhead(opts: BulkheadOptions): {
-    admit: () => AdmitResult;
-    stats: () => {
-        inFlight: number;
-        queued: number;
-        maxConcurrent: number;
-        maxQueue: number;
-    };
+    tryAcquire: () => TryAcquireResult;
+    acquire: (ao?: AcquireOptions) => Promise<AcquireResult>;
+    run: <T>(fn: (signal?: AbortSignal) => Promise<T>, ao?: AcquireOptions) => Promise<T>;
+    stats: () => Stats;
 };
 
-export { type AdmitResult, type BulkheadOptions, createBulkhead };
+export { type AcquireOptions, type AcquireResult, type BulkheadOptions, BulkheadRejectedError, type RejectReason, type Stats, type Token, type TryAcquireResult, createBulkhead };

package/dist/index.js

@@ -1,53 +1,157 @@
 // src/index.ts
+var BulkheadRejectedError = class extends Error {
+  constructor(reason) {
+    super(`Bulkhead rejected: ${reason}`);
+    this.reason = reason;
+    this.name = "BulkheadRejectedError";
+  }
+  code = "BULKHEAD_REJECTED";
+};
 function createBulkhead(opts) {
   if (!Number.isInteger(opts.maxConcurrent) || opts.maxConcurrent <= 0) {
     throw new Error("maxConcurrent must be a positive integer");
   }
   const maxQueue = opts.maxQueue ?? 0;
+  if (!Number.isInteger(maxQueue) || maxQueue < 0) {
+    throw new Error("maxQueue must be an integer >= 0");
+  }
   let inFlight = 0;
-  const queue = [];
-  const tryStartNext = () => {
-    while (inFlight < opts.maxConcurrent && queue.length > 0) {
-      const start = queue.shift();
+  const q = [];
+  let qHead = 0;
+  let aborted = 0;
+  let timedOut = 0;
+  let rejected = 0;
+  let doubleRelease = 0;
+  const pendingCount = () => q.length - qHead;
+  const makeToken = () => {
+    let released = false;
+    return {
+      release() {
+        if (released) {
+          doubleRelease++;
+          return;
+        }
+        released = true;
+        inFlight--;
+        if (inFlight < 0) inFlight = 0;
+        drain();
+      }
+    };
+  };
+  const cleanupWaiter = (w) => {
+    if (w.abortListener) w.abortListener();
+    if (w.timeoutId) clearTimeout(w.timeoutId);
+    w.abortListener = void 0;
+    w.timeoutId = void 0;
+  };
+  const drain = () => {
+    while (inFlight < opts.maxConcurrent && pendingCount() > 0) {
+      const w = q[qHead++];
+      if (w.cancelled) {
+        cleanupWaiter(w);
+        continue;
+      }
       inFlight++;
-      start();
+      cleanupWaiter(w);
+      w.resolve({ ok: true, token: makeToken() });
+    }
+    if (qHead > 1024 && qHead * 2 > q.length) {
+      q.splice(0, qHead);
+      qHead = 0;
     }
   };
-  const release = () => {
-    inFlight = Math.max(0, inFlight - 1);
-    tryStartNext();
+  const tryAcquire = () => {
+    if (inFlight < opts.maxConcurrent) {
+      inFlight++;
+      return { ok: true, token: makeToken() };
+    }
+    if (maxQueue > 0 && pendingCount() >= maxQueue) {
+      rejected++;
+      return { ok: false, reason: "queue_limit" };
+    }
+    rejected++;
+    return { ok: false, reason: maxQueue > 0 ? "queue_limit" : "concurrency_limit" };
   };
-  const admit = () => {
+  const acquire = (ao = {}) => {
     if (inFlight < opts.maxConcurrent) {
       inFlight++;
-      return { ok: true, release };
+      return Promise.resolve({ ok: true, token: makeToken() });
+    }
+    if (maxQueue === 0) {
+      rejected++;
+      return Promise.resolve({ ok: false, reason: "concurrency_limit" });
+    }
+    if (pendingCount() >= maxQueue) {
+      rejected++;
+      return Promise.resolve({ ok: false, reason: "queue_limit" });
     }
-    if (maxQueue > 0 && queue.length < maxQueue) {
-      let started = false;
-      const gate = () => {
-        started = true;
+    return new Promise((resolve) => {
+      const w = {
+        resolve,
+        cancelled: false,
+        abortListener: void 0,
+        timeoutId: void 0
       };
-      queue.push(gate);
-      return {
-        ok: true,
-        release: () => {
-          if (!started) {
-            const idx = queue.indexOf(gate);
-            if (idx >= 0) queue.splice(idx, 1);
-          } else {
-            release();
+      if (ao.signal) {
+        if (ao.signal.aborted) {
+          aborted++;
+          resolve({ ok: false, reason: "aborted" });
+          return;
+        }
+        const onAbort = () => {
+          if (!w.cancelled) {
+            w.cancelled = true;
+            aborted++;
+            cleanupWaiter(w);
+            resolve({ ok: false, reason: "aborted" });
           }
+        };
+        ao.signal.addEventListener("abort", onAbort, { once: true });
+        w.abortListener = () => ao.signal.removeEventListener("abort", onAbort);
+      }
+      if (ao.timeoutMs != null) {
+        if (!Number.isFinite(ao.timeoutMs) || ao.timeoutMs < 0) {
+          timedOut++;
+          resolve({ ok: false, reason: "timeout" });
+          return;
         }
-      };
-    }
-    return { ok: false, reason: maxQueue > 0 ? "queue_limit" : "concurrency_limit" };
+        w.timeoutId = setTimeout(() => {
+          if (!w.cancelled) {
+            w.cancelled = true;
+            timedOut++;
+            cleanupWaiter(w);
+            resolve({ ok: false, reason: "timeout" });
+          }
+        }, ao.timeoutMs);
+      }
+      q.push(w);
+    });
   };
-  return {
-    admit,
-    stats: () => ({ inFlight, queued: queue.length, maxConcurrent: opts.maxConcurrent, maxQueue })
+  const run = async (fn, ao = {}) => {
+    const r = await acquire(ao);
+    if (!r.ok) {
+      throw new BulkheadRejectedError(r.reason);
+    }
+    try {
+      return await fn(ao.signal);
+    } finally {
+      r.token.release();
+    }
   };
+  const stats = () => ({
+    inFlight,
+    pending: pendingCount(),
+    maxConcurrent: opts.maxConcurrent,
+    maxQueue,
+    aborted,
+    timedOut,
+    rejected,
+    doubleRelease
+  });
+  return { tryAcquire, acquire, run, stats };
 }
 export {
+  BulkheadRejectedError,
   createBulkhead
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export type BulkheadOptions = {\n  maxConcurrent: number;\n  maxQueue?: number; // if undefined => no queue (fail fast)\n};\n\nexport type AdmitResult =\n  | { ok: true; release: () => void }\n  | { ok: false; reason: \"concurrency_limit\" | \"queue_limit\" };\n\nexport function createBulkhead(opts: BulkheadOptions) {\n  if (!Number.isInteger(opts.maxConcurrent) || opts.maxConcurrent <= 0) {\n    throw new Error(\"maxConcurrent must be a positive integer\");\n  }\n  const maxQueue = opts.maxQueue ?? 0;\n\n  let inFlight = 0;\n  const queue: Array<() => void> = [];\n\n  const tryStartNext = () => {\n    while (inFlight < opts.maxConcurrent && queue.length > 0) {\n      const start = queue.shift()!;\n      inFlight++;\n      start();\n    }\n  };\n\n  const release = () => {\n    inFlight = Math.max(0, inFlight - 1);\n    tryStartNext();\n  };\n\n  const admit = (): AdmitResult => {\n    if (inFlight < opts.maxConcurrent) {\n      inFlight++;\n      return { ok: true, release };\n    }\n    if (maxQueue > 0 && queue.length < maxQueue) {\n      let started = false;\n      const gate = () => {\n        started = true;\n      };\n      queue.push(gate);\n\n      return {\n        ok: true,\n        release: () => {\n          // If not started yet, remove from queue and free slot reserved by queue entry.\n          if (!started) {\n            const idx = queue.indexOf(gate);\n            if (idx >= 0) queue.splice(idx, 1);\n          } else {\n            release();\n          }\n        }\n      };\n    }\n    return { ok: false, reason: maxQueue > 0 ? \"queue_limit\" : \"concurrency_limit\" };\n  };\n\n  return {\n    admit,\n    stats: () => ({ inFlight, queued: queue.length, maxConcurrent: opts.maxConcurrent, maxQueue })\n  };\n}\n"],"mappings":";AASO,SAAS,eAAe,MAAuB;AACpD,MAAI,CAAC,OAAO,UAAU,KAAK,aAAa,KAAK,KAAK,iBAAiB,GAAG;AACpE,UAAM,IAAI,MAAM,0CAA0C;AAAA,EAC5D;AACA,QAAM,WAAW,KAAK,YAAY;AAElC,MAAI,WAAW;AACf,QAAM,QAA2B,CAAC;AAElC,QAAM,eAAe,MAAM;AACzB,WAAO,WAAW,KAAK,iBAAiB,MAAM,SAAS,GAAG;AACxD,YAAM,QAAQ,MAAM,MAAM;AAC1B;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAEA,QAAM,UAAU,MAAM;AACpB,eAAW,KAAK,IAAI,GAAG,WAAW,CAAC;AACnC,iBAAa;AAAA,EACf;AAEA,QAAM,QAAQ,MAAmB;AAC/B,QAAI,WAAW,KAAK,eAAe;AACjC;AACA,aAAO,EAAE,IAAI,MAAM,QAAQ;AAAA,IAC7B;AACA,QAAI,WAAW,KAAK,MAAM,SAAS,UAAU;AAC3C,UAAI,UAAU;AACd,YAAM,OAAO,MAAM;AACjB,kBAAU;AAAA,MACZ;AACA,YAAM,KAAK,IAAI;AAEf,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,SAAS,MAAM;AAEb,cAAI,CAAC,SAAS;AACZ,kBAAM,MAAM,MAAM,QAAQ,IAAI;AAC9B,gBAAI,OAAO,EAAG,OAAM,OAAO,KAAK,CAAC;AAAA,UACnC,OAAO;AACL,oBAAQ;AAAA,UACV;AAAA,QACF;AAAA,MACF;AAAA,IACF;AACA,WAAO,EAAE,IAAI,OAAO,QAAQ,WAAW,IAAI,gBAAgB,oBAAoB;AAAA,EACjF;AAEA,SAAO;AAAA,IACL;AAAA,IACA,OAAO,OAAO,EAAE,UAAU,QAAQ,MAAM,QAAQ,eAAe,KAAK,eAAe,SAAS;AAAA,EAC9F;AACF;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export type BulkheadOptions = {\n  maxConcurrent: number;\n  maxQueue?: number; // pending waiters allowed (0 => no waiting)\n};\n\nexport type AcquireOptions = {\n  signal?: AbortSignal;\n  timeoutMs?: number; // waiting timeout only\n};\n\nexport type Stats = {\n  inFlight: number;\n  pending: number;\n  maxConcurrent: number;\n  maxQueue: number;\n  // optional debug counters:\n  aborted?: number;\n  timedOut?: number;\n  rejected?: number;\n  doubleRelease?: number;\n};\n\nexport type Token = { release(): void };\n\nexport type TryAcquireResult =\n  | { ok: true; token: Token }\n  | { ok: false; reason: 'concurrency_limit' | 'queue_limit' };\n\nexport type AcquireResult =\n  | { ok: true; token: Token }\n  | { ok: false; reason: 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted' };\n\ntype Waiter = {\n  resolve: (r: AcquireResult) => void;\n  cancelled: boolean;\n\n  abortListener: (() => void) | undefined;\n  timeoutId: ReturnType<typeof setTimeout> | undefined;\n};\n\nexport type RejectReason = 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted';\n\nexport class BulkheadRejectedError extends Error {\n  readonly code = 'BULKHEAD_REJECTED' as const;\n\n  constructor(readonly reason: RejectReason) {\n    super(`Bulkhead rejected: ${reason}`);\n    this.name = 'BulkheadRejectedError';\n  }\n}\n\nexport function createBulkhead(opts: BulkheadOptions) {\n  // ---- validate ----\n  if (!Number.isInteger(opts.maxConcurrent) || opts.maxConcurrent <= 0) {\n    throw new Error('maxConcurrent must be a positive integer');\n  }\n  const maxQueue = opts.maxQueue ?? 0;\n  if (!Number.isInteger(maxQueue) || maxQueue < 0) {\n    throw new Error('maxQueue must be an integer >= 0');\n  }\n\n  // ---- state ----\n  let inFlight = 0;\n\n  // FIFO queue as array with head index (cheap shift)\n  const q: Waiter[] = [];\n  let qHead = 0;\n\n  // optional counters\n  let aborted = 0;\n  let timedOut = 0;\n  let rejected = 0;\n  let doubleRelease = 0;\n\n  const pendingCount = () => q.length - qHead;\n\n  // ---- token factory ----\n  const makeToken = (): Token => {\n    let released = false;\n    return {\n      release() {\n        if (released) {\n          doubleRelease++;\n          return; // idempotent; consider throw in dev builds if you prefer\n        }\n        released = true;\n        inFlight--;\n        if (inFlight < 0) inFlight = 0; // defensive, should never happen\n        drain();\n      },\n    };\n  };\n\n  const cleanupWaiter = (w: Waiter) => {\n    if (w.abortListener) w.abortListener();\n    if (w.timeoutId) clearTimeout(w.timeoutId);\n    w.abortListener = undefined;\n    w.timeoutId = undefined;\n  };\n\n  // ---- drain algorithm ----\n  const drain = () => {\n    while (inFlight < opts.maxConcurrent && pendingCount() > 0) {\n      const w = q[qHead++]!;\n      // skip cancelled waiters\n      if (w.cancelled) {\n        cleanupWaiter(w);\n        continue;\n      }\n\n      // grant slot\n      inFlight++;\n      cleanupWaiter(w);\n      w.resolve({ ok: true, token: makeToken() });\n    }\n\n    // occasional compaction to avoid unbounded growth\n    if (qHead > 1024 && qHead * 2 > q.length) {\n      q.splice(0, qHead);\n      qHead = 0;\n    }\n  };\n\n  // ---- public APIs ----\n\n  const tryAcquire = (): TryAcquireResult => {\n    if (inFlight < opts.maxConcurrent) {\n      inFlight++;\n      return { ok: true, token: makeToken() };\n    }\n    // tryAcquire never waits; queue_limit matters only if maxQueue configured\n    if (maxQueue > 0 && pendingCount() >= maxQueue) {\n      rejected++;\n      return { ok: false, reason: 'queue_limit' };\n    }\n    rejected++;\n    return { ok: false, reason: maxQueue > 0 ? 'queue_limit' : 'concurrency_limit' };\n  };\n\n  const acquire = (ao: AcquireOptions = {}): Promise<AcquireResult> => {\n    // immediate fast path\n    if (inFlight < opts.maxConcurrent) {\n      inFlight++;\n      return Promise.resolve({ ok: true, token: makeToken() });\n    }\n\n    // no waiting allowed\n    if (maxQueue === 0) {\n      rejected++;\n      return Promise.resolve({ ok: false, reason: 'concurrency_limit' });\n    }\n\n    // bounded waiting\n    if (pendingCount() >= maxQueue) {\n      rejected++;\n      return Promise.resolve({ ok: false, reason: 'queue_limit' });\n    }\n\n    // enqueue\n    return new Promise<AcquireResult>((resolve) => {\n      const w: Waiter = {\n        resolve,\n        cancelled: false,\n        abortListener: undefined,\n        timeoutId: undefined,\n      };\n\n      // abort support\n      if (ao.signal) {\n        if (ao.signal.aborted) {\n          aborted++;\n          resolve({ ok: false, reason: 'aborted' });\n          return;\n        }\n        const onAbort = () => {\n          // mark cancelled; drain() will skip it\n          if (!w.cancelled) {\n            w.cancelled = true;\n            aborted++;\n            cleanupWaiter(w);\n            resolve({ ok: false, reason: 'aborted' });\n          }\n        };\n        ao.signal.addEventListener('abort', onAbort, { once: true });\n        w.abortListener = () => ao.signal!.removeEventListener('abort', onAbort);\n      }\n\n      // timeout support (waiting only)\n      if (ao.timeoutMs != null) {\n        if (!Number.isFinite(ao.timeoutMs) || ao.timeoutMs < 0) {\n          // invalid => treat as immediate timeout\n          timedOut++;\n          resolve({ ok: false, reason: 'timeout' });\n          return;\n        }\n        w.timeoutId = setTimeout(() => {\n          if (!w.cancelled) {\n            w.cancelled = true;\n            timedOut++;\n            cleanupWaiter(w);\n            resolve({ ok: false, reason: 'timeout' });\n          }\n        }, ao.timeoutMs);\n      }\n\n      q.push(w);\n      // NOTE: we do NOT reserve capacity here.\n      // A slot is consumed only when drain() grants a token.\n\n      // No need to call drain() here because we already know we’re at capacity,\n      // but it doesn’t hurt if you want (for races with release).\n    });\n  };\n\n  const run = async <T>(\n    fn: (signal?: AbortSignal) => Promise<T>,\n    ao: AcquireOptions = {},\n  ): Promise<T> => {\n    const r = await acquire(ao);\n    if (!r.ok) {\n      throw new BulkheadRejectedError(r.reason);\n    }\n    try {\n      return await fn(ao.signal);\n    } finally {\n      r.token.release();\n    }\n  };\n\n  const stats = (): Stats => ({\n    inFlight,\n    pending: pendingCount(),\n    maxConcurrent: opts.maxConcurrent,\n    maxQueue,\n    aborted,\n    timedOut,\n    rejected,\n    doubleRelease,\n  });\n\n  return { tryAcquire, acquire, run, stats };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "async-bulkhead-ts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Fail-fast admission control + bulkheads for async workloads",
   "license": "MIT",
   "type": "module",