@theokit/http 0.5.4 → 0.7.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { z } from 'zod';
-import { D as DiContainer, M as MiddlewareConsumerImpl } from './middleware-consumer-ljxK1fU_.js';
-export { a as MiddlewareConfigProxy, b as MiddlewareFn, N as NestMiddleware, R as ResolvedMiddleware, m as middlewareMatchesPath, r as resolveOrNew, c as runMiddleware } from './middleware-consumer-ljxK1fU_.js';
+import { D as DiContainer, M as MiddlewareConsumerImpl } from './middleware-consumer-DcaksawH.js';
+export { a as MiddlewareConfigProxy, b as MiddlewareFn, N as NestMiddleware, R as ResolvedMiddleware, m as middlewareMatchesPath, r as resolveOrNew, c as runMiddleware } from './middleware-consumer-DcaksawH.js';
 import { S as ServerHandle } from './types-CGthbcon.js';
 export { ReadinessCheck, TheoApp, TheoAppOptions } from './app.js';
+import * as ReactTypes from 'react';
 
 interface ControllerOptions {
     host?: string;
@@ -69,6 +70,50 @@ declare function Res(opts?: {
     passthrough?: boolean;
 }): ParameterDecorator;
 
+/**
+ * M47 (ADR-M47-1) — `@Expose(agent, opts?)` binds a SEPARATELY-BUILT agent (a pure `agent()…build()` from
+ * `agents/<name>.ts`) to a controller PROPERTY, making the exposure (route, auth via `@UseGuards`, streaming)
+ * visible in one code review. It mirrors the #122 verb decorators (`@Post`) — storing metadata via the same
+ * `Symbol.for()` seam — but records the agent instead of an HTTP verb, so the controller walker turns the
+ * property into an agent-serving route (`POST <prefix>/<property>`) delegated to the ONE runtime
+ * (`mountAgent`), never a JSON handler. It is a new AUTHORING surface over the existing runtime, not a
+ * parallel runtime (G2). CSRF is enforced once at the controller-dispatch boundary. Interceptors do NOT run
+ * for agent routes (the dispatcher delegates straight to `mountAgent`); guards DO (G5). The served path is
+ * the controller prefix + property name — keep it equal to the agent's convention route (`/api/agents/<name>`
+ * for a property named `<name>` under `@Controller('api/agents')`) so the generated `useAgent(handle)` path
+ * lines up.
+ */
+/**
+ * Per-binding options for an exposed agent. Reserved for forward-compat — no options are wired yet.
+ *
+ * Two candidate fields were removed before shipping (M47 review): `path` (a route override) would let the
+ * served URL diverge from the generated handle's path — the codegen derives the handle from the agent's
+ * convention route (`/api/agents/<name>`), so an overridden route would make `useAgent(handle)` hit the
+ * wrong URL. And `csrf` was a no-op — CSRF is enforced exactly once at the controller-dispatch boundary
+ * regardless. Both return only when they can be wired end-to-end (codegen reads `@Expose` metadata / a
+ * per-route CSRF opt-out threads through the dispatcher). Until then, `@Expose(agent)` is the shape, and the
+ * exposure's path MUST be the convention route — put `@Expose` on a property named after the agent under
+ * `@Controller('api/agents')` (e.g. `chat` for `agents/chat.ts` → `/api/agents/chat`).
+ */
+type ExposeOptions = Record<string, never>;
+/** Metadata recorded per `@Expose`-decorated controller member. */
+interface ExposeEntry {
+    /** The separately-built agent module bound to this member. */
+    agent: unknown;
+    /** The per-binding options (defaulted to `{}`). */
+    opts: ExposeOptions;
+    /** The controller member the binding is attached to. */
+    propertyKey: string | symbol;
+}
+/**
+ * Bind an agent to a controller PROPERTY. Accumulates one {@link ExposeEntry} per member under the
+ * `EXPOSE_AGENT` metadata key on the controller constructor — the same accumulation shape `@Post` uses for
+ * `ROUTE_METHODS`, so `walkControllerMetadata` reads both alongside each other. Typed as `PropertyDecorator`
+ * (the exposure is declared as a property, e.g. `@Expose(chatAgent) chat!: typeof chatAgent`); the agent's
+ * behavior lives in its own `agents/<name>.ts`, never in a controller method body.
+ */
+declare function Expose(agent: unknown, opts?: ExposeOptions): PropertyDecorator;
+
 declare function HttpCode(status: number): MethodDecorator;
 declare function Header(name: string, value: string): MethodDecorator;
 interface RedirectMeta {
@@ -77,7 +122,7 @@ interface RedirectMeta {
 }
 declare function Redirect(url: string, status?: number): MethodDecorator;
 
-declare function UseGuards(...guards: Function[]): ClassDecorator & MethodDecorator;
+declare function UseGuards(...guards: Function[]): ClassDecorator & MethodDecorator & PropertyDecorator;
 declare function UseInterceptors(...interceptors: Function[]): ClassDecorator & MethodDecorator;
 declare function UseFilters(...filters: Function[]): ClassDecorator & MethodDecorator;
 /** @Catch(ExceptionType, ...) — marks which exception types an ExceptionFilter handles.
@@ -222,6 +267,7 @@ declare const USE_GUARDS: unique symbol;
 declare const USE_INTERCEPTORS: unique symbol;
 declare const USE_FILTERS: unique symbol;
 declare const CATCH_EXCEPTIONS: unique symbol;
+declare const EXPOSE_AGENT: unique symbol;
 
 /**
  * Typed facade over Reflect.defineMetadata / Reflect.getMetadata.
@@ -342,6 +388,14 @@ interface WalkResult {
     guards: Function[];
     interceptors: Function[];
     filters: Function[];
+    /**
+     * M47 — set when the member is bound via `@Expose(agent, opts)`. The dispatcher delegates such routes to
+     * the agent runtime (`mountAgent`) instead of invoking a JSON handler. `undefined` for normal verb routes.
+     */
+    agent?: {
+        module: unknown;
+        opts: ExposeOptions;
+    };
 }
 /**
  * Normalize a joined path: strip doubles, trim trailing, ensure leading.
@@ -354,6 +408,63 @@ declare function joinPath(prefix: string, path: string): string;
  */
 declare function walkControllerMetadata(ControllerClass: Function): WalkResult[];
 
+/**
+ * SWC-powered module loader for controller files with parameter decorators.
+ *
+ * esbuild (used by tsx/Vite SSR) fundamentally cannot parse TypeScript
+ * parameter decorators (`@Body()`, `@Param()`, `@Query()`). This loader
+ * uses @swc/core to transform controller files with full decorator support
+ * (legacyDecorator + decoratorMetadata), then imports them via a temp .mjs
+ * file written in the SAME directory (preserving relative import resolution).
+ *
+ * Pattern: follows Next.js's approach (read tsconfig → configure SWC)
+ * but scoped to the http-decorators package, not the framework core.
+ *
+ * @see references/next.js/packages/next/src/build/swc/options.ts
+ */
+
+interface SwcCore {
+    transformSync: (src: string, opts: unknown) => {
+        code: string;
+    };
+}
+/**
+ * Transform TypeScript controller SOURCE (with parameter decorators) into
+ * ESM code, emitting the `design:paramtypes` / decorator metadata that esbuild
+ * cannot produce. Pure code→code — no file I/O, no module load — so it is
+ * reusable both by {@link loadControllerWithSwc} (which then temp-writes +
+ * imports) and by a build-tool transform hook that returns `{ code }` directly.
+ *
+ * The `@swc/core` loader is injectable (`loadSwc`) for testability; it defaults
+ * to the cached singleton.
+ *
+ * @throws HttpDecoratorsConfigError when @swc/core is unavailable.
+ */
+declare function transformControllerSource(source: string, filename: string, loadSwc?: () => Promise<SwcCore | null>): Promise<string>;
+/**
+ * Load a TypeScript controller file using @swc/core for decorator support.
+ *
+ * Strategy:
+ *   1. Read source .ts file
+ *   2. Transform via {@link transformControllerSource} (legacyDecorator + metadata)
+ *   3. Write temp .mjs in SAME directory (relative imports resolve correctly)
+ *   4. Dynamic import() the .mjs — transitive .ts imports go through
+ *      tsx/Vite's global hook (they don't have parameter decorators)
+ *   5. Cleanup temp file
+ */
+declare function loadControllerWithSwc(absoluteFilePath: string): Promise<Record<string, unknown>>;
+/**
+ * Scan a glob pattern for controller files and load them all via SWC.
+ * Returns an array of controller class constructors found.
+ */
+declare function loadControllersFromGlob(rootDir: string, pattern: string): Promise<Function[]>;
+/**
+ * Check if a function has @Controller metadata.
+ * Uses Symbol.for() global registry key — same Symbol instance across
+ * module boundaries (SWC-loaded controllers share the global registry).
+ */
+declare function isControllerClass(fn: Function): boolean;
+
 interface RouteRegistration {
     verb: HttpVerb;
     fullPath: string;
@@ -369,14 +480,40 @@ interface RouteRegistration {
 declare function registerControllers(controllers: Function[]): RouteRegistration[];
 
 /**
- * Creates a real HTTP server from decorated controller classes.
- * Uses Web Standard Request/Response internally; Node adapter at the boundary.
+ * M47 — serves an `@Expose`-bound agent route. http is agent-runtime agnostic (G1/G2): it invokes this
+ * injected callback (theo supplies a `mountAgent`-backed impl) instead of calling a controller method.
  */
+type ServeAgent = (agent: unknown, request: Request, opts: ExposeOptions) => Promise<Response>;
 interface CreateDecoratorServerOptions {
     controllers: Function[];
     container?: DiContainer;
     configure?: (consumer: MiddlewareConsumerImpl) => void;
+    /** M47 — required when any controller `@Expose`-binds an agent; serves the agent route. */
+    serveAgent?: ServeAgent;
+}
+/**
+ * A pure Web-Standard controller handler: callable as `(request) => Response | null`
+ * plus a non-executing `matches(method, pathname)` route probe (so a host can gate
+ * — e.g. CSRF — before dispatch runs a handler).
+ */
+interface DecoratorHandler {
+    (request: Request): Promise<Response | null>;
+    /** True when a controller route owns `method` + `pathname` (no handler executed). */
+    matches(method: string, pathname: string): boolean;
 }
+/**
+ * Build a pure Web-Standard request handler from decorated controller classes,
+ * WITHOUT binding a network listener. Returns a {@link DecoratorHandler} whose
+ * call returns `null` when no controller route matched — the caller decides the
+ * miss (a standalone server answers 404; a host middleware falls through to its
+ * own routing). This is the reusable dispatch seam consumed by the framework's
+ * controller dispatch (#122) so it never re-implements match/bind/validate.
+ */
+declare function createDecoratorHandler(controllersOrOpts: Function[] | CreateDecoratorServerOptions): DecoratorHandler;
+/**
+ * Creates a real HTTP server from decorated controller classes.
+ * Uses Web Standard Request/Response internally; Node adapter at the boundary.
+ */
 declare function createDecoratorServer(controllersOrOpts: Function[] | CreateDecoratorServerOptions): ServerHandle;
 
 /**
@@ -998,10 +1135,10 @@ type InferResponse<D> = D extends {
     response: infer R;
 } ? R : unknown;
 interface TypedClient<M extends RouteMap> {
-    get<P extends string & keyof M>(path: P, opts?: {
+    get<P extends string>(path: P, opts?: {
         query?: Record<string, string>;
         headers?: Record<string, string>;
-    }): Promise<InferResponse<M[`GET ${P}`] extends never ? M[P] : M[`GET ${P}`]>>;
+    }): Promise<InferResponse<M[`GET ${P}`]>>;
     post<P extends string>(path: P, body?: InferBody<M[`POST ${P}`]>, opts?: {
         headers?: Record<string, string>;
     }): Promise<InferResponse<M[`POST ${P}`]>>;
@@ -1091,4 +1228,202 @@ declare function isSafePath(pathname: string): boolean;
  */
 declare function createStaticHandler(options?: StaticOptions): (request: Request) => Promise<Response | null>;
 
-export { All, type ArgumentsHost, BadGatewayException, BadRequestException, Body, CATCH_EXCEPTIONS, CONTROLLER_PREFIX, type CanActivate, Catch, ConflictException, Controller, type ControllerMeta, type ControllerOptions, Delete, DiContainer, type ExceptionFilter, type ExecutionContext, ForbiddenException, GatewayTimeoutException, Get, GoneException, Head, Header, Headers, HostParam, HttpCode, HttpDecoratorsConfigError, HttpException, type HttpExceptionOptions, HttpStatus, type HttpStatusCode, type HttpVerb, HttpVersionNotSupportedException, ImATeapotException, type Interceptor, InternalServerErrorException, Ip, type MetadataKey, MethodNotAllowedException, MiddlewareConsumerImpl, NotAcceptableException, NotFoundException, NotImplementedException, Options, Param, type ParamEntry, type ParamSource, Patch, PayloadTooLargeException, Post, PreconditionFailedException, Put, Query, ROUTE_HEADERS, ROUTE_METHODS, ROUTE_PARAMS, ROUTE_REDIRECT, ROUTE_STATUS, Redirect, type RedirectMeta, Reflector, Req, RequestTimeoutException, Res, type RouteDefinition, type RouteMap, type RouteMethodEntry, type RouteRegistration, ServiceUnavailableException, Session, SetMetadata, SkipThrottle, type StaticOptions, Throttle, type ThrottleOptions, TooManyRequestsException, type TypedClient, TypedClientError, USE_FILTERS, USE_GUARDS, USE_INTERCEPTORS, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, UseFilters, UseGuards, UseInterceptors, type WalkResult, contract, createDecorator, createDecoratorServer, createExecutionContext, createStaticHandler, createTypedClient, getMeta, getMimeType, getThrottleOptions, isSafePath, isThrottleSkipped, joinPath, registerControllers, resolveDtoSchema, runExceptionFilters, runInterceptors, setMeta, walkControllerMetadata };
+interface TheoRequestContext {
+    /** The raw Web Standard Request object. */
+    request: Request;
+    /** URL pathname (e.g., '/api/tasks'). */
+    pathname: string;
+    /** HTTP method (e.g., 'GET', 'POST'). */
+    method: string;
+    /** Route params extracted from URL (e.g., { id: '42' }). */
+    params: Record<string, string>;
+    /** Matched controller or agent class name (if resolved). */
+    handler?: string;
+    /** Request start time (ms). */
+    startedAt: number;
+}
+/**
+ * Get the current request context.
+ *
+ * @throws Error if called outside a request (e.g., at module load time).
+ *
+ * @example
+ * ```typescript
+ * import { getRequestContext } from '@theokit/http'
+ *
+ * class AuthGuard {
+ *   canActivate() {
+ *     const { request } = getRequestContext()
+ *     return request.headers.get('authorization') !== null
+ *   }
+ * }
+ * ```
+ */
+declare function getRequestContext(): TheoRequestContext;
+/**
+ * Try to get the current request context, or null if not in a request.
+ * Useful for code that may run both inside and outside requests.
+ */
+declare function tryGetRequestContext(): TheoRequestContext | null;
+
+/**
+ * Error digestion — converts any thrown value into a stable hash + context.
+ *
+ * Inspired by Next.js `create-error-handler.tsx`. Produces a deterministic
+ * digest ID suitable for logging and client-safe error references without
+ * leaking stack traces in production.
+ *
+ * Uses djb2 hash (sync, no crypto dependency) per ADR D3.
+ */
+interface ErrorContext {
+    route?: string;
+    phase?: 'guard' | 'interceptor' | 'handler' | 'filter' | 'agent';
+    source?: string;
+}
+interface DigestedError {
+    digest: string;
+    message: string;
+    status: number;
+    context: ErrorContext;
+    stack?: string;
+}
+/**
+ * Converts any thrown value into a structured {@link DigestedError}.
+ *
+ * - Sync (never async) — safe to call inside catch blocks.
+ * - Stack trace stripped when `process.env.NODE_ENV === 'production'`.
+ * - Preserves {@link HttpException} status codes.
+ * - Handles non-Error throws (string, number, object).
+ */
+declare function digestError(err: unknown, context?: ErrorContext): DigestedError;
+
+/**
+ * Component tree composition — recursive wrapping of file-convention
+ * components (layout, page, loading, error, not-found) into a React
+ * element tree with Suspense and error boundaries.
+ *
+ * Inspired by Next.js `create-component-tree.tsx`.
+ *
+ * React is loaded via dynamic `import('react')` because it is an
+ * optional peerDep of @theokit/http (EC-2).
+ */
+
+interface RouteTree {
+    layout?: ReactTypes.ComponentType<{
+        children: ReactTypes.ReactNode;
+    }>;
+    page?: ReactTypes.ComponentType;
+    loading?: ReactTypes.ComponentType;
+    error?: ReactTypes.ComponentType;
+    notFound?: ReactTypes.ComponentType;
+    children?: Record<string, RouteTree>;
+}
+/**
+ * Composes a {@link RouteTree} into a nested React element tree.
+ *
+ * Wrapping order (outermost → innermost):
+ *   layout → ErrorBoundary(error) → Suspense(loading) → page
+ *
+ * Returns `null` when no `page` component is found in the tree.
+ *
+ * @param tree - The route tree describing file conventions found.
+ * @returns A React element or `null`.
+ */
+declare function composeComponentTree(tree: RouteTree): Promise<ReactTypes.ReactElement | null>;
+
+/**
+ * Streaming SSR — renders a React element tree to a `ReadableStream<Uint8Array>`.
+ *
+ * Inspired by Next.js `stream-ops.ts`. Uses Web Standard `renderToReadableStream`
+ * (works on Node 18+, Bun, Deno). Falls back to `renderToString` wrapped in a
+ * ReadableStream when `renderToReadableStream` is not available (React 17 — EC-4).
+ *
+ * React is loaded via dynamic `import('react-dom/server')` because react-dom
+ * is an optional peerDep of @theokit/http (ADR D2).
+ */
+
+interface StreamRenderOptions {
+    /** React element to render */
+    root: ReactTypes.ReactElement;
+    /** Whether to wait for all Suspense to resolve (default: false — stream immediately) */
+    waitForAll?: boolean;
+}
+interface StreamRenderResult {
+    /** The HTML stream */
+    stream: ReadableStream<Uint8Array>;
+    /** Promise that resolves when all content has been flushed */
+    allReady: Promise<void>;
+}
+/**
+ * Renders a React element to a `ReadableStream<Uint8Array>` (Web Standard).
+ *
+ * 1. Tries `renderToReadableStream` first (React 18+ — Web Standard API).
+ * 2. Falls back to `renderToString` wrapped in a ReadableStream when
+ *    `renderToReadableStream` is not available (React 17 compat — EC-4).
+ * 3. Prepends `<!DOCTYPE html>` to the stream.
+ *
+ * **EC-7 — Streaming error handling:** In streaming mode, errors thrown inside
+ * Suspense boundaries are caught by React's streaming error handler and result
+ * in a client-side error boundary activation (the shell is already sent). In
+ * string mode (`renderToString`), errors throw synchronously before any bytes
+ * are sent, allowing a full 500 error page. Choose streaming when you want
+ * progressive rendering; choose string mode when you want atomic error handling.
+ */
+declare function renderToStream(options: StreamRenderOptions): Promise<StreamRenderResult>;
+/**
+ * Converts a {@link StreamRenderResult} into a Web Standard `Response`.
+ *
+ * Convenience wrapper for use in request handlers:
+ * ```ts
+ * const result = await renderToStream({ root: <App /> })
+ * return streamToResponse(result)
+ * ```
+ */
+declare function streamToResponse(result: StreamRenderResult): Response;
+
+interface RevalidationSignal {
+    kind: 'tag' | 'path';
+    value: string;
+    timestamp: number;
+}
+/**
+ * Signal that a cache tag should be revalidated.
+ *
+ * Safe to call from any request handler (controller, agent, action).
+ * Signals are accumulated per-request and consumed by the cache engine.
+ *
+ * @example
+ * ```typescript
+ * import { revalidateTag } from '@theokit/http'
+ *
+ * @Post()
+ * async createTask(@Body(schema) body) {
+ *   const task = await db.tasks.create(body)
+ *   revalidateTag('tasks')  // invalidate cached task lists
+ *   return task
+ * }
+ * ```
+ */
+declare function revalidateTag(tag: string): void;
+/**
+ * Signal that a cached path should be revalidated.
+ *
+ * @example
+ * ```typescript
+ * import { revalidatePath } from '@theokit/http'
+ *
+ * @Delete(':id')
+ * async removeTask(@Param('id') id: string) {
+ *   await db.tasks.delete(id)
+ *   revalidatePath('/api/tasks')
+ * }
+ * ```
+ */
+declare function revalidatePath(path: string): void;
+/**
+ * Get all revalidation signals collected during the current request.
+ * Called by the cache engine after the handler completes.
+ */
+declare function getRevalidationSignals(): RevalidationSignal[];
+
+export { All, type ArgumentsHost, BadGatewayException, BadRequestException, Body, CATCH_EXCEPTIONS, CONTROLLER_PREFIX, type CanActivate, Catch, ConflictException, Controller, type ControllerMeta, type ControllerOptions, type CreateDecoratorServerOptions, type DecoratorHandler, Delete, DiContainer, type DigestedError, EXPOSE_AGENT, type ErrorContext, type ExceptionFilter, type ExecutionContext, Expose, type ExposeEntry, type ExposeOptions, ForbiddenException, GatewayTimeoutException, Get, GoneException, Head, Header, Headers, HostParam, HttpCode, HttpDecoratorsConfigError, HttpException, type HttpExceptionOptions, HttpStatus, type HttpStatusCode, type HttpVerb, HttpVersionNotSupportedException, ImATeapotException, type Interceptor, InternalServerErrorException, Ip, type MetadataKey, MethodNotAllowedException, MiddlewareConsumerImpl, NotAcceptableException, NotFoundException, NotImplementedException, Options, Param, type ParamEntry, type ParamSource, Patch, PayloadTooLargeException, Post, PreconditionFailedException, Put, Query, ROUTE_HEADERS, ROUTE_METHODS, ROUTE_PARAMS, ROUTE_REDIRECT, ROUTE_STATUS, Redirect, type RedirectMeta, Reflector, Req, RequestTimeoutException, Res, type RevalidationSignal, type RouteDefinition, type RouteMap, type RouteMethodEntry, type RouteRegistration, type RouteTree, type ServeAgent, ServiceUnavailableException, Session, SetMetadata, SkipThrottle, type StaticOptions, type StreamRenderOptions, type StreamRenderResult, type SwcCore, type TheoRequestContext, Throttle, type ThrottleOptions, TooManyRequestsException, type TypedClient, TypedClientError, USE_FILTERS, USE_GUARDS, USE_INTERCEPTORS, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, UseFilters, UseGuards, UseInterceptors, type WalkResult, composeComponentTree, contract, createDecorator, createDecoratorHandler, createDecoratorServer, createExecutionContext, createStaticHandler, createTypedClient, digestError, getMeta, getMimeType, getRequestContext, getRevalidationSignals, getThrottleOptions, isControllerClass, isSafePath, isThrottleSkipped, joinPath, loadControllerWithSwc, loadControllersFromGlob, registerControllers, renderToStream, resolveDtoSchema, revalidatePath, revalidateTag, runExceptionFilters, runInterceptors, setMeta, streamToResponse, transformControllerSource, tryGetRequestContext, walkControllerMetadata };