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

npm install bulkhead

Uso

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