@lithia-js/core 1.0.0-canary.2 → 1.0.0-canary.21

package/dist/index.d.ts

@@ -0,0 +1,824 @@
+import { c as LithiaClientError, E as Event, T as TaskInvocationSource, R as Route } from './protocol-DBwVPJYN.js';
+export { B as BadRequestError, d as ConflictError, F as ForbiddenError, e as LithiaConfig, L as LithiaError, f as LithiaEventError, N as NotFoundError, b as RouteNotFoundError, U as UnauthorizedError, g as defineConfig } from './protocol-DBwVPJYN.js';
+import { Socket, Server } from 'socket.io';
+import { IncomingHttpHeaders, IncomingMessage, ServerResponse, OutgoingHttpHeaders } from 'node:http';
+import { FileInfo } from 'busboy';
+import { Cookies } from 'cookie';
+import { ZodType } from 'zod';
+import '@lithia-js/utils';
+import 'c12';
+
+/**
+ * Indicates that the server hit an unexpected internal failure.
+ */
+declare class InternalServerError extends LithiaClientError {
+    constructor(m: string, d?: any);
+}
+/**
+ * Indicates that the service is temporarily unavailable.
+ */
+declare class ServiceUnavailableError extends LithiaClientError {
+    constructor(m: string, d?: any);
+}
+/**
+ * Indicates that an upstream operation timed out.
+ */
+declare class GatewayTimeoutError extends LithiaClientError {
+    constructor(m: string, d?: any);
+}
+
+/**
+ * Returns the payload received by the current event handler.
+ *
+ * Use this inside helpers called from event handlers when passing the event
+ * payload explicitly would add unnecessary plumbing. Event hook semantics are
+ * described in [Event Handlers](https://lithiajs.org/docs/latest/events).
+ *
+ * @returns {T} Payload currently bound to the active event context.
+ * @throws {NotInEventContextError} Throws when called outside a managed socket
+ * event handler.
+ */
+declare function useData<T = any>(): T;
+/**
+ * Returns the active Socket.IO connection for the current event handler.
+ *
+ * This hook exposes the socket boundary owned by the current event file, so
+ * helper code can emit messages or inspect socket metadata without threading
+ * the socket through every call.
+ *
+ * @returns {Socket} Socket.IO connection bound to the active event context.
+ * @throws {NotInEventContextError} Throws when called outside a managed socket
+ * event handler.
+ */
+declare function useSocket(): Socket;
+/**
+ * Returns the current event manifest entry being handled.
+ *
+ * The returned metadata includes the resolved event name and compiled module
+ * path discovered from `src/app/events`.
+ *
+ * @returns {Event} Event manifest entry bound to the active event context.
+ * @throws {NotInEventContextError} Throws when called outside a managed socket
+ * event handler.
+ */
+declare function useEvent(): Event;
+
+/**
+ * Route params object populated by the route matcher.
+ *
+ * Keys correspond to dynamic segments extracted from the matched route pattern.
+ * The values are assigned by the HTTP transport before the handler runs and
+ * remain mutable for the lifetime of the current request context.
+ */
+type Params = Record<string, any>;
+/**
+ * Query object parsed from the incoming request URL.
+ *
+ * Each value is currently stored as the last string value observed for a given
+ * query key during URL parsing.
+ */
+type Query = Record<string, any>;
+/**
+ * Uploaded multipart file returned by `req.files()`.
+ *
+ * Each file entry contains the metadata reported by Busboy plus the fully
+ * buffered file contents collected while the multipart stream is parsed.
+ */
+interface UploadedFile extends FileInfo {
+    fieldname: string;
+    buffer: Buffer;
+}
+/**
+ * Lithia wrapper around Node's `IncomingMessage`.
+ *
+ * Provides helpers for reading params, query, body, cookies, and multipart
+ * uploads from route handlers and middleware.
+ *
+ * The wrapper parses URL-derived data eagerly in the constructor and reads the
+ * request stream lazily only when `body()` or `files()` is called. Parsed
+ * payloads are cached so route handlers and middleware can safely reuse the
+ * same request wrapper without reparsing the stream.
+ *
+ * Related docs:
+ * - https://lithiajs.org/docs/latest/routes
+ * - https://lithiajs.org/docs/latest/project-structure
+ */
+declare class LithiaRequest {
+    private readonly req;
+    private readonly opts;
+    readonly headers: Readonly<IncomingHttpHeaders>;
+    readonly method: Readonly<string>;
+    readonly pathname: Readonly<string>;
+    query: Query;
+    params: Params;
+    private readonly storage;
+    private _bodyCache;
+    private _filesCache;
+    private _cookies;
+    /**
+     * Creates a request wrapper for the current HTTP transaction.
+     *
+     * The constructor captures headers, reconstructs a best-effort absolute URL,
+     * normalizes the HTTP method to uppercase, and initializes parsed query and
+     * route-param containers for later middleware and handler use.
+     *
+     * @param {IncomingMessage} req - Raw Node.js request object received by the
+     * HTTP server.
+     * @param {{ maxBodySize?: number }} opts - Per-request parsing options used
+     * when consuming the request body stream.
+     */
+    constructor(req: IncomingMessage, opts: {
+        maxBodySize?: number;
+    });
+    /**
+     * Returns the best-effort client IP address for the current request.
+     *
+     * The lookup prefers proxy-forwarded headers before falling back to the raw
+     * socket address, which makes the result suitable for deployments behind
+     * reverse proxies that preserve `x-forwarded-for` or `x-real-ip`.
+     *
+     * @returns {string} The resolved client IP address, or `"unknown"` when no
+     * address can be derived.
+     */
+    ip(): string;
+    /**
+     * Returns the current request user-agent string.
+     *
+     * @returns {string} The raw `user-agent` header value, or an empty string
+     * when the header is missing.
+     */
+    userAgent(): string;
+    /**
+     * Returns whether the current request is using HTTPS.
+     *
+     * The check prefers `x-forwarded-proto` for proxy-aware deployments and then
+     * falls back to the encrypted state of the underlying socket.
+     *
+     * @returns {boolean} `true` when the request should be treated as HTTPS.
+     */
+    isSecure(): boolean;
+    /**
+     * Returns the request host header.
+     *
+     * @returns {string} The current host header value, or `"unknown"` when it is
+     * not available.
+     */
+    host(): string;
+    /**
+     * Returns the absolute request URL reconstructed from the current request.
+     *
+     * This helper rebuilds the URL from the current security state, host header,
+     * and parsed pathname. It does not append the original query string.
+     *
+     * @returns {string} Absolute URL for the current request pathname.
+     */
+    url(): string;
+    /**
+     * Parses and returns the request body.
+     *
+     * JSON and plain text bodies are supported automatically. Multipart requests
+     * populate both `body()` and `files()` through a shared parsing pass. The
+     * parsed value is cached after the first read so later consumers do not touch
+     * the underlying stream again.
+     *
+     * Requests whose method is not one of `POST`, `PUT`, `PATCH`, or `DELETE`
+     * resolve to an empty object without reading the stream.
+     *
+     * @returns {Promise<T>} Parsed request body, multipart field map, raw text, or
+     * an empty object for methods that do not consume a body by default.
+     * @throws {BadRequestError} Thrown when the declared or streamed body size
+     * exceeds `maxBodySize`, or when JSON parsing fails.
+     */
+    body<T>(): Promise<T>;
+    /**
+     * Returns uploaded files for multipart/form-data requests.
+     *
+     * `files()` shares the same multipart parsing pass used by `body()`. The
+     * first call buffers every uploaded file into memory and caches both the
+     * parsed field object and file array for later access.
+     *
+     * @returns {Promise<UploadedFile[]>} Buffered multipart files, or an empty
+     * array when the request is not multipart.
+     */
+    files(): Promise<UploadedFile[]>;
+    /**
+     * Overrides the cached body value for the current request context.
+     *
+     * This mutates only the wrapper cache and the internal storage map. It does
+     * not modify the underlying Node.js request stream.
+     *
+     * @param {unknown} value - Replacement body value to expose through `body()`
+     * and internal request storage.
+     */
+    setBody(value: unknown): void;
+    /**
+     * Returns all parsed cookies from the request.
+     *
+     * Cookies are parsed lazily on first access and cached for the remainder of
+     * the request lifecycle.
+     *
+     * @returns {Cookies} Parsed cookie map for the current request.
+     */
+    cookies(): Cookies;
+    /**
+     * Returns a single cookie value by name.
+     *
+     * @param {string} name - Cookie name to read from the parsed cookie map.
+     * @returns {string | undefined} The cookie value when present.
+     */
+    cookie(name: string): string | undefined;
+    /**
+     * Returns a value stored in the per-request internal storage map.
+     *
+     * This storage is local to the current request wrapper and can be used by
+     * middleware and handlers to exchange derived values without mutating the
+     * typed request surface.
+     *
+     * @param {string} key - Storage key associated with the requested value.
+     * @returns {T | undefined} Stored value for the key, if one exists.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Stores a value in the per-request internal storage map.
+     *
+     * @param {string} key - Storage key to create or overwrite.
+     * @param {unknown} value - Arbitrary value to retain for the lifetime of the
+     * current request wrapper.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Parses a multipart/form-data request into cached fields and file buffers.
+     *
+     * The request stream is piped into Busboy exactly once. Field values are
+     * collected into a plain object, file contents are buffered fully in memory,
+     * and both results are stored in the request cache and internal storage map.
+     *
+     * @returns {Promise<void>} Resolves after Busboy finishes consuming the
+     * multipart stream and caches the parsed payload.
+     */
+    private parseMultipart;
+}
+
+/**
+ * Cookie attributes accepted by `LithiaResponse.cookie()`.
+ *
+ * These options are forwarded to the cookie serializer when pending cookies
+ * are flushed into the `Set-Cookie` header.
+ */
+interface CookieOptions {
+    domain?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    maxAge?: number;
+    path?: string;
+    sameSite?: boolean | "lax" | "strict" | "none";
+    secure?: boolean;
+}
+/**
+ * Lithia wrapper around Node's `ServerResponse`.
+ *
+ * Provides helpers for status management, JSON/text responses, redirects,
+ * cookies, and file responses.
+ *
+ * The wrapper keeps response mutations centralized until one of the terminal
+ * methods sends or streams the response. After that point, further mutations
+ * are rejected to preserve a single-write HTTP lifecycle.
+ *
+ * Related docs:
+ * - https://lithiajs.org/docs/latest/routes
+ * - https://lithiajs.org/docs/latest/project-structure
+ */
+declare class LithiaResponse {
+    private readonly res;
+    _ended: boolean;
+    private _cookies;
+    on: (event: string, listener: (chunk: unknown) => void) => void;
+    /**
+     * Creates a response wrapper for the current HTTP transaction.
+     *
+     * The wrapper binds a pass-through `on()` helper to the underlying Node.js
+     * response object so route-adjacent code can subscribe to response events
+     * without holding the raw `ServerResponse`.
+     *
+     * @param {ServerResponse} res - Raw Node.js response object associated with
+     * the current request.
+     */
+    constructor(res: ServerResponse);
+    /**
+     * Returns the current HTTP status code.
+     *
+     * @returns {number} Status code currently assigned to the underlying
+     * response.
+     */
+    get statusCode(): number;
+    /**
+     * Sets the HTTP status code for the response.
+     *
+     * This mutates the underlying response only while it is still active.
+     *
+     * @param {number} status - HTTP status code to assign before the response is
+     * sent.
+     * @returns {this} The current response wrapper for fluent chaining.
+     * @throws {Error} Thrown when the response has already ended or when the
+     * supplied status code falls outside the valid HTTP range.
+     */
+    status(status: number): this;
+    /**
+     * Returns the currently assigned response headers.
+     *
+     * @returns {Readonly<OutgoingHttpHeaders>} Snapshot of the headers currently
+     * stored on the underlying response.
+     */
+    headers(): Readonly<OutgoingHttpHeaders>;
+    /**
+     * Sets multiple response headers at once.
+     *
+     * @param {OutgoingHttpHeaders} headers - Header entries to assign to the
+     * response before it is sent.
+     * @returns {this} The current response wrapper for fluent chaining.
+     * @throws {Error} Thrown when the response has already ended.
+     */
+    setHeaders(headers: OutgoingHttpHeaders): this;
+    /**
+     * Sets a single response header.
+     *
+     * @param {string} name - Header name to create or overwrite.
+     * @param {string | number | string[]} value - Header value written to the
+     * underlying response.
+     * @returns {this} The current response wrapper for fluent chaining.
+     * @throws {Error} Thrown when the response has already ended.
+     */
+    setHeader(name: string, value: string | number | string[]): this;
+    /**
+     * Removes a response header.
+     *
+     * @param {string} name - Header name to remove.
+     * @returns {this} The current response wrapper for fluent chaining.
+     * @throws {Error} Thrown when the response has already ended.
+     */
+    removeHeader(name: string): this;
+    /**
+     * Queues a cookie to be written when the response is sent.
+     *
+     * Cookies are accumulated in memory and serialized only when a terminal
+     * response method flushes headers.
+     *
+     * @param {string} name - Cookie name.
+     * @param {string} value - Cookie value.
+     * @param {CookieOptions} [options={}] - Cookie serialization options.
+     * @returns {this} The current response wrapper for fluent chaining.
+     * @throws {Error} Thrown when the response has already ended.
+     */
+    cookie(name: string, value: string, options?: CookieOptions): this;
+    /**
+     * Clears a cookie by expiring it immediately.
+     *
+     * @param {string} name - Cookie name to expire.
+     * @param {CookieOptions} [options={}] - Additional cookie attributes that
+     * must match the original cookie scope.
+     * @returns {this} The current response wrapper for fluent chaining.
+     */
+    clearCookie(name: string, options?: CookieOptions): this;
+    /**
+     * Sends a response body using a best-effort content type.
+     *
+     * The method flushes pending cookies before writing, chooses a default
+     * content type when none is set, and treats plain objects as JSON by
+     * delegating to `json()`. Calling `send()` is a terminal operation for the
+     * response lifecycle.
+     *
+     * @param {unknown} [data] - Response payload to send.
+     * @throws {Error} Thrown when the response has already ended.
+     */
+    send(data?: unknown): void;
+    /**
+     * Sends a JSON response.
+     *
+     * Pending cookies are flushed before serialization. If JSON serialization
+     * throws, the method logs the failure and falls back to a `500 Internal
+     * Server Error` response body.
+     *
+     * @param {object} obj - Plain object to serialize as JSON.
+     */
+    json(obj: object): void;
+    /**
+     * Sends a redirect response.
+     *
+     * This sets the status code, writes the `Location` header, and then ends the
+     * response.
+     *
+     * @param {string} url - Redirect target written to the `Location` header.
+     * @param {number} [status=302] - Redirect status code.
+     */
+    redirect(url: string, status?: number): void;
+    /**
+     * Ends the response without sending additional data.
+     *
+     * Pending cookies are flushed before the underlying response is closed.
+     *
+     * @throws {Error} Thrown when the response has already ended.
+     */
+    end(): void;
+    /**
+     * Streams a file to the client.
+     *
+     * The method resolves the final path, verifies that it points to a regular
+     * file, sets `Content-Length`, flushes pending cookies, and pipes the file
+     * stream into the underlying response. Missing files and stream failures fall
+     * back to a `404` JSON error payload.
+     *
+     * @param {string} filePath - File path to stream. When `opts.root` is set, it
+     * is resolved relative to that root.
+     * @param {{ root?: string }} [opts={}] - Optional root directory used to
+     * resolve relative file paths.
+     */
+    sendFile(filePath: string, opts?: {
+        root?: string;
+    }): void;
+    /**
+     * Serializes queued cookies into the response headers and clears the queue.
+     *
+     * Existing `Set-Cookie` headers are preserved and extended so multiple
+     * middleware and handler calls can contribute cookies before the response is
+     * finalized.
+     */
+    private applyPendingCookies;
+    /**
+     * Ensures the response has not already been finalized.
+     *
+     * @throws {Error} Thrown when a terminal response method has already sent or
+     * ended the response.
+     */
+    private ensureActive;
+}
+
+/**
+ * Declares an OpenAPI security requirement object for a route operation.
+ *
+ * Each key references a named security scheme and its value lists the scopes
+ * required for the operation when that scheme supports scoped authorization.
+ */
+type OpenAPISecurityRequirement = Record<string, string[]>;
+/**
+ * Describes a response exposed in the generated OpenAPI document.
+ *
+ * This metadata is attached to a single status code entry inside
+ * `metadata.openapi.responses`.
+ */
+interface OpenAPIResponseMetadata {
+    /**
+     * Human-readable description shown in the generated spec.
+     */
+    description: string;
+    /**
+     * Optional Zod schema used to describe the response body.
+     */
+    schema?: ZodType;
+    /**
+     * Response media type. Defaults to `application/json`.
+     */
+    contentType?: string;
+}
+/**
+ * Explicit OpenAPI metadata attached to an HTTP route module.
+ *
+ * Export this inside `export const metadata = { openapi: ... }` to enrich the
+ * generated OpenAPI document for a route.
+ *
+ * The route file remains the source of truth for the HTTP contract. This type
+ * provides the structured metadata surface used by Lithia's OpenAPI generation
+ * pipeline and Scalar docs integration.
+ *
+ * Related docs:
+ * - https://lithiajs.org/docs/latest/openapi
+ * - https://lithiajs.org/docs/latest/routes
+ */
+interface OpenAPIRouteMetadata {
+    /**
+     * Short operation summary.
+     */
+    summary?: string;
+    /**
+     * Longer operation description.
+     */
+    description?: string;
+    /**
+     * Tags used to group operations in the generated docs.
+     */
+    tags?: string[];
+    /**
+     * Zod schema describing path params.
+     */
+    params?: ZodType;
+    /**
+     * Zod schema describing querystring params.
+     */
+    query?: ZodType;
+    /**
+     * Zod schema describing the JSON request body.
+     */
+    body?: ZodType;
+    /**
+     * Explicit response definitions keyed by status code.
+     */
+    responses?: Record<number | `${number}`, OpenAPIResponseMetadata>;
+    /**
+     * Optional security requirements for the operation.
+     */
+    security?: OpenAPISecurityRequirement[];
+}
+/**
+ * Route module metadata exported from a route file as `export const metadata`.
+ *
+ * This is the top-level metadata envelope recognized by the HTTP route loader.
+ */
+interface RouteMetadata {
+    openapi?: OpenAPIRouteMetadata;
+}
+
+/**
+ * Continuation used by route middleware to hand control to the next step in
+ * the pipeline.
+ *
+ * Calling `next()` transfers control to the next middleware or, once the stack
+ * is exhausted, to the route handler itself.
+ */
+type NextRoute = () => Promise<void> | void;
+/**
+ * Middleware executed before a route handler.
+ *
+ * Route middleware can inspect or mutate the request/response and may stop the
+ * pipeline by not calling `next()`.
+ *
+ * @param {LithiaRequest} req - Current request wrapper shared across the route
+ * pipeline.
+ * @param {LithiaResponse} res - Current response wrapper shared across the
+ * route pipeline.
+ * @param {NextRoute} next - Continuation that advances execution to the next
+ * middleware or the final route handler.
+ * @returns {Promise<void>} Resolves after the middleware finishes its work.
+ */
+type RouteMiddleware = (req: LithiaRequest, res: LithiaResponse, next: NextRoute) => Promise<void>;
+/**
+ * Route module default export signature.
+ *
+ * Route handlers are the terminal HTTP boundary for a matched route module and
+ * receive the current request and response wrappers.
+ *
+ * @param {LithiaRequest} req - Current request wrapper.
+ * @param {LithiaResponse} res - Current response wrapper.
+ * @returns {Promise<void>} Resolves after the handler finishes shaping the HTTP
+ * response.
+ */
+type RouteHandler = (req: LithiaRequest, res: LithiaResponse) => Promise<void>;
+
+/**
+ * Continuation used by event middleware to hand control to the next step in
+ * the event pipeline.
+ *
+ * Calling `next()` transfers control to the next middleware or, once the stack
+ * is exhausted, to the final event handler.
+ */
+type NextEvent = () => Promise<void> | void;
+/**
+ * Middleware executed before a socket event handler.
+ *
+ * @param {Socket} socket - Active socket associated with the event execution.
+ * @param {NextEvent} next - Continuation that advances to the next middleware
+ * or event handler.
+ * @returns {Promise<void>} Resolves after the middleware completes.
+ */
+type EventMiddleware = (socket: Socket, next: NextEvent) => Promise<void>;
+/**
+ * Event module default export signature.
+ *
+ * @param {Socket} socket - Active socket for the current event.
+ * @param {any} [data] - Event payload forwarded from Socket.IO.
+ * @returns {Promise<void>} Resolves after the event handler completes.
+ */
+type EventHandler = (socket: Socket, data?: any) => Promise<void>;
+
+/**
+ * Token used to register or resolve a dependency from the app container.
+ */
+type InjectionKey<T> = symbol | string | {
+    new (...args: any[]): T;
+};
+
+declare module "../hooks/lithia-hooks" {
+    interface LithiaTasks {
+    }
+}
+type TaskInvocationKey = keyof LithiaTasks | (string & {});
+/**
+ * Stores a value in the current app dependency container.
+ *
+ * Values registered with `provide()` can later be retrieved with
+ * `useDependency()` or `useOptionalDependency()` from routes, events, tasks,
+ * and `app/server.ts`.
+ *
+ * The value is written into the container bound to the current Lithia
+ * execution context. When called during mutable bootstrap, the registration
+ * becomes available to later route, event, and task executions.
+ *
+ * @param {InjectionKey<T>} key - Token used to register the dependency.
+ * @param {T} value - Dependency instance stored under `key`.
+ * @throws {NotInLithiaContextError} Throws when called outside a managed
+ * Lithia execution context.
+ */
+declare function provide<T>(key: InjectionKey<T>, value: T): void;
+/**
+ * Resolves a dependency from the current Lithia context.
+ *
+ * Throws when the dependency has not been registered for the current app
+ * lifecycle.
+ *
+ * @param {InjectionKey<T>} key - Token used to resolve the dependency.
+ * @returns {T} Registered dependency instance for `key`.
+ * @throws {NotInLithiaContextError} Throws when called outside a managed
+ * Lithia execution context.
+ * @throws {DependencyNotInitializedError} Throws when `key` has not been
+ * registered in the current container.
+ */
+declare function useDependency<T>(key: InjectionKey<T>): T;
+/**
+ * Resolves a dependency from the current Lithia context when available.
+ *
+ * Returns `undefined` instead of throwing when the dependency has not been
+ * registered.
+ *
+ * @param {InjectionKey<T>} key - Token used to resolve the dependency.
+ * @returns {T | undefined} Registered dependency instance, or `undefined` when
+ * the dependency is absent.
+ * @throws {NotInLithiaContextError} Throws when called outside a managed
+ * Lithia execution context.
+ */
+declare function useOptionalDependency<T>(key: InjectionKey<T>): T | undefined;
+type KnownTaskPayload<T> = T extends (...args: infer P) => any ? P : never;
+type KnownTaskReturn<T> = T extends (...args: any[]) => Promise<infer R> ? R : T extends (...args: any[]) => infer R ? R : any;
+type TaskPayload<K extends TaskInvocationKey> = K extends keyof LithiaTasks ? KnownTaskPayload<LithiaTasks[K]> : any[];
+type TaskReturn<K extends TaskInvocationKey> = K extends keyof LithiaTasks ? KnownTaskReturn<LithiaTasks[K]> : unknown;
+/**
+ * Returned by `dispatchTask()` to identify an async task execution.
+ */
+type TaskExecutionHandle<K extends string = string> = {
+    taskId: K;
+    executionId: string;
+    source: TaskInvocationSource;
+};
+/**
+ * Executes an async task and waits for its result.
+ *
+ * This path uses Lithia's warm task workers to reduce latency for request-time
+ * task execution while still keeping the work outside the app worker.
+ *
+ * Task semantics are described in
+ * [Async Tasks](https://lithiajs.org/docs/latest/async-tasks).
+ *
+ * @param {K} taskId - Task identifier to execute.
+ * @param {...TaskPayload<K>} args - Arguments forwarded to the task worker.
+ * @returns {Promise<Awaited<TaskReturn<K>>>} Resolves with the task result
+ * returned by the worker.
+ * @throws {Error} Throws when called outside a Lithia-managed worker, when the
+ * worker closes before replying, when arguments cannot be cloned, or when the
+ * task worker reports a failure.
+ */
+declare function executeTask<K extends TaskInvocationKey>(taskId: K, ...args: TaskPayload<K>): Promise<Awaited<TaskReturn<K>>>;
+/**
+ * Dispatches an async task without awaiting its result.
+ *
+ * This path is fire-and-forget and returns a handle that can be logged or
+ * correlated later.
+ *
+ * @param {K} taskId - Task identifier to dispatch.
+ * @param {...TaskPayload<K>} args - Arguments forwarded to the task worker.
+ * @returns {TaskExecutionHandle<Extract<K, string>>} Handle that identifies
+ * the dispatched task execution.
+ * @throws {Error} Throws when called outside a Lithia-managed worker or when
+ * arguments cannot be cloned for worker dispatch.
+ */
+declare function dispatchTask<K extends TaskInvocationKey>(taskId: K, ...args: TaskPayload<K>): TaskExecutionHandle<Extract<K, string>>;
+/**
+ * Legacy alias for `executeTask()`.
+ *
+ * Prefer `executeTask()` in new code.
+ *
+ * @param {K} taskId - Task identifier to execute.
+ * @param {...TaskPayload<K>} args - Arguments forwarded to the task worker.
+ * @returns {Promise<Awaited<TaskReturn<K>>>} Resolves with the task result.
+ */
+declare function runTask<K extends TaskInvocationKey>(taskId: K, ...args: TaskPayload<K>): Promise<Awaited<TaskReturn<K>>>;
+/**
+ * Legacy alias for `dispatchTask()`.
+ *
+ * Prefer `dispatchTask()` in new code.
+ *
+ * @param {K} taskId - Task identifier to dispatch.
+ * @param {...TaskPayload<K>} args - Arguments forwarded to the task worker.
+ * @returns {TaskExecutionHandle<Extract<K, string>>} Handle that identifies
+ * the dispatched task execution.
+ */
+declare function runTaskAsync<K extends TaskInvocationKey>(taskId: K, ...args: TaskPayload<K>): TaskExecutionHandle<Extract<K, string>>;
+
+/**
+ * Returns the current Lithia request object.
+ *
+ * This hook is only available while handling an HTTP route.
+ * Route hook semantics are described in
+ * [Route Handlers](https://lithiajs.org/docs/latest/routes).
+ *
+ * @returns {LithiaRequest} Request wrapper bound to the active route context.
+ * @throws {NotInRequestContextError} Throws when called outside a managed HTTP
+ * route handler.
+ */
+declare function useRequest(): LithiaRequest;
+/**
+ * Returns the current Lithia response object.
+ *
+ * This hook is only available while handling an HTTP route.
+ *
+ * @returns {LithiaResponse} Response wrapper bound to the active route
+ * context.
+ * @throws {NotInRequestContextError} Throws when called outside a managed HTTP
+ * route handler.
+ */
+declare function useResponse(): LithiaResponse;
+/**
+ * Returns the matched route manifest entry for the current request.
+ *
+ * The route may be `undefined` when the current request context was created
+ * without a resolved route manifest entry.
+ *
+ * @returns {Route | undefined} Matched route metadata for the current request.
+ * @throws {NotInRequestContextError} Throws when called outside a managed HTTP
+ * route handler.
+ */
+declare function useRoute(): Route | undefined;
+/**
+ * Returns the pathname for the current request.
+ *
+ * @returns {string} URL pathname of the active request.
+ * @throws {NotInRequestContextError} Throws when called outside a managed HTTP
+ * route handler.
+ */
+declare function usePathname(): string;
+/**
+ * Returns the typed route params for the current request.
+ *
+ * This is a typed view over the params already parsed and attached to the
+ * current request object.
+ *
+ * @returns {T} Route params bound to the active request.
+ * @throws {NotInRequestContextError} Throws when called outside a managed HTTP
+ * route handler.
+ */
+declare function useParams<T extends Params = Params>(): T;
+/**
+ * Returns the typed query object for the current request.
+ *
+ * @returns {T} Query object parsed from the active request URL.
+ * @throws {NotInRequestContextError} Throws when called outside a managed HTTP
+ * route handler.
+ */
+declare function useQuery<T extends Query = Query>(): T;
+/**
+ * Returns the raw incoming HTTP headers for the current request.
+ *
+ * @returns {IncomingHttpHeaders} Raw request headers for the active HTTP
+ * request.
+ * @throws {NotInRequestContextError} Throws when called outside a managed HTTP
+ * route handler.
+ */
+declare function useHeaders(): IncomingHttpHeaders;
+/**
+ * Returns the shared Socket.IO server instance.
+ *
+ * Use this from HTTP routes when you need to emit socket events from the
+ * request side of the app.
+ *
+ * @returns {SocketServer} Socket.IO server shared by the current application
+ * runtime.
+ * @throws {NotInRequestContextError} Throws when called outside a managed HTTP
+ * route handler.
+ */
+declare function useSocketServer(): Server;
+
+/**
+ * Optional cleanup returned by `app/server.ts`.
+ *
+ * The cleanup callback runs during controlled shutdown after the startup
+ * bootstrap has completed successfully.
+ */
+type LithiaServerCleanup = void | (() => void | Promise<void>);
+/**
+ * Bootstrap contract for `src/app/server.ts`.
+ *
+ * The function runs before the app starts accepting traffic and may return an
+ * optional cleanup callback that runs during shutdown and reload. Startup
+ * lifecycle details are described in
+ * [Project Structure](https://lithiajs.org/docs/latest/project-structure) and
+ * [Deploying](https://lithiajs.org/docs/latest/deploying).
+ */
+type LithiaServerBootstrap = () => Promise<LithiaServerCleanup>;
+
+export { type CookieOptions, type EventHandler, type EventMiddleware, GatewayTimeoutError, InternalServerError, LithiaClientError, LithiaRequest, LithiaResponse, type LithiaServerBootstrap, type LithiaServerCleanup, type NextEvent, type NextRoute, type OpenAPIResponseMetadata, type OpenAPIRouteMetadata, type OpenAPISecurityRequirement, type Params, type Query, type RouteHandler, type RouteMetadata, type RouteMiddleware, ServiceUnavailableError, type UploadedFile, dispatchTask, executeTask, provide, runTask, runTaskAsync, useData, useDependency, useEvent, useHeaders, useOptionalDependency, useParams, usePathname, useQuery, useRequest, useResponse, useRoute, useSocket, useSocketServer };