weifuwu 0.30.0 → 0.30.2

package/README.md

@@ -2,8 +2,6 @@
 
 Web-standard HTTP microframework for Node.js — `(req, ctx) => Response`.
 
-## Usage
-
 ```bash
 npm install weifuwu
 ```
@@ -18,35 +16,24 @@ serve(app, { port: 3000 })
 
 ## Exports
 
-Everything is exported from `'weifuwu'`:
-
 ### Core
 
-| Export | Kind | Description |
-|---|---|---|
-| `serve(app, opts?)` | function | Start HTTP server. Takes a `Router`. Returns `Server`. |
-| `Router` | class | Trie-based HTTP router with WebSocket support. |
-| `loadEnv(path?)` | function | Load `.env` file into `process.env`. |
-| `isDev()` | function | `true` unless `NODE_ENV` is `production` or `test`. |
-| `isProd()` | function | `true` if `NODE_ENV` is `production`. |
-| `isBundled()` | function | `true` when running the esbuild bundle (checks `__WFW_BUNDLED__`). |
-| `getPublicEnv()` | function | Returns all `process.env` keys prefixed with `WEIFUWU_PUBLIC_`. |
-| `DEFAULT_MAX_BODY` | const | `10 * 1024 * 1024` (10MB). |
+| Export | Description |
+|---|---|
+| `serve(app, opts?)` | Start HTTP server. Returns `Server` with `port`, `hostname`, `ready`, `close()`. |
+| `Router` | Trie-based HTTP router with WebSocket support. |
+| `HttpError` | `new HttpError(message, status)`. Throw to return that status code. |
+| `DEFAULT_MAX_BODY` | `10 * 1024 * 1024` (10MB). |
 
-### Router
+### Router API
 
 ```ts
 const app = new Router()
 
 // HTTP methods
 app.get(path, ...handlers)
-app.post(path, ...handlers)
-app.put(path, ...handlers)
-app.delete(path, ...handlers)
-app.patch(path, ...handlers)
-app.head(path, ...handlers)
-app.options(path, ...handlers)
-app.all(path, ...handlers)    // match any method
+app.post / put / delete / patch / head / options(path, ...handlers)
+app.all(path, ...handlers)    // any method
 
 // WebSocket
 app.ws(path, ...middlewares, handler)
@@ -54,183 +41,145 @@ app.ws(path, ...middlewares, handler)
 
 // Middleware & mounting
 app.use(middleware)           // global middleware
-app.mount(prefix, router)     // mount sub-router at prefix
-app.onError(handler)          // global error handler
-app.routes()                  // debug: string[] of all registered routes
+app.mount(prefix, router)     // sub-router at prefix
+app.onError(handler)          // error handler: (error, req, ctx) => Response
+app.routes()                  // debug: list all registered routes
 
 // Path params
 app.get('/users/:id', (req, ctx) => {
-  const id = ctx.params.id   // string
-  const q = ctx.query.search // from ?search=...
+  ctx.params.id   // string
+  ctx.query.search // from ?search=...
 })
 ```
 
 ### Middleware
 
-| Export | Kind | Description |
-|---|---|---|
-| `cors(opts?)` | middleware | CORS headers. `origin`, `methods`, `headers`, `credentials`, `maxAge`. |
-| `helmet(opts?)` | middleware | Security headers (CSP, HSTS, X-Frame-Options, etc). |
-| `compress(opts?)` | middleware | gzip / brotli / deflate response compression. |
-| `rateLimit(opts?)` | middleware | Sliding-window rate limiter. `windowMs`, `max`, `keyGenerator`. |
-| `requestId(opts?)` | middleware | Generates `X-Request-ID` header. `header`, `generator`. |
-| `logger(opts?)` | middleware | Structured request logging. `format`, `level`, `stream`. |
-| `validate(schemas?)` | middleware | Zod-based request validation. `{ body?, query?, params?, headers? }`. |
-| `upload(opts?)` | middleware | Multipart file upload. `maxSize`, `dest`, `preservePath`. |
-| `health(opts?)` | function→Router | Health check router. Mount at `/_health` or custom path. |
-| `env()` | middleware | Injects `WEIFUWU_PUBLIC_*` env vars into `ctx.env`. |
-| `trace(opts?)` | middleware | Injects trace context into `ctx.trace` (requestId, traceId, startTime, elapsed). |
-
-### Route-level tools
-
-| Export | Kind | Description |
-|---|---|---|
-| `serveStatic(root, opts?)` | handler | Serve static files. `cacheControl`, `index`, `dotfiles`. |
-| `graphql(options)` | function→Router | GraphQL endpoint. Pass a `GraphQLHandler` function `({ query, variables, ctx })`. |
-
-### HTML rendering
-
-| Export | Kind | Description |
-|---|---|---|
-| `html(template, ...values)` | tagged template | Auto-escaped HTML builder. Signal/Computed-aware. |
-| `raw(content)` | function | Raw unescaped HTML string (use with caution). |
-
-### SSE (Server-Sent Events)
-
-| Export | Kind | Description |
-|---|---|---|
-| `createSSEStream()` | function | Create an SSE stream controller for `text/event-stream` responses. |
-| `formatSSE(event, data)` | function | Format a single SSE event string. |
-| `formatSSEData(data)` | function | Format SSE data string. |
-
-### Cookies
-
-| Export | Kind | Description |
-|---|---|---|
-| `getCookies(req)` | function | Parse cookies from `Request`. Returns `Record<string, string>`. |
-| `setCookie(headers, name, value, opts?)` | function | Set `Set-Cookie` header. `path`, `domain`, `maxAge`, `httpOnly`, `secure`, `sameSite`, `partitioned`. |
-| `deleteCookie(headers, name, opts?)` | function | Delete a cookie (Max-Age=0). |
+| Export | Description |
+|---|---|
+| `cors(opts?)` | CORS headers. `origin`, `methods`, `headers`, `credentials`, `maxAge`. |
+| `helmet(opts?)` | Security headers: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, etc. |
+| `compress(opts?)` | gzip / brotli / deflate response compression. |
+| `rateLimit(opts?)` | Sliding-window rate limiter. `windowMs`, `max`, `keyGenerator`, Redis backend. |
+| `logger(opts?)` | Request logging. `format: 'short' | 'combined' | 'json'`. |
+| `upload(opts?)` | Multipart file upload via `req.formData()`. Injects `ctx.parsed`. |
+| `serveStatic(root, opts?)` | Static file handler. `cacheControl`, `index`. |
+| `trace(opts?)` | Injects `ctx.trace = { requestId, traceId, elapsed(), startTime }`. |
 
-### Postgres
+### Tracing
 
-| Export | Kind | Description |
-|---|---|---|
-| `postgres(opts?)` | middleware+client | Create a Postgres client. `url`, `host`, `port`, `database`, `user`, `password`, `max`. |
-| `MIGRATIONS_TABLE` | const | Migration table name: `_weifuwu_migrations`. |
+| Export | Description |
+|---|---|
+| `currentTraceId()` | Current request's trace ID (AsyncLocalStorage). |
+| `currentTrace()` | Current trace context `{ traceId, startTime }`. |
+| `runWithTrace(id, fn)` | Run `fn` in a trace context. Auto-generates UUID if id is null. |
+| `traceElapsed()` | Milliseconds since trace start. |
+| `trace(opts?)` | Middleware that injects `ctx.trace`. |
+
+### Postgres
 
 ```ts
+import { postgres, MIGRATIONS_TABLE } from 'weifuwu'
+
 const sql = postgres({ url: process.env.DATABASE_URL })
+app.use(sql)  // injects ctx.sql
 
-// As middleware — injects ctx.sql
-app.use(sql)
-// As query client
-const rows = await sql.client`SELECT * FROM users WHERE id = ${id}`
+const rows = await sql.sql`SELECT * FROM users WHERE id = ${id}`
 
 // Migrations
 await sql.migrate({
-  '001_init': async (s) => {
-    await s`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`
-  },
+  '001_init': async (s) => await s`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`,
 })
 ```
 
 ### Redis
 
-| Export | Kind | Description |
-|---|---|---|
-| `redis(opts?)` | middleware+client | Create a Redis client (ioredis). `url`, `host`, `port`, `password`, `db`. |
-
 ```ts
+import { redis } from 'weifuwu'
+
 const r = redis({ url: process.env.REDIS_URL })
 app.use(r)  // injects ctx.redis
-await r.client.set('key', 'value')
+await r.redis.set('key', 'value')
 ```
 
 ### Queue & Cron
 
-| Export | Kind | Description |
-|---|---|---|
-| `queue(opts?)` | middleware+instance | In-process job queue with cron support. `concurrency`. |
-
 ```ts
-const q = queue({ concurrency: 3 })
+import { queue } from 'weifuwu'
+
+const q = queue()
 app.use(q)  // injects ctx.queue
 
-q.process('send-email', async (job) => {
-  await sendEmail(job.data.to)
+q.process('email', async (job) => {
+  await sendEmail(job.payload.to)
 })
 
 q.cron('cleanup', '0 3 * * *', async () => {
   await cleanupOldSessions()
 })
 
-await q.add('send-email', { to: 'user@example.com' })
+await q.add('email', { to: 'user@example.com' })
+await q.add('remind', {}, { delay: 60_000 })
+await q.add('report', {}, { schedule: '0 9 * * 1' })
+
+q.run()  // start processing
 ```
 
 ### WebSocket Hub
 
-| Export | Kind | Description |
-|---|---|---|
-| `createHub(opts?)` | function | Pub/Sub hub for cross-connection broadcast. Supports Redis adapter for multi-process. |
-
 ```ts
+import { createHub } from 'weifuwu'
+
 const hub = createHub()
 app.ws('/chat', {
   open(ws, ctx) {
     ctx.ws.join('lobby')
-    ctx.ws.json({ type: 'join', room: 'lobby' })
+    ctx.ws.json({ type: 'join' })
   },
   message(ws, ctx, data) {
-    ctx.ws.sendRoom('lobby', { type: 'chat', text: data.toString() })
+    ctx.ws.sendRoom('lobby', { text: data.toString() })
   },
 })
 ```
 
-### Theme & I18n
-
-| Export | Kind | Description |
-|---|---|---|
-| `theme(opts?)` | middleware+Router | Theme middleware. Injects `ctx.theme` with `get()`, `set(theme)`, `toggle()`. Routes: `/__theme/:theme`. |
-| `i18n(opts?)` | middleware+Router | I18n middleware. Injects `ctx.i18n` with `locale`, `t(key, params?)`, `set(locale)`. `dir` for locale JSON files. Routes: `/__lang/:locale`. |
-| `flash()` | middleware | Flash messages. Injects `ctx.flash` with `set(msg)`, `get()`. One-time messages across redirects. |
-| `csrf()` | middleware | CSRF protection. Injects `ctx.csrf` with `token`. Auto-validates on `POST`/`PUT`/`PATCH`/`DELETE`. |
+### GraphQL
 
-### Tracing
-
-| Export | Kind | Description |
-|---|---|---|
-| `currentTraceId()` | function | Get current request's trace ID (from AsyncLocalStorage). |
-| `currentTrace()` | function | Get current trace context `{ traceId, startTime }`. |
-| `runWithTrace(id, fn)` | function | Run `fn` with a trace context. Auto-generates ID if null. |
-| `traceElapsed()` | function | Milliseconds since trace start. |
-
-### Error handling
-
-| Export | Kind | Description |
-|---|---|---|
-| `HttpError` | class | `new HttpError(message, status)`. Throw to return that status. |
-| `app.onError(handler)` | Router method | Global error handler: `(error, req, ctx) => Response`. |
-
-### Testing
+```ts
+import { graphql } from 'weifuwu'
+
+const gql = graphql((req, ctx) => ({
+  schema: `
+    type Query {
+      hello: String
+      user(id: ID!): User
+    }
+    type User {
+      id: ID
+      name: String
+    }
+  `,
+  resolvers: {
+    Query: {
+      hello: () => 'world',
+      user: (_, { id }) => ctx.sql`SELECT * FROM users WHERE id = ${id}`.then(r => r[0]),
+    },
+  },
+  graphiql: true,
+}))
 
-| Export | Kind | Description |
-|---|---|---|
-| `testApp(app)` | function | Create a test client for a Router. Returns `{ get, post, put, delete, patch }` for `(path, opts?)`. |
-| `createTestServer(app, opts?)` | function | Start a test server on a random port. Returns `{ server, url }`. |
-| `createTestDb()` | function | Create an ephemeral Postgres test database. |
-| `withTestDb(fn)` | function | Run `fn(sql)` with a temp database, auto-cleanup. |
+app.mount('/graphql', gql)
+```
 
 ### Types
 
 | Export | Description |
 |---|---|
-| `Context` | `{ params, query, mountPath?, user?, loaderData?, env?, [key: string] }` |
+| `Context` | `{ params, query, mountPath?, [key: string] }` |
 | `Handler<T>` | `(req: Request, ctx: T) => Response \| Promise<Response>` |
-| `Middleware<In, Out>` | `(req, ctx, next) => Response \| Promise<Response>` |
+| `Middleware` | `(req, ctx, next) => Response \| Promise<Response>` |
 | `WebSocketHandler` | `{ open?, message?, close?, error? }` |
 | `HttpError` | `Error` subclass with `.status: number` |
 | `Closeable` | `{ close(): Promise<void> }` |
-| `Server` | `{ stop, close, port, hostname, ready }` |
+| `Server` | `{ close, port, hostname, ready }` |
 | `ServeOptions` | `{ port, hostname, signal, maxBodySize, timeout, keepAliveTimeout, headersTimeout, shutdown }` |
 
 ## Handler / Middleware patterns
@@ -238,14 +187,13 @@ app.ws('/chat', {
 ```ts
 // Handler — standard Web API
 app.get('/api/data', (req, ctx) => {
-  const { q } = ctx.query
-  const id = ctx.params.id
-  return Response.json({ q, id })
+  const q = ctx.query.q
+  return Response.json({ q })
 })
 
 // Async
 app.get('/db/users', async (req, ctx) => {
-  const rows = await sql`SELECT * FROM users`
+  const rows = await ctx.sql`SELECT * FROM users`
   return Response.json(rows)
 })
 
@@ -264,15 +212,11 @@ app.use(async (req, ctx, next) => {
   return res
 })
 
-// Route-level middleware (before handler)
-app.get('/admin', validate(bodySchema), authCheck, adminHandler)
-
 // Error handler
 app.onError((err, req, ctx) => {
   if (err instanceof HttpError) {
     return Response.json({ error: err.message }, { status: err.status })
   }
-  console.error(err)
   return new Response('Internal error', { status: 500 })
 })
 ```
@@ -280,85 +224,52 @@ app.onError((err, req, ctx) => {
 ## Complete example
 
 ```ts
-import { serve, Router, loadEnv, cors, helmet, compress, logger, requestId, rateLimit, postgres, redis, queue, HttpError, html } from 'weifuwu'
-
-loadEnv()
+import { serve, Router, cors, helmet, compress, logger, trace, rateLimit, postgres, redis, queue, HttpError } from 'weifuwu'
 
 const app = new Router()
 
 // Global middleware
-app.use(requestId())
+app.use(trace())
 app.use(logger())
 app.use(cors())
 app.use(helmet())
 app.use(compress())
 app.use(rateLimit({ windowMs: 60_000, max: 100 }))
 
-// Database & services
-const sql = postgres({ url: process.env.DATABASE_URL })
-const cache = redis({ url: process.env.REDIS_URL })
-const jobs = queue()
-
+// Database
+const sql = postgres()
 app.use(sql)
-app.use(cache)
-app.use(jobs)
 
 // Routes
-app.get('/', () => html`<h1>weifuwu</h1><p>Running on ${process.version}</p>`)
-
 app.get('/api/users', async (req, ctx) => {
-  const users = await ctx.sql`SELECT id, name, email FROM users ORDER BY id`
+  const users = await ctx.sql`SELECT id, name FROM users ORDER BY id`
   return Response.json(users)
 })
 
-app.get('/api/users/:id', async (req, ctx) => {
-  const [user] = await ctx.sql`SELECT * FROM users WHERE id = ${ctx.params.id}`
-  if (!user) throw new HttpError('User not found', 404)
-  return Response.json(user)
-})
-
 app.post('/api/users', async (req, ctx) => {
   const { name, email } = await req.json()
-  const [user] = await ctx.sql`INSERT INTO users (name, email) VALUES (${name}, ${email}) RETURNING *`
+  const [user] = await ctx.sql`INSERT INTO users (name,email) VALUES (${name},${email}) RETURNING *`
   return Response.json(user, { status: 201 })
 })
 
-// Background job
-jobs.process('welcome-email', async (job) => {
-  const { userId } = job.data
-  const [user] = await sql.client`SELECT * FROM users WHERE id = ${userId}`
-  await sendWelcomeEmail(user.email)
-})
-
-app.post('/api/register', async (req, ctx) => {
-  const { name, email } = await req.json()
-  const [user] = await ctx.sql`INSERT INTO users (name, email) VALUES (${name}, ${email}) RETURNING *`
-  await ctx.queue.add('welcome-email', { userId: user.id })
-  return Response.json(user, { status: 201 })
+app.get('/api/users/:id', async (req, ctx) => {
+  const [user] = await ctx.sql`SELECT * FROM users WHERE id = ${ctx.params.id}`
+  if (!user) throw new HttpError('Not found', 404)
+  return Response.json(user)
 })
 
-// WebSocket chat
+// WebSocket
 app.ws('/chat', {
-  open(ws, ctx) {
-    ctx.ws.join('lobby')
-  },
-  message(ws, ctx, data) {
-    ctx.ws.sendRoom('lobby', { text: data.toString() })
-  },
+  open(ws, ctx) { ctx.ws.join('lobby') },
+  message(ws, ctx, data) { ctx.ws.sendRoom('lobby', { text: data.toString() }) },
 })
 
 // Error handling
-app.onError((err, req, ctx) => {
-  if (err instanceof HttpError) {
-    return Response.json({ error: err.message }, { status: err.status })
-  }
+app.onError((err) => {
+  if (err instanceof HttpError) return Response.json({ error: err.message }, { status: err.status })
   return Response.json({ error: 'Internal error' }, { status: 500 })
 })
 
-// Health check
-import { health } from 'weifuwu'
-app.mount('/_health', health())
-
 serve(app, { port: 3000 })
 ```
 
@@ -368,27 +279,28 @@ serve(app, { port: 3000 })
 weifuwu/
 ├── package.json
 ├── tsconfig.json
+├── docker-compose.yml      ← postgres + redis for tests
 ├── scripts/
 │   ├── build.mjs
 │   └── release.mjs
 ├── src/
-│   ├── index.ts              ← all exports
-│   ├── types.ts              ← Context, Handler, Middleware, HttpError
-├── core/                 ← serve, router, trace, env, logger, cookie, sse, html
-│   ├── middleware/        ← cors, compress, helmet, rate-limit, static, validate, upload, health, theme, i18n, flash, csrf, request-id
-├── postgres/             ← postgres client, migrations, module injection
-│   ├── redis/                ← redis client
-│   ├── queue/                ← job queue, cron
-│   ├── graphql.ts            ← schema-first GraphQL handler
-│   ├── hub.ts                ← pub/sub hub (WebSocket rooms)
-│   └── test/                 ← 324 tests
+│   ├── index.ts
+│   ├── types.ts
+│   ├── core/               ← serve, router, ws, trace, logger
+│   ├── middleware/          ← cors, helmet, compress, rate-limit, static, upload
+│   ├── postgres/
+│   ├── redis/
+│   ├── queue/              ← cron, index, types
+│   ├── graphql.ts
+│   ├── hub.ts
+│   └── test/               ← 122 tests (18 files)
 └── dist/
 ```
 
 ## Development
 
 ```bash
-npm run build          # esbuild bundle → dist/index.js
+npm run build          # esbuild → dist/index.js
 npm run typecheck      # tsc --noEmit
-npm test              # node --test (324 tests, 0 failures)
+npm test              # 122 tests (requires docker compose)
 ```

package/dist/core/router.d.ts

@@ -1,30 +1,17 @@
-import type { WebSocket, Context, Handler, Middleware, ErrorHandler } from '../types.ts';
-import { type IncomingMessage } from 'node:http';
-import type { Duplex } from 'node:stream';
+import type { Context, Handler, Middleware, ErrorHandler } from '../types.ts';
 import { type Hub } from '../hub.ts';
+import { type WebSocketHandler, type WsUpgradeHandler } from './ws.ts';
 declare module '../types.ts' {
     interface Context {
         ws: {
-            /** Per-connection state object */
             state: Record<string, unknown>;
-            /** Send JSON to this connection */
             json(data: unknown): void;
-            /** Join a room */
             join(room: string): void;
-            /** Leave a room */
             leave(room: string): void;
-            /** Broadcast to a room */
             sendRoom(room: string, data: unknown): void;
         };
     }
 }
-export type WebSocketHandler = {
-    open?: (ws: WebSocket, ctx: Context) => void | Promise<void>;
-    message?: (ws: WebSocket, ctx: Context, data: string | Buffer) => void | Promise<void>;
-    close?: (ws: WebSocket, ctx: Context) => void | Promise<void>;
-    error?: (ws: WebSocket, ctx: Context, error: Error) => void | Promise<void>;
-};
-type WsUpgradeHandler = (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
 export declare class Router<T extends Context = Context> {
     private root;
     private wsRoot;
@@ -33,63 +20,39 @@ export declare class Router<T extends Context = Context> {
     private _hasWildcard;
     private _hub?;
     private _wss?;
-    /** Track which ctx fields have been injected so far (for dependency checking). */
     private _ctxFields;
     private get wss();
     private get hub();
-    /** Inject a custom hub (e.g. with Redis for cross-process broadcast). */
     wsHub(hub: Hub): this;
-    /** Global middleware — accumulates types into Router<T>. */
-    use<Out extends Context>(mw: Middleware<Context, Out>): Router<T & Out>;
-    /**
-     * Mount a sub-router at the given path prefix.
-     * All routes from the sub-router are registered with the prefix.
-     *
-     * ```ts
-     * const admin = new Router()
-     * admin.get('/dashboard', handler)
-     * app.mount('/admin', admin)  // → GET /admin/dashboard
-     * ```
-     */
+    use(mw: Middleware<Context, Context>): Router<T>;
     mount(path: string, router: Router<Context>): Router<T>;
-    /**
-     * Check a middleware's dependency metadata and emit warnings if
-     * required fields haven't been injected yet.
-     * Attach __meta to a middleware function:
-     *
-     * ```ts
-     * mw.__meta = { injects: ['sql'], depends: ['session'] }
-     * ```
-     */
-    private _checkMiddlewareMeta;
-    get(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
-    post(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
-    put(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
-    delete(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
-    patch(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
-    head(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
-    options(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
-    all(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
     onError(handler: ErrorHandler<T>): Router<T>;
-    private _route;
-    /** Internal route registration — no type constraints (used by _mountRouter). */
-    private _routeImpl;
-    ws(path: string, ...args: [...Middleware<T, T>[], WebSocketHandler]): Router<T>;
+    get(path: string, ...rest: [...Middleware[], Handler | Router<Context>]): Router<T>;
+    post(path: string, ...rest: [...Middleware[], Handler | Router<Context>]): Router<T>;
+    put(path: string, ...rest: [...Middleware[], Handler | Router<Context>]): Router<T>;
+    delete(path: string, ...rest: [...Middleware[], Handler | Router<Context>]): Router<T>;
+    patch(path: string, ...rest: [...Middleware[], Handler | Router<Context>]): Router<T>;
+    head(path: string, ...rest: [...Middleware[], Handler | Router<Context>]): Router<T>;
+    options(path: string, ...rest: [...Middleware[], Handler | Router<Context>]): Router<T>;
+    all(path: string, ...rest: [...Middleware[], Handler | Router<Context>]): Router<T>;
+    ws(path: string, ...args: [...Middleware[], WebSocketHandler]): Router<T>;
     handler(): Handler<T>;
-    /** Returns a human-readable list of all registered routes. Useful for debugging. */
-    routes(): string[];
-    private _collectRoutes;
-    private _collectWsRoutes;
     websocketHandler(): WsUpgradeHandler;
+    routes(): string[];
+    private _route;
+    private _routeImpl;
     private _mountRouter;
     private _collect;
     private _collectWs;
     private splitPath;
+    private _collectRoutes;
+    private _collectWsRoutes;
     private matchTrie;
+    private _wildcardMatch;
+    private _resolveMatch;
     private matchWsTrie;
-    private handleError;
-    private _notFoundResponse;
     private handle;
+    private handleError;
     private runChain;
+    private _checkMiddlewareMeta;
 }
-export {};

package/dist/core/serve.d.ts

@@ -29,8 +29,4 @@ export declare function createRequest(req: IncomingMessage, body: Buffer): [Requ
 export declare function sendResponse(res: ServerResponse, response: Response, opts?: {
     traceId?: string | null;
 }): Promise<void>;
-export declare function createTestServer(router: Router, options?: ServeOptions): Promise<{
-    server: Server;
-    url: string;
-}>;
 export declare function serve(router: Router, options?: ServeOptions): Server;

package/dist/core/ws.d.ts

@@ -0,0 +1,28 @@
+/**
+ * WebSocket upgrade + connection lifecycle.
+ *
+ * Handles the HTTP-to-WS upgrade and per-connection state.
+ * Used internally by Router — not exported to end users.
+ */
+import { WebSocketServer } from 'ws';
+import type { WebSocket, Context, Handler, Middleware } from '../types.ts';
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { type Hub } from '../hub.ts';
+/** WebSocket lifecycle handler. */
+export type WebSocketHandler = {
+    open?: (ws: WebSocket, ctx: Context) => void | Promise<void>;
+    message?: (ws: WebSocket, ctx: Context, data: string | Buffer) => void | Promise<void>;
+    close?: (ws: WebSocket, ctx: Context) => void | Promise<void>;
+    error?: (ws: WebSocket, ctx: Context, error: Error) => void | Promise<void>;
+};
+export type WsUpgradeHandler = (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+export declare function nodeReqHeadersToRecord(headers: IncomingMessage['headers']): Record<string, string>;
+export declare function upgradeSocket(wss: WebSocketServer, req: IncomingMessage, socket: Duplex, head: Buffer, handler: WebSocketHandler, ctx: Context, hub: Hub): void;
+type WsMatch = {
+    handler: WebSocketHandler;
+    middlewares: Middleware[];
+    params: Record<string, string>;
+};
+export declare function createWsUpgradeHandler(wss: WebSocketServer, hub: Hub, matchWsFn: (segments: string[]) => WsMatch | null, globalMws: Middleware[], runChainFn: (mws: Middleware[], h: Handler, req: Request, ctx: Context) => Promise<Response>): WsUpgradeHandler;
+export {};