@felipe-lib/bulkhead 1.0.0

package/README.md

@@ -0,0 +1,70 @@
+# bulkhead
+
+**Student project** — Bulkhead pattern implementation for TypeScript. Limits concurrent executions and queues excess requests to prevent resource exhaustion.
+
+## Install
+
+```bash
+npm install bulkhead
+```
+
+## Usage
+
+```typescript
+import { Bulkhead } from "bulkhead";
+
+// Per-route instances for proper isolation
+const ordersApi = new Bulkhead<Order>(5, 10);
+const paymentsApi = new Bulkhead<Payment>(3, 5);
+
+// Example 1: basic usage
+async function getOrder(id: string): Promise<Order> {
+    return ordersApi.execute(() => fetch(`/orders/${id}`).then(r => r.json()));
+}
+
+// Example 2: with error handling
+async function processPayment(data: PaymentData): Promise<Payment> {
+    try {
+        return await paymentsApi.execute(() =>
+            fetch("/payments", {
+                method: "POST",
+                body: JSON.stringify(data),
+                headers: { "Content-Type": "application/json" },
+            }).then(r => r.json())
+        );
+    } catch (e) {
+        if (e instanceof Error && e.message === "Queue is full") {
+            console.error("Payment service busy — try again later");
+            // Fallback: return cached result or throw a friendly error
+        }
+        throw e;
+    }
+}
+
+// Example 3: concurrent requests — bulkhead limits automatically
+async function fetchAll(ids: string[]): Promise<Order[]> {
+    const results = await Promise.allSettled(
+        ids.map(id => getOrder(id))
+    );
+    return results
+        .filter((r): r is PromiseFulfilledResult<Order> => r.status === "fulfilled")
+        .map(r => r.value);
+}
+```
+
+## API
+
+### `new Bulkhead<T>(maxLimit, maxLimitQueue)`
+
+Creates a bulkhead instance.
+
+- `maxLimit` — max concurrent executions (must be > 0)
+- `maxLimitQueue` — max queue size (must be >= 0)
+
+### `bulkhead.execute(fn): Promise<T>`
+
+Executes `fn` immediately if under `maxLimit`. Otherwise queues the request and runs it as soon as a slot frees up. Throws `"Queue is full"` when both limits are reached.
+
+## License
+
+ISC

package/README.pt-BR.md

@@ -0,0 +1,70 @@
+# bulkhead
+
+**Projeto estudantil** — Implementação do padrão bulkhead para TypeScript. Limita execuções concorrentes e enfileira requisições excedentes para evitar esgotamento de recursos.
+
+## Instalação
+
+```bash
+npm install bulkhead
+```
+
+## Uso
+
+```typescript
+import { Bulkhead } from "bulkhead";
+
+// Instâncias por rota para isolamento adequado
+const ordersApi = new Bulkhead<Order>(5, 10);
+const paymentsApi = new Bulkhead<Payment>(3, 5);
+
+// Exemplo 1: uso básico
+async function getOrder(id: string): Promise<Order> {
+    return ordersApi.execute(() => fetch(`/orders/${id}`).then(r => r.json()));
+}
+
+// Exemplo 2: com tratamento de erro
+async function processPayment(data: PaymentData): Promise<Payment> {
+    try {
+        return await paymentsApi.execute(() =>
+            fetch("/payments", {
+                method: "POST",
+                body: JSON.stringify(data),
+                headers: { "Content-Type": "application/json" },
+            }).then(r => r.json())
+        );
+    } catch (e) {
+        if (e instanceof Error && e.message === "Queue is full") {
+            console.error("Serviço de pagamento ocupado — tente novamente mais tarde");
+            // Fallback: usar resultado em cache ou lançar erro amigável
+        }
+        throw e;
+    }
+}
+
+// Exemplo 3: requisições concorrentes — bulkhead limita automaticamente
+async function fetchAll(ids: string[]): Promise<Order[]> {
+    const results = await Promise.allSettled(
+        ids.map(id => getOrder(id))
+    );
+    return results
+        .filter((r): r is PromiseFulfilledResult<Order> => r.status === "fulfilled")
+        .map(r => r.value);
+}
+```
+
+## API
+
+### `new Bulkhead<T>(maxLimit, maxLimitQueue)`
+
+Cria uma instância do bulkhead.
+
+- `maxLimit` — máximo de execuções simultâneas (deve ser > 0)
+- `maxLimitQueue` — tamanho máximo da fila (deve ser >= 0)
+
+### `bulkhead.execute(fn): Promise<T>`
+
+Executa `fn` imediatamente se abaixo de `maxLimit`. Caso contrário, enfileira a requisição e executa assim que uma vaga for liberada. Lança `"Queue is full"` quando ambos os limites são atingidos.
+
+## Licença
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export declare class Bulkhead<T = unknown> {
+    private currentProcess;
+    private maxLimit;
+    private maxLimitQueue;
+    private queue;
+    constructor(maxLimit: number, maxLimitQueue: number);
+    execute(fetchPromise: () => Promise<T>): Promise<void | T>;
+    private resolveFetchers;
+    private processQueue;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,qBAAa,QAAQ,CAAC,CAAC,GAAG,OAAO;IAC7B,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,KAAK,CAAsB;IAEnC,YAAY,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAGlD;IAEY,OAAO,CAAC,YAAY,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,qBAiBlD;YAEa,eAAe;YAgBf,YAAY;CAY7B"}

package/dist/index.js

@@ -0,0 +1,58 @@
+export class Bulkhead {
+    currentProcess = 0;
+    maxLimit = 10;
+    maxLimitQueue = 10;
+    queue = [];
+    constructor(maxLimit, maxLimitQueue) {
+        this.maxLimit = maxLimit;
+        this.maxLimitQueue = maxLimitQueue;
+    }
+    async execute(fetchPromise) {
+        if (this.currentProcess < this.maxLimit) {
+            return await this.resolveFetchers({ fnFetch: fetchPromise });
+        }
+        else if (this.currentProcess >= this.maxLimit &&
+            this.queue.length < this.maxLimitQueue) {
+            return new Promise((resolve, reject) => {
+                this.queue.push({
+                    fnFetch: fetchPromise,
+                    fnReject: reject,
+                    fnResolve: resolve,
+                });
+            });
+        }
+        else {
+            throw new Error("Queue is full");
+        }
+    }
+    async resolveFetchers(item) {
+        this.currentProcess++;
+        try {
+            const data = await item.fnFetch();
+            if (item?.fnResolve)
+                item.fnResolve(data);
+            return data;
+        }
+        catch (e) {
+            if (item?.fnReject)
+                return item.fnReject(e);
+            throw e;
+        }
+        finally {
+            this.currentProcess--;
+            await this.processQueue();
+        }
+    }
+    async processQueue() {
+        if (this.queue.length > 0 && this.currentProcess < this.maxLimit) {
+            const item = this.queue.shift();
+            if (item)
+                return await this.resolveFetchers({
+                    fnFetch: item.fnFetch,
+                    fnReject: item.fnReject,
+                    fnResolve: item.fnResolve,
+                });
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,QAAQ;IACT,cAAc,GAAW,CAAC,CAAC;IAC3B,QAAQ,GAAW,EAAE,CAAC;IACtB,aAAa,GAAW,EAAE,CAAC;IAC3B,KAAK,GAAmB,EAAE,CAAC;IAEnC,YAAY,QAAgB,EAAE,aAAqB;QAC/C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACvC,CAAC;IAEM,KAAK,CAAC,OAAO,CAAC,YAA8B;QAC/C,IAAI,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtC,OAAO,MAAM,IAAI,CAAC,eAAe,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;QACjE,CAAC;aAAM,IACH,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,QAAQ;YACpC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,aAAa,EACxC,CAAC;YACC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACtC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;oBACZ,OAAO,EAAE,YAAY;oBACrB,QAAQ,EAAE,MAAM;oBAChB,SAAS,EAAE,OAAO;iBACrB,CAAC,CAAC;YACP,CAAC,CAAC,CAAC;QACP,CAAC;aAAM,CAAC;YACJ,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;QACrC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,eAAe,CAAC,IAAkB;QAC5C,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,IAAI,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,IAAI,EAAE,SAAS;gBAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAE1C,OAAO,IAAI,CAAC;QAChB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,IAAI,IAAI,EAAE,QAAQ;gBAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC5C,MAAM,CAAC,CAAC;QACZ,CAAC;gBAAS,CAAC;YACP,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QAC9B,CAAC;IACL,CAAC;IACO,KAAK,CAAC,YAAY;QACtB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YAEhC,IAAI,IAAI;gBACJ,OAAO,MAAM,IAAI,CAAC,eAAe,CAAC;oBAC9B,OAAO,EAAE,IAAI,CAAC,OAAO;oBACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,SAAS,EAAE,IAAI,CAAC,SAAS;iBAC5B,CAAC,CAAC;QACX,CAAC;IACL,CAAC;CACJ"}

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+export interface QueueItem<T = unknown> {
+    fnFetch: () => Promise<T>;
+    fnReject?: (reason?: any) => void;
+    fnResolve?: (value: T | PromiseLike<T>) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IAClC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CACnD"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,33 @@
+{
+    "name": "@felipe-lib/bulkhead",
+    "version": "1.0.0",
+    "description": "Bulkhead pattern implementation for TypeScript",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "bulkhead",
+        "resilience",
+        "concurrency",
+        "typescript"
+    ],
+    "author": "",
+    "license": "ISC",
+    "packageManager": "npm@11.16.0",
+    "devDependencies": {
+        "typescript": "^7.0.2"
+    }
+}