Definitions

Handler

A function that returns a Response.

It will usually be associated with a route.

interface UniversalHandler<Context> {
  (request: Request, context: Context): Response | Promise<Response>;
}

NOTE

In some frameworks, a Response can be anything from a web Response, a string, an object, a ServerResponse, etc. Only web Response are supported by universal-middleware, as this is part of the WinterCG standard.

Middleware

A function that alters the Context or Response. Can also return an early Response.

It will usually NOT be associated with a route.

Check the recipes for details.

type Awaitable<T> = T | Promise<T>;

interface UniversalMiddleware<InContext, OutContext> { 
  (request: Request, context: InContext):
    Awaitable<
    | Response // Can return an early Response
    | OutContext // Can return a new context. Ensures type-safe context representation
    | ((response: Response) => Awaitable<Response>) // Can return a function that manipulates the Response
    | void | undefined // Can return nothing
    >;
}

Context

Some data, usually added by a middleware, with the same lifespan as a Request.

For instance, a { user: User } context can be set by a middleware, then accessed by others.

NOTE

Each framework has its own way to attach data related to the request, either by attaching values to their internal request representation (like Express), or by having their own context encapsulating the request (like Hono).

On the other hand, a universal context is just an object, detached from the request, but with the same lifespan.

TIP

Each adapter provides a getContext helper to retrieve the universal context from any non-universal middleware or handler.

TIP

One can also override the global Universal.Context, making it visible to all Universal Middlewares.

import { User } from 'my-lib';

declare global {
  namespace Universal {
    interface Context {
      user: User;
    }
  }
}