async-bulkhead-ts 0.1.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Balangue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# async-bulkhead-ts
+
+Fail-fast **admission control** and **bulkheads** for async workloads in Node.js.
+
+Designed for services that prefer **rejecting work early** over queueing and degrading under load.
+
+---
+
+## Features
+
+- ✅ **Fail-fast by default** (no hidden queues)
+- ✅ Simple **bulkhead / concurrency limits**
+- ✅ Explicit admission + release lifecycle
+- ✅ Zero dependencies
+- ✅ ESM + CJS support
+- ✅ Node.js **20+**
+
+Non-goals (by design):
+- ❌ No background workers
+- ❌ No retry logic
+- ❌ No distributed coordination
+- ❌ No metrics backend (hooks later)
+
+---
+
+## Install
+
+```bash
+npm install async-bulkhead-ts
+```
+
+## Basic Usage
+
+```ts
+import { createBulkhead } from 'async-bulkhead-ts';
+
+const bulkhead = createBulkhead({ maxConcurrent: 10 });
+const admission = bulkhead.admit();
+
+if (!admission.ok) {
+  // Fail fast — shed load, return 503, etc.
+  throw new Error('Service overloaded');
+}
+
+try {
+  // Do async work
+  await doWork();
+} finally {
+  admission.release();
+}
+```
+
+## With a Queue (Optional)
+
+Queues are opt-in and bounded.
+ ```ts
+const bulkhead = createBulkhead({
+  maxConcurrent: 10,
+  maxQueue: 20,
+});
+```
+
+If both concurrency and queue limits are exceeded, admission fails immediately.
+
+## API
+
+`createBulkhead(options)`
+
+```ts
+type BulkheadOptions = {
+  maxConcurrent: number;
+  maxQueue?: number;
+};
+```
+
+Returns:
+
+```json
+{
+  admit(): AdmitResult;
+  stats(): {
+    inFlight: number;
+    queued: number;
+    maxConcurrent: number;
+    maxQueue: number;
+  };
+}
+```
+
+`admit()`
+
+```ts
+type AdmitResult =
+  | { ok: true; release: () => void }
+  | { ok: false; reason: 'concurrency_limit' | 'queue_limit' };
+```
+
+You must call `release()` exactly once if admission succeeds.
+
+Failing to release will permanently reduce capacity.
+
+## Design Philosophy
+
+This library is intentionally small.
+
+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.
+
+## 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

@@ -0,0 +1,78 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createBulkhead: () => createBulkhead
+});
+module.exports = __toCommonJS(index_exports);
+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;
+  let inFlight = 0;
+  const queue = [];
+  const tryStartNext = () => {
+    while (inFlight < opts.maxConcurrent && queue.length > 0) {
+      const start = queue.shift();
+      inFlight++;
+      start();
+    }
+  };
+  const release = () => {
+    inFlight = Math.max(0, inFlight - 1);
+    tryStartNext();
+  };
+  const admit = () => {
+    if (inFlight < opts.maxConcurrent) {
+      inFlight++;
+      return { ok: true, release };
+    }
+    if (maxQueue > 0 && queue.length < maxQueue) {
+      let started = false;
+      const gate = () => {
+        started = true;
+      };
+      queue.push(gate);
+      return {
+        ok: true,
+        release: () => {
+          if (!started) {
+            const idx = queue.indexOf(gate);
+            if (idx >= 0) queue.splice(idx, 1);
+          } else {
+            release();
+          }
+        }
+      };
+    }
+    return { ok: false, reason: maxQueue > 0 ? "queue_limit" : "concurrency_limit" };
+  };
+  return {
+    admit,
+    stats: () => ({ inFlight, queued: queue.length, maxConcurrent: opts.maxConcurrent, maxQueue })
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createBulkhead
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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":[]}

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+type BulkheadOptions = {
+    maxConcurrent: number;
+    maxQueue?: number;
+};
+type AdmitResult = {
+    ok: true;
+    release: () => void;
+} | {
+    ok: false;
+    reason: "concurrency_limit" | "queue_limit";
+};
+declare function createBulkhead(opts: BulkheadOptions): {
+    admit: () => AdmitResult;
+    stats: () => {
+        inFlight: number;
+        queued: number;
+        maxConcurrent: number;
+        maxQueue: number;
+    };
+};
+
+export { type AdmitResult, type BulkheadOptions, createBulkhead };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+type BulkheadOptions = {
+    maxConcurrent: number;
+    maxQueue?: number;
+};
+type AdmitResult = {
+    ok: true;
+    release: () => void;
+} | {
+    ok: false;
+    reason: "concurrency_limit" | "queue_limit";
+};
+declare function createBulkhead(opts: BulkheadOptions): {
+    admit: () => AdmitResult;
+    stats: () => {
+        inFlight: number;
+        queued: number;
+        maxConcurrent: number;
+        maxQueue: number;
+    };
+};
+
+export { type AdmitResult, type BulkheadOptions, createBulkhead };

package/dist/index.js

@@ -0,0 +1,53 @@
+// src/index.ts
+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;
+  let inFlight = 0;
+  const queue = [];
+  const tryStartNext = () => {
+    while (inFlight < opts.maxConcurrent && queue.length > 0) {
+      const start = queue.shift();
+      inFlight++;
+      start();
+    }
+  };
+  const release = () => {
+    inFlight = Math.max(0, inFlight - 1);
+    tryStartNext();
+  };
+  const admit = () => {
+    if (inFlight < opts.maxConcurrent) {
+      inFlight++;
+      return { ok: true, release };
+    }
+    if (maxQueue > 0 && queue.length < maxQueue) {
+      let started = false;
+      const gate = () => {
+        started = true;
+      };
+      queue.push(gate);
+      return {
+        ok: true,
+        release: () => {
+          if (!started) {
+            const idx = queue.indexOf(gate);
+            if (idx >= 0) queue.splice(idx, 1);
+          } else {
+            release();
+          }
+        }
+      };
+    }
+    return { ok: false, reason: maxQueue > 0 ? "queue_limit" : "concurrency_limit" };
+  };
+  return {
+    admit,
+    stats: () => ({ inFlight, queued: queue.length, maxConcurrent: opts.maxConcurrent, maxQueue })
+  };
+}
+export {
+  createBulkhead
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "async-bulkhead-ts",
+  "version": "0.1.0",
+  "description": "Fail-fast admission control + bulkheads for async workloads",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "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"
+      }
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest",
+    "lint": "eslint .",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.9",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.53.1",
+    "vitest": "^4.0.17"
+  }
+}