@fishenv/http 0.0.2 → 0.0.3

package/dist/contract/builder.d.ts

@@ -1,4 +1,4 @@
-import type { AnySchema, BasePathParams, HttpMethod, InferOutput, InputKind, InputOptions, MergeParam, RouteMeta } from "./types.ts";
+import type { AnySchema, BasePathParams, ErrorTypes, HttpMethod, InferOutput, InputKind, InputOptions, MergeParam, RouteMeta } from "./types.ts";
 /**
  * Plain-data snapshot of a contract endpoint.
  *
@@ -14,7 +14,7 @@ export interface ContractDefinition {
     inputKind: InputKind;
     inputOptions: InputOptions<InputKind>;
     outputSchema?: AnySchema;
-    errorTypes?: (new (...args: unknown[]) => Error)[];
+    errorTypes?: ErrorTypes;
     meta?: RouteMeta;
 }
 /**
@@ -30,7 +30,7 @@ export declare class ContractBuilder<M extends HttpMethod, P extends string, K e
     #private;
     readonly method: M;
     readonly path: P;
-    constructor(method: M, path: P, paramSchemas?: Map<string, AnySchema>, inputKind?: InputKind, inputOptions?: InputOptions<InputKind>, outputSchema?: AnySchema, errorTypes?: (new (...args: unknown[]) => Error)[], meta?: RouteMeta);
+    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 */
@@ -38,7 +38,7 @@ export declare class ContractBuilder<M extends HttpMethod, P extends string, K e
     /** 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?: (new (...args: unknown[]) => Error)[]): ContractBuilder<M, P, K, O, Params, InferOutput<S>>;
+    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
@@ -73,6 +73,11 @@ export type AnyContractBuilder = ContractBuilder<any, any, any, any, any, any>;
  * ```
  */
 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>;

package/dist/contract/builder.js

@@ -1,3 +1,4 @@
+import { wsContractFactories } from "./ws.js";
 /**
  * Fluent, immutable contract endpoint builder.
  *
@@ -78,6 +79,7 @@ function endpoint(method) {
  * ```
  */
 export const c = {
+    ...wsContractFactories,
     get: endpoint("GET"),
     post: endpoint("POST"),
     put: endpoint("PUT"),

package/dist/contract/index.d.ts

@@ -1,2 +1,4 @@
 export { type AnyContractBuilder, ContractBuilder, type ContractDefinition, type ContractShape, c, } from "./builder.ts";
-export type { AnySchema, BasePathParams, ExtractParams, HttpMethod, InferBody, InferCookies, InferHeaders, InferOutput, InferQuery, InputKind, InputOptions, MergeParam, RouteMeta, ValibotSchema, } from "./types.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

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

package/dist/contract/types.d.ts

@@ -25,7 +25,8 @@ export type InferBody<K extends InputKind, O extends InputOptions<K>> = K extend
 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>;
-export type ExtractParams<P extends string> = P extends `${string}:${infer Param}/${infer Rest}` ? (Param extends `${infer Name}?` ? Name : Param) | ExtractParams<`/${Rest}`> : P extends `${string}:${infer Param}` ? Param extends `${infer Name}?` ? Name : Param : never;
+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;
 };
@@ -37,3 +38,10 @@ export interface RouteMeta {
     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.js

@@ -50,6 +50,11 @@ export function coerceToResponse(raw, def) {
  */
 export async function dispatch(req, definition, params, container, errorHandlers) {
     try {
+        // 0. Guards run before any middleware
+        if (definition.guards) {
+            for (const guard of definition.guards)
+                await guard(req);
+        }
         // 1. Build context via middleware chain
         const ctx = await runMiddlewarePipeline(req, definition.middlewares, container);
         // 2. Parse & validate input

package/dist/core/error.d.ts

@@ -1,8 +1,27 @@
 import type * as v from "valibot";
 import type { HttpMethod } from "./types.ts";
+/** Stable machine-readable code for a status, e.g. `403` → `"forbidden"`. */
+export declare function errorCodeForStatus(status: number): string;
+/**
+ * Transport-neutral error payload. HTTP responses and WebSocket replies are
+ * both rendered from this, so they share one disclosure policy.
+ */
+export interface HttpErrorJSON {
+    status: number;
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+    stack?: string;
+}
 export declare class HttpError extends Error {
     readonly status: number;
     constructor(status: number, message: string, cause?: unknown);
+    /** Machine-readable code. Override in subclasses for custom errors. */
+    get code(): string;
+    /** Extra public fields (e.g. validation issues). Never include secrets. */
+    protected details(): Record<string, unknown> | undefined;
+    /** The public payload; the stack is only included in development. */
+    toJSON(development?: boolean): HttpErrorJSON;
     toResponse(development?: boolean): Response;
 }
 export declare class BadRequestError extends HttpError {
@@ -37,6 +56,8 @@ export declare class ValidationError extends HttpError {
     readonly field: ValidationField;
     readonly issues: v.BaseIssue<unknown>[];
     constructor(field: ValidationField, issues: v.BaseIssue<unknown>[]);
+    get code(): string;
+    protected details(): Record<string, unknown>;
     toResponse(): Response;
 }
 export interface ErrorHandlerOpts {

package/dist/core/error.js

@@ -1,3 +1,18 @@
+const CODES = {
+    400: "bad_request",
+    401: "unauthorized",
+    403: "forbidden",
+    404: "not_found",
+    405: "method_not_allowed",
+    409: "conflict",
+    422: "unprocessable_entity",
+    429: "too_many_requests",
+    500: "internal",
+};
+/** Stable machine-readable code for a status, e.g. `403` → `"forbidden"`. */
+export function errorCodeForStatus(status) {
+    return CODES[status] ?? `http_${status}`;
+}
 export class HttpError extends Error {
     status;
     constructor(status, message, cause) {
@@ -5,10 +20,33 @@ export class HttpError extends Error {
         this.status = status;
         this.name = "HttpError";
     }
-    toResponse(development = false) {
-        const body = { error: this.message };
+    /** Machine-readable code. Override in subclasses for custom errors. */
+    get code() {
+        return errorCodeForStatus(this.status);
+    }
+    /** Extra public fields (e.g. validation issues). Never include secrets. */
+    details() {
+        return undefined;
+    }
+    /** The public payload; the stack is only included in development. */
+    toJSON(development = false) {
+        const json = {
+            status: this.status,
+            code: this.code,
+            message: this.message,
+        };
+        const details = this.details();
+        if (details != null)
+            json.details = details;
         if (development && this.stack)
-            body.stack = this.stack;
+            json.stack = this.stack;
+        return json;
+    }
+    toResponse(development = false) {
+        const json = this.toJSON(development);
+        const body = { error: json.message };
+        if (json.stack)
+            body.stack = json.stack;
         return Response.json(body, { status: this.status });
     }
 }
@@ -66,15 +104,20 @@ export class ValidationError extends HttpError {
         this.field = field;
         this.issues = issues;
     }
-    toResponse() {
-        return Response.json({
-            error: "ValidationError",
+    get code() {
+        return "validation_error";
+    }
+    details() {
+        return {
             field: this.field,
             issues: this.issues.map((i) => ({
                 message: i.message,
                 path: i.path?.map((p) => p.key) ?? [],
             })),
-        }, { status: 400 });
+        };
+    }
+    toResponse() {
+        return Response.json({ error: "ValidationError", ...this.details() }, { status: 400 });
     }
 }
 export function defaultErrorHandler(err, _args, opts = {}) {

package/dist/core/index.d.ts

@@ -1,8 +1,8 @@
 export { coerceToResponse, dispatch, runInterceptors, runMiddlewarePipeline, } from "./compose.ts";
 export type { CompiledCors, CorsOptions } from "./cors.ts";
 export { buildCors } from "./cors.ts";
-export type { ValidationField } from "./error.ts";
-export { BadRequestError, ConflictError, defaultErrorHandler, defaultMethodNotAllowedHandler, defaultNotFoundHandler, ForbiddenError, HttpError, InternalServerError, MethodNotAllowedError, NotFoundError, TooManyRequestsError, UnauthorizedError, UnprocessableEntityError, ValidationError, } from "./error.ts";
+export type { HttpErrorJSON, ValidationField } from "./error.ts";
+export { BadRequestError, ConflictError, defaultErrorHandler, defaultMethodNotAllowedHandler, defaultNotFoundHandler, errorCodeForStatus, ForbiddenError, HttpError, InternalServerError, MethodNotAllowedError, NotFoundError, TooManyRequestsError, UnauthorizedError, UnprocessableEntityError, ValidationError, } from "./error.ts";
 export type { MatchedRoute, RouterMatcher } from "./matcher.ts";
 export { Matcher } from "./matcher.ts";
 export type { ParsedInput } from "./request.ts";
@@ -11,6 +11,10 @@ export type { RouterRef } from "./route-builder.ts";
 export { createRouteBuilder, createRouteBuilderFromContract, FinishedRoute, RouteBuilder, } from "./route-builder.ts";
 export type { CtxOf, HttpServer, Logger, ServeOptions } from "./router.ts";
 export { Router, r, router, serve } from "./router.ts";
-export type { AfterInterceptorFn, AnySchema, BasePathParams, BeforeInterceptorFn, DIContainer, ErrorHandlerFn, ExtractParams, HandlerArgs, HandlerFn, HttpMethod, InferBody, InferCookies, InferHeaders, InferOutput, InferQuery, InputKind, InputOptions, InterceptorPair, InterceptorState, MergeCtx, MergeParam, MiddlewareFn, NotFoundHandler, ResolvedInput, RouteDefinition, RouteMeta, ValibotSchema, } from "./types.ts";
+export type { Transport, TransportBridge, TransportEnvelope, WithoutOrigin, } from "./transport.ts";
+export { createMemoryTransport, createTransportBridge } from "./transport.ts";
+export type { AfterInterceptorFn, AnySchema, BasePathParams, BeforeInterceptorFn, BuildEnv, DIContainer, ErrorHandlerFn, ExtractParams, HandlerArgs, HandlerFn, HttpMethod, InferBody, InferCookies, InferHeaders, InferOutput, InferQuery, InputKind, InputOptions, InterceptorPair, InterceptorState, MergeCtx, MergeParam, MiddlewareFn, NotFoundHandler, ResolvedInput, RouteDefinition, RouteGuardFn, RouteMeta, ValibotSchema, } from "./types.ts";
+export type { SocketData, SocketHandlers, UpgradedSocket, UpgradeIntent, WebSocketRuntime, WsServerOptions, } from "./upgrade.ts";
+export { CLOSE_GOING_AWAY, CLOSE_INTERNAL_ERROR, completeUpgrade, createWebSocketRuntime, DEFAULT_BACKPRESSURE_LIMIT, DEFAULT_MAX_PAYLOAD_LENGTH, requestUpgrade, takeUpgrade, } from "./upgrade.ts";
 export { buildRouteRegex, extractParamNames, mergePaths } from "./utils/url.ts";
 export { validateField, validatePathParams } from "./validation.ts";

package/dist/core/index.js

@@ -4,7 +4,7 @@ export { coerceToResponse, dispatch, runInterceptors, runMiddlewarePipeline, } f
 // CORS
 export { buildCors } from "./cors.js";
 // Errors
-export { BadRequestError, ConflictError, defaultErrorHandler, defaultMethodNotAllowedHandler, defaultNotFoundHandler, ForbiddenError, HttpError, InternalServerError, MethodNotAllowedError, NotFoundError, TooManyRequestsError, UnauthorizedError, UnprocessableEntityError, ValidationError, } from "./error.js";
+export { BadRequestError, ConflictError, defaultErrorHandler, defaultMethodNotAllowedHandler, defaultNotFoundHandler, errorCodeForStatus, ForbiddenError, HttpError, InternalServerError, MethodNotAllowedError, NotFoundError, TooManyRequestsError, UnauthorizedError, UnprocessableEntityError, ValidationError, } from "./error.js";
 // Matcher
 export { Matcher } from "./matcher.js";
 // Request parsing
@@ -13,6 +13,10 @@ export { extractHeaders, extractQuery, parseBody, parseCookies, parseInput, } fr
 export { createRouteBuilder, createRouteBuilderFromContract, FinishedRoute, RouteBuilder, } from "./route-builder.js";
 // Router
 export { Router, r, router, serve } from "./router.js";
+// Transport (shared by SSE and WS hubs)
+export { createMemoryTransport, createTransportBridge } from "./transport.js";
+// WebSocket upgrade plumbing
+export { CLOSE_GOING_AWAY, CLOSE_INTERNAL_ERROR, completeUpgrade, createWebSocketRuntime, DEFAULT_BACKPRESSURE_LIMIT, DEFAULT_MAX_PAYLOAD_LENGTH, requestUpgrade, takeUpgrade, } from "./upgrade.js";
 // URL utilities
 export { buildRouteRegex, extractParamNames, mergePaths } from "./utils/url.js";
 // Validation

package/dist/core/matcher.js

@@ -4,8 +4,9 @@ function specificity(path) {
     return path.split("/").reduce((score, seg) => {
         if (!seg)
             return score;
-        if (seg === "**")
+        if (seg === "**" || (seg.startsWith(":") && seg.endsWith("*"))) {
             return score + 0;
+        }
         if (seg.includes("*") || seg.includes("{"))
             return score + 1;
         if (seg.startsWith(":"))

package/dist/core/route-builder.d.ts

@@ -1,4 +1,4 @@
-import type { AnyContractBuilder, ContractShape } from "../contract/index.ts";
+import type { AnyContractBuilder, ContractShape, ErrorTypes } from "../contract/index.ts";
 import type { AfterInterceptorFn, AnySchema, BasePathParams, BeforeInterceptorFn, ErrorHandlerFn, HandlerArgs, HttpMethod, InferOutput, InputKind, InputOptions, InterceptorPair, MergeParam, MiddlewareFn, RouteDefinition, RouteMeta } from "./types.ts";
 /**
  * Internal interface — the Router class (step 06) will implement this.
@@ -26,7 +26,7 @@ export declare class FinishedRoute {
  */
 export declare class RouteBuilder<RouterCtx extends Record<string, unknown>, RouteCtx extends Record<string, unknown>, K extends InputKind = "none", O extends InputOptions<K> = InputOptions<K>, Params extends Record<string, unknown> = Record<string, unknown>, Output = undefined> {
     #private;
-    constructor(router: RouterRef, method: HttpMethod, path: string, middlewares?: MiddlewareFn<Record<string, unknown>, Record<string, unknown>>[], paramSchemas?: Map<string, AnySchema>, inputKind?: InputKind, inputOptions?: InputOptions<InputKind>, outputSchema?: AnySchema, errorTypes?: (new (...args: unknown[]) => Error)[], meta?: RouteMeta, interceptors?: InterceptorPair<Record<string, unknown>>[]);
+    constructor(router: RouterRef, method: HttpMethod, path: string, middlewares?: MiddlewareFn<Record<string, unknown>, Record<string, unknown>>[], paramSchemas?: Map<string, AnySchema>, inputKind?: InputKind, inputOptions?: InputOptions<InputKind>, outputSchema?: AnySchema, errorTypes?: ErrorTypes, meta?: RouteMeta, interceptors?: InterceptorPair<Record<string, unknown>>[]);
     /** Set route metadata (title, tags, etc.) — mutates, returns this */
     meta(data: RouteMeta): this;
     /** Narrow/coerce a path param with a Valibot schema — returns new builder */
@@ -36,11 +36,11 @@ export declare class RouteBuilder<RouterCtx extends Record<string, unknown>, Rou
     /** Set input kind and options — returns new builder */
     input<NK extends InputKind, NO extends InputOptions<NK>>(kind: NK, options?: NO): RouteBuilder<RouterCtx, RouteCtx, 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?: (new (...args: unknown[]) => Error)[]): RouteBuilder<RouterCtx, RouteCtx, K, O, Params, InferOutput<S>>;
+    output<S extends AnySchema>(schema: S, errors?: ErrorTypes): RouteBuilder<RouterCtx, RouteCtx, K, O, Params, InferOutput<S>>;
     /** Add a before/after interceptor pair — mutates, returns this */
     intercept(before?: BeforeInterceptorFn<RouterCtx & RouteCtx>, after?: AfterInterceptorFn<RouterCtx & RouteCtx>): this;
     /** Terminal — registers the route on the router and returns a FinishedRoute */
-    handle(fn: (args: HandlerArgs<RouterCtx & RouteCtx, K, O, Params>) => Output extends undefined ? Response | Promise<Response> : Response | Output | Promise<Response | Output>): FinishedRoute;
+    handle(fn: (args: HandlerArgs<RouterCtx & RouteCtx, K, O, Params>) => [Output] extends [undefined] ? Response | Promise<Response> : Response | Output | Promise<Response | Output>): FinishedRoute;
 }
 /**
  * Factory — creates a RouteBuilder bound to a router reference.