@fishenv/http 0.0.0-stage → 0.0.3

package/dist/contract/builder.d.ts

@@ -0,0 +1,87 @@
+import type { AnySchema, BasePathParams, ErrorTypes, HttpMethod, InferOutput, InputKind, InputOptions, MergeParam, RouteMeta } from "./types.ts";
+/**
+ * Plain-data snapshot of a contract endpoint.
+ *
+ * This is the runtime shape consumers (the API's `router.contract()`, an
+ * OpenAPI generator, a typed client, ...) read from. It intentionally has no
+ * generic parameters — the compile-time shape lives on `ContractBuilder`
+ * itself and is recovered via `ContractShape<C>`.
+ */
+export interface ContractDefinition {
+    method: HttpMethod;
+    path: string;
+    paramSchemas: Map<string, AnySchema>;
+    inputKind: InputKind;
+    inputOptions: InputOptions<InputKind>;
+    outputSchema?: AnySchema;
+    errorTypes?: ErrorTypes;
+    meta?: RouteMeta;
+}
+/**
+ * Fluent, immutable contract endpoint builder.
+ *
+ * Mirrors `RouteBuilder` from `@fishenv/http` (method/path/param/input/output)
+ * minus everything server-only (middleware, handlers, DI). A finished
+ * `ContractBuilder` is portable data: it can be handed to
+ * `router.contract(endpoint)` on the API side, or read by an OpenAPI
+ * generator / typed client on the consumer side.
+ */
+export declare class ContractBuilder<M extends HttpMethod, P extends string, K extends InputKind = "none", O extends InputOptions<K> = InputOptions<K>, Params extends Record<string, unknown> = Record<string, unknown>, Output = undefined> {
+    #private;
+    readonly method: M;
+    readonly path: P;
+    constructor(method: M, path: P, paramSchemas?: Map<string, AnySchema>, inputKind?: InputKind, inputOptions?: InputOptions<InputKind>, outputSchema?: AnySchema, errorTypes?: ErrorTypes, meta?: RouteMeta);
+    /** Set contract metadata (title, tags, etc.) — returns new builder */
+    meta(data: RouteMeta): ContractBuilder<M, P, K, O, Params, Output>;
+    /** Narrow/coerce a path param with a Valibot schema — returns new builder */
+    param<Name extends string & keyof Params, S extends AnySchema>(name: Name, schema: S): ContractBuilder<M, P, K, O, MergeParam<Params, Name, S>, Output>;
+    /** Set input kind and options — returns new builder */
+    input<NK extends InputKind, NO extends InputOptions<NK>>(kind: NK, options?: NO): ContractBuilder<M, P, NK, NO extends InputOptions<NK> ? NO : InputOptions<NK>, Params, Output>;
+    /** Set output schema + optional error types — returns new builder */
+    output<S extends AnySchema>(schema: S, errors?: ErrorTypes): ContractBuilder<M, P, K, O, Params, InferOutput<S>>;
+    /**
+     * Runtime snapshot of this endpoint. Used by consumers such as
+     * `router.contract()`, OpenAPI generation, or a typed client — not meant
+     * to be read directly by application code.
+     */
+    get _definition(): ContractDefinition;
+}
+/**
+ * Recovers the compile-time shape (input/output/params) of a `ContractBuilder`.
+ * Used by consumers to derive their own generics from a contract endpoint.
+ */
+export type ContractShape<C> = C extends ContractBuilder<infer M, infer P, infer K, infer O, infer Params, infer Output> ? {
+    method: M;
+    path: P;
+    inputKind: K;
+    inputOptions: O;
+    params: Params;
+    output: Output;
+} : never;
+/** Loosest possible `ContractBuilder` — use as a generic constraint. */
+export type AnyContractBuilder = ContractBuilder<any, any, any, any, any, any>;
+/**
+ * Entry point for defining contract endpoints, e.g.:
+ *
+ * ```ts
+ * export const contract = {
+ *   users: {
+ *     create: c.post("/users").input("json", { body: CreateUserSchema }).output(UserSchema),
+ *     get: c.get("/users/:id").output(UserSchema),
+ *   },
+ * };
+ * ```
+ */
+export declare const c: {
+    ws: <P extends string>(path: P) => import("./ws.ts").WsContract<P, BasePathParams<P>, "raw", [], undefined, undefined>;
+    channel: <N extends string>(name: N) => import("./ws.ts").ChannelContract<N, BasePathParams<N>, {
+        payload: undefined;
+        reply: undefined;
+    }, Record<never, never>, Record<never, never>, undefined>;
+    get: <P extends string>(path: P) => ContractBuilder<"GET", P, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    post: <P extends string>(path: P) => ContractBuilder<"POST", P, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    put: <P extends string>(path: P) => ContractBuilder<"PUT", P, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    patch: <P extends string>(path: P) => ContractBuilder<"PATCH", P, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    delete: <P extends string>(path: P) => ContractBuilder<"DELETE", P, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    options: <P extends string>(path: P) => ContractBuilder<"OPTIONS", P, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+};

package/dist/contract/builder.js

@@ -0,0 +1,89 @@
+import { wsContractFactories } from "./ws.js";
+/**
+ * Fluent, immutable contract endpoint builder.
+ *
+ * Mirrors `RouteBuilder` from `@fishenv/http` (method/path/param/input/output)
+ * minus everything server-only (middleware, handlers, DI). A finished
+ * `ContractBuilder` is portable data: it can be handed to
+ * `router.contract(endpoint)` on the API side, or read by an OpenAPI
+ * generator / typed client on the consumer side.
+ */
+export class ContractBuilder {
+    method;
+    path;
+    #paramSchemas;
+    #inputKind;
+    #inputOptions;
+    #outputSchema;
+    #errorTypes;
+    #meta;
+    constructor(method, path, paramSchemas = new Map(), inputKind = "none", inputOptions = {}, outputSchema, errorTypes, meta) {
+        this.method = method;
+        this.path = path;
+        this.#paramSchemas = paramSchemas;
+        this.#inputKind = inputKind;
+        this.#inputOptions = inputOptions;
+        this.#outputSchema = outputSchema;
+        this.#errorTypes = errorTypes;
+        this.#meta = meta;
+    }
+    /** Set contract metadata (title, tags, etc.) — returns new builder */
+    meta(data) {
+        return new ContractBuilder(this.method, this.path, new Map(this.#paramSchemas), this.#inputKind, this.#inputOptions, this.#outputSchema, this.#errorTypes ? [...this.#errorTypes] : undefined, { ...this.#meta, ...data });
+    }
+    /** Narrow/coerce a path param with a Valibot schema — returns new builder */
+    param(name, schema) {
+        const newSchemas = new Map(this.#paramSchemas);
+        newSchemas.set(name, schema);
+        return new ContractBuilder(this.method, this.path, newSchemas, this.#inputKind, this.#inputOptions, this.#outputSchema, this.#errorTypes ? [...this.#errorTypes] : undefined, this.#meta ? { ...this.#meta } : undefined);
+    }
+    /** Set input kind and options — returns new builder */
+    input(kind, options) {
+        return new ContractBuilder(this.method, this.path, new Map(this.#paramSchemas), kind, (options ?? {}), this.#outputSchema, this.#errorTypes ? [...this.#errorTypes] : undefined, this.#meta ? { ...this.#meta } : undefined);
+    }
+    /** Set output schema + optional error types — returns new builder */
+    output(schema, errors) {
+        return new ContractBuilder(this.method, this.path, new Map(this.#paramSchemas), this.#inputKind, this.#inputOptions, schema, errors, this.#meta ? { ...this.#meta } : undefined);
+    }
+    /**
+     * Runtime snapshot of this endpoint. Used by consumers such as
+     * `router.contract()`, OpenAPI generation, or a typed client — not meant
+     * to be read directly by application code.
+     */
+    get _definition() {
+        return {
+            method: this.method,
+            path: this.path,
+            paramSchemas: this.#paramSchemas,
+            inputKind: this.#inputKind,
+            inputOptions: this.#inputOptions,
+            outputSchema: this.#outputSchema,
+            errorTypes: this.#errorTypes,
+            meta: this.#meta,
+        };
+    }
+}
+function endpoint(method) {
+    return (path) => new ContractBuilder(method, path);
+}
+/**
+ * Entry point for defining contract endpoints, e.g.:
+ *
+ * ```ts
+ * export const contract = {
+ *   users: {
+ *     create: c.post("/users").input("json", { body: CreateUserSchema }).output(UserSchema),
+ *     get: c.get("/users/:id").output(UserSchema),
+ *   },
+ * };
+ * ```
+ */
+export const c = {
+    ...wsContractFactories,
+    get: endpoint("GET"),
+    post: endpoint("POST"),
+    put: endpoint("PUT"),
+    patch: endpoint("PATCH"),
+    delete: endpoint("DELETE"),
+    options: endpoint("OPTIONS"),
+};

package/dist/contract/index.d.ts

@@ -0,0 +1,4 @@
+export { type AnyContractBuilder, ContractBuilder, type ContractDefinition, type ContractShape, c, } from "./builder.ts";
+export type { AnySchema, BasePathParams, ErrorTypes, ExtractParams, HttpMethod, InferBody, InferCookies, InferHeaders, InferOutput, InferQuery, InputKind, InputOptions, MergeParam, RouteMeta, ValibotSchema, } from "./types.ts";
+export type { AnyChannelContract, AnyWsContract, ChannelContractDefinition, ChannelEventDefinition, EventSchemas, InferChannel, InferSocket, JoinSchemas, SchemaInput, SchemaOutput, WsContractDefinition, WsContractKind, } from "./ws.ts";
+export { CHANNELS_PROTOCOL, ChannelContract, WsContract } from "./ws.ts";

package/dist/contract/index.js

@@ -0,0 +1,2 @@
+export { ContractBuilder, c, } from "./builder.js";
+export { CHANNELS_PROTOCOL, ChannelContract, WsContract } from "./ws.js";

package/dist/contract/types.d.ts

@@ -0,0 +1,47 @@
+import type * as v from "valibot";
+/**
+ * `@fishenv/http-contract` — the "shape" types shared between an API and its
+ * consumers (the API itself, an OpenAPI generator, a typed client, ...).
+ *
+ * This module has zero server-runtime dependencies (no DI, no middleware, no
+ * `Bun.serve`) — it only describes *what* an endpoint looks like: method,
+ * path, input, output. `@fishenv/http` (the `core` package) depends on this
+ * package to build its route registration API; this package must never
+ * depend back on `core`.
+ */
+export type ValibotSchema<O = unknown> = v.BaseSchema<unknown, O, v.BaseIssue<unknown>>;
+export type AnySchema = ValibotSchema<unknown>;
+export type InferOutput<S extends AnySchema> = v.InferOutput<S>;
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+export type InputKind = "json" | "multipart" | "urlencoded" | "blob" | "text" | "none";
+export interface InputOptions<K extends InputKind> {
+    body?: K extends "blob" | "text" ? never : AnySchema;
+    headers?: AnySchema;
+    query?: AnySchema;
+    cookies?: AnySchema;
+    maxSize?: K extends "blob" | "multipart" ? number : never;
+}
+export type InferBody<K extends InputKind, O extends InputOptions<K>> = K extends "blob" ? Blob : K extends "text" ? string : K extends "none" ? undefined : O["body"] extends AnySchema ? InferOutput<O["body"]> : K extends "multipart" | "urlencoded" ? FormData : unknown;
+export type InferHeaders<O extends InputOptions<InputKind>> = O["headers"] extends AnySchema ? InferOutput<O["headers"]> : Record<string, string>;
+export type InferQuery<O extends InputOptions<InputKind>> = O["query"] extends AnySchema ? InferOutput<O["query"]> : Record<string, string | string[]>;
+export type InferCookies<O extends InputOptions<InputKind>> = O["cookies"] extends AnySchema ? InferOutput<O["cookies"]> : Record<string, string>;
+type ParamName<Param extends string> = Param extends `${infer Name}?` ? Name : Param extends `${infer Name}*` ? Name : Param;
+export type ExtractParams<P extends string> = P extends `${string}:${infer Param}/${infer Rest}` ? ParamName<Param> | ExtractParams<`/${Rest}`> : P extends `${string}:${infer Param}` ? ParamName<Param> : never;
+export type BasePathParams<P extends string> = {
+    [K in ExtractParams<P>]: string;
+};
+export type MergeParam<Base extends Record<string, unknown>, Name extends string, Schema extends AnySchema> = Omit<Base, Name> & Record<Name, InferOutput<Schema>>;
+export interface RouteMeta {
+    title?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    operationId?: string;
+}
+/**
+ * Error classes a handler may throw — documentation and client typing only
+ * (`.output(schema, errors)`, WebSocket replies). `any[]` so that classes with
+ * typed constructor params (`ForbiddenError(message?: string)`) fit.
+ */
+export type ErrorTypes = (abstract new (...args: any[]) => Error)[];
+export {};

package/dist/contract/ws.d.ts

@@ -0,0 +1,178 @@
+/**
+ * WebSocket contracts — portable data describing sockets and channels, shared
+ * by the server (`@fishenv/http/ws`) and typed clients.
+ *
+ * ```ts
+ * export const room = c
+ *   .channel("rooms/:roomId")
+ *   .param("roomId", v.pipe(v.string(), v.uuid()))
+ *   .join(JoinPayload, JoinReply, [ForbiddenError])
+ *   .clientEvent("message", MessageIn, MessageAck)
+ *   .serverEvent("message", Message)
+ *   .presence(PresenceMeta, { clientUpdates: true });
+ *
+ * export const socket = c.ws("/socket").channels(room);
+ * ```
+ *
+ * Like HTTP contracts, builders are immutable and expose a plain
+ * `_definition` snapshot; the compile-time shape is recovered with
+ * {@link InferChannel} / {@link InferSocket}.
+ */
+import type * as v from "valibot";
+import type { AnySchema, BasePathParams, ErrorTypes, MergeParam, RouteMeta } from "./types.ts";
+/** The channel protocol's subprotocol name. */
+export declare const CHANNELS_PROTOCOL = "fishenv.channels.v1";
+type Maybe<S> = S extends AnySchema ? S : undefined;
+/** What the sender passes in (before schema transforms). */
+export type SchemaInput<S> = S extends AnySchema ? v.InferInput<S> : undefined;
+/** What the receiver gets (after validation and transforms). */
+export type SchemaOutput<S> = S extends AnySchema ? v.InferOutput<S> : undefined;
+export interface EventSchemas {
+    payload: AnySchema;
+    reply: AnySchema | undefined;
+}
+export interface JoinSchemas {
+    payload: AnySchema | undefined;
+    reply: AnySchema | undefined;
+}
+export interface ChannelEventDefinition {
+    payload: AnySchema;
+    reply?: AnySchema;
+    errors?: ErrorTypes;
+}
+export interface ChannelContractDefinition {
+    /** Pattern using router path syntax, e.g. `rooms/:roomId`. */
+    name: string;
+    paramSchemas: Map<string, AnySchema>;
+    join: {
+        payload?: AnySchema;
+        reply?: AnySchema;
+        errors?: ErrorTypes;
+    };
+    clientEvents: Map<string, ChannelEventDefinition>;
+    serverEvents: Map<string, AnySchema>;
+    presence?: {
+        meta: AnySchema;
+        clientUpdates: boolean;
+    };
+    meta?: RouteMeta;
+}
+export declare class ChannelContract<N extends string, Params extends Record<string, unknown> = BasePathParams<N>, J extends JoinSchemas = {
+    payload: undefined;
+    reply: undefined;
+}, CE extends Record<string, EventSchemas> = Record<never, never>, SE extends Record<string, AnySchema> = Record<never, never>, PM extends AnySchema | undefined = undefined> {
+    #private;
+    readonly name: N;
+    constructor(name: N, def?: ChannelContractDefinition);
+    meta(data: RouteMeta): ChannelContract<N, Params, J, CE, SE, PM>;
+    /** Narrow/coerce a channel-name param. */
+    param<Name extends string & keyof Params, S extends AnySchema>(name: Name, schema: S): ChannelContract<N, MergeParam<Params, Name, S>, J, CE, SE, PM>;
+    /** Join payload, join reply and documented errors. All optional. */
+    join<P extends AnySchema | undefined = undefined, R extends AnySchema | undefined = undefined>(payload?: P, reply?: R, errors?: ErrorTypes): ChannelContract<N, Params, {
+        payload: Maybe<P>;
+        reply: Maybe<R>;
+    }, CE, SE, PM>;
+    /** Client → server event. Without `reply` it is fire-and-forget. */
+    clientEvent<E extends string, P extends AnySchema, R extends AnySchema | undefined = undefined>(name: E, payload: P, reply?: R, errors?: ErrorTypes): ChannelContract<N, Params, J, CE & Record<E, {
+        payload: P;
+        reply: Maybe<R>;
+    }>, SE, PM>;
+    /** Server → client event. */
+    serverEvent<E extends string, P extends AnySchema>(name: E, payload: P): ChannelContract<N, Params, J, CE, SE & Record<E, P>, PM>;
+    /**
+     * Enable presence for this channel. `clientUpdates` lets clients change
+     * their own meta (rate-limited server-side).
+     */
+    presence<M extends AnySchema>(meta: M, opts?: {
+        clientUpdates?: boolean;
+    }): ChannelContract<N, Params, J, CE, SE, M>;
+    get _definition(): ChannelContractDefinition;
+}
+export type AnyChannelContract = ChannelContract<any, any, any, any, any, any>;
+/** Compile-time shape of a channel contract, from both sides' perspective. */
+export type InferChannel<C> = C extends ChannelContract<infer N, infer Params, infer J, infer CE, infer SE, infer PM> ? {
+    name: N;
+    params: Params;
+    join: {
+        /** What the client sends / the server receives. */
+        payloadIn: SchemaInput<J["payload"]>;
+        payload: SchemaOutput<J["payload"]>;
+        /** What the server returns / the client receives. */
+        replyIn: SchemaInput<J["reply"]>;
+        reply: SchemaOutput<J["reply"]>;
+    };
+    clientEvents: {
+        [K in keyof CE]: {
+            payloadIn: SchemaInput<CE[K]["payload"]>;
+            payload: SchemaOutput<CE[K]["payload"]>;
+            replyIn: SchemaInput<CE[K]["reply"]>;
+            reply: SchemaOutput<CE[K]["reply"]>;
+        };
+    };
+    serverEvents: {
+        [K in keyof SE]: {
+            payloadIn: SchemaInput<SE[K]>;
+            payload: SchemaOutput<SE[K]>;
+        };
+    };
+    presenceMeta: PM extends AnySchema ? {
+        in: SchemaInput<PM>;
+        out: SchemaOutput<PM>;
+    } : never;
+} : never;
+export type WsContractKind = "raw" | "messages" | "channels";
+export interface WsContractDefinition {
+    path: string;
+    paramSchemas: Map<string, AnySchema>;
+    kind: WsContractKind;
+    protocols?: string[];
+    channels: AnyChannelContract[];
+    messages?: {
+        client: AnySchema;
+        server: AnySchema;
+    };
+    meta?: RouteMeta;
+}
+export declare class WsContract<P extends string, Params extends Record<string, unknown> = BasePathParams<P>, K extends WsContractKind = "raw", Channels extends readonly AnyChannelContract[] = [], Client extends AnySchema | undefined = undefined, Server extends AnySchema | undefined = undefined> {
+    #private;
+    readonly path: P;
+    constructor(path: P, def?: WsContractDefinition);
+    meta(data: RouteMeta): WsContract<P, Params, K, Channels, Client, Server>;
+    param<Name extends string & keyof Params, S extends AnySchema>(name: Name, schema: S): WsContract<P, MergeParam<Params, Name, S>, K, Channels, Client, Server>;
+    /** Subprotocols for raw/message sockets (channels use their own). */
+    protocols(list: string[]): WsContract<P, Params, K, Channels, Client, Server>;
+    /** A typed socket exchanging one JSON message type in each direction. */
+    messages<CS extends AnySchema, SS extends AnySchema>(schemas: {
+        client: CS;
+        server: SS;
+    }): WsContract<P, Params, "messages", [], CS, SS>;
+    /** A socket speaking the channel protocol with exactly these channels. */
+    channels<const Cs extends readonly AnyChannelContract[]>(...channels: Cs): WsContract<P, Params, "channels", Cs, undefined, undefined>;
+    get _definition(): WsContractDefinition;
+}
+export type AnyWsContract = WsContract<any, any, any, any, any, any>;
+export type InferSocket<C> = C extends WsContract<infer P, infer Params, infer K, infer Channels, infer Client, infer Server> ? {
+    path: P;
+    params: Params;
+    kind: K;
+    channels: {
+        [I in keyof Channels]: InferChannel<Channels[I]>;
+    };
+    channelNames: Channels[number]["name"];
+    /** Client → server message (raw `messages()` sockets). */
+    clientMessageIn: SchemaInput<Client>;
+    clientMessage: SchemaOutput<Client>;
+    /** Server → client message. */
+    serverMessageIn: SchemaInput<Server>;
+    serverMessage: SchemaOutput<Server>;
+} : never;
+export declare const wsContractFactories: {
+    /** A WebSocket endpoint. */
+    ws: <P extends string>(path: P) => WsContract<P, BasePathParams<P>, "raw", [], undefined, undefined>;
+    /** A channel, named with router path syntax (`rooms/:roomId`). */
+    channel: <N extends string>(name: N) => ChannelContract<N, BasePathParams<N>, {
+        payload: undefined;
+        reply: undefined;
+    }, Record<never, never>, Record<never, never>, undefined>;
+};
+export {};

package/dist/contract/ws.js

@@ -0,0 +1,164 @@
+/**
+ * WebSocket contracts — portable data describing sockets and channels, shared
+ * by the server (`@fishenv/http/ws`) and typed clients.
+ *
+ * ```ts
+ * export const room = c
+ *   .channel("rooms/:roomId")
+ *   .param("roomId", v.pipe(v.string(), v.uuid()))
+ *   .join(JoinPayload, JoinReply, [ForbiddenError])
+ *   .clientEvent("message", MessageIn, MessageAck)
+ *   .serverEvent("message", Message)
+ *   .presence(PresenceMeta, { clientUpdates: true });
+ *
+ * export const socket = c.ws("/socket").channels(room);
+ * ```
+ *
+ * Like HTTP contracts, builders are immutable and expose a plain
+ * `_definition` snapshot; the compile-time shape is recovered with
+ * {@link InferChannel} / {@link InferSocket}.
+ */
+/** The channel protocol's subprotocol name. */
+export const CHANNELS_PROTOCOL = "fishenv.channels.v1";
+export class ChannelContract {
+    name;
+    #def;
+    constructor(name, def) {
+        if (name.startsWith("/")) {
+            throw new Error(`Channel name "${name}" must not start with "/"`);
+        }
+        this.name = name;
+        this.#def = def ?? {
+            name,
+            paramSchemas: new Map(),
+            join: {},
+            clientEvents: new Map(),
+            serverEvents: new Map(),
+        };
+    }
+    #next(patch) {
+        const def = this.#def;
+        return new ChannelContract(this.name, {
+            ...def,
+            paramSchemas: new Map(def.paramSchemas),
+            join: { ...def.join },
+            clientEvents: new Map(def.clientEvents),
+            serverEvents: new Map(def.serverEvents),
+            presence: def.presence ? { ...def.presence } : undefined,
+            meta: def.meta ? { ...def.meta } : undefined,
+            ...patch,
+        });
+    }
+    meta(data) {
+        return this.#next({ meta: { ...this.#def.meta, ...data } });
+    }
+    /** Narrow/coerce a channel-name param. */
+    param(name, schema) {
+        const paramSchemas = new Map(this.#def.paramSchemas);
+        paramSchemas.set(name, schema);
+        return this.#next({ paramSchemas });
+    }
+    /** Join payload, join reply and documented errors. All optional. */
+    join(payload, reply, errors) {
+        return this.#next({ join: { payload, reply, errors } });
+    }
+    /** Client → server event. Without `reply` it is fire-and-forget. */
+    clientEvent(name, payload, reply, errors) {
+        if (this.#def.clientEvents.has(name)) {
+            throw new Error(`clientEvent "${name}" is already defined`);
+        }
+        const clientEvents = new Map(this.#def.clientEvents);
+        clientEvents.set(name, { payload, reply, errors });
+        return this.#next({ clientEvents });
+    }
+    /** Server → client event. */
+    serverEvent(name, payload) {
+        if (this.#def.serverEvents.has(name)) {
+            throw new Error(`serverEvent "${name}" is already defined`);
+        }
+        const serverEvents = new Map(this.#def.serverEvents);
+        serverEvents.set(name, payload);
+        return this.#next({ serverEvents });
+    }
+    /**
+     * Enable presence for this channel. `clientUpdates` lets clients change
+     * their own meta (rate-limited server-side).
+     */
+    presence(meta, opts = {}) {
+        return this.#next({
+            presence: { meta, clientUpdates: opts.clientUpdates ?? false },
+        });
+    }
+    get _definition() {
+        return this.#def;
+    }
+}
+export class WsContract {
+    path;
+    #def;
+    constructor(path, def) {
+        this.path = path;
+        this.#def = def ?? {
+            path,
+            paramSchemas: new Map(),
+            kind: "raw",
+            channels: [],
+        };
+    }
+    #next(patch) {
+        const def = this.#def;
+        return new WsContract(this.path, {
+            ...def,
+            paramSchemas: new Map(def.paramSchemas),
+            channels: [...def.channels],
+            protocols: def.protocols ? [...def.protocols] : undefined,
+            ...patch,
+        });
+    }
+    meta(data) {
+        return this.#next({ meta: { ...this.#def.meta, ...data } });
+    }
+    param(name, schema) {
+        const paramSchemas = new Map(this.#def.paramSchemas);
+        paramSchemas.set(name, schema);
+        return this.#next({ paramSchemas });
+    }
+    /** Subprotocols for raw/message sockets (channels use their own). */
+    protocols(list) {
+        return this.#next({ protocols: [...list] });
+    }
+    /** A typed socket exchanging one JSON message type in each direction. */
+    messages(schemas) {
+        if (this.#def.kind === "channels") {
+            throw new Error("messages() and channels() are mutually exclusive");
+        }
+        return this.#next({ kind: "messages", messages: { ...schemas } });
+    }
+    /** A socket speaking the channel protocol with exactly these channels. */
+    channels(...channels) {
+        if (this.#def.kind === "messages") {
+            throw new Error("messages() and channels() are mutually exclusive");
+        }
+        const names = new Set();
+        for (const ch of channels) {
+            if (names.has(ch.name)) {
+                throw new Error(`Channel "${ch.name}" is listed twice`);
+            }
+            names.add(ch.name);
+        }
+        return this.#next({
+            kind: "channels",
+            channels: [...channels],
+            protocols: [CHANNELS_PROTOCOL],
+        });
+    }
+    get _definition() {
+        return this.#def;
+    }
+}
+export const wsContractFactories = {
+    /** A WebSocket endpoint. */
+    ws: (path) => new WsContract(path),
+    /** A channel, named with router path syntax (`rooms/:roomId`). */
+    channel: (name) => new ChannelContract(name),
+};

package/dist/core/compose.d.ts

@@ -0,0 +1,22 @@
+import type { DIContainer, ErrorHandlerFn, InterceptorPair, MiddlewareFn, RouteDefinition } from "./types.ts";
+/**
+ * Run the middleware pipeline, accumulating context via object spread.
+ * Each middleware receives the accumulated ctx and returns new fields to merge.
+ */
+export declare function runMiddlewarePipeline(req: Request, middlewares: MiddlewareFn<Record<string, unknown>, Record<string, unknown>>[], container: DIContainer): Promise<Record<string, unknown>>;
+/**
+ * Run before interceptors, the handler, then after interceptors (in reverse).
+ * Before and after share a mutable `state` object created per-request.
+ */
+export declare function runInterceptors(interceptors: InterceptorPair<Record<string, unknown>>[], req: Request, ctx: Record<string, unknown>, handlerFn: () => Promise<Response>): Promise<Response>;
+/**
+ * Coerce a handler's return value into a Response.
+ * - If already a Response, pass through.
+ * - If output schema is defined, serialize as JSON.
+ * - Otherwise throw — handler contract violation.
+ */
+export declare function coerceToResponse(raw: unknown, def: RouteDefinition): Response;
+/**
+ * Full request dispatch: middleware → input parsing → interceptors + handler → error chain.
+ */
+export declare function dispatch(req: Request, definition: RouteDefinition, params: Record<string, string>, container: DIContainer, errorHandlers: ErrorHandlerFn[]): Promise<Response>;