async-bulkhead-ts 0.2.0 → 0.2.2

package/README.md

@@ -1,19 +1,19 @@
 # async-bulkhead-ts
 
-Fail-fast **admission control** and **bulkheads** for async workloads in Node.js.
+Fail-fast **admission control** (async bulkheads) for Node.js / TypeScript.
 
-Designed for services that prefer **rejecting work early** over queueing and degrading under load.
+Designed for services that prefer **rejecting work early** over silently degrading via growing queues and timeouts.
 
 ---
 
 ## Features
 
-- ✅ **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
+- ✅ Hard **max in-flight** concurrency (`maxConcurrent`)
+- ✅ Optional **bounded FIFO waiting** (`maxQueue`)
+- ✅ **Fail-fast by default** (`maxQueue: 0`)
+- ✅ Explicit acquire + release via a **token**
+- ✅ `bulkhead.run(fn)` helper (acquire + `finally` release)
+- ✅ Optional waiting **timeout** and **AbortSignal** cancellation
 - ✅ Zero dependencies
 - ✅ ESM + CJS support
 - ✅ Node.js **20+**
@@ -22,7 +22,6 @@ Non-goals (by design):
 - ❌ No background workers
 - ❌ No retry logic
 - ❌ No distributed coordination
-- ❌ No built-in metrics backend (hooks only)
 
 ---
 
@@ -32,49 +31,55 @@ Non-goals (by design):
 npm install async-bulkhead-ts
 ```
 
-## Basic Usage (Manual)
+## Basic Usage (Manual acquire/release)
 
 ```ts
 import { createBulkhead } from 'async-bulkhead-ts';
 
-const bulkhead = createBulkhead({ maxConcurrent: 10 });
-const admission = bulkhead.admit();
+const bulkhead = createBulkhead({
+  maxConcurrent: 10,
+});
+
+const r = await bulkhead.acquire();
 
-if (!admission.ok) {
+if (!r.ok) {
   // Fail fast — shed load, return 503, etc.
-  throw admission.error;
+  // r.reason is one of:
+  // 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted'
+  throw new Error(`Rejected: ${r.reason}`);
 }
 
 try {
   await doWork();
 } finally {
-  admission.release();
+  r.token.release();
 }
 ```
 
-You must call `release()` exactly once if admission succeeds.
-Failing to release permanently reduces capacity.
+You must call `token.release()` exactly once if acquisition succeeds.
+Failing to release permanently reduces available capacity.
 
 ## Convenience Helper
 
 For most use cases, prefer `bulkhead.run(fn)`:
 
 ```ts
-await bulkhead.run(async () => {
-  await doWork();
-});
+await bulkhead.run(async () => doWork());
 ```
 
 Behavior:
 
-* Admission + release handled automatically
-* Still fail-fast
-* Admission failures throw typed errors
-* Supports cancellation via AbortSignal
+- Acquire + release handled automatically (finally release)
+- Still fail-fast (unless you configure `maxQueue`)
+- Rejections throw a typed `BulkheadRejectedError` when using `run()`
+- The provided `AbortSignal` is passed through to the function
+- Supports waiting cancellation via `AbortSignal` and `timeoutMs`
+
+> The signal passed to `run()` only affects admission and observation; in-flight work is not forcibly cancelled.
 
 ## With a Queue (Optional)
 
-Queues are opt-in and bounded.
+Waiting is opt-in and bounded (FIFO).
 
 ```ts
 const bulkhead = createBulkhead({
@@ -83,28 +88,45 @@ const bulkhead = createBulkhead({
 });
 ```
 
-When both concurrency and queue limits are exceeded, admission fails immediately.
+> Note: bounded waiting is optional.
+> Future major versions may focus on fail-fast admission only.
 
-Queue ordering is FIFO.
+
+Semantics:
+- If `inFlight` < `maxConcurrent`: `acquire()` succeeds immediately.
+- Else if `maxQueue` > 0 and queue has space: `acquire()` waits FIFO.
+- Else: rejected immediately.
 
 ## Cancellation
 
-Bulkhead operations can be bound to an `AbortSignal`:
+Waiting can be cancelled with an `AbortSignal`:
 
 ```ts
 await bulkhead.run(
-  async () => {
-    await doWork();
-  },
+  async () => doWork(),
   { signal }
 );
 ```
 
 Cancellation guarantees:
+- Work that is waiting in the queue can be cancelled before it starts.
+- In-flight work is not forcibly terminated (your function may observe the signal).
+- Capacity is always released correctly for acquired tokens.
+- Cancelled or timed-out waiters do not permanently consume queue capacity.
+- Cancelled waiters will not block subsequent admissions.
+- FIFO order is preserved for non-cancelled waiters.
+
+You can also bound waiting time:
+
+```ts
+await bulkhead.run(async () => doWork(), { timeoutMs: 50 });
+```
+
+## Behavioral Guarantees
 
-* Queued work can be cancelled before execution
-* In-flight work observes the signal but is not forcibly terminated
-* Capacity is always released correctly
+- maxConcurrent is never exceeded.
+- pending never exceeds maxQueue.
+- Under cancellation or timeout churn, admission remains bounded and deterministic.
 
 ## API
 
@@ -113,7 +135,7 @@ Cancellation guarantees:
 ```ts
 type BulkheadOptions = {
   maxConcurrent: number;
-  maxQueue?: number;
+  maxQueue?: number; // pending waiters allowed (0 => no waiting)
 };
 ```
 
@@ -121,38 +143,62 @@ Returns:
 
 ```ts
 {
-  admit(): AdmitResult;
-  run<T>(fn: () => Promise<T>, options?): Promise<T>;
+  tryAcquire(): TryAcquireResult;
+  acquire(options?): Promise<AcquireResult>;
+  run<T>(fn: (signal?: AbortSignal) => Promise<T>, options?): Promise<T>;
   stats(): {
     inFlight: number;
-    queued: number;
+    pending: number;
     maxConcurrent: number;
     maxQueue: number;
+    aborted?: number;
+    timedOut?: number;
+    rejected?: number;
+    doubleRelease?: number;
   };
 }
 ```
 
-`admit()`
+`tryAcquire()`
 
 ```ts
-type AdmitResult =
-  | { ok: true; release: () => void }
-  | { ok: false; error: BulkheadError };
+export type TryAcquireResult =
+  | { ok: true; token: Token }
+  | { ok: false; reason: 'concurrency_limit' };
 ```
 
-Admission failures are returned as typed errors, not strings.
+> `tryAcquire()` never waits and never enqueues; it either acquires immediately or fails fast.
 
-## Metrics Hooks
+`acquire(options?)`
 
-Optional lifecycle hooks allow integration with metrics systems:
+```ts
+type AcquireOptions = {
+  signal?: AbortSignal;
+  timeoutMs?: number; // waiting timeout only
+};
+
+type AcquireResult =
+  | { ok: true; token: Token }
+  | { ok: false; reason: 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted' };
+```
 
-* admission accepted
-* queued
-* execution started
-* released
-* rejected
+`run(fn, options?)`
 
-Hooks are synchronous and side-effect–free by design.
+Throws on rejection:
+
+```ts
+class BulkheadRejectedError extends Error {
+  readonly code = 'BULKHEAD_REJECTED';
+  readonly reason: 'concurrency_limit' | 'queue_limit' | 'timeout' | 'aborted';
+}
+```
+
+The function passed to `run()` receives the same `AbortSignal` (if provided), allowing
+in-flight work to observe cancellation:
+
+```ts
+await bulkhead.run(async (signal) => doWork(signal), { signal });
+```
 
 ## Design Philosophy
 
@@ -171,6 +217,7 @@ If you need retries, buffering, scheduling, or persistence—compose those aroun
 * Node.js: 20+ (24 LTS recommended)
 * Module formats: ESM and CommonJS
 
+
 ## License
 
 MIT © 2026

package/dist/index.cjs

@@ -24,6 +24,47 @@ __export(index_exports, {
   createBulkhead: () => createBulkhead
 });
 module.exports = __toCommonJS(index_exports);
+var RingDeque = class {
+  buf;
+  head = 0;
+  tail = 0;
+  size = 0;
+  constructor(capacity) {
+    const cap = Math.max(4, capacity | 0);
+    this.buf = new Array(cap);
+  }
+  get length() {
+    return this.size;
+  }
+  pushBack(item) {
+    if (this.size === this.buf.length) {
+      this.grow();
+    }
+    const idx = (this.head + this.size) % this.buf.length;
+    this.buf[idx] = item;
+    this.size++;
+  }
+  peekFront() {
+    if (this.size === 0) return void 0;
+    return this.buf[this.head];
+  }
+  popFront() {
+    if (this.size === 0) return void 0;
+    const item = this.buf[this.head];
+    this.buf[this.head] = void 0;
+    this.head = (this.head + 1) % this.buf.length;
+    this.size--;
+    return item;
+  }
+  grow() {
+    const newBuf = new Array(this.buf.length * 2);
+    for (let i = 0; i < this.size; i++) {
+      newBuf[i] = this.buf[(this.head + i) % this.buf.length];
+    }
+    this.buf = newBuf;
+    this.head = 0;
+  }
+};
 var BulkheadRejectedError = class extends Error {
   constructor(reason) {
     super(`Bulkhead rejected: ${reason}`);
@@ -41,13 +82,11 @@ function createBulkhead(opts) {
     throw new Error("maxQueue must be an integer >= 0");
   }
   let inFlight = 0;
-  const q = [];
-  let qHead = 0;
+  const q = new RingDeque(maxQueue + 1);
   let aborted = 0;
   let timedOut = 0;
   let rejected = 0;
   let doubleRelease = 0;
-  const pendingCount = () => q.length - qHead;
   const makeToken = () => {
     let released = false;
     return {
@@ -63,26 +102,46 @@ function createBulkhead(opts) {
       }
     };
   };
+  const pruneCancelledFront = () => {
+    while (q.length > 0) {
+      const w = q.peekFront();
+      if (w.cancelled || w.settled) {
+        cleanupWaiter(w);
+        q.popFront();
+        continue;
+      } else {
+        break;
+      }
+    }
+  };
+  const pendingCount = () => {
+    pruneCancelledFront();
+    return q.length;
+  };
   const cleanupWaiter = (w) => {
     if (w.abortListener) w.abortListener();
     if (w.timeoutId) clearTimeout(w.timeoutId);
     w.abortListener = void 0;
     w.timeoutId = void 0;
   };
+  const settle = (w, r) => {
+    if (w.settled) return;
+    w.settled = true;
+    if (!w.cancelled && !r.ok) w.cancelled = true;
+    cleanupWaiter(w);
+    w.resolve(r);
+  };
   const drain = () => {
-    while (inFlight < opts.maxConcurrent && pendingCount() > 0) {
-      const w = q[qHead++];
+    pruneCancelledFront();
+    while (inFlight < opts.maxConcurrent && q.length > 0) {
+      const w = q.popFront();
       if (w.cancelled) {
         cleanupWaiter(w);
+        pruneCancelledFront();
         continue;
       }
       inFlight++;
-      cleanupWaiter(w);
-      w.resolve({ ok: true, token: makeToken() });
-    }
-    if (qHead > 1024 && qHead * 2 > q.length) {
-      q.splice(0, qHead);
-      qHead = 0;
+      settle(w, { ok: true, token: makeToken() });
     }
   };
   const tryAcquire = () => {
@@ -90,12 +149,7 @@ function createBulkhead(opts) {
       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" };
+    return { ok: false, reason: "concurrency_limit" };
   };
   const acquire = (ao = {}) => {
     if (inFlight < opts.maxConcurrent) {
@@ -114,22 +168,20 @@ function createBulkhead(opts) {
       const w = {
         resolve,
         cancelled: false,
+        settled: false,
         abortListener: void 0,
         timeoutId: void 0
       };
       if (ao.signal) {
         if (ao.signal.aborted) {
           aborted++;
-          resolve({ ok: false, reason: "aborted" });
+          settle(w, { ok: false, reason: "aborted" });
           return;
         }
         const onAbort = () => {
-          if (!w.cancelled) {
-            w.cancelled = true;
-            aborted++;
-            cleanupWaiter(w);
-            resolve({ ok: false, reason: "aborted" });
-          }
+          aborted++;
+          w.cancelled = true;
+          settle(w, { ok: false, reason: "aborted" });
         };
         ao.signal.addEventListener("abort", onAbort, { once: true });
         w.abortListener = () => ao.signal.removeEventListener("abort", onAbort);
@@ -137,19 +189,17 @@ function createBulkhead(opts) {
       if (ao.timeoutMs != null) {
         if (!Number.isFinite(ao.timeoutMs) || ao.timeoutMs < 0) {
           timedOut++;
-          resolve({ ok: false, reason: "timeout" });
+          settle(w, { ok: false, reason: "timeout" });
           return;
         }
         w.timeoutId = setTimeout(() => {
-          if (!w.cancelled) {
-            w.cancelled = true;
-            timedOut++;
-            cleanupWaiter(w);
-            resolve({ ok: false, reason: "timeout" });
-          }
+          timedOut++;
+          w.cancelled = true;
+          settle(w, { ok: false, reason: "timeout" });
         }, ao.timeoutMs);
       }
-      q.push(w);
+      q.pushBack(w);
+      drain();
     });
   };
   const run = async (fn, ao = {}) => {

package/dist/index.cjs.map

@@ -1 +1 @@
-{"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":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * A small ring-buffer queue.\n * - O(1) pushBack / popFront\n * - avoids array shift and head-index + compaction heuristics \n */\nclass RingDeque<T> {\n  private buf: Array<T | undefined>;\n  private head = 0;\n  private tail = 0;\n  private size = 0;\n\n  constructor(capacity: number) {\n    const cap = Math.max(4, capacity | 0);\n    this.buf = new Array<T | undefined>(cap);\n  }\n\n  get length() {\n    return this.size;\n  }\n\n  pushBack(item: T) {\n    if (this.size === this.buf.length) {\n      this.grow();\n    }\n    const idx = (this.head + this.size) % this.buf.length;\n    this.buf[idx] = item;\n    this.size++;\n  }\n\n  peekFront(): T | undefined {\n    if (this.size === 0) return undefined;\n    return this.buf[this.head];\n  }\n\n  popFront(): T | undefined {\n    if (this.size === 0) return undefined;\n    const item = this.buf[this.head];\n    this.buf[this.head] = undefined; // help GC\n    this.head = (this.head + 1) % this.buf.length;\n    this.size--;\n    return item;\n  }\n\n  private grow() {\n    const newBuf = new Array<T | undefined>(this.buf.length * 2);\n    for (let i = 0; i < this.size; i++) {\n      newBuf[i] = this.buf[(this.head + i) % this.buf.length];\n    }\n    this.buf = newBuf;\n    this.head = 0;\n  }\n}\n\nexport 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' };\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  settled: 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 deque (no head index, just pushBack / popFront)\n  const q = new RingDeque<Waiter>(maxQueue + 1); // +1 to avoid full queue edge case\n\n  // optional counters\n  let aborted = 0;\n  let timedOut = 0;\n  let rejected = 0;\n  let doubleRelease = 0;\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 pruneCancelledFront = () => {\n    // Remove cancelled/settled waiters at the front so they stop consuming maxQueue.\n    while (q.length > 0) {\n      const w = q.peekFront()!;\n      if (w.cancelled || w.settled) {\n        cleanupWaiter(w);\n        q.popFront();\n        continue;\n      } else {\n        break;\n      }\n    }\n  }\n\n  const pendingCount = () => {\n    pruneCancelledFront();\n    return q.length;\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  const settle = (w: Waiter, r: AcquireResult) => {\n    if (w.settled) return;\n    w.settled = true;\n    // Once settled, it's effectively cancelled for drain-skipping purposes.\n    // (We keep cancelled separate because drain checks it.)\n    if (!w.cancelled && !r.ok) w.cancelled = true;\n    cleanupWaiter(w);\n    w.resolve(r);\n  };\n\n  // ---- drain algorithm ----\n  const drain = () => {\n    // Prune first so cancelled/settled waiters don't block the head.\n    pruneCancelledFront();\n    while (inFlight < opts.maxConcurrent && q.length > 0) {\n      const w = q.popFront()!; \n      // If it was cancelled after peek/prune but before pop, skip it.\n      if (w.cancelled) {\n        cleanupWaiter(w);\n        pruneCancelledFront(); // in case there are more cancelled after this one\n        continue;\n      }\n      inFlight++;\n      settle(w, { ok: true, token: makeToken() });\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    return { ok: false, reason: '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        settled: false,\n        abortListener: undefined,\n        timeoutId: undefined,\n      };\n\n      // abort support\n      if (ao.signal) {\n        if (ao.signal.aborted) {\n          aborted++;\n          settle(w, { ok: false, reason: 'aborted' });\n          return;\n        }\n        const onAbort = () => {\n          // mark cancelled; drain() will skip it\n          aborted++;\n          w.cancelled = true;\n          settle(w, { 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          settle(w, { ok: false, reason: 'timeout' });\n          return;\n        }\n        w.timeoutId = setTimeout(() => {\n          timedOut++;\n          w.cancelled = true;\n          settle(w, { ok: false, reason: 'timeout' });\n        }, ao.timeoutMs);\n      }\n\n      q.pushBack(w);\n      drain(); // required: capacity may have freed after the fast-path check but before enqueue\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

@@ -24,7 +24,7 @@ type TryAcquireResult = {
     token: Token;
 } | {
     ok: false;
-    reason: 'concurrency_limit' | 'queue_limit';
+    reason: 'concurrency_limit';
 };
 type AcquireResult = {
     ok: true;

package/dist/index.d.ts

@@ -24,7 +24,7 @@ type TryAcquireResult = {
     token: Token;
 } | {
     ok: false;
-    reason: 'concurrency_limit' | 'queue_limit';
+    reason: 'concurrency_limit';
 };
 type AcquireResult = {
     ok: true;

package/dist/index.js

@@ -1,4 +1,45 @@
 // src/index.ts
+var RingDeque = class {
+  buf;
+  head = 0;
+  tail = 0;
+  size = 0;
+  constructor(capacity) {
+    const cap = Math.max(4, capacity | 0);
+    this.buf = new Array(cap);
+  }
+  get length() {
+    return this.size;
+  }
+  pushBack(item) {
+    if (this.size === this.buf.length) {
+      this.grow();
+    }
+    const idx = (this.head + this.size) % this.buf.length;
+    this.buf[idx] = item;
+    this.size++;
+  }
+  peekFront() {
+    if (this.size === 0) return void 0;
+    return this.buf[this.head];
+  }
+  popFront() {
+    if (this.size === 0) return void 0;
+    const item = this.buf[this.head];
+    this.buf[this.head] = void 0;
+    this.head = (this.head + 1) % this.buf.length;
+    this.size--;
+    return item;
+  }
+  grow() {
+    const newBuf = new Array(this.buf.length * 2);
+    for (let i = 0; i < this.size; i++) {
+      newBuf[i] = this.buf[(this.head + i) % this.buf.length];
+    }
+    this.buf = newBuf;
+    this.head = 0;
+  }
+};
 var BulkheadRejectedError = class extends Error {
   constructor(reason) {
     super(`Bulkhead rejected: ${reason}`);
@@ -16,13 +57,11 @@ function createBulkhead(opts) {
     throw new Error("maxQueue must be an integer >= 0");
   }
   let inFlight = 0;
-  const q = [];
-  let qHead = 0;
+  const q = new RingDeque(maxQueue + 1);
   let aborted = 0;
   let timedOut = 0;
   let rejected = 0;
   let doubleRelease = 0;
-  const pendingCount = () => q.length - qHead;
   const makeToken = () => {
     let released = false;
     return {
@@ -38,26 +77,46 @@ function createBulkhead(opts) {
       }
     };
   };
+  const pruneCancelledFront = () => {
+    while (q.length > 0) {
+      const w = q.peekFront();
+      if (w.cancelled || w.settled) {
+        cleanupWaiter(w);
+        q.popFront();
+        continue;
+      } else {
+        break;
+      }
+    }
+  };
+  const pendingCount = () => {
+    pruneCancelledFront();
+    return q.length;
+  };
   const cleanupWaiter = (w) => {
     if (w.abortListener) w.abortListener();
     if (w.timeoutId) clearTimeout(w.timeoutId);
     w.abortListener = void 0;
     w.timeoutId = void 0;
   };
+  const settle = (w, r) => {
+    if (w.settled) return;
+    w.settled = true;
+    if (!w.cancelled && !r.ok) w.cancelled = true;
+    cleanupWaiter(w);
+    w.resolve(r);
+  };
   const drain = () => {
-    while (inFlight < opts.maxConcurrent && pendingCount() > 0) {
-      const w = q[qHead++];
+    pruneCancelledFront();
+    while (inFlight < opts.maxConcurrent && q.length > 0) {
+      const w = q.popFront();
       if (w.cancelled) {
         cleanupWaiter(w);
+        pruneCancelledFront();
         continue;
       }
       inFlight++;
-      cleanupWaiter(w);
-      w.resolve({ ok: true, token: makeToken() });
-    }
-    if (qHead > 1024 && qHead * 2 > q.length) {
-      q.splice(0, qHead);
-      qHead = 0;
+      settle(w, { ok: true, token: makeToken() });
     }
   };
   const tryAcquire = () => {
@@ -65,12 +124,7 @@ function createBulkhead(opts) {
       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" };
+    return { ok: false, reason: "concurrency_limit" };
   };
   const acquire = (ao = {}) => {
     if (inFlight < opts.maxConcurrent) {
@@ -89,22 +143,20 @@ function createBulkhead(opts) {
       const w = {
         resolve,
         cancelled: false,
+        settled: false,
         abortListener: void 0,
         timeoutId: void 0
       };
       if (ao.signal) {
         if (ao.signal.aborted) {
           aborted++;
-          resolve({ ok: false, reason: "aborted" });
+          settle(w, { ok: false, reason: "aborted" });
           return;
         }
         const onAbort = () => {
-          if (!w.cancelled) {
-            w.cancelled = true;
-            aborted++;
-            cleanupWaiter(w);
-            resolve({ ok: false, reason: "aborted" });
-          }
+          aborted++;
+          w.cancelled = true;
+          settle(w, { ok: false, reason: "aborted" });
         };
         ao.signal.addEventListener("abort", onAbort, { once: true });
         w.abortListener = () => ao.signal.removeEventListener("abort", onAbort);
@@ -112,19 +164,17 @@ function createBulkhead(opts) {
       if (ao.timeoutMs != null) {
         if (!Number.isFinite(ao.timeoutMs) || ao.timeoutMs < 0) {
           timedOut++;
-          resolve({ ok: false, reason: "timeout" });
+          settle(w, { ok: false, reason: "timeout" });
           return;
         }
         w.timeoutId = setTimeout(() => {
-          if (!w.cancelled) {
-            w.cancelled = true;
-            timedOut++;
-            cleanupWaiter(w);
-            resolve({ ok: false, reason: "timeout" });
-          }
+          timedOut++;
+          w.cancelled = true;
+          settle(w, { ok: false, reason: "timeout" });
         }, ao.timeoutMs);
       }
-      q.push(w);
+      q.pushBack(w);
+      drain();
     });
   };
   const run = async (fn, ao = {}) => {

package/dist/index.js.map

@@ -1 +1 @@
-{"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":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * A small ring-buffer queue.\n * - O(1) pushBack / popFront\n * - avoids array shift and head-index + compaction heuristics \n */\nclass RingDeque<T> {\n  private buf: Array<T | undefined>;\n  private head = 0;\n  private tail = 0;\n  private size = 0;\n\n  constructor(capacity: number) {\n    const cap = Math.max(4, capacity | 0);\n    this.buf = new Array<T | undefined>(cap);\n  }\n\n  get length() {\n    return this.size;\n  }\n\n  pushBack(item: T) {\n    if (this.size === this.buf.length) {\n      this.grow();\n    }\n    const idx = (this.head + this.size) % this.buf.length;\n    this.buf[idx] = item;\n    this.size++;\n  }\n\n  peekFront(): T | undefined {\n    if (this.size === 0) return undefined;\n    return this.buf[this.head];\n  }\n\n  popFront(): T | undefined {\n    if (this.size === 0) return undefined;\n    const item = this.buf[this.head];\n    this.buf[this.head] = undefined; // help GC\n    this.head = (this.head + 1) % this.buf.length;\n    this.size--;\n    return item;\n  }\n\n  private grow() {\n    const newBuf = new Array<T | undefined>(this.buf.length * 2);\n    for (let i = 0; i < this.size; i++) {\n      newBuf[i] = this.buf[(this.head + i) % this.buf.length];\n    }\n    this.buf = newBuf;\n    this.head = 0;\n  }\n}\n\nexport 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' };\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  settled: 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 deque (no head index, just pushBack / popFront)\n  const q = new RingDeque<Waiter>(maxQueue + 1); // +1 to avoid full queue edge case\n\n  // optional counters\n  let aborted = 0;\n  let timedOut = 0;\n  let rejected = 0;\n  let doubleRelease = 0;\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 pruneCancelledFront = () => {\n    // Remove cancelled/settled waiters at the front so they stop consuming maxQueue.\n    while (q.length > 0) {\n      const w = q.peekFront()!;\n      if (w.cancelled || w.settled) {\n        cleanupWaiter(w);\n        q.popFront();\n        continue;\n      } else {\n        break;\n      }\n    }\n  }\n\n  const pendingCount = () => {\n    pruneCancelledFront();\n    return q.length;\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  const settle = (w: Waiter, r: AcquireResult) => {\n    if (w.settled) return;\n    w.settled = true;\n    // Once settled, it's effectively cancelled for drain-skipping purposes.\n    // (We keep cancelled separate because drain checks it.)\n    if (!w.cancelled && !r.ok) w.cancelled = true;\n    cleanupWaiter(w);\n    w.resolve(r);\n  };\n\n  // ---- drain algorithm ----\n  const drain = () => {\n    // Prune first so cancelled/settled waiters don't block the head.\n    pruneCancelledFront();\n    while (inFlight < opts.maxConcurrent && q.length > 0) {\n      const w = q.popFront()!; \n      // If it was cancelled after peek/prune but before pop, skip it.\n      if (w.cancelled) {\n        cleanupWaiter(w);\n        pruneCancelledFront(); // in case there are more cancelled after this one\n        continue;\n      }\n      inFlight++;\n      settle(w, { ok: true, token: makeToken() });\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    return { ok: false, reason: '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        settled: false,\n        abortListener: undefined,\n        timeoutId: undefined,\n      };\n\n      // abort support\n      if (ao.signal) {\n        if (ao.signal.aborted) {\n          aborted++;\n          settle(w, { ok: false, reason: 'aborted' });\n          return;\n        }\n        const onAbort = () => {\n          // mark cancelled; drain() will skip it\n          aborted++;\n          w.cancelled = true;\n          settle(w, { 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          settle(w, { ok: false, reason: 'timeout' });\n          return;\n        }\n        w.timeoutId = setTimeout(() => {\n          timedOut++;\n          w.cancelled = true;\n          settle(w, { ok: false, reason: 'timeout' });\n        }, ao.timeoutMs);\n      }\n\n      q.pushBack(w);\n      drain(); // required: capacity may have freed after the fast-path check but before enqueue\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.2.0",
+  "version": "0.2.2",
   "description": "Fail-fast admission control + bulkheads for async workloads",
   "license": "MIT",
   "type": "module",
@@ -10,19 +10,17 @@
   ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": {
-        "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       },
       "require": {
-        "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
     }
   },
+  "types": "./dist/index.d.ts",
   "engines": {
     "node": ">=20"
   },