@sigitex/route 1.0.0 → 1.0.2

package/README.md

@@ -1,7 +1,379 @@
 # @sigitex/route
 
-`bun add @sigitex/route`
-
 A server-side web framework.
 
+`bun add @sigitex/route`
+
 > **Note:** This package currently exports TypeScript sources directly. A TypeScript-compatible runtime or bundler (Bun, etc.) is required.
+
+## Quick Start
+
+```ts
+import { route, get, post, prefix, cors, hardened, cookies } from "@sigitex/route"
+import { bun } from "@sigitex/route/bun"
+
+const fetch = route(
+  bun({ assets: "./public" }),
+  get("/health", () => ({ status: "ok" })),
+  prefix("/api/", [cors(), cookies(), hardened()],
+    get("/users", async () => {
+      return Response.json(await getUsers())
+    }),
+    get("/users/:id", async ({ params }: { params: { id: string } }) => {
+      return Response.json(await getUser(params.id))
+    }),
+    post("/users", async ({ request }: { request: Request }) => {
+      const body = await request.json()
+      return Response.json(await createUser(body))
+    }),
+  ),
+)
+
+Bun.serve({ fetch })
+```
+
+On Cloudflare Workers:
+
+```ts
+import { route, get } from "@sigitex/route"
+import { cloudflare } from "@sigitex/route/cloudflare"
+
+export default {
+  fetch: route(
+    cloudflare(),
+    get("/hello", () => ({ hello: "world" })),
+  ),
+}
+```
+
+## `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.
+
+```ts
+const fetch = route(handler1, handler2, handler3)
+```
+
+An optional `RouterOptions` object can be passed as the first argument:
+
+```ts
+const fetch = route({ container, middlewares: [cors()] }, handler1, handler2)
+```
+
+Falsy values (`null`, `undefined`, `false`, `0`) are silently ignored, allowing conditional handlers:
+
+```ts
+route(
+  isDev && get("/debug", debugHandler),
+  get("/", homeHandler),
+)
+```
+
+### `RouterOptions`
+
+| Option        | Type              | Description                                            |
+| ------------- | ----------------- | ------------------------------------------------------ |
+| `container`   | `Container`       | A `@sigitex/bind` IoC container for dependency injection |
+| `middlewares`  | `RouteMiddleware[]` | Global middlewares applied to every dispatched handler  |
+
+## Handlers
+
+Handlers are functions that receive a context object and return a `Response`, a JSON-serializable value, or `undefined` to skip.
+
+### `get(path, handler, ...middlewares)`
+
+Matches GET requests against `path`. Path parameters use `regexparam` syntax (`:param`, `*`).
+
+```ts
+get("/users/:id", ({ params }: { params: { id: string } }) => {
+  return Response.json({ id: params.id })
+})
+```
+
+### `post(path, handler, ...middlewares)`
+
+Matches POST requests.
+
+### `put(path, handler, ...middlewares)`
+
+Matches PUT requests.
+
+### `del(path, handler, ...middlewares)`
+
+Matches DELETE requests.
+
+### `patch(path, handler, ...middlewares)`
+
+Matches PATCH requests.
+
+### `pattern(method, path, handler, ...middlewares)`
+
+Generic version -- pass `null` as the method to match any HTTP method.
+
+```ts
+pattern(null, "/any-method/:id", handler)
+pattern("GET", "/explicit", handler)
+```
+
+### `prefix(prefix, ...handlers)`
+
+Groups handlers under a URL prefix. The prefix is stripped from the URL before child handlers see it.
+
+```ts
+prefix("/api/v1/",
+  get("/users", listUsers),   // matches /api/v1/users
+  get("/posts", listPosts),   // matches /api/v1/posts
+)
+```
+
+Accepts an optional middlewares array as the second argument:
+
+```ts
+prefix("/api/", [cors(), bodyLimit()],
+  post("/upload", uploadHandler),
+)
+```
+
+### `mount(fetchFn)`
+
+Wraps a standard `(request: Request) => Promise<Response>` function as a handler. Useful for mounting sub-applications or external fetch handlers.
+
+```ts
+mount(subApp.fetch)
+```
+
+### `assets()`
+
+Serves static files via the platform's `Assets` binding. Returns `undefined` on 404 so subsequent handlers can match.
+
+```ts
+route(bun(), assets(), get("/", homeHandler))
+```
+
+### `app(routes)`
+
+Serves `index.html` for paths matching a client-side `RouteTree`. Intended for single-page applications where the client handles routing.
+
+```ts
+app({
+  users: "/users",
+  user: "/users/:id",
+  settings: { general: "/settings/general" },
+})
+```
+
+### `noop`
+
+A handler that does nothing and returns `undefined`. Used internally by middleware composition.
+
+### `use(middlewares, ...handlers)`
+
+Applies a set of middlewares to a group of handlers without creating a prefix.
+
+```ts
+use([cors(), cookies()],
+  get("/a", handlerA),
+  get("/b", handlerB),
+)
+```
+
+### `filter(predicate)`
+
+Higher-order function that conditionally runs a handler based on a predicate.
+
+```ts
+const onlyJson = filter(({ request }) =>
+  request.headers.get("Accept")?.includes("application/json") ?? false
+)
+
+onlyJson(get("/data", dataHandler))
+```
+
+### `https()`
+
+Redirects HTTP requests to HTTPS with a 301.
+
+```ts
+route(https(), get("/", homeHandler))
+```
+
+### `www(options)`
+
+Redirects non-www requests to the www subdomain.
+
+```ts
+www({ secure: true })  // also upgrades to https
+```
+
+## Middleware
+
+Middlewares are objects with optional `before` and `after` hooks. `before` runs before the handler; `after` runs after. Either can return a `Response` to short-circuit.
+
+```ts
+const myMiddleware: RouteMiddleware = {
+  before: ({ request, bind }) => {
+    bind({ startTime: Date.now() })
+  },
+  after: ({ response, startTime }) => {
+    response.headers.set("X-Duration", String(Date.now() - startTime))
+  },
+}
+```
+
+### `cors(options?)`
+
+Handles CORS preflight and response headers.
+
+| Option          | Type                                              | Default    |
+| --------------- | ------------------------------------------------- | ---------- |
+| `origin`        | `string \| string[] \| (origin: string) => boolean` | `"*"`      |
+| `methods`       | `string[]`                                        | all standard |
+| `allowHeaders`  | `string[]`                                        | mirrors request |
+| `exposeHeaders` | `string[]`                                        | --         |
+| `credentials`   | `boolean`                                         | `false`    |
+| `maxAge`        | `number`                                          | --         |
+
+### `cookies()`
+
+Parses request cookies and collects `Set-Cookie` headers on the response. Binds a `Cookies` object to context:
+
+```ts
+cookies.get("session")           // read
+cookies.set("session", token, {  // write
+  httpOnly: true,
+  secure: true,
+  sameSite: "strict",
+  maxAge: 86400,
+  path: "/",
+})
+```
+
+#### `CookieOptions`
+
+`domain`, `expires`, `httpOnly`, `maxAge`, `path`, `sameSite` (`"strict" | "lax" | "none"`), `secure`.
+
+### `bodyLimit(options?)`
+
+Rejects requests exceeding a body size or with disallowed content types.
+
+| Option         | Type       | Default   |
+| -------------- | ---------- | --------- |
+| `maxSize`      | `number`   | 1 MB      |
+| `contentTypes` | `string[]` | any       |
+
+### `cache(options)`
+
+Sets `Cache-Control` (and optionally `Vary`) headers on responses.
+
+```ts
+cache({ public: true, maxAge: 3600 })
+cache("no-store")
+```
+
+#### `CacheOptions`
+
+`public`, `private`, `maxAge`, `sMaxAge`, `noCache`, `noStore`, `mustRevalidate`, `proxyRevalidate`, `immutable`, `staleWhileRevalidate`, `staleIfError`, `vary`.
+
+### `csp(options)`
+
+Sets `Content-Security-Policy` headers. Supports automatic nonce generation via the `CSP.nonce` symbol -- the nonce is bound to context as `cspNonce`.
+
+```ts
+import { CSP } from "@sigitex/route"
+
+csp({
+  defaultSrc: [CSP.self],
+  scriptSrc: [CSP.self, CSP.nonce],
+  styleSrc: [CSP.self, CSP.unsafeInline],
+  imgSrc: [CSP.self, CSP.data],
+  reportOnly: true,
+})
+```
+
+### `csrf(options?)`
+
+Double-submit cookie CSRF protection. Requires `cookies()` in the middleware stack.
+
+| Option    | Type       | Default                          |
+| --------- | ---------- | -------------------------------- |
+| `cookie`  | `string`   | `"csrf-token"`                   |
+| `header`  | `string`   | `"X-CSRF-Token"`                 |
+| `methods` | `string[]` | POST, PUT, PATCH, DELETE         |
+
+### `rateLimit(options?)`
+
+IP-based rate limiting with pluggable storage.
+
+| Option    | Type               | Default                  |
+| --------- | ------------------ | ------------------------ |
+| `window`  | `number` (seconds) | `60`                     |
+| `max`     | `number`           | `100`                    |
+| `key`     | `(ctx) => string`  | `rateLimit.ip`           |
+| `store`   | `RateLimitStore`   | `rateLimit.memory()`     |
+| `headers` | `boolean`          | `true`                   |
+
+Built-in helpers:
+
+- `rateLimit.ip` -- key extractor using `CF-Connecting-IP` or `X-Forwarded-For`
+- `rateLimit.memory()` -- in-memory sliding window store
+
+### `hardened(options?)`
+
+Convenience bundle applying `noSniff`, `frameGuard`, `referrerPolicy`, and `hsts`. Any can be disabled:
+
+```ts
+hardened()                              // all defaults
+hardened({ hsts: false })               // skip HSTS
+hardened({ frameGuard: "sameOrigin" })  // override frame guard
+```
+
+### `hsts(options?)`
+
+Sets `Strict-Transport-Security`. Defaults: `max-age=31536000; includeSubDomains`.
+
+| Option              | Type      | Default     |
+| ------------------- | --------- | ----------- |
+| `maxAge`            | `number`  | `31536000`  |
+| `includeSubDomains` | `boolean` | `true`      |
+| `preload`           | `boolean` | `false`     |
+
+### `noSniff`
+
+Sets `X-Content-Type-Options: nosniff`.
+
+### `frameGuard.deny` / `frameGuard.sameOrigin`
+
+Sets `X-Frame-Options`.
+
+### `referrerPolicy.*`
+
+Pre-built policies: `noReferrer`, `noReferrerWhenDowngrade`, `origin`, `originWhenCrossOrigin`, `sameOrigin`, `strictOrigin`, `strictOriginWhenCrossOrigin`, `unsafeUrl`.
+
+### `requestId(options?)`
+
+Reads or generates a request ID, binds it to context as `requestId`, and echoes it on the response.
+
+| Option     | Type           | Default              |
+| ---------- | -------------- | -------------------- |
+| `header`   | `string`       | `"X-Request-Id"`     |
+| `generate` | `() => string` | `crypto.randomUUID`  |
+
+### `setHeader(header, value)`
+
+Sets a header on every response. Returns a `ResponseHandler` (use as an `after` hook).
+
+```ts
+{ after: setHeader("X-Powered-By", "sigitex") }
+```
+
+## Errors
+
+Error classes that can be thrown from handlers:
+
+| Class              | Status | Default Message          |
+| ------------------ | ------ | ------------------------ |
+| `RouterError`      | any    | --                       |
+| `NotFound`         | 404    | `"Not found."`           |
+| `MethodNotAllowed` | 405    | `"Method not allowed."`  |
+| `InvalidRequest`   | 400    | `"Invalid request."`     |
+| `ServerError`      | --     | `"Internal error."`      |

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",
@@ -21,9 +21,9 @@
     "@commitlint/config-conventional": "^20.5.3",
     "@markwylde/semantic-release-gitea": "^2.2.0",
     "@semantic-release/exec": "^7.0.3",
-    "@sigitex/bind": "*",
-    "@sigitex/ssjs": "*",
-    "@types/bun": "1.3.11",
+    "@sigitex/bind": "^1.0.0",
+    "@sigitex/ssjs": "^1.1.0",
+    "@types/bun": "^1.3.13",
     "@typescript/native-preview": "beta",
     "husky": "^9.1.7",
     "multi-semantic-release": "^3.1.0",
@@ -35,13 +35,13 @@
     "regexparam": "3.0.0"
   },
   "scripts": {
-    "check": "tsgo --noEmit && find . -mindepth 2 -name tsconfig.json -not -path '*/node_modules/*' -exec tsgo --noEmit -p {} \\;",
-    "test": "bun test --pass-with-no-tests",
+    "check": "tsgo --build",
+    "test": "bun test --pass-with-no-tests --tsconfig-override tsconfig.test.json",
     "prepare": "husky",
     "lint": "oxlint"
   },
   "files": [
     "src"
   ],
-  "version": "1.0.0"
+  "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/cloudflare/env.d.ts

@@ -0,0 +1 @@
+interface Env {}

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

package/src/bun/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "types": ["bun"]
-  },
-  "include": [".", "../env.d.ts"],
-  "exclude": []
-}

package/src/cloudflare/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "types": ["@cloudflare/workers-types"]
-  },
-  "include": [".", "../env.d.ts"],
-  "exclude": []
-}