@fishenv/http 0.0.0-stage → 0.0.2

package/dist/core/matcher.d.ts

@@ -0,0 +1,17 @@
+import type { HttpMethod, RouteDefinition } from "./types.ts";
+export interface MatchedRoute {
+    definition: RouteDefinition;
+    params: Record<string, string>;
+    allowedMethods?: HttpMethod[];
+}
+export interface RouterMatcher {
+    add(method: HttpMethod | "ALL", path: string, def: RouteDefinition): void;
+    match(method: string, path: string): MatchedRoute | null;
+    compile(): void;
+}
+export declare class Matcher implements RouterMatcher {
+    #private;
+    add(method: HttpMethod | "ALL", path: string, def: RouteDefinition): void;
+    compile(): void;
+    match(method: string, path: string): MatchedRoute | null;
+}

package/dist/core/matcher.js

@@ -0,0 +1,109 @@
+import { buildRouteRegex } from "./utils/url.js";
+/** Score: more static segments = higher, broad globs = lower */
+function specificity(path) {
+    return path.split("/").reduce((score, seg) => {
+        if (!seg)
+            return score;
+        if (seg === "**")
+            return score + 0;
+        if (seg.includes("*") || seg.includes("{"))
+            return score + 1;
+        if (seg.startsWith(":"))
+            return score + 2;
+        return score + 3;
+    }, 0);
+}
+function hasPatternSyntax(path) {
+    return path.includes(":") || path.includes("*") || path.includes("{");
+}
+export class Matcher {
+    #rawRoutes = [];
+    #compiled = false;
+    // Per method: static map + dynamic list
+    #staticRoutes = new Map();
+    #dynamicRoutes = new Map();
+    add(method, path, def) {
+        if (this.#compiled) {
+            throw new Error("Cannot add routes after compile()");
+        }
+        this.#rawRoutes.push({ method: method.toUpperCase(), path, def });
+    }
+    compile() {
+        for (const { method, path, def } of this.#rawRoutes) {
+            if (!hasPatternSyntax(path)) {
+                // Static path
+                if (!this.#staticRoutes.has(method)) {
+                    this.#staticRoutes.set(method, new Map());
+                }
+                this.#staticRoutes.get(method).set(path, def);
+            }
+            else {
+                // Dynamic path
+                const { regex, paramNames } = buildRouteRegex(path);
+                const compiled = { regex, paramNames, definition: def };
+                if (!this.#dynamicRoutes.has(method)) {
+                    this.#dynamicRoutes.set(method, []);
+                }
+                this.#dynamicRoutes.get(method).push(compiled);
+            }
+        }
+        // Sort dynamic routes: higher specificity first
+        for (const list of this.#dynamicRoutes.values()) {
+            list.sort((a, b) => specificity(b.definition.path) - specificity(a.definition.path));
+        }
+        this.#compiled = true;
+    }
+    match(method, path) {
+        method = method.toUpperCase();
+        // Check static routes (exact method, then ALL)
+        const def = this.#staticRoutes.get(method)?.get(path) ??
+            this.#staticRoutes.get("ALL")?.get(path);
+        if (def)
+            return { definition: def, params: {} };
+        // Check dynamic routes (exact method, then ALL)
+        const dynamicForMethod = this.#dynamicRoutes.get(method) ?? [];
+        const dynamicForAll = this.#dynamicRoutes.get("ALL") ?? [];
+        for (const route of [...dynamicForMethod, ...dynamicForAll]) {
+            const m = route.regex.exec(path);
+            if (m) {
+                const params = {};
+                route.paramNames.forEach((name, i) => {
+                    if (m[i + 1] !== undefined) {
+                        params[name] = m[i + 1];
+                    }
+                });
+                return { definition: route.definition, params };
+            }
+        }
+        // 405: check if ANY method matches this path
+        const allowed = this.#findAllowedMethods(path);
+        if (allowed.length > 0) {
+            return {
+                definition: undefined,
+                params: {},
+                allowedMethods: allowed,
+            };
+        }
+        return null;
+    }
+    #findAllowedMethods(path) {
+        const methods = new Set();
+        for (const [method, map] of this.#staticRoutes) {
+            if (method === "ALL")
+                continue;
+            if (map.has(path))
+                methods.add(method);
+        }
+        for (const [method, routes] of this.#dynamicRoutes) {
+            if (method === "ALL")
+                continue;
+            for (const route of routes) {
+                if (route.regex.test(path)) {
+                    methods.add(method);
+                    break;
+                }
+            }
+        }
+        return [...methods];
+    }
+}

package/dist/core/request.d.ts

@@ -0,0 +1,28 @@
+import type { InputKind, InputOptions, RouteDefinition } from "./types.ts";
+export interface ParsedInput {
+    body: unknown;
+    headers: Record<string, string>;
+    query: Record<string, string | string[]>;
+    cookies: Record<string, string>;
+    path: Record<string, unknown>;
+}
+/**
+ * Parse and validate all input from a request according to the route definition.
+ */
+export declare function parseInput(req: Request, def: RouteDefinition, rawParams: Record<string, string>): Promise<ParsedInput>;
+/**
+ * Parse the request body based on InputKind.
+ */
+export declare function parseBody(req: Request, kind: InputKind, opts: InputOptions<InputKind>): Promise<unknown>;
+/**
+ * Extract all headers as a lowercased-key record.
+ */
+export declare function extractHeaders(req: Request): Record<string, string>;
+/**
+ * Parse cookies from the Cookie header.
+ */
+export declare function parseCookies(req: Request): Record<string, string>;
+/**
+ * Extract query parameters. Duplicate keys become arrays.
+ */
+export declare function extractQuery(req: Request): Record<string, string | string[]>;

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 } 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?: (new (...args: unknown[]) => Error)[], 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?: (new (...args: unknown[]) => Error)[]): 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,148 @@
+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, DIContainer, ErrorHandlerFn, InputOptions, MiddlewareFn, NotFoundHandler, RouteDefinition } from "./types.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;
+    build(): void;
+    /**
+     * Entry point for request handling — available after build().
+     * Use directly for testing without binding a port.
+     */
+    readonly fetch: (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;
+    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. */
+    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 {};