@fishenv/http 0.0.0-stage → 0.0.3

package/dist/core/request.js

@@ -0,0 +1,106 @@
+import { BadRequestError, HttpError } from "./error.js";
+import { validateField, validatePathParams } from "./validation.js";
+/**
+ * Parse and validate all input from a request according to the route definition.
+ */
+export async function parseInput(req, def, rawParams) {
+    const cookies = parseCookies(req);
+    const headers = extractHeaders(req);
+    const query = extractQuery(req);
+    const body = await parseBody(req, def.inputKind, def.inputOptions);
+    const path = validatePathParams(rawParams, def.paramSchemas);
+    // Validate each field if a schema is provided
+    const opts = def.inputOptions;
+    return {
+        body: opts.body ? validateField(opts.body, body, "body") : body,
+        headers: (opts.headers
+            ? validateField(opts.headers, headers, "headers")
+            : headers),
+        query: (opts.query
+            ? validateField(opts.query, query, "query")
+            : query),
+        cookies: (opts.cookies
+            ? validateField(opts.cookies, cookies, "cookies")
+            : cookies),
+        path,
+    };
+}
+/**
+ * Parse the request body based on InputKind.
+ */
+export async function parseBody(req, kind, opts) {
+    switch (kind) {
+        case "json":
+            try {
+                return await req.json();
+            }
+            catch (e) {
+                throw new BadRequestError("Invalid JSON", e);
+            }
+        case "multipart":
+        case "urlencoded":
+            enforceMaxSize(req, opts.maxSize);
+            return req.formData();
+        case "blob":
+            enforceMaxSize(req, opts.maxSize);
+            return req.blob();
+        case "text":
+            return req.text();
+        case "none":
+        default:
+            return undefined;
+    }
+}
+/**
+ * Check Content-Length against maxSize before reading the body.
+ */
+function enforceMaxSize(req, maxSize) {
+    if (!maxSize)
+        return;
+    const contentLength = req.headers.get("content-length");
+    if (contentLength && parseInt(contentLength) > maxSize) {
+        throw new HttpError(413, "Payload Too Large");
+    }
+}
+/**
+ * Extract all headers as a lowercased-key record.
+ */
+export function extractHeaders(req) {
+    const headers = {};
+    req.headers.forEach((value, key) => {
+        headers[key] = value; // Headers API already lowercases keys
+    });
+    return headers;
+}
+/**
+ * Parse cookies from the Cookie header.
+ */
+export function parseCookies(req) {
+    const header = req.headers.get("cookie") ?? "";
+    if (!header)
+        return {};
+    return Object.fromEntries(header
+        .split(";")
+        .map((pair) => pair.trim().split("="))
+        .filter(([k]) => k?.length > 0)
+        .map(([k, ...v]) => [k.trim(), decodeURIComponent(v.join("="))]));
+}
+/**
+ * Extract query parameters. Duplicate keys become arrays.
+ */
+export function extractQuery(req) {
+    const params = {};
+    new URL(req.url).searchParams.forEach((value, key) => {
+        const existing = params[key];
+        if (existing === undefined) {
+            params[key] = value;
+        }
+        else if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else {
+            params[key] = [existing, value];
+        }
+    });
+    return params;
+}

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

@@ -0,0 +1,58 @@
+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.
+ * Allows RouteBuilder to register completed routes without a circular dependency.
+ */
+export interface RouterRef {
+    _registerRoute(def: RouteDefinition): void;
+    _getMiddlewares(): MiddlewareFn<Record<string, unknown>, Record<string, unknown>>[];
+    _getPrefix(): string;
+}
+/**
+ * A completed route — returned by `RouteBuilder.handle()`.
+ * Exposes the route definition for testing/introspection and allows `.catch()`.
+ */
+export declare class FinishedRoute {
+    readonly definition: RouteDefinition;
+    constructor(definition: RouteDefinition);
+    catch(fn: ErrorHandlerFn): this;
+}
+/**
+ * Fluent route builder chain.
+ *
+ * Each method that changes generic type params returns a new instance.
+ * Methods that only add runtime data (.meta(), .intercept()) mutate and return `this`.
+ */
+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?: 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 */
+    param<Name extends string & keyof Params, S extends AnySchema>(name: Name, schema: S): RouteBuilder<RouterCtx, RouteCtx, K, O, MergeParam<Params, Name, S>, Output>;
+    /** Add route-level middleware — returns new builder with extended context */
+    with<NewCtx extends Record<string, unknown>>(mw: MiddlewareFn<RouterCtx & RouteCtx, NewCtx>): RouteBuilder<RouterCtx, RouteCtx & NewCtx, K, O, Params, Output>;
+    /** 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?: 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;
+}
+/**
+ * Factory — creates a RouteBuilder bound to a router reference.
+ * Used internally by the Router class method helpers (.get(), .post(), etc.)
+ */
+export declare function createRouteBuilder<RouterCtx extends Record<string, unknown>, P extends string>(router: RouterRef, method: HttpMethod, path: P): RouteBuilder<RouterCtx, Record<never, never>, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+/**
+ * Factory — creates a `RouteBuilder` pre-populated from a `@fishenv/http-contract`
+ * endpoint (method, path, params, input, output). Used by `Router.contract()`.
+ *
+ * The returned builder carries exactly the generic shape (`K`, `O`, `Params`,
+ * `Output`) declared on the contract endpoint, so `.handle()` gets the same
+ * type safety as manually chaining `.input().output().param()`.
+ */
+export declare function createRouteBuilderFromContract<RouterCtx extends Record<string, unknown>, C extends AnyContractBuilder>(router: RouterRef, endpoint: C): RouteBuilder<RouterCtx, Record<never, never>, ContractShape<C>["inputKind"], ContractShape<C>["inputOptions"], ContractShape<C>["params"], ContractShape<C>["output"]>;

package/dist/core/route-builder.js

@@ -0,0 +1,122 @@
+/**
+ * A completed route — returned by `RouteBuilder.handle()`.
+ * Exposes the route definition for testing/introspection and allows `.catch()`.
+ */
+export class FinishedRoute {
+    definition;
+    constructor(definition) {
+        this.definition = definition;
+    }
+    catch(fn) {
+        this.definition.errorHandler = fn;
+        return this;
+    }
+}
+/**
+ * Fluent route builder chain.
+ *
+ * Each method that changes generic type params returns a new instance.
+ * Methods that only add runtime data (.meta(), .intercept()) mutate and return `this`.
+ */
+export class RouteBuilder {
+    #router;
+    #method;
+    #path;
+    #middlewares;
+    #paramSchemas;
+    #inputKind;
+    #inputOptions;
+    #outputSchema;
+    #errorTypes;
+    #meta;
+    #interceptors;
+    constructor(router, method, path, middlewares = [], paramSchemas = new Map(), inputKind = "none", inputOptions = {}, outputSchema, errorTypes, meta, interceptors = []) {
+        this.#router = router;
+        this.#method = method;
+        this.#path = path;
+        this.#middlewares = middlewares;
+        this.#paramSchemas = paramSchemas;
+        this.#inputKind = inputKind;
+        this.#inputOptions = inputOptions;
+        this.#outputSchema = outputSchema;
+        this.#errorTypes = errorTypes;
+        this.#meta = meta;
+        this.#interceptors = interceptors;
+    }
+    /** Set route metadata (title, tags, etc.) — mutates, returns this */
+    meta(data) {
+        this.#meta = { ...this.#meta, ...data };
+        return this;
+    }
+    /** 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 RouteBuilder(this.#router, this.#method, this.#path, [...this.#middlewares], newSchemas, this.#inputKind, this.#inputOptions, this.#outputSchema, this.#errorTypes ? [...this.#errorTypes] : undefined, this.#meta ? { ...this.#meta } : undefined, [...this.#interceptors]);
+    }
+    /** Add route-level middleware — returns new builder with extended context */
+    with(mw) {
+        return new RouteBuilder(this.#router, this.#method, this.#path, [
+            ...this.#middlewares,
+            mw,
+        ], new Map(this.#paramSchemas), this.#inputKind, this.#inputOptions, this.#outputSchema, this.#errorTypes ? [...this.#errorTypes] : undefined, this.#meta ? { ...this.#meta } : undefined, [...this.#interceptors]);
+    }
+    /** Set input kind and options — returns new builder */
+    input(kind, options) {
+        return new RouteBuilder(this.#router, this.#method, this.#path, [...this.#middlewares], new Map(this.#paramSchemas), kind, (options ?? {}), this.#outputSchema, this.#errorTypes ? [...this.#errorTypes] : undefined, this.#meta ? { ...this.#meta } : undefined, [...this.#interceptors]);
+    }
+    /** Set output schema + optional error types — returns new builder */
+    output(schema, errors) {
+        return new RouteBuilder(this.#router, this.#method, this.#path, [...this.#middlewares], new Map(this.#paramSchemas), this.#inputKind, this.#inputOptions, schema, errors, this.#meta ? { ...this.#meta } : undefined, [...this.#interceptors]);
+    }
+    /** Add a before/after interceptor pair — mutates, returns this */
+    intercept(before, after) {
+        this.#interceptors.push({
+            before: before,
+            after: after,
+        });
+        return this;
+    }
+    /** Terminal — registers the route on the router and returns a FinishedRoute */
+    handle(fn) {
+        const fullPath = this.#router._getPrefix()
+            ? `${this.#router._getPrefix()}${this.#path}`
+            : this.#path;
+        const routerMiddlewares = this.#router._getMiddlewares();
+        const definition = {
+            method: this.#method,
+            path: fullPath,
+            middlewares: [...routerMiddlewares, ...this.#middlewares],
+            paramSchemas: this.#paramSchemas,
+            inputKind: this.#inputKind,
+            inputOptions: this.#inputOptions,
+            outputSchema: this.#outputSchema,
+            errorTypes: this.#errorTypes,
+            meta: this.#meta,
+            interceptors: this.#interceptors,
+            handler: fn,
+            kind: "http",
+        };
+        this.#router._registerRoute(definition);
+        return new FinishedRoute(definition);
+    }
+}
+/**
+ * Factory — creates a RouteBuilder bound to a router reference.
+ * Used internally by the Router class method helpers (.get(), .post(), etc.)
+ */
+export function createRouteBuilder(router, method, path) {
+    return new RouteBuilder(router, method, path);
+}
+/**
+ * Factory — creates a `RouteBuilder` pre-populated from a `@fishenv/http-contract`
+ * endpoint (method, path, params, input, output). Used by `Router.contract()`.
+ *
+ * The returned builder carries exactly the generic shape (`K`, `O`, `Params`,
+ * `Output`) declared on the contract endpoint, so `.handle()` gets the same
+ * type safety as manually chaining `.input().output().param()`.
+ */
+export function createRouteBuilderFromContract(router, endpoint) {
+    const def = endpoint._definition;
+    return new RouteBuilder(router, def.method, def.path, [], new Map(def.paramSchemas), def.inputKind, def.inputOptions, def.outputSchema, def.errorTypes ? [...def.errorTypes] : undefined, def.meta ? { ...def.meta } : undefined, []);
+}

package/dist/core/router.d.ts

@@ -0,0 +1,162 @@
+import type { AnyContractBuilder, ContractShape } from "../contract/index.ts";
+import { type CorsOptions } from "./cors.ts";
+import { type RouteBuilder, type RouterRef } from "./route-builder.ts";
+import type { BasePathParams, BuildEnv, DIContainer, ErrorHandlerFn, InputOptions, MiddlewareFn, NotFoundHandler, RouteDefinition } from "./types.ts";
+import { type WsServerOptions } from "./upgrade.ts";
+type AnyRouter = Router<any, any>;
+/**
+ * A router mounted via `.add()`, together with the prefix and middleware of
+ * the parent variant it was mounted on. Applied to the child's routes at build().
+ */
+interface MountedRouter {
+    router: AnyRouter;
+    prefix: string;
+    middlewares: MiddlewareFn<Record<string, unknown>, Record<string, unknown>>[];
+}
+/**
+ * Shared mutable state between a Router and all its .use() variants.
+ * Routes registered on any variant end up in the same store.
+ */
+interface RouterStore {
+    routes: RouteDefinition[];
+    children: MountedRouter[];
+    locked: boolean;
+}
+/**
+ * Router — immutable middleware chain, mutable route registration.
+ *
+ * `.use()` returns a new Router with the extended Ctx type but the same
+ * backing store — routes registered on either instance are collected together.
+ * Route methods (.get, .post, etc.) return a RouteBuilder chain.
+ * Call `.build()` before `.fetch` or `serve()`.
+ *
+ * `Requires` is the context this router expects a parent to provide when it
+ * is mounted via `.add()`. Create one with `r<AppCtx>()`; `.add()` only
+ * accepts it on a parent whose `Ctx` satisfies `AppCtx`, and `serve()` only
+ * accepts routers with no outstanding requirements.
+ */
+export declare class Router<Ctx extends Record<string, unknown> = Record<never, never>, Requires extends Record<string, unknown> = Record<never, never>> implements RouterRef {
+    #private;
+    /** @internal Phantom — makes `Requires` contravariant for `.add()` checks. */
+    readonly _requires?: (ctx: Requires) => void;
+    constructor(opts?: {
+        prefix?: string;
+    }, middlewares?: MiddlewareFn<Record<string, unknown>, Record<string, unknown>>[], errorHandler?: ErrorHandlerFn, notFoundHandler?: NotFoundHandler, store?: RouterStore);
+    _registerRoute(def: RouteDefinition): void;
+    _getMiddlewares(): MiddlewareFn<Record<string, unknown>, Record<string, unknown>>[];
+    _getPrefix(): string;
+    use<NewCtx extends Record<string, unknown>>(mw: MiddlewareFn<Ctx, NewCtx>): Router<Ctx & NewCtx, Requires>;
+    /** Create a child router and mount it on this one — shorthand for `r<Ctx>(opts)` + `.add()`. */
+    extend(opts?: {
+        prefix?: string;
+    }): Router<Ctx, Ctx>;
+    /**
+     * Mount routers defined elsewhere, optionally under an extra prefix:
+     *
+     * ```ts
+     * app.add(users, posts);
+     * app.add("/v1", users);
+     * ```
+     *
+     * Each child's routes get this router's prefix and middleware prepended at
+     * build(). A child created with `r<AppCtx>()` only type-checks here if this
+     * router's context provides `AppCtx`.
+     */
+    add(...children: Router<any, Ctx>[]): this;
+    add(prefix: string, ...children: Router<any, Ctx>[]): this;
+    get<P extends string>(path: P): RouteBuilder<Ctx, Record<never, never>, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    post<P extends string>(path: P): RouteBuilder<Ctx, Record<never, never>, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    put<P extends string>(path: P): RouteBuilder<Ctx, Record<never, never>, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    patch<P extends string>(path: P): RouteBuilder<Ctx, Record<never, never>, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    delete<P extends string>(path: P): RouteBuilder<Ctx, Record<never, never>, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    options<P extends string>(path: P): RouteBuilder<Ctx, Record<never, never>, "none", InputOptions<"none">, BasePathParams<P>, undefined>;
+    /**
+     * Register a route from a `@fishenv/http-contract` endpoint definition, e.g.:
+     *
+     * ```ts
+     * router.contract(contract.users.create).handle(({ body }) => { ... });
+     * ```
+     *
+     * `.handle()` gets exactly the same type safety (body/query/params/output)
+     * as chaining `.input().output().param()` manually, because the contract
+     * endpoint and the route builder share the same shape types.
+     */
+    contract<C extends AnyContractBuilder>(endpoint: C): RouteBuilder<Ctx, Record<never, never>, ContractShape<C>["inputKind"], ContractShape<C>["inputOptions"], ContractShape<C>["params"], ContractShape<C>["output"]>;
+    cors(options: CorsOptions): this;
+    onError(handler: ErrorHandlerFn): this;
+    notFound(handler: NotFoundHandler): this;
+    /** @internal Set by serve(). For testing, call before build(). */
+    _setContainer(container: DIContainer): void;
+    /** @internal Set by serve() before build(); forwarded to route `onBuild` hooks. */
+    _setEnv(env: Partial<Omit<BuildEnv, "cors">>): void;
+    build(): void;
+    /**
+     * Entry point for request handling — available after build().
+     * Use directly for testing without binding a port.
+     */
+    readonly fetch: (req: Request) => Promise<Response>;
+    /**
+     * @internal Used by serve(): HEAD responses keep their body so Bun can
+     * derive `Content-Length` from it before dropping it (it does not drain
+     * streams to do so).
+     */
+    readonly _serverFetch: (req: Request) => Promise<Response>;
+}
+/**
+ * Create a router. Pass a context type to declare what a parent must provide
+ * when this router is mounted with `.add()`:
+ *
+ * ```ts
+ * // context.ts
+ * export const base = r().use(auth);
+ * export type AppCtx = CtxOf<typeof base>;
+ *
+ * // users.ts — type-only import, no runtime cycle
+ * export const users = r<AppCtx>({ prefix: "/users" });
+ *
+ * // main.ts
+ * serve(base.add(users));
+ * ```
+ */
+export declare function r<Req extends Record<string, unknown> = Record<never, never>>(opts?: {
+    prefix?: string;
+}): Router<Req, Req>;
+export declare const router: typeof r;
+/** The context type a router's handlers receive. */
+export type CtxOf<R> = R extends Router<infer C, infer _> ? C : never;
+export interface ServeOptions {
+    port?: number;
+    hostname?: string;
+    container?: DIContainer;
+    development?: boolean;
+    logger?: Logger;
+    signal?: AbortSignal;
+    /**
+     * Seconds a connection may sit idle before Bun closes it. Defaults to `0`
+     * (disabled) so long-lived SSE streams are not cut between keepalives.
+     */
+    idleTimeout?: number;
+    /** Server-wide WebSocket settings (secure defaults; see {@link WsServerOptions}). */
+    websocket?: WsServerOptions;
+    onListen?: (addr: {
+        hostname: string;
+        port: number;
+    }) => void;
+}
+/** A running server started by {@link serve}. */
+export interface HttpServer {
+    readonly hostname: string;
+    readonly port: number;
+    /**
+     * Stop accepting connections; `force` also closes in-flight ones. Open
+     * WebSockets are always closed with `1001 Going Away` first.
+     */
+    stop(force?: boolean): Promise<void>;
+}
+export interface Logger {
+    error(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+}
+export declare function serve(app: Router<any, Record<never, never>>, options?: ServeOptions): HttpServer;
+export {};