alien-middleware 0.9.1 → 0.10.1

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-B5T_qCSA.d.ts → index-BRjj7Wf2.d.ts}

@@ -21,12 +21,16 @@ type Merge<TSource extends object, TOverrides extends object | undefined> = Eval
     [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
@@ -36,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: {
@@ -70,20 +74,31 @@ 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['$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.
@@ -98,10 +113,12 @@ type RequestContext<TEnv extends object = any, TProperties extends object = neve
  *
  * When type `T` is `never`, a default context is returned.
  */
-type MiddlewareContext<T extends MiddlewareChain> = [T] extends [never] ? RequestContext<{}, never, unknown> : RequestContext<Env<T>, Properties<T>, Platform<T>>;
+type MiddlewareContext<T extends MiddlewareChain | Middleware[]> = [
+    T
+] extends [never] ? RequestContext<{}, never, unknown> : T extends MiddlewareChain ? RequestContext<Env<T>, Properties<T>, Platform<T>> : T extends Middleware[] ? MiddlewareContext<ApplyMiddlewares<T>> : never;
 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> {
 }
 /**
@@ -112,7 +129,7 @@ interface RequestHandler<T extends MiddlewareTypes = any> extends HattipHandler<
  * 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>;
+    (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: {
@@ -132,12 +149,12 @@ 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, TResult> : Current<TFirst>;
+} : 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;
@@ -156,6 +173,13 @@ type ApplyMiddleware<TFirst extends MiddlewareChain, TSecond extends Middleware>
     current: TCurrent;
     platform: CastNever<Platform<TFirst>, MiddlewarePlatform<TSecond>>;
 }> : never;
+/**
+ * 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: {};
@@ -184,19 +208,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. */
     $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.
@@ -223,4 +249,4 @@ declare function chain<TEnv extends object = {}, TProperties extends object = {}
 }>;
 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,3 +1,3 @@
-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-B5T_qCSA.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-BRjj7Wf2.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,5 +1,5 @@
-import { R as Router, M as MiddlewareContext, a as MiddlewareChain, E as EmptyMiddlewareChain } from './index-B5T_qCSA.js';
-export { b as RouteContext, c as RouteHandler } from './index-B5T_qCSA.js';
+import { R as Router, M as MiddlewareContext, a as MiddlewareChain, E as EmptyMiddlewareChain } from './index-BRjj7Wf2.js';
+export { b as RouteContext, c as RouteHandler } from './index-BRjj7Wf2.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.1",
+  "version": "0.10.1",
   "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'
@@ -146,6 +154,14 @@ Request middleware runs sequentially before a `Response` is generated.
   const app = chain().use(addApiKey).use(useApiKey)
   ```
 
+- **Setting Response Headers:** Call the `context.setHeader()` method to set a response header.
+
+  ```typescript
+  const app = chain().use(context => {
+    context.setHeader('X-Powered-By', 'alien-middleware')
+  })
+  ```
+
 > [!NOTE]
 > If you're wondering why you need to return an object to define properties
 > (rather than simply assigning to the context object), it's because TypeScript
@@ -156,35 +172,63 @@ 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.
+
+#### Non-Blocking Response Callbacks
+
+To ensure the client receives a response as soon as possible, your response callbacks should avoid using `await` unless absolutely necessary. Prefer using `context.waitUntil()` to register independent promises that shouldn't block the response from being sent.
+
+```typescript
+const app = chain().use(context => {
+  context.onResponse(async response => {
+    // ❌ Bad! This blocks the response from being sent.
+    await myLoggingService.logResponse(response)
+
+    // ❌ Bad! This may be interrupted by serverless runtimes.
+    myLoggingService.logResponse(response).catch(console.error)
+
+    // ✅ Good! This doesn't block the response from being sent.
+    context.waitUntil(myLoggingService.logResponse(response))
+  })
+})
+```
 
 ### Merging a Middleware Chain