polly-ts-express

Express middleware for Polly-TS, enabling resilience policies on your API routes.

Installation

npm install polly-ts-core polly-ts-express
# or
pnpm add polly-ts-core polly-ts-express

Usage

Wrap your route handlers with the polly middleware to apply policies like Circuit Breaker, Bulkhead, or Timeout.

import express from 'express';
import { polly } from 'polly-ts-express';
import { CircuitBreakerPolicy } from 'polly-ts-core';

const app = express();
const breaker = new CircuitBreakerPolicy({
  failureThreshold: 3,
  breakDuration: 30000,
});

app.get(
  '/unstable-endpoint',
  // Stop processing requests if backend is failing involved
  polly(breaker),
  async (req, res) => {
    // ... risky operation ...
    res.send('Success');
  },
);

app.listen(3000);

Error Handling

If a policy rejects the request (e.g., Circuit Open, Timeout, Bulkhead Rejected), the middleware calls next(err). You should have a global error handler to format these errors appropriately.

import { CircuitOpenError } from 'polly-ts-core';

app.use((err, req, res, next) => {
  if (err instanceof CircuitOpenError) {
    res.status(503).send('Service Unavailable');
  } else {
    res.status(500).send('Internal Server Error');
  }
});

Examples

polly

const breaker = new CircuitBreakerPolicy({ failureThreshold: 3, breakDuration: 30000 });

app.get('/api/data', polly(breaker), async (req, res) => {
  res.json({ ok: true });
});

POLLY_CONTEXT

app.use((req, _res, next) => {
  req[POLLY_CONTEXT] = { operation: 'get-users' };
  next();
});

API Reference

| API | Kind | Description | Example | | --------------- | -------- | ----------------------------------------------------------------- | ------------------------------------------------- | | polly | Function | Express middleware that executes a request inside a Polly policy. | app.get('/path', polly(policy), handler); | | POLLY_CONTEXT | Constant | Symbol key for attaching Polly metadata to req. | req[POLLY_CONTEXT] = { operation: 'get-user' }; |