expediate 1.0.4 → 1.0.6

package/docs/openapi.md

@@ -0,0 +1,180 @@
+# OpenAPI Spec Generation
+
+Expediate can generate an OpenAPI 3.1.0 document straight from your route definitions — no separate spec to hand-maintain. Annotate handlers with `describe()`, then call `openApiSpec()` (or `apiBuilder`'s `api.spec()` / `api.specHandler()`) to produce the document. Routes that aren't backed by a `ServiceDefinition` at all — e.g. JWT auth endpoints mounted directly with `app.post(...)` — can still be documented and merged into the same spec via a spec-only `ServiceOpenApi` source.
+
+---
+
+## Quick start
+
+```ts
+import { apiBuilder, describe } from 'expediate';
+import type { ServiceDefinition, ApiContext } from 'expediate';
+
+const service: ServiceDefinition<State> = {
+  GET: {
+    '/items/:id': describe(
+      function (this: State, ctx: ApiContext) { return this.findOrThrow(ctx.params.id); },
+      {
+        summary: 'Get an item by ID',
+        tags:    ['items'],
+        responses: {
+          '200': { description: 'The item' },
+          '404': { description: 'Not found' },
+        },
+      },
+    ),
+  },
+};
+
+const api = apiBuilder(service);
+app.use('/api', api);
+app.get('/openapi.json', api.specHandler({ title: 'Items API', version: '1.0.0' }));
+app.get('/openapi.yaml', api.specHandler({ title: 'Items API', version: '1.0.0' }, 'yaml'));
+```
+
+---
+
+## `describe(handler, meta)`
+
+Annotates a service method handler with OpenAPI operation metadata. The returned function behaves identically to `handler` — it can be used directly in a `ServiceDefinition` route map. Metadata is attached via a non-enumerable property keyed by the `DESCRIBE_META` symbol, so it never pollutes `Object.keys()` or `JSON.stringify()` output.
+
+```ts
+GET: {
+  '/todos/:id': describe(
+    function (this: State, ctx) { return this.findOrThrow(ctx.params.id); },
+    {
+      summary:    'Get a todo by ID',
+      tags:       ['todos'],
+      permission: 'todo.read',          // → auth.check + security in the spec
+      responses: {
+        '200': { description: 'The todo', content: { 'application/json': { schema: { $ref: '#/components/schemas/Todo' } } } },
+        '404': { description: 'Not found' },
+      },
+    },
+  ),
+}
+```
+
+`OperationMeta` fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `summary` | `string` | Short summary shown in UI tooling |
+| `description` | `string` | Longer description (Markdown supported) |
+| `operationId` | `string` | Overrides the auto-generated id (e.g. `getTodosById`) |
+| `tags` | `string[]` | UI grouping; falls back to controller `tags`, then the source's default tag |
+| `parameters` | `ParameterObject[]` | Merged with auto-detected path params by `name`; query/header/cookie params must be listed here — never auto-inferred |
+| `requestBody` | `RequestBodyObject` | Provide when the operation consumes a body |
+| `responses` | `Record<string, ResponseObject>` | Replaces the default response set entirely; a `'500'` reference to the built-in `ApiError` component is injected unless you supply your own `'500'` key |
+| `deprecated` | `boolean` | Marks the operation deprecated |
+| `guards` | `Guard[]` | Request-pipeline guards (ignored by spec generation) |
+| `permission` | `string \| string[]` | Overrides the controller-level `permission`; emits `security` + the permissions vendor extension |
+| `x-*` | `unknown` | Any other vendor extension is passed straight through |
+
+Unspecified fields are inferred: path parameters auto-detected from the route pattern, default responses assigned by HTTP verb (`POST` → `201`, others → `200`), and `operationId` generated from the verb + path.
+
+---
+
+## `openApiSpec(service, opts)`
+
+The free function underlying `api.spec()` — use it when you have a definition but not (or not only) a router built by `apiBuilder`.
+
+```ts
+import { openApiSpec } from 'expediate';
+
+const doc = openApiSpec(todoService, {
+  title:    'Todo API',
+  version:  '1.0.0',
+  basePath: '/api',
+});
+```
+
+Controllers merge into the same document as the root route map — see [API Builder](api-builder.md) for `controllers`, `guards`, and `auth`. The generated document always includes an `ApiError` schema (`{ status?, message?, data? }`) in `components.schemas` and a matching `500` reference in `components.responses`.
+
+### `SpecOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | **required** | API title |
+| `version` | `string` | **required** | API version |
+| `description` | `string` | — | API description |
+| `basePath` | `string` | — | Prefix prepended to every path |
+| `servers` | `{ url, description? }[]` | — | OpenAPI server objects |
+| `schemas` | `Record<string, JsonSchema>` | — | Extra component schemas (superseded by a source's own `schemas` on name conflicts) |
+
+### `api.spec(opts)` and `api.specHandler(opts, format?)`
+
+The router returned by `apiBuilder` can introspect its own definition — controllers included:
+
+```ts
+const api = apiBuilder(service);
+
+app.use('/api', api);
+app.get('/openapi.json', api.specHandler({ title: 'Todo API', version: '1.0.0' }));
+app.get('/openapi.yaml', api.specHandler({ title: 'Todo API', version: '1.0.0' }, 'yaml'));
+
+// Or get the document object directly:
+const doc = api.spec({ title: 'Todo API', version: '1.0.0', basePath: '/api' });
+```
+
+`specHandler` generates the spec once and caches it on the returned handler's first call. Both methods document the single `ServiceDefinition` passed to `apiBuilder` — for merging in routes from elsewhere, use `openApiSpec()` directly with multiple sources (below).
+
+---
+
+## Multiple sources
+
+`openApiSpec()` accepts a single source **or an array of sources**, merged into one document. This is how routes with no `ServiceDefinition` at all — most notably the JWT plugin's `/auth/login`, `/auth/refresh`, `/auth/logout`, typically mounted directly with `app.post(...)` — get documented alongside a real API:
+
+```ts
+import { openApiSpec } from 'expediate';
+import type { ServiceOpenApi } from 'expediate';
+
+const authDocs: ServiceOpenApi = {
+  openapi: { tag: 'auth' },
+  POST: {
+    '/auth/login':   { summary: 'Log in',          requestBody: loginBody },
+    '/auth/refresh': { summary: 'Refresh a token',  requestBody: refreshBody },
+    '/auth/logout':  { summary: 'Log out' },
+  },
+};
+
+const spec = openApiSpec([authDocs, todoService], { title: 'Todo API', version: '1.0.0' });
+```
+
+`ServiceOpenApi` is a spec-only counterpart to `ServiceDefinition`: same shape (`controllers`, root route maps, `schemas`, `auth`, service-level `openapi` metadata) but route map values are `OperationMeta` objects directly instead of handler functions, since there's no handler to call. `guards` and `validate` are accepted for structural parity only — spec generation ignores both, as there's no request pipeline to run them against. `ControllerOpenApi` and `RouteOpenApi` are the equivalent spec-only counterparts to `ControllerDefinition` and a handler route map.
+
+`OpenApiSource = ServiceDefinition<any> | ServiceOpenApi` is the type accepted by `openApiSpec()`, so a real service and a `ServiceOpenApi` mix in the same array with no casts needed.
+
+### Merge rules
+
+- **Routes** — every source's root route map and `controllers` are flattened into one globally-sorted route table (same specificity scoring as `apiBuilder`'s `collectRoutes`). A duplicate `(verb, path)` pair throws, even when the two routes come from different sources.
+- **Tags and `x-required-permissions`** — each route resolves its default tag (`openapi.tag`) and permissions vendor-extension name (`auth.permissionsExtension`) from **its own** originating source, not a single global value.
+- **`components.securitySchemes.bearerAuth`** — taken from the first source in array order that declares a custom `auth.scheme`; falls back to the default HTTP bearer/JWT scheme if none do.
+- **`components.schemas` / `components.responses`** — merged source by source in array order, so a later source's `schemas` wins on a name conflict. For a single source this reproduces the original precedence exactly: built-ins ← `openapi.schemas` ← `opts.schemas` ← the source's own `schemas`.
+
+Passing a single source (not wrapped in an array) behaves identically to the pre-multi-source API — `openApiSpec(service, opts)` and `openApiSpec([service], opts)` produce the same document.
+
+This merge logic (`collectOpenApiRoutes`) is entirely separate from `apiBuilder`'s request-handling pipeline — it only inspects route shapes to build documentation and never invokes a handler, so adding spec-only sources cannot affect runtime routing.
+
+---
+
+## Security output
+
+Routes carrying a `permission` (route- or controller-level) automatically receive `security: [{ bearerAuth: [] }]` and an `x-required-permissions: [...]` vendor extension (name overridable via `auth.permissionsExtension`). `components.securitySchemes.bearerAuth` is emitted once, only when at least one operation declares a permission, defaulting to:
+
+```json
+{ "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
+```
+
+---
+
+## `serializeSpec(doc, format?)`
+
+Serialize an `OpenApiDocument` to a JSON or YAML string (both zero-dependency):
+
+```ts
+import { serializeSpec } from 'expediate';
+
+const json = serializeSpec(doc);          // JSON (default), 2-space indented
+const yaml = serializeSpec(doc, 'yaml');  // block-style YAML 1.2
+```

package/docs/router.md

@@ -0,0 +1,356 @@
+# Router
+
+The core of Expediate is a zero-dependency HTTP router built on top of Node.js `http`/`https`. It supports named parameters, glob wildcards, regular expressions, nested sub-routers, signed cookies, per-request timeouts, and graceful shutdown.
+
+---
+
+## Creating a router
+
+```ts
+import { createRouter } from 'expediate';
+
+const app = createRouter();
+// or with options:
+const app = createRouter({
+  secret:     process.env.COOKIE_SECRET,   // for signed cookies
+  timeout:    30_000,                       // ms; 0 = disabled
+  trustProxy: true,                         // trust X-Forwarded-* headers
+});
+```
+
+`createRouter()` returns a `Router` which is itself a middleware function (`router.listener`), so it can be nested inside any other router.
+
+---
+
+## Route registration
+
+### HTTP method routes
+
+```ts
+router.get(path,    ...middleware)
+router.post(path,   ...middleware)
+router.put(path,    ...middleware)
+router.delete(path, ...middleware)
+router.patch(path,  ...middleware)
+router.all(path,    ...middleware)   // matches any HTTP method
+```
+
+Method routes use **endpoint matching**: the pattern must match the entire path (up to an optional trailing slash). `get('/users')` matches `/users` and `/users/` but **not** `/users/42`.
+
+### Prefix / mount routes
+
+```ts
+router.use(path, ...middleware)
+```
+
+`use()` uses **prefix matching**: the pattern is tested as a prefix, and the matched portion is **stripped from `req.path`** before the middleware is called. After the middleware calls `done()`, `req.path` is restored so sibling layers see the original path.
+
+This makes `use()` the correct mount mechanism for sub-routers and global middleware.
+
+### Middleware argument shapes
+
+Each slot accepts a `Middleware` function, a `Router` instance, or an array of either:
+
+```ts
+app.get('/admin', authGuard, adminHandler);
+app.get('/multi', [guard, logger], handler);
+app.use('/api',   apiRouter);             // Router instance
+app.use('/api',   apiRouter.listener);    // equivalent
+```
+
+### Fluent route builder
+
+`router.route(path)` returns a chainable `RouteBuilder` for registering several HTTP methods against the same path without repeating it:
+
+```ts
+app.route('/users/:id')
+  .get(getUser)
+  .put(updateUser)
+  .delete(deleteUser);
+
+// equivalent to:
+app.get('/users/:id',    getUser);
+app.put('/users/:id',    updateUser);
+app.delete('/users/:id', deleteUser);
+```
+
+`path` may be a string or `RegExp`. The builder exposes `.all/.get/.put/.post/.delete/.patch/.head/.options`, each registering on the underlying router and returning the same builder for further chaining.
+
+---
+
+## Path patterns
+
+### Plain strings with `:param` segments
+
+```ts
+app.get('/users/:id',             handler);  // req.params.id
+app.get('/orgs/:org/repos/:repo', handler);  // req.params.org, .repo
+```
+
+#### Inline regex constraints
+
+Append a constraint in parentheses to restrict what a parameter segment matches. Only requests whose segment passes the constraint reach the handler — others fall through:
+
+```ts
+app.get('/items/:id(\\d+)',        handler);  // digits only
+app.get('/files/:name([\\w-]+)',   handler);  // word chars + hyphens
+app.get('/v:ver(\\d+)/api',       handler);  // literal suffix after constraint
+```
+
+Named capture groups inside constraints are not allowed (they conflict with the outer `(?<name>…)` wrapper).
+
+### Glob patterns
+
+```ts
+app.use('/static/**', handler);  // any depth under /static/
+app.get('/api/*',     handler);  // exactly one path segment
+app.get('/**/*.php',  handler);  // PHP files anywhere
+app.get('/v?/status', handler);  // one character wildcard
+```
+
+Glob rules: `?` → one non-slash character; `*` → any non-slash characters; `**` → any characters including slashes (cross-segment).
+
+### Regular expressions
+
+Named capture groups become `req.params` entries:
+
+```ts
+app.get(/^\/users\/(?<id>\d+)/, handler);
+```
+
+> **Restriction:** RegExp patterns with the `g` (global) or `y` (sticky) flag are **rejected at registration time** with a `TypeError`. These flags make `exec()` stateful, causing intermittent routing failures across requests.
+
+---
+
+## Request fields
+
+The router augments every incoming request before any middleware runs. The augmentation is idempotent — safe across nested routers sharing the same request object.
+
+| Field | Type | Description |
+|---|---|---|
+| `req.originalUrl` | `string` | Raw URL string, never modified |
+| `req.path` | `string` | Pathname; rewritten by `use()` layers for sub-routers |
+| `req.params` | `Record<string, string>` | Merged URL query params + named route params (flat, first-value for repeated keys) |
+| `req.query` | `Record<string, string \| string[]>` | URL query parameters; repeated keys produce arrays. Alias for `req.queries.url` |
+| `req.queries.url` | same as above | Structured query string bucket |
+| `req.queries.route` | `Record<string, string>` | Named route parameters from the matched pattern |
+| `req.cookies` | `Record<string, unknown>` | Parsed `Cookie` header. `j:` values are JSON-decoded; `s:` values are HMAC-verified (requires `secret`) |
+| `req.ip` | `string` | Remote client IP. With `trustProxy: true`: first `X-Forwarded-For` value |
+| `req.ips` | `string[]` | Full `X-Forwarded-For` chain (oldest first). Empty when `trustProxy` is disabled |
+| `req.hostname` | `string` | `Host` header with port stripped. With `trustProxy: true`: taken from `X-Forwarded-Host` |
+| `req.protocol` | `string` | `'http'` or `'https'`. With `trustProxy: true`: taken from `X-Forwarded-Proto` |
+| `req.secure` | `boolean` | `true` when `req.protocol === 'https'` |
+| `req.baseUrl` | `string` | Accumulated path prefix stripped by parent `use()` mounts. `''` at the root level |
+| `req.json(opts?)` | `Promise<unknown\|null>` | Parse request body as JSON. Returns cached value if body already parsed |
+| `req.text(opts?)` | `Promise<string\|null>` | Decode request body as plain text |
+| `req.formData(opts?)` | `Promise<FormPart[]\|null>` | Parse request body as `multipart/form-data` |
+
+### Cookies
+
+Cookie values are decoded automatically:
+
+- Plain strings are returned as-is.
+- `j:<json>` prefixed values are JSON-parsed.
+- `s:<sig>.<value>` prefixed values are HMAC-SHA256 verified; cookies that fail verification are silently dropped. Requires `secret` option on `createRouter()`.
+
+---
+
+## Response helpers
+
+Every response is augmented with convenience methods. All chainable helpers return `this`.
+
+```ts
+res.send('Hello');                      // write string body and end
+res.send();                             // end with no body
+res.json({ ok: true });                 // set Content-Type: application/json and end
+res.status(404).send('Not Found');      // set status code (validated 100–999)
+res.status(201, { 'X-Id': '42' }).end(); // set status + headers
+res.redirect('/new-path');              // 302 Found
+
+res.type('text/csv').send(data);        // set Content-Type (chainable)
+res.etag('v1').json(payload);           // weak ETag W/"v1" (chainable)
+res.etag(sha256, true).send(buf);       // strong ETag "sha256"
+
+res.cookie('session', 'abc', {
+  maxAge:   3_600_000,                  // ms; also sets Expires
+  path:     '/api',
+  httpOnly: true,
+  secure:   true,
+  sameSite: 'Strict',
+  signed:   true,                       // HMAC-sign (requires router secret)
+});
+res.clearCookie('session');             // Max-Age=0, Expires=epoch
+res.clearCookie('tok', { path: '/admin' }); // match original options
+
+res.download('/path/file.pdf');         // Content-Disposition: attachment
+res.download('/path/file.pdf', 'invoice.pdf'); // custom filename
+res.attachment('report.pdf').send(buf); // set disposition + Content-Type, no file I/O
+
+res.append('X-Custom', 'v1');           // append to header (comma-joins; Set-Cookie accumulates)
+res.vary('Accept');                     // add to Vary header, deduplicating
+res.vary(['Accept', 'Accept-Encoding']);
+res.location('/new-path');              // set Location header
+res.sendStatus(200);                    // set status + send standard text body
+
+res.locals['user'] = currentUser;       // request-scoped storage for middleware chains
+```
+
+### `res.status()` validation
+
+The code must be an integer in the range `100–999`. Passing a non-integer or out-of-range value throws a `RangeError` at call time, which is caught by the router error handler.
+
+### Cookies — writing
+
+Setting a cookie with `signed: true` produces an `s:<hmac>.<value>` string. The router's `secret` is required. Objects are serialised with a `j:` prefix and JSON-decoded on read.
+
+---
+
+## Error handling
+
+→ Full reference: [errors.md](errors.md)
+
+Synchronous throws, async rejections, and `next(err)` calls all enter the router's **error channel**, which resolves through an ordered `error()` chain, an `onError()` fallback, and finally **bubbles to parent routers** before defaulting to `500`.
+
+### Ordered error handlers (`error()`)
+
+```ts
+app.error((err, _req, res, next) => {
+  if ((err as any)?.status === 404) return res.status(404).json({ error: 'Not Found' });
+  next(err); // forward to the next handler, or bubble to the parent router
+});
+
+app.error((err, _req, res, _next) =>
+  res.status((err as any)?.status ?? 500).json({ error: String(err) }));
+```
+
+The error value is the **first** argument. `next()` forwards the same error; `next(err)` replaces it. Handlers run in registration order until one ends the response.
+
+### Single terminal fallback (`onError()`)
+
+```ts
+app.onError((err, _req, res) => {
+  const status = (err as any)?.status ?? 500;
+  res.status(status).json({ error: String(err) });
+});
+```
+
+`onError()` is the simple, single catch-all. It runs after the `error()` chain is exhausted and, unlike `error()`, does **not** bubble — it is terminal for its router. Without any handler, the default sends `500` and logs to `console.warn`.
+
+### Custom 404 handler
+
+Register a catch-all as the **last** layer. Layers match in registration order, so it runs only when no earlier route handled the request. `/**` matches any path and `all()` matches any method:
+
+```ts
+app.all('/**', (_req, res) => res.status(404).json({ error: 'Not Found' }));
+```
+
+With no catch-all, unmatched requests fall back to the built-in `Cannot METHOD /path` 404.
+
+### Passing errors through middleware
+
+```ts
+app.use('/protected', (req, _res, next) => {
+  if (!req.headers.authorization) return next(new Error('Unauthorized'));
+  next();
+});
+```
+
+Calling `next(err)` skips remaining route layers and enters the error channel directly.
+
+---
+
+## Sub-routers and `req.baseUrl`
+
+Routers are fully nestable. The matched prefix is stripped from `req.path` when mounted with `use()`:
+
+```ts
+const api = createRouter();
+api.get('/users',     listUsers);
+api.get('/users/:id', getUser);
+
+const app = createRouter();
+app.use('/api/v1', api);  // /api/v1/users → api sees req.path = '/users'
+                          //                  req.baseUrl = '/api/v1'
+```
+
+`req.baseUrl` accumulates the stripped prefix as the request descends through nested `use()` mounts. It is `''` at the root level and is restored for sibling layers after a sub-router calls `done()`.
+
+### Prefix router creation
+
+```ts
+const v1 = createRouter('/api/v1');  // implicitly strips this prefix
+app.use(v1);
+```
+
+---
+
+## Starting the server
+
+`router.listen()` returns the underlying `http.Server` (or `https.Server`, or `http2.Http2SecureServer`) instance:
+
+```ts
+// Plain HTTP
+const server = app.listen(3000, () => console.log('Ready'));
+
+// HTTPS
+app.listen(443, {
+  key:  readFileSync('server.key'),
+  cert: readFileSync('server.crt'),
+});
+
+// HTTP/2 (requires TLS)
+app.listen(443, { key, cert, http2: true });
+
+// Ephemeral port (useful in tests)
+const server = app.listen(0, () => {
+  const { port } = server.address() as AddressInfo;
+  console.log(`Listening on :${port}`);
+});
+```
+
+### Graceful shutdown
+
+```ts
+process.on('SIGTERM', () => app.shutdown(10_000)); // 10 s drain window
+```
+
+### Request timeout
+
+```ts
+const app = createRouter({ timeout: 30_000 }); // 408 after 30 s of no response
+```
+
+---
+
+## Introspecting registered routes
+
+```ts
+console.log(app.routes());
+// [{ method: 'GET', path: '/users', stripPath: false }, ...]
+```
+
+`method` is `null` for `use()` / `all()` layers. `stripPath: true` identifies `use()` layers.
+
+---
+
+## CookieOptions reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `signed` | `boolean` | `false` | HMAC-sign the value (requires router `secret`) |
+| `expires` | `Date` | — | Expiry date |
+| `maxAge` | `number` | — | Max age in **milliseconds** (also derives `Expires`) |
+| `path` | `string` | `'/'` | Cookie path |
+| `httpOnly` | `boolean` | `false` | Mark `HttpOnly` |
+| `secure` | `boolean` | `false` | Mark `Secure` |
+| `sameSite` | `'Strict'\|'Lax'\|'None'` | — | `SameSite` attribute |
+
+---
+
+## RouterOptions reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `secret` | `string` | — | Cookie-signing secret. Required for signed cookies |
+| `timeout` | `number` | `0` (disabled) | Request timeout in milliseconds |
+| `trustProxy` | `boolean` | `false` | Trust `X-Forwarded-*` headers |

package/docs/static.md

@@ -0,0 +1,128 @@
+# Static File Serving
+
+Expediate includes a full static file serving implementation with ETag caching, conditional GET, MIME detection, dot-file policies, path traversal protection, and an optional directory listing.
+
+---
+
+## `serveStatic(root, opts?)`
+
+Serve all files under a directory:
+
+```ts
+import { serveStatic } from 'expediate';
+
+app.use('/public', serveStatic('./dist'));
+```
+
+### StaticOptions
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fallthrough` | `boolean` | `true` | Call `next()` instead of 404 for missing files/paths |
+| `dotfiles` | `'allow' \| 'deny' \| 'hide'` | `'hide'` | Dot-file access: `allow` serves them, `deny` sends 403, `hide` sends 404 |
+| `redirect` | `boolean` | `true` | Redirect bare directory URLs to their trailing-slash form |
+| `index` | `string` | `'index.html'` | Default file to serve for directory requests |
+| `etag` | `boolean` | `true` | Send weak `ETag` header (`W/"<size_hex>-<mtime_hex>"`) |
+| `lastModified` | `boolean` | `true` | Send `Last-Modified` header |
+| `maxage` / `maxAge` | `number` | `0` | Cache lifetime in **milliseconds** → `Cache-Control: public, max-age=<s>` |
+| `immutable` | `boolean` | `false` | Append `, immutable` to `Cache-Control` |
+| `contentType` | `string \| null` | `null` | Override the auto-detected `Content-Type` |
+| `headers` | `Record<string, string>` | security defaults | Extra response headers, merged with built-in security headers |
+| `indexOf` | `boolean` | `false` | Enable Apache-style directory listing |
+
+### HTTP methods
+
+Only `GET` and `HEAD` are served. Other methods receive **405 Method Not Allowed** (or fall through if `fallthrough: true`).
+
+### Default security headers
+
+Every static response includes these headers by default:
+
+```
+Content-Security-Policy: default-src 'self'
+X-Content-Type-Options: nosniff
+```
+
+### Conditional GET (caching)
+
+`serveStatic` honours `If-None-Match` and `If-Modified-Since` request headers. When the client's cached version is still fresh, a `304 Not Modified` is returned with no body. `Cache-Control: no-cache` forces a full response even when the ETag matches.
+
+`If-Match` and `If-Unmodified-Since` are also honoured: when the condition fails, the response is `412 Precondition Failed` instead of serving the file.
+
+---
+
+## `serveFile(filepath, opts?)`
+
+Serve a single fixed file for every request — useful for SPA catch-all routes:
+
+```ts
+import { serveFile } from 'expediate';
+
+// Serve dist/index.html for every unmatched path
+app.get('/**', serveFile('./dist/index.html'));
+```
+
+Accepts the same options as `serveStatic()`. Returns `500 EISDIR` if the path resolves to a directory.
+
+---
+
+## `sendFile(req, res, filepath, opts?)`
+
+Low-level utility for sending a dynamically resolved file path. Does not require middleware wrapping:
+
+```ts
+import { sendFile } from 'expediate';
+
+app.get('/downloads/:name', (req, res) => {
+  const fp = path.join('./downloads', req.params.name);
+  sendFile(req as any, res as any, fp);
+});
+```
+
+---
+
+## MIME type detection
+
+The `mime` object provides type lookup:
+
+```ts
+import { mime } from 'expediate';
+
+mime.lookup('image.png');              // 'image/png'
+mime.lookup('archive.tar.gz');         // 'application/gzip'
+mime.lookup('file', 'text/plain');     // fallback to 'text/plain' if unknown
+mime.charsets('text/html');            // 'UTF-8'
+mime.charsets('image/png');            // null
+```
+
+MIME types are loaded from a bundled `mimetypes.json` file.
+
+---
+
+## Directory listing
+
+When `indexOf: true`, requesting a directory URL generates an Apache-style HTML listing with sortable columns:
+
+```ts
+app.use('/', serveStatic('./public', { indexOf: true }));
+```
+
+Sort controls use query parameters: `C` for column (`N`=name, `M`=mtime, `S`=size) and `O` for order (`A`=ascending, `D`=descending). Directories always sort above files regardless of the active column.
+
+All user-controlled content (URL paths, filenames) is **HTML-escaped** before being inserted into the page. Link `href` values use `encodeURIComponent`. This prevents XSS when a directory contains files with HTML-significant names.
+
+---
+
+## Security
+
+### Path traversal protection
+
+All resolved file paths are checked against the declared root. Any path that resolves outside the root is rejected with `403 Forbidden`. This is a defense-in-depth check that runs after the `..` segment guard (`/(\/|^)(\.\.?)(\/|$)/`).
+
+### Malformed percent-encoding
+
+Requests with malformed percent-encoded characters in the path (e.g. `/%zz`, `/%a`) receive `400 Bad Request` instead of a 500 error.
+
+### Dot-file policy
+
+The default `dotfiles: 'hide'` policy responds with `404` for paths that include a dot-file segment, without revealing whether the file exists.