@orkestrel/router 0.0.1 → 0.0.2

package/dist/src/server/{helpers.d.ts → index.d.cts}

@@ -1,127 +1,166 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { DispatcherInterface } from '@src/core';
-import type { ListenerFunction, RequestOptions, StateFunction } from './types.js';
-/**
- * Determine whether a `node:http` connection socket is TLS-encrypted — the
- * total, never-throwing narrow (AGENTS §14) `buildRequest` uses to pick the
- * derived scheme (`https` vs `http`).
- *
- * @param socket - The connection value to test (typically `message.socket`)
- * @returns `true` when `socket` carries a truthy `encrypted` property (a
- *   `tls.TLSSocket`), `false` for anything else (including `undefined`)
- *
- * @example
- * ```ts
- * import { isEncryptedSocket } from '@src/server'
- *
- * isEncryptedSocket({ encrypted: true }) // true
- * isEncryptedSocket({}) // false
- * ```
- */
-export declare function isEncryptedSocket(socket: unknown): socket is {
-    readonly encrypted: true;
-};
-/**
- * Build a fetch-standard `Request` from a `node:http` `IncomingMessage` — the
- * server-adapter half of the §5.3 conversion seam.
- *
- * @remarks
- * - `method` is carried over verbatim (defaulting to `GET` when absent).
- * - The URL is built against `options.origin` when given, otherwise a scheme
- *   derived from the connection (`https` when {@link isEncryptedSocket}, else
- *   `http`) plus the `Host` header (absent `Host` ⇒ `localhost`).
- * - Every request header is copied; multi-value headers are joined per fetch
- *   semantics (`', '`-joined), except `set-cookie`, whose values are each
- *   appended individually (fetch `Headers` preserves multiple `set-cookie`
- *   entries distinctly).
- * - For a method that carries a body (anything but `GET`/`HEAD`), the message
- *   is pumped chunk by chunk into a DOM-compatible `ReadableStream<Uint8Array>`
- *   (reconciling the DOM + node type worlds under the root config), with
- *   `duplex: 'half'` set as Node's fetch implementation requires for a
- *   streamed request body.
- * - A fresh `@orkestrel/abort` handle backs `request.signal`: if the
- *   connection closes before the message finished (`!message.complete`), the
- *   handle aborts — so a handler awaiting `request.signal` observes a client
- *   disconnect the fetch-standard way, with zero router-specific API.
- *
- * @param message - The raw `node:http` request
- * @param options - Optional `origin` override (§5.3 {@link RequestOptions})
- * @returns A fetch `Request` whose `signal` fires on client disconnect
- *
- * @example
- * ```ts
- * import { buildRequest } from '@src/server'
- * import http from 'node:http'
- *
- * const server = http.createServer((incoming) => {
- * 	const request = buildRequest(incoming)
- * 	console.log(request.method, request.url)
- * })
- * ```
- */
-export declare function buildRequest(message: IncomingMessage, options?: RequestOptions): Request;
-/**
- * Write a fetch-standard `Response` back to a `node:http` `ServerResponse` —
- * the reverse half of the §5.3 conversion seam.
- *
- * @remarks
- * Writes `status`/`statusText`, then every response header (`set-cookie`
- * written via {@link Headers.getSetCookie} so multiple cookies stay distinct
- * instead of collapsing into one comma-joined header), then streams the web
- * body to `target` chunk by chunk (`for await` over `response.body`), ending
- * `target` when the stream completes. A `null` body ends `target` immediately
- * with no further writes. Total error posture: if `target` is destroyed
- * mid-stream (the client disconnected), the write loop stops and `target` is
- * left as-is rather than throwing an unhandled rejection — a destroyed
- * target is not this function's error to surface.
- *
- * @param response - The fetch `Response` to write
- * @param target - The `node:http` response to write it to
- * @returns A promise that resolves once `target` has been ended (or the
- *   stream stopped because `target` was destroyed)
- *
- * @example
- * ```ts
- * import { sendResponse } from '@src/server'
- * import http from 'node:http'
- *
- * const server = http.createServer(async (_incoming, target) => {
- * 	await sendResponse(new Response('ok'), target)
- * })
- * ```
- */
-export declare function sendResponse(response: Response, target: ServerResponse): Promise<void>;
-/**
- * Create a `node:http` request listener over a core {@link DispatcherInterface} —
- * the whole server face's entry point (§5.3): convert the incoming message to
- * a fetch `Request`, hand it to the dispatcher with the consumer's per-request
- * `state`, and write the resulting `Response` back.
- *
- * @remarks
- * A rejected `dispatcher.handle` (a route handler throw — the dispatcher
- * never invents an error boundary, §5.1) is this listener's transport-level
- * LAST RESORT, distinct from an application error boundary: when nothing has
- * been sent yet, it destroys the connection with a bare `500` head (never
- * leaking a hanging socket); once headers are already sent, it destroys the
- * connection outright. The router still owns no error POLICY — a consumer
- * that wants mapped error responses installs its own boundary around
- * `dispatcher.handle` (the future `@orkestrel/server` seam, §7).
- *
- * @typeParam TState - The consumer's opaque per-request state type
- * @param dispatcher - The core dispatcher to run each converted request through
- * @param state - Derives the consumer's per-request `state` from the raw message
- * @returns A `(request, response) => void` listener, passable directly to
- *   `http.createServer`
- *
- * @example
- * ```ts
- * import { createListener } from '@src/server'
- * import { createDispatcher } from '@src/core'
- * import http from 'node:http'
- *
- * const dispatcher = createDispatcher()
- * dispatcher.add({ method: 'GET', path: '/health', handler: () => new Response('ok') })
- * http.createServer(createListener(dispatcher, () => undefined)).listen(0)
- * ```
- */
-export declare function createListener<TState>(dispatcher: DispatcherInterface<TState>, state: StateFunction<TState>): ListenerFunction;
+import { DispatcherInterface } from '../core/index.ts';
+import { IncomingMessage } from 'node:http';
+import { ServerResponse } from 'node:http';
+
+/**
+ * Build a fetch-standard `Request` from a `node:http` `IncomingMessage` — the
+ * server-adapter half of the §5.3 conversion seam.
+ *
+ * @remarks
+ * - `method` is carried over verbatim (defaulting to `GET` when absent).
+ * - The URL is built against `options.origin` when given, otherwise a scheme
+ *   derived from the connection (`https` when {@link isEncryptedSocket}, else
+ *   `http`) plus the `Host` header (absent `Host` ⇒ `localhost`).
+ * - Every request header is copied; multi-value headers are joined per fetch
+ *   semantics (`', '`-joined), except `set-cookie`, whose values are each
+ *   appended individually (fetch `Headers` preserves multiple `set-cookie`
+ *   entries distinctly).
+ * - For a method that carries a body (anything but `GET`/`HEAD`), the message
+ *   is pumped chunk by chunk into a DOM-compatible `ReadableStream<Uint8Array>`
+ *   (reconciling the DOM + node type worlds under the root config), with
+ *   `duplex: 'half'` set as Node's fetch implementation requires for a
+ *   streamed request body.
+ * - A fresh `@orkestrel/abort` handle backs `request.signal`: if the
+ *   connection closes before the message finished (`!message.complete`), the
+ *   handle aborts — so a handler awaiting `request.signal` observes a client
+ *   disconnect the fetch-standard way, with zero router-specific API.
+ *
+ * @param message - The raw `node:http` request
+ * @param options - Optional `origin` override (§5.3 {@link RequestOptions})
+ * @returns A fetch `Request` whose `signal` fires on client disconnect
+ *
+ * @example
+ * ```ts
+ * import { buildRequest } from '@src/server'
+ * import http from 'node:http'
+ *
+ * const server = http.createServer((incoming) => {
+ * 	const request = buildRequest(incoming)
+ * 	console.log(request.method, request.url)
+ * })
+ * ```
+ */
+export declare function buildRequest(message: IncomingMessage, options?: RequestOptions): Request;
+
+/**
+ * Create a `node:http` request listener over a core {@link DispatcherInterface} —
+ * the whole server face's entry point (§5.3): convert the incoming message to
+ * a fetch `Request`, hand it to the dispatcher with the consumer's per-request
+ * `state`, and write the resulting `Response` back.
+ *
+ * @remarks
+ * A rejected `dispatcher.handle` (a route handler throw — the dispatcher
+ * never invents an error boundary, §5.1) is this listener's transport-level
+ * LAST RESORT, distinct from an application error boundary: when nothing has
+ * been sent yet, it destroys the connection with a bare `500` head (never
+ * leaking a hanging socket); once headers are already sent, it destroys the
+ * connection outright. The router still owns no error POLICY — a consumer
+ * that wants mapped error responses installs its own boundary around
+ * `dispatcher.handle` (the future `@orkestrel/server` seam, §7).
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ * @param dispatcher - The core dispatcher to run each converted request through
+ * @param state - Derives the consumer's per-request `state` from the raw message
+ * @returns A `(request, response) => void` listener, passable directly to
+ *   `http.createServer`
+ *
+ * @example
+ * ```ts
+ * import { createListener } from '@src/server'
+ * import { createDispatcher } from '@src/core'
+ * import http from 'node:http'
+ *
+ * const dispatcher = createDispatcher()
+ * dispatcher.add({ method: 'GET', path: '/health', handler: () => new Response('ok') })
+ * http.createServer(createListener(dispatcher, () => undefined)).listen(0)
+ * ```
+ */
+export declare function createListener<TState>(dispatcher: DispatcherInterface<TState>, state: StateFunction<TState>): ListenerFunction;
+
+/**
+ * Determine whether a `node:http` connection socket is TLS-encrypted — the
+ * total, never-throwing narrow (AGENTS §14) `buildRequest` uses to pick the
+ * derived scheme (`https` vs `http`).
+ *
+ * @param socket - The connection value to test (typically `message.socket`)
+ * @returns `true` when `socket` carries a truthy `encrypted` property (a
+ *   `tls.TLSSocket`), `false` for anything else (including `undefined`)
+ *
+ * @example
+ * ```ts
+ * import { isEncryptedSocket } from '@src/server'
+ *
+ * isEncryptedSocket({ encrypted: true }) // true
+ * isEncryptedSocket({}) // false
+ * ```
+ */
+export declare function isEncryptedSocket(socket: unknown): socket is {
+    readonly encrypted: true;
+};
+
+/**
+ * A `node:http` request handler — the function `createListener` returns,
+ * matching `http.createServer`'s handler signature.
+ *
+ * @remarks
+ * Invoked once per incoming message with the raw `IncomingMessage`/
+ * `ServerResponse` pair; never returns a value (writes the response as a
+ * side effect).
+ */
+export declare type ListenerFunction = (request: IncomingMessage, response: ServerResponse) => void;
+
+/**
+ * Options for `buildRequest` — how to derive the built `Request`'s origin.
+ *
+ * @remarks
+ * - `origin` — an explicit scheme + host to build the request URL against
+ *   (`https://api.example.com`). Omitted ⇒ derived from the connection: the
+ *   socket's `encrypted` presence picks `https`/`http`, and the `Host`
+ *   header supplies the host (absent `Host` ⇒ `localhost`).
+ */
+export declare interface RequestOptions {
+    readonly origin?: string;
+}
+
+/**
+ * Write a fetch-standard `Response` back to a `node:http` `ServerResponse` —
+ * the reverse half of the §5.3 conversion seam.
+ *
+ * @remarks
+ * Writes `status`/`statusText`, then every response header (`set-cookie`
+ * written via {@link Headers.getSetCookie} so multiple cookies stay distinct
+ * instead of collapsing into one comma-joined header), then streams the web
+ * body to `target` chunk by chunk (`for await` over `response.body`), ending
+ * `target` when the stream completes. A `null` body ends `target` immediately
+ * with no further writes. Total error posture: if `target` is destroyed
+ * mid-stream (the client disconnected), the write loop stops and `target` is
+ * left as-is rather than throwing an unhandled rejection — a destroyed
+ * target is not this function's error to surface.
+ *
+ * @param response - The fetch `Response` to write
+ * @param target - The `node:http` response to write it to
+ * @returns A promise that resolves once `target` has been ended (or the
+ *   stream stopped because `target` was destroyed)
+ *
+ * @example
+ * ```ts
+ * import { sendResponse } from '@src/server'
+ * import http from 'node:http'
+ *
+ * const server = http.createServer(async (_incoming, target) => {
+ * 	await sendResponse(new Response('ok'), target)
+ * })
+ * ```
+ */
+export declare function sendResponse(response: Response, target: ServerResponse): Promise<void>;
+
+/**
+ * Derives a consumer's opaque per-request `TState` from the raw
+ * `IncomingMessage` — the `state` argument `createListener` threads into
+ * `dispatcher.handle`.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ */
+export declare type StateFunction<TState> = (message: IncomingMessage) => TState;
+
+export { }

package/dist/src/server/index.d.ts

@@ -1,2 +1,166 @@
-export type * from './types.js';
-export * from './helpers.js';
+import { DispatcherInterface } from '../core/index.ts';
+import { IncomingMessage } from 'node:http';
+import { ServerResponse } from 'node:http';
+
+/**
+ * Build a fetch-standard `Request` from a `node:http` `IncomingMessage` — the
+ * server-adapter half of the §5.3 conversion seam.
+ *
+ * @remarks
+ * - `method` is carried over verbatim (defaulting to `GET` when absent).
+ * - The URL is built against `options.origin` when given, otherwise a scheme
+ *   derived from the connection (`https` when {@link isEncryptedSocket}, else
+ *   `http`) plus the `Host` header (absent `Host` ⇒ `localhost`).
+ * - Every request header is copied; multi-value headers are joined per fetch
+ *   semantics (`', '`-joined), except `set-cookie`, whose values are each
+ *   appended individually (fetch `Headers` preserves multiple `set-cookie`
+ *   entries distinctly).
+ * - For a method that carries a body (anything but `GET`/`HEAD`), the message
+ *   is pumped chunk by chunk into a DOM-compatible `ReadableStream<Uint8Array>`
+ *   (reconciling the DOM + node type worlds under the root config), with
+ *   `duplex: 'half'` set as Node's fetch implementation requires for a
+ *   streamed request body.
+ * - A fresh `@orkestrel/abort` handle backs `request.signal`: if the
+ *   connection closes before the message finished (`!message.complete`), the
+ *   handle aborts — so a handler awaiting `request.signal` observes a client
+ *   disconnect the fetch-standard way, with zero router-specific API.
+ *
+ * @param message - The raw `node:http` request
+ * @param options - Optional `origin` override (§5.3 {@link RequestOptions})
+ * @returns A fetch `Request` whose `signal` fires on client disconnect
+ *
+ * @example
+ * ```ts
+ * import { buildRequest } from '@src/server'
+ * import http from 'node:http'
+ *
+ * const server = http.createServer((incoming) => {
+ * 	const request = buildRequest(incoming)
+ * 	console.log(request.method, request.url)
+ * })
+ * ```
+ */
+export declare function buildRequest(message: IncomingMessage, options?: RequestOptions): Request;
+
+/**
+ * Create a `node:http` request listener over a core {@link DispatcherInterface} —
+ * the whole server face's entry point (§5.3): convert the incoming message to
+ * a fetch `Request`, hand it to the dispatcher with the consumer's per-request
+ * `state`, and write the resulting `Response` back.
+ *
+ * @remarks
+ * A rejected `dispatcher.handle` (a route handler throw — the dispatcher
+ * never invents an error boundary, §5.1) is this listener's transport-level
+ * LAST RESORT, distinct from an application error boundary: when nothing has
+ * been sent yet, it destroys the connection with a bare `500` head (never
+ * leaking a hanging socket); once headers are already sent, it destroys the
+ * connection outright. The router still owns no error POLICY — a consumer
+ * that wants mapped error responses installs its own boundary around
+ * `dispatcher.handle` (the future `@orkestrel/server` seam, §7).
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ * @param dispatcher - The core dispatcher to run each converted request through
+ * @param state - Derives the consumer's per-request `state` from the raw message
+ * @returns A `(request, response) => void` listener, passable directly to
+ *   `http.createServer`
+ *
+ * @example
+ * ```ts
+ * import { createListener } from '@src/server'
+ * import { createDispatcher } from '@src/core'
+ * import http from 'node:http'
+ *
+ * const dispatcher = createDispatcher()
+ * dispatcher.add({ method: 'GET', path: '/health', handler: () => new Response('ok') })
+ * http.createServer(createListener(dispatcher, () => undefined)).listen(0)
+ * ```
+ */
+export declare function createListener<TState>(dispatcher: DispatcherInterface<TState>, state: StateFunction<TState>): ListenerFunction;
+
+/**
+ * Determine whether a `node:http` connection socket is TLS-encrypted — the
+ * total, never-throwing narrow (AGENTS §14) `buildRequest` uses to pick the
+ * derived scheme (`https` vs `http`).
+ *
+ * @param socket - The connection value to test (typically `message.socket`)
+ * @returns `true` when `socket` carries a truthy `encrypted` property (a
+ *   `tls.TLSSocket`), `false` for anything else (including `undefined`)
+ *
+ * @example
+ * ```ts
+ * import { isEncryptedSocket } from '@src/server'
+ *
+ * isEncryptedSocket({ encrypted: true }) // true
+ * isEncryptedSocket({}) // false
+ * ```
+ */
+export declare function isEncryptedSocket(socket: unknown): socket is {
+    readonly encrypted: true;
+};
+
+/**
+ * A `node:http` request handler — the function `createListener` returns,
+ * matching `http.createServer`'s handler signature.
+ *
+ * @remarks
+ * Invoked once per incoming message with the raw `IncomingMessage`/
+ * `ServerResponse` pair; never returns a value (writes the response as a
+ * side effect).
+ */
+export declare type ListenerFunction = (request: IncomingMessage, response: ServerResponse) => void;
+
+/**
+ * Options for `buildRequest` — how to derive the built `Request`'s origin.
+ *
+ * @remarks
+ * - `origin` — an explicit scheme + host to build the request URL against
+ *   (`https://api.example.com`). Omitted ⇒ derived from the connection: the
+ *   socket's `encrypted` presence picks `https`/`http`, and the `Host`
+ *   header supplies the host (absent `Host` ⇒ `localhost`).
+ */
+export declare interface RequestOptions {
+    readonly origin?: string;
+}
+
+/**
+ * Write a fetch-standard `Response` back to a `node:http` `ServerResponse` —
+ * the reverse half of the §5.3 conversion seam.
+ *
+ * @remarks
+ * Writes `status`/`statusText`, then every response header (`set-cookie`
+ * written via {@link Headers.getSetCookie} so multiple cookies stay distinct
+ * instead of collapsing into one comma-joined header), then streams the web
+ * body to `target` chunk by chunk (`for await` over `response.body`), ending
+ * `target` when the stream completes. A `null` body ends `target` immediately
+ * with no further writes. Total error posture: if `target` is destroyed
+ * mid-stream (the client disconnected), the write loop stops and `target` is
+ * left as-is rather than throwing an unhandled rejection — a destroyed
+ * target is not this function's error to surface.
+ *
+ * @param response - The fetch `Response` to write
+ * @param target - The `node:http` response to write it to
+ * @returns A promise that resolves once `target` has been ended (or the
+ *   stream stopped because `target` was destroyed)
+ *
+ * @example
+ * ```ts
+ * import { sendResponse } from '@src/server'
+ * import http from 'node:http'
+ *
+ * const server = http.createServer(async (_incoming, target) => {
+ * 	await sendResponse(new Response('ok'), target)
+ * })
+ * ```
+ */
+export declare function sendResponse(response: Response, target: ServerResponse): Promise<void>;
+
+/**
+ * Derives a consumer's opaque per-request `TState` from the raw
+ * `IncomingMessage` — the `state` argument `createListener` threads into
+ * `dispatcher.handle`.
+ *
+ * @typeParam TState - The consumer's opaque per-request state type
+ */
+export declare type StateFunction<TState> = (message: IncomingMessage) => TState;
+
+export { }