alien-middleware 0.3.1 → 0.5.0

package/dist/index-DQDr9Gkb.d.ts

@@ -0,0 +1,138 @@
+import { AdapterRequestContext, HattipHandler } from '@hattip/core';
+import { Any } from 'radashi';
+
+type RequestPlugin = {
+    /**
+     * Define properties on the request context.
+     */
+    define?: object;
+    /**
+     * Add type-safe environment variables.
+     */
+    env?: object;
+};
+type Inputs<T extends MiddlewareChain> = T['$']['input'];
+type Platform<T extends MiddlewareChain> = T['$']['platform'];
+type InputProperties<T extends MiddlewareChain> = Inputs<T>['properties'];
+type InputEnv<T extends MiddlewareChain> = Inputs<T>['env'];
+type Current<T extends MiddlewareChain> = T['$']['current'];
+type Properties<T extends MiddlewareChain> = Current<T>['properties'];
+type Env<T extends MiddlewareChain> = Current<T>['env'];
+type MiddlewareTypes<TProperties extends object = any, TEnv extends object = any> = {
+    properties: TProperties;
+    env: TEnv;
+};
+interface HattipContext<TPlatform, TEnv extends object> extends AdapterRequestContext<TPlatform> {
+    /**
+     * 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;
+}
+/**
+ * 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 RequestContext<TProperties extends object = any, TEnv extends object = any, TPlatform = any> = HattipContext<TPlatform, TEnv> & Intersectable<TProperties>;
+/**
+ * Extract a `RequestContext` type from a `MiddlewareChain` type.
+ *
+ * When type `T` is `never`, a default context is returned.
+ */
+type MiddlewareContext<T extends MiddlewareChain> = [T] extends [never] ? RequestContext<{}, {}, unknown> : RequestContext<Properties<T>, Env<T>, Platform<T>>;
+type Awaitable<T> = T | Promise<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 RequestHandler<TInputs extends MiddlewareTypes = any, TCurrent extends MiddlewareTypes = any, TPlatform = any> = HattipHandler<TPlatform> & MiddlewareChain<TInputs, TCurrent, TPlatform>;
+/**
+ * Either a request middleware or a response middleware.
+ *
+ * If your middleware declares the `response` parameter, it's treated as a
+ * response middleware. This means it will run *after* a `Response` is generated
+ * by a request middleware.
+ */
+type Middleware<TProperties extends object = any, TEnv extends object = any, TPlatform = any> = (context: RequestContext<TProperties, TEnv, TPlatform>, response: Response) => Awaitable<Response | RequestPlugin | void>;
+/**
+ * Extract a `Middleware` type from a `MiddlewareChain` type.
+ */
+type ExtractMiddleware<T extends MiddlewareChain> = Middleware<Properties<T>, Env<T>, Platform<T>>;
+type Merge<TSource extends object, TOverrides extends object | undefined> = {} & (TOverrides extends object ? {
+    [K in keyof TSource | keyof TOverrides]: K extends keyof TOverrides ? TOverrides[K] : K extends keyof TSource ? TSource[K] : never;
+} : TSource);
+type ApplyRequestPlugin<TParent extends MiddlewareChain, TPlugin extends RequestPlugin> = {
+    properties: Merge<Properties<TParent>, TPlugin['define']>;
+    env: Merge<Env<TParent>, TPlugin['env']>;
+};
+/**
+ * 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.
+ */
+type ApplyMiddleware<TParent extends MiddlewareChain, TMiddleware> = TMiddleware extends MiddlewareChain ? RequestHandler<Inputs<TParent>, Current<TParent>, Platform<TParent>> : TMiddleware extends () => Awaitable<infer TPlugin extends RequestPlugin> ? RequestHandler<Inputs<TParent>, ApplyRequestPlugin<TParent, TPlugin>, Platform<TParent>> : RequestHandler<Inputs<TParent>, Current<TParent>, Platform<TParent>>;
+type ApplyFirstMiddleware<T extends Middleware> = T extends MiddlewareChain ? T : ApplyMiddleware<MiddlewareChain<{
+    properties: {};
+    env: {};
+}, {
+    properties: {};
+    env: {};
+}, unknown>, T>;
+type MergeMiddleware<TFirst extends MiddlewareChain, TSecond extends Middleware<Properties<TFirst>, Env<TFirst>, Platform<TFirst>>> = RequestHandler<Inputs<TFirst>, TSecond extends MiddlewareChain ? {
+    properties: Merge<Properties<TFirst>, Properties<TSecond>>;
+    env: Merge<Env<TFirst>, Env<TSecond>>;
+} : TSecond extends () => Awaitable<infer TPlugin extends RequestPlugin> ? ApplyRequestPlugin<TFirst, TPlugin> : Current<TFirst>, Platform<TFirst>>;
+type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
+type RouterContext<T extends MiddlewareChain = any, TPathParams extends object = any, TMethod extends RouteMethod = RouteMethod> = MiddlewareContext<T> & {
+    params: TPathParams;
+    method: TMethod;
+};
+type RouteHandler<T extends MiddlewareChain = any, TPathParams extends object = any, TMethod extends RouteMethod = RouteMethod> = (context: RouterContext<T, TPathParams, TMethod>) => Awaitable<Response | void>;
+
+declare const kRequestChain: unique symbol;
+declare const kResponseChain: unique symbol;
+declare class MiddlewareChain<
+/** Values expected by the start of the chain. */
+TInputs extends MiddlewareTypes = any, 
+/** Values provided by the end of the chain. */
+TCurrent extends MiddlewareTypes = any, 
+/** Values from the host platform. */
+TPlatform = any> {
+    /** This property won't exist at runtime. It contains type information for inference purposes. */
+    $: {
+        input: TInputs;
+        current: TCurrent;
+        platform: TPlatform;
+    };
+    /** 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.
+     *
+     * @returns a new `MiddlewareChain` instance
+     */
+    use<const TMiddleware extends ExtractMiddleware<this>>(middleware: TMiddleware): ApplyMiddleware<this, TMiddleware>;
+    /**
+     * Merge two middleware chains. The middlewares from the second chain will be
+     * executed after the middlewares from the first chain.
+     *
+     * For ease of use, this method may be given a middleware function, which
+     * short-circuits to the `use` method. You should prefer using the `use`
+     * method directly, if possible.
+     */
+    merge<TMiddleware extends ExtractMiddleware<this>>(chain: TMiddleware): MergeMiddleware<this, TMiddleware>;
+}
+declare function chain<TProperties extends object = {}, TEnv extends object = {}, TPlatform = unknown>(): MiddlewareChain<{
+    env: TEnv;
+    properties: TProperties;
+}, {
+    env: TEnv;
+    properties: TProperties;
+}, TPlatform>;
+declare function chain<const T extends Middleware = Middleware>(middleware: T): ApplyFirstMiddleware<T>;
+
+export { type ApplyMiddleware as A, type ExtractMiddleware as E, MiddlewareChain as M, type RouteHandler as R, type MiddlewareContext as a, type RouteMethod as b, chain as c, type MergeMiddleware as d, type Middleware as e, type RequestContext as f, type RequestHandler as g, type RequestMiddleware as h, type RequestPlugin as i, type ResponseMiddleware as j };

package/dist/index.d.ts

@@ -1,103 +1,3 @@
-import { AdapterRequestContext, HattipHandler } from '@hattip/core';
-import { Any } from 'radashi';
-
-type RequestPlugin = {
-    /**
-     * Define properties on the request context.
-     */
-    define?: object;
-    /**
-     * Add type-safe environment variables.
-     */
-    env?: object;
-};
-type Inputs<T extends MiddlewareChain> = T['$']['input'];
-type Platform<T extends MiddlewareChain> = T['$']['platform'];
-type InputProperties<T extends MiddlewareChain> = Inputs<T>['properties'];
-type InputEnv<T extends MiddlewareChain> = Inputs<T>['env'];
-type Current<T extends MiddlewareChain> = T['$']['current'];
-type Properties<T extends MiddlewareChain> = Current<T>['properties'];
-type Env<T extends MiddlewareChain> = Current<T>['env'];
-type MiddlewareTypes<TProperties extends object = any, TEnv extends object = any> = {
-    properties: TProperties;
-    env: TEnv;
-};
-interface HattipContext<TPlatform, TEnv extends object> extends AdapterRequestContext<TPlatform> {
-    /**
-     * 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;
-}
-/**
- * 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 RequestContext<TProperties extends object = any, TEnv extends object = any, TPlatform = any> = HattipContext<TPlatform, TEnv> & Intersectable<TProperties>;
-type Awaitable<T> = T | PromiseLike<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 RequestHandler<TInputs extends MiddlewareTypes = any, TCurrent extends MiddlewareTypes = any, TPlatform = any> = HattipHandler<TPlatform> & MiddlewareChain<TInputs, TCurrent, TPlatform>;
-/**
- * Either a request middleware or a response middleware.
- *
- * If your middleware declares the `response` parameter, it's treated as a
- * response middleware. This means it will run *after* a `Response` is generated
- * by a request middleware.
- */
-type Middleware<TProperties extends object = any, TEnv extends object = any, TPlatform = unknown> = (context: RequestContext<TProperties, TEnv, TPlatform>, response: Response) => Awaitable<Response | RequestPlugin | void>;
-type Merge<TSource extends object, TOverrides extends object | undefined> = {} & (TOverrides extends object ? {
-    [K in keyof TSource | keyof TOverrides]: K extends keyof TOverrides ? TOverrides[K] : K extends keyof TSource ? TSource[K] : never;
-} : TSource);
-type ApplyMiddleware<TChain extends MiddlewareChain, TMiddleware> = TMiddleware extends MiddlewareChain ? RequestHandler<Inputs<TChain>, Current<TChain>, Platform<TChain>> : TMiddleware extends () => Awaitable<infer TPlugin extends RequestPlugin> ? RequestHandler<Inputs<TChain>, {
-    properties: Merge<Properties<TChain>, TPlugin['define']>;
-    env: Merge<Env<TChain>, TPlugin['env']>;
-}, Platform<TChain>> : RequestHandler<Inputs<TChain>, Current<TChain>, Platform<TChain>>;
-type ApplyFirstMiddleware<T extends Middleware> = ApplyMiddleware<MiddlewareChain<{
-    properties: {};
-    env: {};
-}, {
-    properties: {};
-    env: {};
-}, unknown>, T>;
-
-declare const kRequestChain: unique symbol;
-declare const kResponseChain: unique symbol;
-declare class MiddlewareChain<
-/** Values expected by the start of the chain. */
-TInputs extends MiddlewareTypes = any, 
-/** Values provided by the end of the chain. */
-TCurrent extends MiddlewareTypes = any, 
-/** Values from the host platform. */
-TPlatform = any> {
-    /** This property won't exist at runtime. It contains type information for inference purposes. */
-    $: {
-        input: TInputs;
-        current: TCurrent;
-        platform: TPlatform;
-    };
-    /** The number of parameters when called as a function. */
-    readonly length: 1;
-    protected [kRequestChain]: RequestMiddleware[];
-    protected [kResponseChain]: ResponseMiddleware[];
-    /**
-     * Attach a middleware. If the `response` paramter is declared, it will be
-     * treated as a response middleware. Otherwise, it will be treated as a
-     * request middleware.
-     *
-     * @returns a new `MiddlewareChain` instance
-     */
-    use<const TMiddleware extends Middleware<TCurrent['properties'], TCurrent['env'], TPlatform>>(middleware: TMiddleware): ApplyMiddleware<this, TMiddleware>;
-}
-declare function chain<TProperties extends object = {}, TEnv extends object = {}, TPlatform = unknown>(): MiddlewareChain<{
-    env: TEnv;
-    properties: TProperties;
-}, {
-    env: TEnv;
-    properties: TProperties;
-}, TPlatform>;
-declare function chain<const T extends Middleware = Middleware>(middleware: T): ApplyFirstMiddleware<T>;
-
-export { type Middleware, MiddlewareChain, type RequestContext, type RequestHandler, type RequestMiddleware, type RequestPlugin, type ResponseMiddleware, chain };
+export { A as ApplyMiddleware, E as ExtractMiddleware, d as MergeMiddleware, e as Middleware, M as MiddlewareChain, a as MiddlewareContext, f as RequestContext, g as RequestHandler, h as RequestMiddleware, i as RequestPlugin, j as ResponseMiddleware, c as chain } from './index-DQDr9Gkb.js';
+import '@hattip/core';
+import 'radashi';

package/dist/index.js

@@ -1,15 +1,3 @@
-// node_modules/.pnpm/radashi@12.5.0-beta.6d5c035/node_modules/radashi/dist/radashi.js
-var asyncIteratorSymbol = (
-  /* c8 ignore next */
-  Symbol.asyncIterator || Symbol.for("Symbol.asyncIterator")
-);
-function isFunction(value) {
-  return typeof value === "function";
-}
-function isPromise(value) {
-  return !!value && isFunction(value.then);
-}
-
 // src/index.ts
 var kRequestChain = Symbol("requestChain");
 var kResponseChain = Symbol("responseChain");
@@ -27,7 +15,7 @@ var MiddlewareChain = class _MiddlewareChain {
   [kRequestChain] = [];
   [kResponseChain] = [];
   /**
-   * Attach a middleware. If the `response` paramter is declared, it will be
+   * 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.
    *
@@ -41,66 +29,91 @@ var MiddlewareChain = class _MiddlewareChain {
     } else {
       responseChain = [...responseChain, middleware];
     }
-    async function handler(parentContext) {
-      const context = Object.create(parentContext);
-      context[kIgnoreNotFound] = true;
-      if (!("url" in context)) {
-        Object.defineProperty(context, "url", urlDescriptor);
+    return createHandler(requestChain, responseChain);
+  }
+  /**
+   * Merge two middleware chains. The middlewares from the second chain will be
+   * executed after the middlewares from the first chain.
+   *
+   * For ease of use, this method may be given a middleware function, which
+   * short-circuits to the `use` method. You should prefer using the `use`
+   * method directly, if possible.
+   */
+  merge(chain2) {
+    if (chain2 instanceof _MiddlewareChain) {
+      return createHandler(
+        [...this[kRequestChain], ...chain2[kRequestChain]],
+        [...this[kResponseChain], ...chain2[kResponseChain]]
+      );
+    }
+    return this.use(chain2);
+  }
+};
+function createHandler(requestChain, responseChain) {
+  async function handler(parentContext) {
+    const context = Object.create(parentContext);
+    context[kIgnoreNotFound] = true;
+    if (!("url" in context)) {
+      Object.defineProperty(context, "url", urlDescriptor);
+    }
+    const cache = context[kMiddlewareCache] ||= /* @__PURE__ */ new Set();
+    let response;
+    let env;
+    for (const middleware of requestChain) {
+      if (cache.has(middleware)) {
+        continue;
       }
-      const cache = context[kMiddlewareCache] ||= /* @__PURE__ */ new Set();
-      let response;
-      let env;
-      for (const middleware2 of requestChain) {
-        if (cache.has(middleware2)) {
-          continue;
-        }
-        cache.add(middleware2);
-        let result = middleware2(context);
-        if (isPromise(result)) {
-          result = await result;
+      cache.add(middleware);
+      let result = middleware(context);
+      if (result instanceof Promise) {
+        result = await result;
+      }
+      if (result) {
+        if (result instanceof Response) {
+          response = result;
+          break;
         }
-        if (result) {
-          if (result instanceof Response) {
-            response = result;
-            break;
-          }
-          if (result.define) {
-            Object.assign(context, result.define);
-          }
-          if (result.env) {
-            env ||= createExtendedEnv(context);
-            Object.assign(env, result.env);
+        if (result.define) {
+          for (const key in result.define) {
+            Object.defineProperty(context, key, {
+              ...Object.getOwnPropertyDescriptor(result.define, key),
+              configurable: false
+            });
           }
         }
-      }
-      if (!response) {
-        if (parentContext[kIgnoreNotFound]) {
-          return;
+        if (result.env) {
+          env ||= createExtendedEnv(context);
+          Object.assign(env, result.env);
         }
-        response = new Response("Not Found", { status: 404 });
       }
-      for (const middleware2 of responseChain) {
-        if (cache.has(middleware2)) {
-          continue;
-        }
-        cache.add(middleware2);
-        let result = middleware2(context, response);
-        if (isPromise(result)) {
-          result = await result;
-        }
-        if (result && result instanceof Response) {
-          response = result;
-          continue;
-        }
+    }
+    if (!response) {
+      if (parentContext[kIgnoreNotFound]) {
+        return;
       }
-      return response;
+      response = new Response("Not Found", { status: 404 });
     }
-    Object.setPrototypeOf(handler, _MiddlewareChain.prototype);
-    handler[kRequestChain] = requestChain;
-    handler[kResponseChain] = responseChain;
-    return handler;
+    for (const middleware of responseChain) {
+      if (cache.has(middleware)) {
+        continue;
+      }
+      cache.add(middleware);
+      let result = middleware(context, response);
+      if (result instanceof Promise) {
+        result = await result;
+      }
+      if (result && result instanceof Response) {
+        response = result;
+        continue;
+      }
+    }
+    return response;
   }
-};
+  Object.setPrototypeOf(handler, MiddlewareChain.prototype);
+  handler[kRequestChain] = requestChain;
+  handler[kResponseChain] = responseChain;
+  return handler;
+}
 function createExtendedEnv(context) {
   const env = /* @__PURE__ */ Object.create(null);
   const superEnv = context.env;
@@ -108,6 +121,9 @@ function createExtendedEnv(context) {
   return env;
 }
 function chain(middleware) {
+  if (middleware instanceof MiddlewareChain) {
+    return middleware;
+  }
   const handler = new MiddlewareChain();
   return middleware ? handler.use(middleware) : handler;
 }

package/dist/router.d.ts

@@ -0,0 +1,16 @@
+import { InferParams } from 'pathic';
+import { M as MiddlewareChain, a as MiddlewareContext, R as RouteHandler, b as RouteMethod } from './index-DQDr9Gkb.js';
+import '@hattip/core';
+import 'radashi';
+
+type OneOrMany<T> = T | readonly T[];
+type Router<T extends MiddlewareChain = any> = ReturnType<typeof routes<T>>;
+declare function routes<T extends MiddlewareChain>(middlewares?: T): {
+    (context: MiddlewareContext<T>): void | Response | Promise<void | Response> | undefined;
+    use: {
+        <TPath extends string>(path: TPath, handler: RouteHandler<T, InferParams<TPath>>): /*elided*/ any;
+        <TPath extends string, TMethod extends RouteMethod = RouteMethod>(method: OneOrMany<TMethod> | "*", path: TPath, handler: RouteHandler<T, InferParams<TPath>, TMethod>): /*elided*/ any;
+    };
+};
+
+export { type Router, routes };

package/dist/router.js

@@ -0,0 +1,50 @@
+// src/router.ts
+import { compilePaths } from "pathic";
+
+// node_modules/.pnpm/radashi@12.5.0-beta.6d5c035/node_modules/radashi/dist/radashi.js
+var isArray = /* @__PURE__ */ (() => Array.isArray)();
+var asyncIteratorSymbol = (
+  /* c8 ignore next */
+  Symbol.asyncIterator || Symbol.for("Symbol.asyncIterator")
+);
+function isFunction(value) {
+  return typeof value === "function";
+}
+
+// src/router.ts
+function routes(middlewares) {
+  const paths = [];
+  const filters = [];
+  const handlers = [];
+  function use(method, path, handler) {
+    if (isFunction(path)) {
+      paths.push(method);
+      filters.push(null);
+      handlers.push(path);
+    } else {
+      paths.push(path);
+      filters.push(
+        method === "*" ? null : isArray(method) ? (m) => method.includes(m) : (m) => method === m
+      );
+      handlers.push(handler);
+    }
+    return router;
+  }
+  let matcher;
+  function router(context) {
+    matcher ||= compilePaths(paths);
+    const method = context.request.method;
+    return matcher(context.request.path, (index, params) => {
+      if (!filters[index] || filters[index](method)) {
+        context.method = method;
+        context.params = params;
+        return middlewares ? middlewares.use(handlers[index])(context) : handlers[index](context);
+      }
+    });
+  }
+  router.use = use;
+  return router;
+}
+export {
+  routes
+};

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "alien-middleware",
   "type": "module",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "exports": {
-    "types": "./dist/index.d.ts",
-    "default": "./dist/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./router": {
+      "types": "./dist/router.d.ts",
+      "default": "./dist/router.js"
+    }
   },
   "files": [
     "dist"
@@ -31,6 +37,9 @@
     "typescript": "^5.8.3",
     "vitest": "^3.1.2"
   },
+  "dependencies": {
+    "pathic": "^0.1.6"
+  },
   "scripts": {
     "dev": "rimraf dist && tsup --sourcemap --watch",
     "build": "rimraf dist && tsup",

package/readme.md

@@ -82,6 +82,14 @@ server.listen(3000, () => {
 > If no middleware in the chain returns a `Response`, a `404 Not Found` response
 > is automatically returned.
 
+#### Middlewares are deduplicated.
+
+If you add the same middleware multiple times, it will only run once. This is a safety measure that allows you to use the same middleware in different places without worrying about it running multiple times.
+
+```typescript
+const app = chain().use(myMiddleware).use(myMiddleware)
+```
+
 ### Request Middleware
 
 Request middleware runs sequentially before a `Response` is generated.
@@ -203,6 +211,16 @@ const finalApp = chain().use(innerChain).use(outerMiddleware)
 
 If a nested chain does not return a `Response`, execution continues with the next middleware in the outer chain.
 
+### Merging Chains
+
+You can merge two middleware chains using the `merge` method. This is useful if you want to combine middleware from multiple files or modules.
+
+```typescript
+const mergedApp = chain().use(middleware1).merge(chain().use(middleware2))
+// …is equivalent to…
+const mergedApp = chain().use(middleware1).use(middleware2)
+```
+
 ### Safe Environment Variables
 
 When writing a Hattip handler without this package, the `context.env()` method is inherently unsafe. Its return type is always `string | undefined`, which means you either need to write defensive checks or use type assertions. Neither is ideal.
@@ -235,3 +253,110 @@ const myMiddleware = (context: RequestContext<any, Env>) => {
 ```
 
 In both examples, we skip declaring any additional context properties (the first type parameter) because we're not using any. The second type parameter is for environment variables. The third is for the special `context.platform` property, whose value is provided by the host platform (e.g. Node.js, Deno, Bun, etc). On principle, a middleware should avoid using the `context.platform` property, since that could make it non-portable unless you write extra fallback logic for other hosts.
+
+## Router
+
+The `routes` function provides a way to create a router instance for handling different paths and HTTP methods.
+
+```typescript
+import { routes } from 'alien-middleware/router'
+
+const router = routes()
+```
+
+### Path Parameter Type Inference
+
+The `routes` function leverages `pathic` to provide type inference for path parameters.
+
+```typescript
+import { routes } from 'alien-middleware/router'
+
+const router = routes()
+
+router.use('/users/:userId', context => {
+  // context.params.userId is automatically typed as string
+  const userId = context.params.userId
+  return new Response(`User ID: ${userId}`)
+})
+```
+
+### Handling Specific HTTP Methods
+
+You can specify one or more HTTP methods for a route by providing the method(s) as the first argument to `.use()`.
+
+```typescript
+import { routes } from 'alien-middleware/router'
+
+const router = routes()
+
+// This handler will only run for GET requests to /api/items
+router.use('GET', '/api/items', context => {
+  return new Response('List of items')
+})
+
+// This handler will only run for POST requests to /api/items
+router.use('POST', '/api/items', context => {
+  return new Response('Create a new item', { status: 201 })
+})
+
+// This handler will run for both PUT and PATCH requests to /api/items/:id
+router.use(['PUT', 'PATCH'], '/api/items/:id', context => {
+  const itemId = context.params.id
+  return new Response(`Update item ${itemId}`)
+})
+
+// This handler will run for any method to /status
+router.use('/status', context => {
+  return new Response('Status: OK')
+})
+```
+
+> [!NOTE]
+> Your routes don't need to be in any particular order, unless their path
+> patterns are exactly the same. The `pathic` library will match the most
+> specific path first. This allows you to split your routes into multiple files
+> for better organization.
+
+### Type-Safe Middleware with `routes()`
+
+You can pass a middleware chain to the `routes()` function to apply middleware specifically to the routes defined by that router instance. This provides type safety for context extensions within the router.
+
+```typescript
+import {
+  chain,
+  type RequestContext,
+  type RequestPlugin,
+} from 'alien-middleware'
+import { routes } from 'alien-middleware/router'
+
+// Define a middleware that adds a user to the context
+const addUserMiddleware = (context: RequestContext): RequestPlugin => {
+  const user = { id: 123, name: 'Alice' }
+  return { define: { user } }
+}
+
+// Create a chain with the middleware
+const authMiddlewares = chain(addUserMiddleware)
+
+// Pass the chain to the routes function
+const authenticatedRouter = routes(authMiddlewares)
+
+// Define a route that uses the context property added by the middleware
+authenticatedRouter.use('/profile', context => {
+  // context.user is now type-safe and available
+  return new Response(`Welcome, ${context.user.name}!`)
+})
+
+// Routes defined on a router without a chain won't have the user property
+const publicRouter = routes()
+
+publicRouter.use('/public', context => {
+  // context.user is not available here
+  // @ts-expect-error - user is not defined on this context
+  console.log(context.user)
+  return new Response('Public content')
+})
+
+// You can combine routers using .use()
+const app = chain().use(authenticatedRouter).use(publicRouter)
+```