@sigitex/route 1.0.1 → 1.0.2

package/README.md

@@ -46,14 +46,6 @@ export default {
 }
 ```
 
-## Entry Points
-
-| Import                      | Description                         |
-| --------------------------- | ----------------------------------- |
-| `@sigitex/route`            | Core router, handlers, middleware   |
-| `@sigitex/route/bun`        | Bun runtime adapter                |
-| `@sigitex/route/cloudflare` | Cloudflare Workers runtime adapter  |
-
 ## `route(...handlers)`
 
 Creates a fetch function `(request: Request, env: Env) => Promise<Response>` from a list of handlers. Handlers are tried in order; the first to return a value produces the response. If none match, a 404 is returned.

package/package.json

@@ -8,7 +8,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/sigitex/route.git"
+    "url": "git+https://github.com/sigitex/route.git"
   },
   "exports": {
     ".": "./src/index.ts",
@@ -43,5 +43,5 @@
   "files": [
     "src"
   ],
-  "version": "1.0.1"
+  "version": "1.0.2"
 }

package/src/Assets.ts

@@ -1,3 +1,4 @@
+/** Platform-agnostic interface for serving static files. */
 export type Assets = {
   static(path: string): Promise<Response>
   file(request: Request): Promise<Response | undefined>

package/src/CSP.ts

@@ -1,5 +1,6 @@
 const nonce = Symbol("csp-nonce")
 
+/** Content-Security-Policy source value constants. */
 export const CSP = {
   self: "'self'",
   none: "'none'",
@@ -15,4 +16,5 @@ export const CSP = {
   wss: "wss:",
 } as const
 
+/** A CSP source value: a string directive or the nonce symbol. */
 export type CspSource = string | typeof nonce

package/src/HTTP.ts

@@ -1,3 +1,4 @@
+/** HTTP constants for methods, statuses, headers, and content types. */
 export const HTTP = {
   method: {
     GET: "GET",

package/src/Router.ts

@@ -3,9 +3,10 @@ import type {
   RequestHandler,
   RouterOptions,
   RouteMiddleware,
-  RequestContext
+  RequestContext,
 } from "./router.types"
 
+/** Core router that dispatches requests through a handler chain. */
 export class Router {
   private readonly handlers: RequestHandler[]
   private readonly container: Container | undefined
@@ -17,10 +18,7 @@ export class Router {
     this.middlewares = options.middlewares ?? []
   }
 
-  async route(
-    request: Request,
-    env: Env,
-  ): Promise<Response> {
+  async route(request: Request, env: Env): Promise<Response> {
     const url = new URL(request.url)
     const context: RequestContext = {
       request,
@@ -36,7 +34,9 @@ export class Router {
       }
       for (const handler of this.handlers) {
         const result = await dispatch(handler, this.middlewares)
-        if (result === undefined) continue
+        if (result === undefined) {
+          continue
+        }
         return result
       }
       return fail(404, "Not found.")
@@ -59,9 +59,13 @@ export class Router {
       middlewares: RouteMiddleware[],
     ): Promise<Response | undefined> {
       for (const { before } of middlewares) {
-        if (!before) continue
+        if (!before) {
+          continue
+        }
         const interrupt = await Promise.resolve(invoke(before))
-        if (interrupt !== undefined) return respond(interrupt)
+        if (interrupt !== undefined) {
+          return respond(interrupt)
+        }
       }
       const result = await Promise.resolve(invoke(handler))
       if (result === undefined) {
@@ -70,9 +74,13 @@ export class Router {
       const response = respond(result)
       bind({ response })
       for (const { after } of middlewares) {
-        if (!after) continue
+        if (!after) {
+          continue
+        }
         const interrupt = await Promise.resolve(invoke(after))
-        if (interrupt !== undefined) return respond(interrupt)
+        if (interrupt !== undefined) {
+          return respond(interrupt)
+        }
       }
       return respond(result)
     }
@@ -87,7 +95,7 @@ export class Router {
 }
 
 function fail(status: number, error: string) {
-  return new Response(JSON.stringify({ error }), {
+  return Response.json({ error }, {
     status,
     statusText: error,
   })
@@ -96,5 +104,5 @@ function fail(status: number, error: string) {
 function respond(result: unknown) {
   return result instanceof Response
     ? result
-    : new Response(JSON.stringify(result))
+    : Response.json(result)
 }

package/src/RouterError.ts

@@ -1,31 +1,42 @@
+// oxlint-disable unicorn/custom-error-definition
+/** Base error class with an HTTP status code. */
 export class RouterError extends Error {
   readonly code: number
   constructor(code: number, message: string) {
     super(message)
     this.code = code
+    this.name = "RouterError"
   }
 }
 
+/** 404 Not Found error. */
 export class NotFound extends RouterError {
   constructor(message?: string) {
     super(404, message ?? "Not found.")
+    this.name = "NotFound"
   }
 }
 
+/** Generic server error (no HTTP status code). */
 export class ServerError extends Error {
   constructor(message?: string) {
     super(message ?? "Internal error.")
+    this.name = "ServerError"
   }
 }
 
+/** 405 Method Not Allowed error. */
 export class MethodNotAllowed extends RouterError {
   constructor(message?: string) {
     super(405, message ?? "Method not allowed.")
+    this.name = "MethodNotAllowed"
   }
 }
 
+/** 400 Invalid Request error. */
 export class InvalidRequest extends RouterError {
   constructor(message?: string) {
     super(400, message ?? "Invalid request.")
+    this.name = "InvalidRequest"
   }
 }

package/src/bun/bun.ts

@@ -6,6 +6,7 @@ type BunOptions = {
   readonly assets?: string
 }
 
+/** Bun runtime adapter; binds a local-filesystem Assets implementation. */
 export function bun(options: BunOptions = {}): RequestHandler {
   const assets = bunAssets(options.assets ?? "./assets")
   return ({ bind }: { bind: (bindings: { assets: Assets }) => void }) => {
@@ -19,7 +20,9 @@ function bunAssets(dir: string): Assets {
   return {
     async static(path) {
       const cached = cache.get(path)
-      if (cached) return cached.clone() as Response
+      if (cached) {
+        return cached.clone() as Response
+      }
       const file = Bun.file(join(dir, path))
       const response = new Response(await file.bytes(), {
         headers: { "Content-Type": file.type },
@@ -30,7 +33,9 @@ function bunAssets(dir: string): Assets {
     async file(request) {
       const path = new URL(request.url).pathname
       const file = Bun.file(join(dir, path))
-      if (!await file.exists()) return undefined
+      if (!(await file.exists())) {
+        return undefined
+      }
       return new Response(file) as Response
     },
   }

package/src/cloudflare/cloudflare.ts

@@ -9,6 +9,7 @@ type CloudflareOptions = {
   readonly assets?: string
 }
 
+/** Cloudflare Workers adapter; binds a Workers Assets implementation. */
 export function cloudflare(options: CloudflareOptions = {}): RequestHandler {
   const assetsKey = options.assets ?? "ASSETS"
   return ({

package/src/handler/app.ts

@@ -2,6 +2,7 @@ import * as RegexParam from "regexparam"
 import type { Assets } from "../Assets"
 import type { RequestHandler, RouteTree } from "../router.types"
 
+/** Serves index.html for paths matching a client-side RouteTree (SPA support). */
 export function app(routes: RouteTree): RequestHandler {
   const patterns: RegExp[] = getAppPatterns(routes)
   return async ({ assets, url }: { assets: Assets, url: URL }) => {

package/src/handler/assets.ts

@@ -1,10 +1,13 @@
 import type { Assets } from "../Assets"
 import type { RequestHandler } from "../router.types"
 
+/** Serves static files via the platform's Assets binding. */
 export function assets(): RequestHandler {
-  return async ({ assets, request }: { assets: Assets, request: Request }) => {
+  return async ({ assets, request }: { assets: Assets; request: Request }) => {
     const response = await assets.file(request)
-    if (!response || response.status === 404) return
+    if (!response || response.status === 404) {
+      return
+    }
     return response
   }
 }

package/src/handler/noop.ts

@@ -1,3 +1,4 @@
 import type { RequestHandler } from "../router.types"
 
+/** A handler that does nothing; used internally by middleware composition. */
 export const noop: RequestHandler = () => {}

package/src/handler/pattern.ts

@@ -1,7 +1,12 @@
 import * as RegexParam from "regexparam"
 import { MethodNotAllowed } from "../RouterError"
-import type { RequestContext, RequestHandler, RouteMiddleware } from "../router.types"
+import type {
+  RequestContext,
+  RequestHandler,
+  RouteMiddleware,
+} from "../router.types"
 
+/** Matches a request by method and path pattern, binding extracted params. */
 export function pattern(
   method: string | null,
   path: string,
@@ -11,7 +16,9 @@ export function pattern(
   const { pattern, keys } = RegexParam.parse(path)
   return ({ url, request, bind, dispatch }: RequestContext) => {
     const match = pattern.exec(url.pathname)
-    if (!match) return
+    if (!match) {
+      return
+    }
     if (method !== null && request.method !== method) {
       return new MethodNotAllowed(`Please use "${method}".`)
     }
@@ -30,6 +37,7 @@ export function pattern(
   }
 }
 
+/** Matches GET requests against a path pattern. */
 export function get(
   path: string,
   handler: RequestHandler,
@@ -38,6 +46,7 @@ export function get(
   return pattern("GET", path, handler, ...middlewares)
 }
 
+/** Matches POST requests against a path pattern. */
 export function post(
   path: string,
   handler: RequestHandler,
@@ -46,6 +55,7 @@ export function post(
   return pattern("POST", path, handler, ...middlewares)
 }
 
+/** Matches PUT requests against a path pattern. */
 export function put(
   path: string,
   handler: RequestHandler,
@@ -54,6 +64,7 @@ export function put(
   return pattern("PUT", path, handler, ...middlewares)
 }
 
+/** Matches DELETE requests against a path pattern. */
 export function del(
   path: string,
   handler: RequestHandler,
@@ -62,6 +73,7 @@ export function del(
   return pattern("DELETE", path, handler, ...middlewares)
 }
 
+/** Matches PATCH requests against a path pattern. */
 export function patch(
   path: string,
   handler: RequestHandler,

package/src/handler/prefix.ts

@@ -1,6 +1,11 @@
-import type { RequestContext, RequestHandler, RouteMiddleware } from "../router.types"
+import type {
+  RequestContext,
+  RequestHandler,
+  RouteMiddleware,
+} from "../router.types"
 import { use } from "./use"
 
+/** Groups handlers under a URL prefix, stripping it before dispatch. */
 export function prefix(
   prefix: string,
   ...handlers: RequestHandler[]

package/src/handler/use.ts

@@ -1,6 +1,11 @@
-import type { RequestContext, RequestHandler, RouteMiddleware } from "../router.types"
+import type {
+  RequestContext,
+  RequestHandler,
+  RouteMiddleware,
+} from "../router.types"
 import { noop } from "./noop"
 
+/** Applies middlewares to a group of handlers without creating a prefix. */
 export function use(
   middlewares: RouteMiddleware[],
   ...handlers: RequestHandler[]
@@ -19,7 +24,9 @@ export function use(
     let response: Response | undefined
     for (const handler of handlers) {
       response = await dispatch(handler, [])
-      if (response !== undefined) break
+      if (response !== undefined) {
+        break
+      }
     }
     if (response === undefined) {
       return

package/src/middleware/bodyLimit.ts

@@ -6,6 +6,7 @@ export type BodyLimitOptions = {
   readonly contentTypes?: string[]
 }
 
+/** Rejects requests exceeding a body size or with disallowed content types. */
 export function bodyLimit(options?: BodyLimitOptions): RouteMiddleware {
   const maxSize = options?.maxSize ?? 1_048_576
   const contentTypes = options?.contentTypes
@@ -14,8 +15,8 @@ export function bodyLimit(options?: BodyLimitOptions): RouteMiddleware {
     before: ({ request }: RequestContext) => {
       const contentLength = request.headers.get(HTTP.header.ContentLength)
       if (contentLength && Number.parseInt(contentLength, 10) > maxSize) {
-        return new Response(
-          JSON.stringify({ error: HTTP.statusText.PayloadTooLarge }),
+        return Response.json(
+          { error: HTTP.statusText.PayloadTooLarge },
           {
             status: HTTP.status.PayloadTooLarge,
             statusText: HTTP.statusText.PayloadTooLarge,
@@ -29,8 +30,8 @@ export function bodyLimit(options?: BodyLimitOptions): RouteMiddleware {
           contentType &&
           !contentTypes.some((allowed) => contentType.startsWith(allowed))
         ) {
-          return new Response(
-            JSON.stringify({ error: HTTP.statusText.UnsupportedMediaType }),
+          return Response.json(
+            { error: HTTP.statusText.UnsupportedMediaType },
             {
               status: HTTP.status.UnsupportedMediaType,
               statusText: HTTP.statusText.UnsupportedMediaType,

package/src/middleware/cache.ts

@@ -18,6 +18,7 @@ export type CacheOptions = {
   readonly vary?: string | string[]
 }
 
+/** Sets Cache-Control (and optionally Vary) headers on responses. */
 export function cache(options: string | CacheOptions): RouteMiddleware {
   const directive =
     typeof options === "string" ? options : buildDirective(options)

package/src/middleware/cookies.ts

@@ -1,3 +1,4 @@
+// oxlint-disable curly
 import type {
   RequestContext,
   ResponseContext,
@@ -14,11 +15,13 @@ export type CookieOptions = {
   secure?: boolean
 }
 
+/** Cookie reader/writer bound to the request context. */
 export type Cookies = {
   get(name: string): string | undefined
   set(name: string, value: string, options?: CookieOptions): void
 }
 
+/** Parses request cookies and collects Set-Cookie headers on the response. */
 export function cookies(): RouteMiddleware {
   const pending: { name: string; value: string; options?: CookieOptions }[] = []
   let parsed: Record<string, string> = {}
@@ -49,10 +52,14 @@ function parseCookies(header: string): Record<string, string> {
   const result: Record<string, string> = {}
   for (const pair of header.split(";")) {
     const index = pair.indexOf("=")
-    if (index === -1) continue
+    if (index === -1) {
+      continue
+    }
     const key = pair.slice(0, index).trim()
     const value = pair.slice(index + 1).trim()
-    if (key) result[key] = decodeURIComponent(value)
+    if (key) {
+      result[key] = decodeURIComponent(value)
+    }
   }
   return result
 }

package/src/middleware/cors.ts

@@ -14,6 +14,7 @@ export type CorsOptions = {
   readonly maxAge?: number
 }
 
+/** Handles CORS preflight and response headers. */
 export function cors(options?: CorsOptions): RouteMiddleware {
   const originOption = options?.origin ?? "*"
   const methods = options?.methods ?? [
@@ -31,10 +32,14 @@ export function cors(options?: CorsOptions): RouteMiddleware {
 
   return {
     before: ({ request }: RequestContext) => {
-      if (request.method !== HTTP.method.OPTIONS) return
+      if (request.method !== HTTP.method.OPTIONS) {
+        return
+      }
 
       const requestOrigin = request.headers.get(HTTP.header.Origin)
-      if (!requestOrigin) return
+      if (!requestOrigin) {
+        return
+      }
 
       const response = new Response(null, { status: HTTP.status.NoContent })
       setOriginHeader(response, requestOrigin, originOption)
@@ -71,7 +76,9 @@ export function cors(options?: CorsOptions): RouteMiddleware {
     },
     after: ({ request, response }: ResponseContext) => {
       const requestOrigin = request.headers.get(HTTP.header.Origin)
-      if (!requestOrigin) return
+      if (!requestOrigin) {
+        return
+      }
 
       setOriginHeader(response, requestOrigin, originOption)
 

package/src/middleware/csp.ts

@@ -45,6 +45,7 @@ const directiveMap: Record<string, string> = {
   manifestSrc: "manifest-src",
 }
 
+/** Sets Content-Security-Policy headers with optional automatic nonce generation. */
 export function csp(options: CspOptions): RouteMiddleware {
   const usesNonce = detectsNonce(options)
   const reportOnly = options.reportOnly ?? false
@@ -87,10 +88,14 @@ function buildPolicy(options: CspOptions, nonce?: string): string {
 
   for (const [key, directive] of Object.entries(directiveMap)) {
     const sources = options[key as keyof CspOptions]
-    if (!Array.isArray(sources) || sources.length === 0) continue
+    if (!Array.isArray(sources) || sources.length === 0) {
+      continue
+    }
 
     const resolved = sources.map((source) => {
-      if (source === CSP.nonce) return `'nonce-${nonce}'`
+      if (source === CSP.nonce) {
+        return `'nonce-${nonce}'`
+      }
       return source as string
     })
 

package/src/middleware/csrf.ts

@@ -8,6 +8,7 @@ export type CsrfOptions = {
   readonly methods?: string[]
 }
 
+/** Double-submit cookie CSRF protection; requires cookies() middleware. */
 export function csrf(options?: CsrfOptions): RouteMiddleware {
   const cookieName = options?.cookie ?? "csrf-token"
   const headerName = options?.header ?? HTTP.header.XCsrfToken
@@ -26,13 +27,15 @@ export function csrf(options?: CsrfOptions): RouteMiddleware {
         )
       }
 
-      if (!methods.includes(request.method)) return
+      if (!methods.includes(request.method)) {
+        return
+      }
 
       const origin = request.headers.get(HTTP.header.Origin)
       const url = new URL(request.url)
       if (origin && origin !== url.origin) {
-        return new Response(
-          JSON.stringify({ error: HTTP.statusText.Forbidden }),
+        return Response.json(
+          { error: HTTP.statusText.Forbidden },
           {
             status: HTTP.status.Forbidden,
             statusText: HTTP.statusText.Forbidden,
@@ -44,8 +47,8 @@ export function csrf(options?: CsrfOptions): RouteMiddleware {
       const headerToken = request.headers.get(headerName)
 
       if (!cookieToken || !headerToken || cookieToken !== headerToken) {
-        return new Response(
-          JSON.stringify({ error: HTTP.statusText.Forbidden }),
+        return Response.json(
+          { error: HTTP.statusText.Forbidden },
           {
             status: HTTP.status.Forbidden,
             statusText: HTTP.statusText.Forbidden,
@@ -54,7 +57,9 @@ export function csrf(options?: CsrfOptions): RouteMiddleware {
       }
     },
     after: ({ cookies }: { cookies?: Cookies }) => {
-      if (!cookies) return
+      if (!cookies) {
+        return
+      }
       const token = crypto.randomUUID()
       cookies.set(cookieName, token, {
         httpOnly: false,

package/src/middleware/filter.ts

@@ -1,10 +1,13 @@
 import type { RequestContext, RequestHandler } from "../router.types"
 
+/** Higher-order function that conditionally runs a handler based on a predicate. */
 export function filter(
   predicate: (context: RequestContext) => boolean | Promise<boolean>,
 ): (handler: RequestHandler) => RequestHandler {
   return (handler) => async (context: RequestContext) => {
-    if (!(await predicate(context))) return
+    if (!(await predicate(context))) {
+      return
+    }
     return context.dispatch(handler, [])
   }
 }

package/src/middleware/frameGuard.ts

@@ -9,6 +9,7 @@ function make(value: string): RouteMiddleware {
   }
 }
 
+/** Sets X-Frame-Options header to prevent clickjacking. */
 export namespace frameGuard {
   export const deny = make(HTTP.frameOption.deny)
   export const sameOrigin = make(HTTP.frameOption.sameOrigin)

package/src/middleware/hardened.ts

@@ -11,6 +11,7 @@ export type HardenedOptions = {
   readonly hsts?: false | HstsOptions
 }
 
+/** Convenience bundle applying noSniff, frameGuard, referrerPolicy, and hsts. */
 export function hardened(options?: HardenedOptions): RouteMiddleware {
   const parts: RouteMiddleware[] = []
 
@@ -36,7 +37,9 @@ export function hardened(options?: HardenedOptions): RouteMiddleware {
   return {
     after: (context: ResponseContext) => {
       for (const part of parts) {
-        if (part.after) part.after(context)
+        if (part.after) {
+          part.after(context)
+        }
       }
     },
   }

package/src/middleware/hsts.ts

@@ -7,14 +7,19 @@ export type HstsOptions = {
   readonly preload?: boolean
 }
 
+/** Sets Strict-Transport-Security header. */
 export function hsts(options?: HstsOptions): RouteMiddleware {
   const maxAge = options?.maxAge ?? 31536000
   const includeSubDomains = options?.includeSubDomains ?? true
   const preload = options?.preload ?? false
 
   let value = `max-age=${maxAge}`
-  if (includeSubDomains) value += "; includeSubDomains"
-  if (preload) value += "; preload"
+  if (includeSubDomains) {
+    value += "; includeSubDomains"
+  }
+  if (preload) {
+    value += "; preload"
+  }
 
   return {
     after: ({ response }: ResponseContext) => {

package/src/middleware/https.ts

@@ -1,8 +1,11 @@
 import type { RequestContext, RequestHandler } from "../router.types"
 
+/** Redirects HTTP requests to HTTPS with a 301. */
 export function https(): RequestHandler {
   return ({ url }: RequestContext) => {
-    if (url.protocol === "https:") return
+    if (url.protocol === "https:") {
+      return
+    }
     url.protocol = "https:"
     return Response.redirect(url, 301)
   }

package/src/middleware/noSniff.ts

@@ -1,6 +1,7 @@
 import { HTTP } from "../HTTP"
 import type { ResponseContext, RouteMiddleware } from "../router.types"
 
+/** Sets X-Content-Type-Options: nosniff. */
 export const noSniff: RouteMiddleware = {
   after: ({ response }: ResponseContext) => {
     response.headers.set(

package/src/middleware/rateLimit.ts

@@ -1,9 +1,9 @@
-import { HTTP } from "../HTTP";
+import { HTTP } from "../HTTP"
 import type {
   RequestContext,
   ResponseContext,
   RouteMiddleware,
-} from "../router.types";
+} from "../router.types"
 
 export type RateLimitStore = {
   increment(
@@ -20,6 +20,7 @@ export type RateLimitOptions = {
   readonly headers?: boolean
 }
 
+/** IP-based rate limiting with pluggable storage. */
 export function rateLimit(options?: RateLimitOptions): RouteMiddleware {
   const window = options?.window ?? 60
   const max = options?.max ?? 100
@@ -36,8 +37,8 @@ export function rateLimit(options?: RateLimitOptions): RouteMiddleware {
       lastResult = result
 
       if (result.count > max) {
-        const response = new Response(
-          JSON.stringify({ error: HTTP.statusText.TooManyRequests }),
+        const response = Response.json(
+          { error: HTTP.statusText.TooManyRequests },
           {
             status: HTTP.status.TooManyRequests,
             statusText: HTTP.statusText.TooManyRequests,
@@ -97,7 +98,9 @@ export namespace rateLimit {
 
         // Clean up expired windows
         for (const [k, v] of windows) {
-          if (v.reset < now) windows.delete(k)
+          if (v.reset < now) {
+            windows.delete(k)
+          }
         }
 
         return { count: 1, reset }

package/src/middleware/referrerPolicy.ts

@@ -9,6 +9,7 @@ function make(value: string): RouteMiddleware {
   }
 }
 
+/** Pre-built Referrer-Policy header middlewares. */
 export namespace referrerPolicy {
   export const noReferrer = make(HTTP.referrerPolicy.noReferrer)
   export const noReferrerWhenDowngrade = make(

package/src/middleware/requestId.ts

@@ -10,6 +10,7 @@ export type RequestIdOptions = {
   readonly generate?: () => string
 }
 
+/** Reads or generates a request ID, binds it to context, and echoes it on the response. */
 export function requestId(options?: RequestIdOptions): RouteMiddleware {
   const header = options?.header ?? HTTP.header.XRequestId
   const generate = options?.generate ?? (() => crypto.randomUUID())

package/src/middleware/setHeader.ts

@@ -1,5 +1,6 @@
 import type { ResponseContext, ResponseHandler } from "../router.types"
 
+/** Sets a header on every response. */
 export function setHeader(header: string, value: string): ResponseHandler {
   return ({ response }: ResponseContext) => {
     response.headers.set(header, value)

package/src/middleware/www.ts

@@ -1,12 +1,15 @@
 import type { RequestContext, RequestHandler } from "../router.types"
 
+/** Redirects non-www requests to the www subdomain. */
 export function www({ secure }: { readonly secure?: boolean }): RequestHandler {
   return ({ url }: RequestContext) => {
     const isWww = url.hostname.startsWith("www.")
     const isSecure = url.protocol === "https:"
     if (isWww && (secure ? isSecure : true)) return
     url.hostname = `www.${url.hostname}`
-    if (secure) url.protocol = "https:"
+    if (secure) {
+      url.protocol = "https:"
+    }
     return Response.redirect(url, 301)
   }
 }

package/src/route.ts

@@ -1,8 +1,10 @@
 import { Router } from "./Router"
 import type { RequestHandler, RouterFetch, RouterOptions } from "./router.types"
 
+/** A handler value that may be falsy, allowing conditional handlers. */
 export type MaybeHandler = RequestHandler | null | undefined | false | 0
 
+/** Creates a fetch function from a list of handlers, tried in order. */
 export function route(...handlers: MaybeHandler[]): RouterFetch
 export function route(
   options: RouterOptions,

package/src/router.types.ts

@@ -1,15 +1,18 @@
 // oxlint-disable typescript/no-explicit-any
 import type { Container } from "@sigitex/bind"
 
+/** Nested map of route names to path patterns for client-side routing. */
 export type RouteTree = {
   [key: string]: string | RouteTree
 }
 
+/** The fetch function signature returned by `route()`. */
 export type RouterFetch = (
   request: Request,
   env: Env,
 ) => Promise<Response>
 
+/** Context object passed to request handlers. */
 export type RequestContext = {
   readonly request: Request
   readonly env: Env
@@ -18,30 +21,37 @@ export type RequestContext = {
   readonly dispatch: RouterDispatch
 }
 
+/** Adds values to the current request context. */
 export type RouterBind = (bindings: { [key: string]: any }) => void
 
+/** Dispatches a handler through a middleware chain. */
 export type RouterDispatch = (
   handler: RequestHandler,
   middlewares: RouteMiddleware[],
 ) => Promise<Response | undefined>
 
+/** Context available to after-middleware, includes the response. */
 export type ResponseContext = RequestContext & {
   readonly response: Response
 }
 
+/** A function that handles a request and optionally returns a response. */
 export type RequestHandler = (
   context: any,
 ) => unknown
 
+/** A function that runs after a response is produced. */
 export type ResponseHandler = (
   context: any,
 ) => unknown
 
+/** Options for the `route()` entry point. */
 export type RouterOptions = {
   readonly container?: Container
   readonly middlewares?: RouteMiddleware[]
 }
 
+/** A middleware with optional before/after hooks. */
 export type RouteMiddleware = {
   readonly before?: RequestHandler
   readonly after?: ResponseHandler