Behavioral

Chain of Responsibility

Avoid coupling the sender of a request to its receiver by giving more than one object a chance to handle the request. Chain the receiving objects and pass the request along the chain until an object handles it.

Intent

Decouple the sender of a request from its receiver by allowing multiple objects to handle the request in sequence. Each handler decides either to process the request or to pass it along to the next handler in the chain.

Problem

You have a request that could be handled by several different objects, and you do not want the sender to know which specific object will handle it. Hard-coding the handler selection creates tight coupling and makes the system rigid when new handlers need to be added or the order needs to change.

Solution

Define a Handler interface with a method for processing requests and a reference to the next handler. Each ConcreteHandler either processes the request if it can, or forwards it to its successor. The client sends the request to the first handler in the chain without knowing which handler will ultimately process it. Handlers can be reordered, added, or removed without affecting the client.

Participants

Handler — defines the interface for handling requests and optionally holds a reference to the next handler
BaseHandler — optional abstract class that implements the default chaining behavior (forwarding to the next handler)
ConcreteHandler — handles requests it is responsible for; can access its successor to forward unhandled requests
Client — initiates the request to the first handler in the chain

Advantages

Reduces coupling — the sender does not need to know which handler processes the request
Flexible chain composition — handlers can be added, removed, or reordered at runtime
Each handler has a single responsibility, following the Single Responsibility Principle
A request can be handled by multiple handlers in sequence (middleware-style processing)

Disadvantages

No guarantee that a request will be handled — it may fall off the end of the chain
Debugging can be difficult because the flow passes through multiple objects
Chain configuration must be set up correctly; an incorrect order can produce wrong results
Performance may suffer with very long chains, as each handler adds overhead

Real-World Analogy

Calling a company's customer support hotline is a chain of responsibility. Your call goes to a front-line agent first. If they cannot resolve your issue, they escalate it to a specialist. If the specialist cannot help either, it goes to a manager. You, the caller, do not choose who handles your issue — you just enter the chain and each level decides whether to handle or escalate.

Use Cases

HTTP middleware pipelines — authentication, logging, CORS, rate limiting, compression
Validation chains — each validator checks one rule and passes to the next if valid
Support ticket routing — escalate from tier-1 to tier-2 to tier-3
Event bubbling in DOM — events propagate from child to parent elements
Approval workflows — manager, director, VP each have different authority levels
Exception handling — catch blocks form a chain that handles different exception types

Code Examples

chain-of-responsibility.ts

// Request object
interface Request {
  method: string;
  path: string;
  headers: Map<string, string>;
  clientIp: string;
}

// Handler interface
interface Handler {
  setNext(handler: Handler): Handler;
  handle(request: Request): Request | null;
}

// Abstract base handler with chaining logic
abstract class BaseHandler implements Handler {
  private next: Handler | null = null;

  setNext(handler: Handler): Handler {
    this.next = handler;
    return handler; // enables chaining: a.setNext(b).setNext(c)
  }

  handle(request: Request): Request | null {
    if (this.next) {
      return this.next.handle(request);
    }
    return request;
  }
}

// Checks for a valid Authorization header
class AuthHandler extends BaseHandler {
  handle(request: Request): Request | null {
    const auth = request.headers.get("Authorization");
    if (!auth) {
      console.log("[Auth] Rejected: missing Authorization header");
      return null; // stops the chain
    }
    console.log(`[Auth] Passed: token present for ${request.clientIp}`);
    return super.handle(request);
  }
}

// Tracks per-IP request counts and rejects above threshold
class RateLimitHandler extends BaseHandler {
  private counts = new Map<string, number>();
  private readonly limit = 100;

  handle(request: Request): Request | null {
    const count = (this.counts.get(request.clientIp) ?? 0) + 1;
    this.counts.set(request.clientIp, count);
    if (count > this.limit) {
      console.log(`[RateLimit] Rejected: ${request.clientIp} exceeded ${this.limit} requests`);
      return null;
    }
    console.log(`[RateLimit] Passed: ${request.clientIp} at ${count}/${this.limit}`);
    return super.handle(request);
  }
}

// Logs the request method and path, always passes through
class LoggingHandler extends BaseHandler {
  handle(request: Request): Request | null {
    console.log(`[Logging] ${request.method} ${request.path} from ${request.clientIp}`);
    return super.handle(request);
  }
}

// Build the chain: auth -> rateLimit -> logging
const auth = new AuthHandler();
const rateLimit = new RateLimitHandler();
const logging = new LoggingHandler();
auth.setNext(rateLimit).setNext(logging);

// Valid request — passes all handlers
console.log("--- Valid request ---");
const validReq: Request = {
  method: "GET",
  path: "/api/users",
  headers: new Map([["Authorization", "Bearer abc123"]]),
  clientIp: "192.168.1.10",
};
auth.handle(validReq);
// [Auth] Passed: token present for 192.168.1.10
// [RateLimit] Passed: 192.168.1.10 at 1/100
// [Logging] GET /api/users from 192.168.1.10

// Invalid request — rejected by AuthHandler
console.log("\n--- Invalid request ---");
const invalidReq: Request = {
  method: "POST",
  path: "/api/admin",
  headers: new Map(),
  clientIp: "10.0.0.5",
};
auth.handle(invalidReq);
// [Auth] Rejected: missing Authorization header

An HTTP middleware pipeline where AuthHandler, RateLimitHandler, and LoggingHandler each inspect the request and decide whether to pass it to the next handler or reject it.

Related Patterns