alien-middleware 0.9.0 → 0.10.0

package/dist/{chunk-OH7VM54L.js → chunk-BBMRIHZ5.js}

@@ -21,19 +21,25 @@ function defineParsedURL(context) {
   }
 }
 
+// src/middleware/filterPlatform.ts
+function filterPlatform(name) {
+  return function(ctx) {
+    if (ctx.platform.name !== name) {
+      return ctx.passThrough();
+    }
+    return null;
+  };
+}
+
 // src/index.ts
 var kRequestChain = Symbol("requestChain");
-var kResponseChain = Symbol("responseChain");
 var kIgnoreNotFound = Symbol("ignoreNotFound");
 var kMiddlewareCache = Symbol("middlewareCache");
 var kResponseHeaders = Symbol("responseHeaders");
 var MiddlewareChain = class _MiddlewareChain {
   [kRequestChain] = [];
-  [kResponseChain] = [];
   /**
-   * Attach a middleware. If the `response` parameter is declared, it will be
-   * treated as a response middleware. Otherwise, it will be treated as a
-   * request middleware.
+   * Add a request middleware to the end of the chain.
    *
    * If a middleware chain is given, its middlewares will be executed after any
    * existing middlewares in this chain.
@@ -41,20 +47,9 @@ var MiddlewareChain = class _MiddlewareChain {
    * @returns a new `MiddlewareChain` instance
    */
   use(middleware) {
-    if (middleware instanceof _MiddlewareChain) {
-      return createHandler(
-        [...this[kRequestChain], ...middleware[kRequestChain]],
-        [...this[kResponseChain], ...middleware[kResponseChain]]
-      );
-    }
-    let requestChain = this[kRequestChain];
-    let responseChain = this[kResponseChain];
-    if (middleware.length < 2) {
-      requestChain = [...requestChain, middleware];
-    } else {
-      responseChain = [...responseChain, middleware];
-    }
-    return createHandler(requestChain, responseChain);
+    return createHandler(
+      middleware instanceof _MiddlewareChain ? [...this[kRequestChain], ...middleware[kRequestChain]] : [...this[kRequestChain], middleware]
+    );
   }
   /**
    * Create a middleware function that encapsulates this middleware chain, so
@@ -64,7 +59,7 @@ var MiddlewareChain = class _MiddlewareChain {
     return isFunction(this) ? (ctx) => this(ctx) : noop;
   }
 };
-function createHandler(requestChain, responseChain) {
+function createHandler(requestChain) {
   async function handler(parentContext) {
     const context = Object.create(parentContext);
     context[kIgnoreNotFound] = true;
@@ -80,7 +75,13 @@ function createHandler(requestChain, responseChain) {
       }
       context[kResponseHeaders].set(name, value);
     };
-    const cache = context[kMiddlewareCache] ||= /* @__PURE__ */ new Set();
+    const responseChain = [];
+    context.onResponse = (callback) => {
+      responseChain.push(callback);
+    };
+    const cache = context[kMiddlewareCache] = new Set(
+      parentContext[kMiddlewareCache]
+    );
     let response;
     let env;
     for (const middleware of requestChain) {
@@ -102,11 +103,17 @@ function createHandler(requestChain, responseChain) {
         }
         for (const key in result) {
           if (key === "env") {
-            env ||= createExtendedEnv(context);
-            Object.defineProperties(
-              env,
-              Object.getOwnPropertyDescriptors(result.env)
-            );
+            if (result.env) {
+              env ||= createExtendedEnv(context);
+              Object.defineProperties(
+                env,
+                Object.getOwnPropertyDescriptors(result.env)
+              );
+            }
+          } else if (key === "onResponse") {
+            if (result.onResponse) {
+              responseChain.push(result.onResponse);
+            }
           } else {
             const descriptor = Object.getOwnPropertyDescriptor(result, key);
             descriptor.configurable = false;
@@ -131,16 +138,12 @@ function createHandler(requestChain, responseChain) {
       response.headers.set(name, value);
     });
     context.setHeader = null;
-    for (const middleware of responseChain) {
-      if (cache.has(middleware)) {
-        continue;
-      }
-      cache.add(middleware);
-      let result = middleware(context, response);
+    for (const plugin of responseChain) {
+      let result = plugin(response);
       if (result instanceof Promise) {
         result = await result;
       }
-      if (result && result instanceof Response) {
+      if (result) {
         response = result;
         continue;
       }
@@ -149,7 +152,6 @@ function createHandler(requestChain, responseChain) {
   }
   Object.setPrototypeOf(handler, MiddlewareChain.prototype);
   handler[kRequestChain] = requestChain;
-  handler[kResponseChain] = responseChain;
   return handler;
 }
 function createExtendedEnv(context) {
@@ -170,6 +172,7 @@ export {
   isArray,
   isFunction,
   defineParsedURL,
+  filterPlatform,
   MiddlewareChain,
   chain
 };

package/dist/{index-vRvlpUCy.d.ts → index-B3m3gxNA.d.ts}

@@ -1,4 +1,3 @@
-import { Any, noop } from 'radashi';
 import { AdapterRequestContext, HattipHandler } from '@hattip/core';
 import { InferParams } from 'pathic';
 
@@ -7,10 +6,7 @@ type Eval<T> = {} & {
 };
 type Awaitable<T> = T | Promise<T>;
 type OneOrMany<T> = T | readonly T[];
-/**
- * Converts a type `T` to something that can be intersected with an object.
- */
-type Intersectable<T extends object> = [T] extends [never] ? {} : [T] extends [Any] ? Record<PropertyKey, any> : T;
+type CastNever<T, U> = [T] extends [never] ? U : T;
 
 type Keys<T> = T extends any ? keyof T : never;
 type IsOptional<T, K> = K extends keyof T ? T[K] extends Required<T>[K] ? false : true : true;
@@ -21,16 +17,20 @@ type MergeProperty<TSource, TOverrides, K> = (K extends keyof TOverrides ? Possi
  *
  * **FIXME:** Optional properties resolve as `foo: Foo | undefined` instead of `foo?: Foo`.
  */
-type Merge<TSource extends object, TOverrides extends object | undefined> = Eval<Omit<TSource, Keys<TOverrides>> & {
-    [K in Keys<TOverrides>]: TOverrides extends any ? MergeProperty<TSource, TOverrides, K> : never;
+type Merge<TSource extends object, TOverrides extends object | undefined> = Eval<Omit<CastNever<TSource, {}>, Keys<TOverrides>> & {
+    [K in Keys<TOverrides>]: TOverrides extends any ? MergeProperty<CastNever<TSource, {}>, TOverrides, K> : never;
 }>;
 
-type RequestEnvPlugin = {
+type ReservedProperties = {
     /**
      * Add type-safe environment variables. These are accessed with the `env()`
      * method on the request context.
      */
     env?: object;
+    /**
+     * Intercept the response before it's sent to the client.
+     */
+    onResponse?: ResponseCallback;
 };
 /**
  * The object returned by a request middleware that is merged into the request
@@ -40,7 +40,7 @@ type RequestEnvPlugin = {
  * May contain special properties:
  * - `env`: Add type-safe environment variables.
  */
-type RequestPlugin = Record<string, unknown> & RequestEnvPlugin;
+type RequestPlugin = Record<string, unknown> & ReservedProperties;
 type MiddlewareTypes = {
     /** Values expected by the start of the chain. */
     initial: {
@@ -67,27 +67,38 @@ type AnyMiddlewareTypes = {
     platform: any;
 };
 type AnyMiddlewareChain = MiddlewareChain<AnyMiddlewareTypes>;
-type Inputs<T extends AnyMiddlewareChain> = T['$']['initial'];
+type Inputs<T extends AnyMiddlewareChain> = T['$MiddlewareChain']['initial'];
 type InputProperties<T extends AnyMiddlewareChain> = Inputs<T>['properties'];
 type InputEnv<T extends AnyMiddlewareChain> = Inputs<T>['env'];
-type Current<T extends AnyMiddlewareChain> = T['$']['current'];
+type Current<T extends AnyMiddlewareChain> = T['$MiddlewareChain']['current'];
 type Properties<T extends AnyMiddlewareChain> = Current<T>['properties'];
 type Env<T extends AnyMiddlewareChain> = Current<T>['env'];
-type Platform<T extends AnyMiddlewareChain> = T['$']['platform'];
+type Platform<T extends AnyMiddlewareChain> = T['$MiddlewareChain']['platform'];
+/**
+ * The `context.env` method used to access environment variables.
+ */
+type EnvAccessor<TEnv extends object> = {
+    <K extends keyof TEnv>(key: Extract<K, string>): TEnv[K];
+    (key: never): string | undefined;
+};
 interface HattipContext<TPlatform, TEnv extends object> extends AdapterRequestContext<TPlatform> {
+    env: EnvAccessor<TEnv>;
+    passThrough(): never;
     /**
      * The `request.url` string parsed into a `URL` object. Parsing is performed
      * on-demand and the result is cached.
      */
     url: URL;
-    env<K extends keyof TEnv>(key: Extract<K, string>): TEnv[K];
-    env(key: never): string | undefined;
     /**
      * Set a response header from a request middleware.
      *
      * Response middlewares should use `response.headers.set()` instead.
      */
     setHeader(name: string, value: string): void;
+    /**
+     * Add a callback to be called when a response is generated.
+     */
+    onResponse(callback: ResponseCallback): void;
 }
 /**
  * An extensible Hattip context object.
@@ -96,7 +107,7 @@ interface HattipContext<TPlatform, TEnv extends object> extends AdapterRequestCo
  * should prefer `RequestContext<any>` over `RequestContext` (no type
  * parameters), as the default type is stricter.
  */
-type RequestContext<TEnv extends object = any, TProperties extends object = never, TPlatform = any> = HattipContext<TPlatform, TEnv> & Intersectable<TProperties>;
+type RequestContext<TEnv extends object = any, TProperties extends object = never, TPlatform = any> = HattipContext<TPlatform, TEnv> & CastNever<TProperties, unknown>;
 /**
  * Extract a `RequestContext` type from a `MiddlewareChain` type.
  *
@@ -105,7 +116,7 @@ type RequestContext<TEnv extends object = any, TProperties extends object = neve
 type MiddlewareContext<T extends MiddlewareChain> = [T] extends [never] ? RequestContext<{}, never, unknown> : RequestContext<Env<T>, Properties<T>, Platform<T>>;
 type IsolatedContext<T extends MiddlewareChain> = RequestContext<InputProperties<T>, InputEnv<T>, Platform<T>>;
 type RequestMiddleware<T extends MiddlewareChain = MiddlewareChain> = (context: RequestContext<InputProperties<T>, InputEnv<T>, Platform<T>>) => Awaitable<Response | RequestPlugin | void>;
-type ResponseMiddleware<T extends MiddlewareChain = MiddlewareChain> = (context: RequestContext<InputProperties<T>, InputEnv<T>, Platform<T>>, response: Response) => Awaitable<Response | void>;
+type ResponseCallback = (response: Response) => Awaitable<Response | void>;
 interface RequestHandler<T extends MiddlewareTypes = any> extends HattipHandler<T['platform']>, MiddlewareChain<T> {
 }
 /**
@@ -115,11 +126,20 @@ interface RequestHandler<T extends MiddlewareTypes = any> extends HattipHandler<
  * response middleware. This means it will run *after* a `Response` is generated
  * by a request middleware.
  */
-type Middleware<TEnv extends object = any, TProperties extends object = any, TPlatform = any> = (context: RequestContext<TEnv, TProperties, TPlatform>, response: Response) => Awaitable<Response | RequestPlugin | void>;
+type Middleware<TEnv extends object = any, TProperties extends object = any, TPlatform = any> = {
+    (context: RequestContext<TEnv, TProperties, TPlatform>): Awaitable<Response | RequestPlugin | void>;
+    /** This property won't exist at runtime. It contains type information for inference purposes. */
+    $Middleware?: MiddlewareTypes & {
+        initial: {
+            env: TEnv;
+            properties: TProperties;
+        };
+    };
+};
 /**
  * Extract a `Middleware` type from a `MiddlewareChain` type.
  */
-type ExtractMiddleware<T extends MiddlewareChain> = Middleware<Env<T>, Properties<T>, Platform<T>>;
+type ExtractMiddleware<T extends MiddlewareChain> = [T] extends [never] ? Middleware<{}, {}, any> : Middleware<Env<T>, Properties<T>, Platform<T>>;
 /**
  * Merge a request plugin into a middleware chain.
  */
@@ -127,22 +147,38 @@ type ApplyMiddlewareResult<TParent extends MiddlewareChain, TResult> = Eval<{
     env: Merge<Env<TParent>, TResult extends {
         env: infer TEnv extends object | undefined;
     } ? TEnv : undefined>;
-    properties: Merge<Properties<TParent>, TResult extends RequestPlugin ? Omit<TResult, keyof RequestEnvPlugin> : undefined>;
+    properties: Merge<Properties<TParent>, TResult extends RequestPlugin ? Omit<TResult, keyof ReservedProperties> : undefined>;
 }>;
+type ApplyMiddlewareOutputs<TFirst extends MiddlewareChain, TSecond extends Middleware> = TSecond extends MiddlewareChain ? {
+    env: Merge<Env<TFirst>, Env<TSecond>>;
+    properties: Merge<Properties<TFirst>, Properties<TSecond>>;
+} : TSecond extends (...args: any[]) => Awaitable<infer TResult> ? ApplyMiddlewareResult<TFirst, Exclude<TResult, Response>> : Current<TFirst>;
+type MiddlewareInputs<T extends Middleware> = T extends Middleware<infer TEnv, infer TProperties> ? {
+    env: TEnv;
+    properties: TProperties;
+} : never;
+type MiddlewarePlatform<T extends Middleware> = T extends Middleware<any, any, infer TPlatform> ? TPlatform : never;
 /**
  * This applies a middleware to a chain. If the type `TMiddleware` is itself a
  * chain, it's treated as a nested chain, which won't leak its plugins into the
  * parent chain.
+ *
+ * The `TFirst` type is allowed to be `never`, which results in the middleware's
+ * output types being used as the request handler's input types.
  */
-type ApplyMiddleware<TFirst extends MiddlewareChain, TSecond extends Middleware<Env<TFirst>, Properties<TFirst>, Platform<TFirst>>> = (TSecond extends MiddlewareChain ? {
-    env: Merge<Env<TFirst>, Env<TSecond>>;
-    properties: Merge<Properties<TFirst>, Properties<TSecond>>;
-} : TSecond extends (...args: any[]) => Awaitable<infer TResult> ? ApplyMiddlewareResult<TFirst, TResult> : Current<TFirst>) extends infer TOutputs extends MiddlewareTypes['current'] ? RequestHandler<{
-    initial: Inputs<TFirst>;
-    current: TOutputs;
-    platform: Platform<TFirst>;
+type ApplyMiddleware<TFirst extends MiddlewareChain, TSecond extends Middleware> = ApplyMiddlewareOutputs<TFirst, TSecond> extends infer TCurrent extends MiddlewareTypes['current'] ? RequestHandler<{
+    initial: CastNever<Inputs<TFirst>, MiddlewareInputs<TSecond>>;
+    current: TCurrent;
+    platform: CastNever<Platform<TFirst>, MiddlewarePlatform<TSecond>>;
 }> : never;
-type EmptyMiddlewareChain = MiddlewareChain<{
+/**
+ * Apply a list of middlewares to an empty middleware chain.
+ */
+type ApplyMiddlewares<T extends Middleware[]> = T extends [
+    ...infer TRest extends Middleware[],
+    infer TLast extends Middleware
+] ? ApplyMiddleware<ApplyMiddlewares<TRest>, TLast> : ApplyFirstMiddleware<T[0]>;
+type EmptyMiddlewareChain<TPlatform = unknown> = MiddlewareChain<{
     initial: {
         env: {};
         properties: {};
@@ -151,18 +187,18 @@ type EmptyMiddlewareChain = MiddlewareChain<{
         env: {};
         properties: {};
     };
-    platform: unknown;
+    platform: TPlatform;
 }>;
-type ApplyFirstMiddleware<T extends Middleware> = T extends MiddlewareChain ? T : ApplyMiddleware<EmptyMiddlewareChain, T>;
+type ApplyFirstMiddleware<T extends Middleware> = T extends MiddlewareChain ? T : ApplyMiddleware<EmptyMiddlewareChain<MiddlewarePlatform<T>>, T>;
 type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | (string & {});
-type RouteContext<T extends RouterTypes = any, TPathParams extends object = any, TMethod extends RouteMethod = RouteMethod> = MiddlewareContext<ApplyMiddleware<MiddlewareChain<T['$']>, () => {
+type RouteContext<T extends RouterTypes = any, TPathParams extends object = any, TMethod extends RouteMethod = RouteMethod> = MiddlewareContext<ApplyMiddleware<MiddlewareChain<T['$Router']>, () => {
     params: TPathParams;
     method: TMethod;
 }>>;
 type RouteHandler<T extends RouterTypes = any, TPathParams extends object = any, TMethod extends RouteMethod = RouteMethod> = (context: RouteContext<T, TPathParams, TMethod>) => Awaitable<Response | void>;
 declare class RouterTypes<T extends MiddlewareChain = any> extends Function {
     /** This property won't exist at runtime. It contains type information for inference purposes. */
-    $: T['$'];
+    $Router: T['$MiddlewareChain'];
 }
 interface Router<T extends MiddlewareChain = any> extends RouterTypes<T> {
     (context: AdapterRequestContext<Platform<T>>): Awaitable<void | Response>;
@@ -170,19 +206,21 @@ interface Router<T extends MiddlewareChain = any> extends RouterTypes<T> {
     use<TPath extends string, TMethod extends RouteMethod = RouteMethod>(method: OneOrMany<TMethod> | '*', path: TPath, handler: RouteHandler<this, InferParams<TPath>, TMethod>): Router;
 }
 
+declare function filterPlatform<TPlatform extends {
+    name: string;
+}>(name: TPlatform['name']): (ctx: RequestContext) => {
+    platform: TPlatform;
+};
+
 declare const kRequestChain: unique symbol;
-declare const kResponseChain: unique symbol;
 declare class MiddlewareChain<T extends MiddlewareTypes = any> {
     /** This property won't exist at runtime. It contains type information for inference purposes. */
-    $: T;
+    $MiddlewareChain: T;
     /** The number of parameters when called as a function. */
     readonly length: 1;
     protected [kRequestChain]: RequestMiddleware[];
-    protected [kResponseChain]: ResponseMiddleware[];
     /**
-     * Attach a middleware. If the `response` parameter is declared, it will be
-     * treated as a response middleware. Otherwise, it will be treated as a
-     * request middleware.
+     * Add a request middleware to the end of the chain.
      *
      * If a middleware chain is given, its middlewares will be executed after any
      * existing middlewares in this chain.
@@ -194,7 +232,7 @@ declare class MiddlewareChain<T extends MiddlewareTypes = any> {
      * Create a middleware function that encapsulates this middleware chain, so
      * any modifications it makes to the request context are not leaked.
      */
-    isolate(): ((ctx: IsolatedContext<this>) => Promise<Response | void>) | typeof noop;
+    isolate(): (ctx: IsolatedContext<this>) => Awaitable<Response | void>;
 }
 declare function chain<TEnv extends object = {}, TProperties extends object = {}, TPlatform = unknown>(): MiddlewareChain<{
     initial: {
@@ -207,6 +245,6 @@ declare function chain<TEnv extends object = {}, TProperties extends object = {}
     };
     platform: TPlatform;
 }>;
-declare function chain<const T extends Middleware = Middleware>(middleware: T): ApplyFirstMiddleware<T>;
+declare function chain<const T extends Middleware = Middleware<{}, {}, unknown>>(middleware: T): ApplyFirstMiddleware<T>;
 
-export { type ApplyMiddleware as A, type EmptyMiddlewareChain as E, type MiddlewareContext as M, type Router as R, MiddlewareChain as a, type RouteContext as b, type RouteHandler as c, chain as d, type ExtractMiddleware as e, type Middleware as f, type RequestContext as g, type RequestHandler as h, type RequestMiddleware as i, type RequestPlugin as j, type ResponseMiddleware as k };
+export { type ApplyMiddleware as A, type EmptyMiddlewareChain as E, type MiddlewareContext as M, type Router as R, MiddlewareChain as a, type RouteContext as b, type RouteHandler as c, chain as d, type ApplyMiddlewares as e, filterPlatform as f, type EnvAccessor as g, type ExtractMiddleware as h, type Middleware as i, type RequestContext as j, type RequestHandler as k, type RequestMiddleware as l, type RequestPlugin as m, type ResponseCallback as n };

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import 'radashi';
-export { A as ApplyMiddleware, e as ExtractMiddleware, f as Middleware, a as MiddlewareChain, M as MiddlewareContext, g as RequestContext, h as RequestHandler, i as RequestMiddleware, j as RequestPlugin, k as ResponseMiddleware, d as chain } from './index-vRvlpUCy.js';
+export { A as ApplyMiddleware, e as ApplyMiddlewares, g as EnvAccessor, h as ExtractMiddleware, i as Middleware, a as MiddlewareChain, M as MiddlewareContext, j as RequestContext, k as RequestHandler, l as RequestMiddleware, m as RequestPlugin, n as ResponseCallback, d as chain, f as filterPlatform } from './index-B3m3gxNA.js';
 import '@hattip/core';
 import 'pathic';

package/dist/index.js

@@ -1,8 +1,10 @@
 import {
   MiddlewareChain,
-  chain
-} from "./chunk-OH7VM54L.js";
+  chain,
+  filterPlatform
+} from "./chunk-BBMRIHZ5.js";
 export {
   MiddlewareChain,
-  chain
+  chain,
+  filterPlatform
 };

package/dist/router.d.ts

@@ -1,6 +1,5 @@
-import { R as Router, M as MiddlewareContext, a as MiddlewareChain, E as EmptyMiddlewareChain } from './index-vRvlpUCy.js';
-export { b as RouteContext, c as RouteHandler } from './index-vRvlpUCy.js';
-import 'radashi';
+import { R as Router, M as MiddlewareContext, a as MiddlewareChain, E as EmptyMiddlewareChain } from './index-B3m3gxNA.js';
+export { b as RouteContext, c as RouteHandler } from './index-B3m3gxNA.js';
 import '@hattip/core';
 import 'pathic';
 

package/dist/router.js

@@ -3,7 +3,7 @@ import {
   defineParsedURL,
   isArray,
   isFunction
-} from "./chunk-OH7VM54L.js";
+} from "./chunk-BBMRIHZ5.js";
 
 // src/router.ts
 import { compilePaths } from "pathic";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "alien-middleware",
   "type": "module",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",

package/readme.md

@@ -4,9 +4,17 @@ Reusable middleware chains with top-notch TypeScript support. Built upon [Hattip
 
 ## Philosophy
 
-By default, middlewares in `alien-middleware` are **synchronous** or **promise-based**. There is no `next()` function to call. If a middleware returns a `Response`, the chain is terminated. If a middleware wants to extend the request context, it returns an object implementing the `RequestPlugin` interface.
+alien-middleware is built on a few key principles:
 
-Middlewares are either **request-oriented** (the default) or **response-oriented**. Response-oriented middlewares run _after_ a `Response` has been generated. They're allowed to return a new `Response`, but cannot return a `RequestPlugin` object.
+1. **Best-in-class TypeScript support** - Type safety is a first-class citizen. The library provides strong type inference for middleware chains, context extensions, and environment variables.
+
+2. **Web Standards** - Built on standard Web APIs like `Request` and `Response`, allowing you to write idiomatic code that follows established patterns and conventions.
+
+3. **No vendor lock-in** - Thanks to Hattip's adapter system, your middleware can run anywhere: Node.js, Deno, Bun, Cloudflare Workers, and more.
+
+4. **Linear middleware flow** - Unlike Express-style middleware, there's no `next()` function to call. Middleware either returns a `Response` (ending the chain) or doesn't (continuing to the next middleware). This makes the flow easier to reason about and eliminates common bugs like forgetting to call `next()`.
+
+5. **Immutable chains** - Middleware chains are immutable, making them easier to compose, extend, and reason about.
 
 ## Quick Start
 
@@ -34,7 +42,7 @@ const appWithInitial = chain(context => {
 
 ### Adding Middleware with `.use()`
 
-Use the `.use()` method to add middleware functions to the chain. Each call to `.use()` returns a _new_, immutable chain instance.
+Use the `.use()` method to add middleware functions to the chain.
 
 ```typescript
 import type { RequestContext } from 'alien-middleware'
@@ -156,35 +164,44 @@ Request middleware runs sequentially before a `Response` is generated.
 > `.use(…)` call expression, since that requires you to unnecessarily declare
 > the type of the context object. It's better to define them inline.
 
-### Response Middleware
+### Response Callbacks
+
+Request middleware can register a _response callback_ to receive the `Response` object. This is done by either returning an `onResponse` method or by calling `context.onResponse(callback)`. Response callbacks may return a new `Response` object.
 
-Response middleware runs _after_ a `Response` has been generated by a request middleware or the final handler. It receives both the context and the generated `Response`.
+Response callbacks are called even if none of your middlewares generate a `Response`. In this case, they receive the default `404 Not Found` response. Note that [isolated middleware chains](#isolating-a-middleware-chain) are an exception to this rule, since a default response is not generated for them.
 
 ```typescript
-const poweredByMiddleware = (context: RequestContext, response: Response) => {
-  response.headers.set('X-Powered-By', 'alien-middleware')
-}
+// Approach 1: Returning an `onResponse` method
+const poweredByMiddleware = (context: RequestContext) => ({
+  onResponse(response) {
+    response.headers.set('X-Powered-By', 'alien-middleware')
+  },
+})
 
 const mainHandler = (context: RequestContext) => {
+  // Approach 2: Calling `context.onResponse(callback)`
+  context.onResponse(response => {
+    assert(response instanceof Response)
+  })
+
   return new Response('Main content')
 }
 
-// `poweredByMiddleware` runs after `mainHandler` generates a response
-const app = chain().use(mainHandler).use(poweredByMiddleware)
+const app = chain().use(poweredByMiddleware).use(mainHandler)
 
 const response = await app({…})
 console.log(response.headers.get('X-Powered-By')) // Output: alien-middleware
 ```
 
 > [!NOTE]
-> Response middleware cannot extend the context using `{ define }` or `{ env }`.
-> They can only inspect the `Response` or replace it by returning a new
-> `Response`.
-
-Your response middlewares will run even if no `Response` is generated by the
-request middlewares, **except** when the middleware chain is nested inside
-another chain, since the outer chain will still have a chance to return a
-`Response`.
+> Remember that request middlewares may not be called if a previous middleware
+> returns a `Response`. In that case, any response callbacks added by the
+> uncalled middleware will not be executed. Therefore, order your middlewares
+> carefully.
+
+#### Modifying Response Headers
+
+Even if a middleware returns an immutable `Response` (e.g. from a `fetch()` call), your _response callback_ can still modify the headers. We make sure to clone the response before processing it with any response callbacks.
 
 ### Merging a Middleware Chain