@ozanarslan/corpus 0.0.1

package/dist/Res/index.d.ts

@@ -0,0 +1,353 @@
+/**
+ * Response building: status codes, body serialization, streaming, and cookies.
+ *
+ * A {@link Res} is what a handler shapes on its way to a native `Response`. It
+ * is created lazily on {@link Context.res}, so a handler that just returns a
+ * value never constructs one; reach for it when the response needs a status,
+ * headers, cookies, or a body form that a plain return value cannot express —
+ * a file, a redirect, or a stream.
+ *
+ * Body serialization is inferred from the value's type at
+ * {@link Res.toNativeResponse} time, so an object becomes JSON, a typed array
+ * stays binary, and a stream passes through untouched — each with a matching
+ * `Content-Type` unless one was set explicitly.
+ *
+ * ```ts
+ * import { Res, Status } from "@ozanarslan/corpus";
+ *
+ * new Res({ id: 1 }, { status: Status.CREATED });
+ * new Res().file("./report.pdf");
+ * new Res().redirect("/login");
+ * ```
+ *
+ * @module Res
+ */
+import { Cookies } from "../Cookies";
+import { type ContentDispositionDefinition } from "../Headers";
+import { type MaybePromise, type Nullable } from "../utils/is";
+import type { ValueOf } from "../utils/object";
+import { XFile } from "../XFile";
+/** Commonly used HTTP status codes. */
+declare const Status: {
+    /** Continue: Request received, please continue */
+    readonly CONTINUE: 100;
+    /** Switching Protocols: Protocol change request approved */
+    readonly SWITCHING_PROTOCOLS: 101;
+    /** Processing (WebDAV) */
+    readonly PROCESSING: 102;
+    /** Early Hints */
+    readonly EARLY_HINTS: 103;
+    /** OK: Request succeeded */
+    readonly OK: 200;
+    /** Created: Resource created */
+    readonly CREATED: 201;
+    /** Accepted: Request accepted but not completed */
+    readonly ACCEPTED: 202;
+    /** Non-Authoritative Information */
+    readonly NON_AUTHORITATIVE_INFORMATION: 203;
+    /** No Content: Request succeeded, no body returned */
+    readonly NO_CONTENT: 204;
+    /** Reset Content: Clear form or view */
+    readonly RESET_CONTENT: 205;
+    /** Partial Content: Partial GET successful (e.g. range requests) */
+    readonly PARTIAL_CONTENT: 206;
+    /** Multi-Status (WebDAV) */
+    readonly MULTI_STATUS: 207;
+    /** Already Reported (WebDAV) */
+    readonly ALREADY_REPORTED: 208;
+    /** IM Used (HTTP Delta encoding) */
+    readonly IM_USED: 226;
+    /** Multiple Choices */
+    readonly MULTIPLE_CHOICES: 300;
+    /** Moved Permanently: Resource moved to a new URL */
+    readonly MOVED_PERMANENTLY: 301;
+    /** Found: Resource temporarily under different URI */
+    readonly FOUND: 302;
+    /** See Other: Redirect to another URI using GET */
+    readonly SEE_OTHER: 303;
+    /** Not Modified: Cached version is still valid */
+    readonly NOT_MODIFIED: 304;
+    /** Use Proxy: Deprecated */
+    readonly USE_PROXY: 305;
+    /** Temporary Redirect: Resource temporarily at another URI */
+    readonly TEMPORARY_REDIRECT: 307;
+    /** Permanent Redirect: Resource permanently at another URI */
+    readonly PERMANENT_REDIRECT: 308;
+    /** Bad Request: Malformed request */
+    readonly BAD_REQUEST: 400;
+    /** Unauthorized: Missing or invalid auth credentials */
+    readonly UNAUTHORIZED: 401;
+    /** Payment Required: Reserved for future use */
+    readonly PAYMENT_REQUIRED: 402;
+    /** Forbidden: Authenticated but no permission */
+    readonly FORBIDDEN: 403;
+    /** Not Found: Resource does not exist */
+    readonly NOT_FOUND: 404;
+    /** Method Not Allowed: HTTP method not allowed */
+    readonly METHOD_NOT_ALLOWED: 405;
+    /** Not Acceptable: Response not acceptable by client */
+    readonly NOT_ACCEPTABLE: 406;
+    /** Proxy Authentication Required */
+    readonly PROXY_AUTHENTICATION_REQUIRED: 407;
+    /** Request Timeout: Server timeout waiting for client */
+    readonly REQUEST_TIMEOUT: 408;
+    /** Conflict: Request conflict (e.g. duplicate resource) */
+    readonly CONFLICT: 409;
+    /** Gone: Resource is no longer available */
+    readonly GONE: 410;
+    /** Length Required: Missing Content-Length header */
+    readonly LENGTH_REQUIRED: 411;
+    /** Precondition Failed */
+    readonly PRECONDITION_FAILED: 412;
+    /** Payload Too Large */
+    readonly PAYLOAD_TOO_LARGE: 413;
+    /** URI Too Long */
+    readonly URI_TOO_LONG: 414;
+    /** Unsupported Media Type */
+    readonly UNSUPPORTED_MEDIA_TYPE: 415;
+    /** Range Not Satisfiable */
+    readonly RANGE_NOT_SATISFIABLE: 416;
+    /** Expectation Failed */
+    readonly EXPECTATION_FAILED: 417;
+    /** I'm a teapot: Joke response for coffee machines */
+    readonly IM_A_TEAPOT: 418;
+    /** Misdirected Request: Sent to the wrong server */
+    readonly MISDIRECTED_REQUEST: 421;
+    /** Unprocessable Entity (WebDAV) */
+    readonly UNPROCESSABLE_ENTITY: 422;
+    /** Locked (WebDAV) */
+    readonly LOCKED: 423;
+    /** Failed Dependency (WebDAV) */
+    readonly FAILED_DEPENDENCY: 424;
+    /** Too Early: Request might be replayed */
+    readonly TOO_EARLY: 425;
+    /** Upgrade Required */
+    readonly UPGRADE_REQUIRED: 426;
+    /** Precondition Required */
+    readonly PRECONDITION_REQUIRED: 428;
+    /** Too Many Requests: Rate limiting */
+    readonly TOO_MANY_REQUESTS: 429;
+    /** Request Header Fields Too Large */
+    readonly REQUEST_HEADER_FIELDS_TOO_LARGE: 431;
+    /** Unavailable For Legal Reasons */
+    readonly UNAVAILABLE_FOR_LEGAL_REASONS: 451;
+    /** Internal Server Error: Unhandled server error */
+    readonly INTERNAL_SERVER_ERROR: 500;
+    /** Not Implemented: Endpoint/method not implemented */
+    readonly NOT_IMPLEMENTED: 501;
+    /** Bad Gateway: Invalid response from upstream server */
+    readonly BAD_GATEWAY: 502;
+    /** Service Unavailable: Server temporarily overloaded/down */
+    readonly SERVICE_UNAVAILABLE: 503;
+    /** Gateway Timeout: No response from upstream server */
+    readonly GATEWAY_TIMEOUT: 504;
+    /** HTTP Version Not Supported */
+    readonly HTTP_VERSION_NOT_SUPPORTED: 505;
+    /** Variant Also Negotiates */
+    readonly VARIANT_ALSO_NEGOTIATES: 506;
+    /** Insufficient Storage (WebDAV) */
+    readonly INSUFFICIENT_STORAGE: 507;
+    /** Loop Detected (WebDAV) */
+    readonly LOOP_DETECTED: 508;
+    /** Not Extended */
+    readonly NOT_EXTENDED: 510;
+    /** Network Authentication Required */
+    readonly NETWORK_AUTHENTICATION_REQUIRED: 511;
+};
+/**
+ * An HTTP status code. The {@link Status} constants are suggested, but any
+ * number is assignable.
+ */
+type Status = ValueOf<typeof Status> | (number & {});
+/**
+ * Produces the events for a server-sent event stream, used by {@link Res.sse}.
+ *
+ * @param send - Emits one event. `data` is JSON-serialized; `event` names the
+ * event type for a client listening on something other than `message`, and `id`
+ * lets a client resume from where it left off.
+ * @returns Nothing when the source is finite — the stream is closed for you once
+ * it resolves — or a cleanup function when it is open-ended, in which case the
+ * stream stays open and the function runs if the client disconnects.
+ */
+type SseSource = (send: (item: {
+    data: unknown;
+    event?: string;
+    id?: string;
+}) => void) => MaybePromise<void | (() => void)>;
+/**
+ * Produces the lines for a newline-delimited JSON stream, used by
+ * {@link Res.ndjson}.
+ *
+ * @param send - Emits one item, JSON-serialized on its own line.
+ * @returns Nothing to close the stream when the source resolves, or a cleanup
+ * function to keep it open and be told when the client disconnects.
+ */
+type NdjsonSource = (send: (item: unknown) => void) => MaybePromise<void | (() => void)>;
+/** A `ResponseInit` that can also carry cookies. */
+interface ResInit extends ResponseInit {
+    /** Cookies to seed {@link Res.cookies} with. */
+    cookies?: Cookies;
+}
+/**
+ * A response under construction.
+ *
+ * Everything is mutable until {@link Res.toNativeResponse} is called, so a
+ * {@link Middleware} can adjust a response a route handler already built. The
+ * body is kept as the original value rather than serialized eagerly, which is
+ * what lets the content type be inferred from it at the very end.
+ *
+ * Headers and cookies are both lazy, so an untouched response allocates neither.
+ * The chainable methods — {@link Res.file}, {@link Res.redirect},
+ * {@link Res.sse} and the rest — set the body and its headers together and
+ * return `this`.
+ *
+ * @typeParam R - The body type, carried from the route's own response type.
+ */
+declare class Res<R = unknown> {
+    /**
+     * Creates a response.
+     *
+     * @param body - The body value. Serialized by {@link resolveResBody} at
+     * {@link Res.toNativeResponse} time, not now.
+     * @param init - Status, status text, headers and cookies. See
+     * {@link ResInit}.
+     */
+    constructor(body?: Nullable<BodyInit | R>, init?: ResInit);
+    /**
+     * The body to send. Assign any value — objects become JSON, typed arrays stay
+     * binary, streams pass through — and {@link resolveResBody} works out the rest
+     * at serialization time.
+     */
+    body: Nullable<BodyInit | R>;
+    /** The status code. Defaults to {@link Status.OK}. */
+    status: number;
+    /** The status text. Empty by default, which lets the runtime supply the standard phrase. */
+    statusText: string;
+    /** Backing store for {@link Res.headers}, created on first access. */
+    private _headers;
+    /**
+     * The response headers.
+     *
+     * Reading them rewrites the `Set-Cookie` lines from {@link Res.cookies} first,
+     * so the two views never disagree — and writing `Set-Cookie` here feeds back
+     * into the cookie map. Values may be numbers or booleans, since
+     * {@link patchGlobalHeaders} has stringified setters.
+     *
+     * @returns The headers, created on first access.
+     */
+    get headers(): Headers;
+    /** Backing store for {@link Res.cookies}, created on first access. */
+    private _cookies;
+    /**
+     * The cookies to send, as a mutable map.
+     *
+     * This is the authoritative view: the map is serialized into `Set-Cookie`
+     * whenever {@link Res.headers} is read, so deleting a cookie here removes its
+     * header. Values are percent-encoded on serialization, which is what keeps a
+     * CRLF in a cookie value from splitting the response.
+     *
+     * @returns The {@link Cookies} map, created on first access.
+     */
+    get cookies(): Cookies;
+    /**
+     * Serializes everything into a native `Response`.
+     *
+     * The content type inferred from the body is applied only when none was set
+     * explicitly, so a handler's own choice always wins. `X-Content-Type-Options:
+     * nosniff` is set unconditionally — without it a browser will sniff a
+     * `text/plain` body that looks like markup and render it as HTML, turning any
+     * reflected value into XSS.
+     *
+     * @returns The response to send over the wire. Called by
+     * {@link App.respond}.
+     */
+    toNativeResponse(): Response;
+    /**
+     * Turns the response into a server-sent event stream.
+     *
+     * Sets the body to a stream and the headers browsers require for `EventSource`
+     * to work — the event stream type, no caching, and a kept-alive connection.
+     *
+     * @param source - The {@link SseSource} producing events. Return a cleanup
+     * function from it to keep the stream open indefinitely.
+     * @param retry - Reconnection delay in milliseconds, sent with every event to
+     * tell the client how long to wait before reconnecting.
+     * @returns This response, for chaining.
+     */
+    sse(source: SseSource, retry?: number): this;
+    /**
+     * Turns the response into a newline-delimited JSON stream.
+     *
+     * Each item is serialized onto its own line, so a client can parse results as
+     * they arrive instead of waiting for a whole array. Useful for large result
+     * sets and progressive output where the event semantics of {@link Res.sse} are
+     * not needed.
+     *
+     * @param source - The {@link NdjsonSource} producing items. Return a cleanup
+     * function from it to keep the stream open indefinitely.
+     * @returns This response, for chaining.
+     */
+    ndjson(source: NdjsonSource): this;
+    /**
+     * Streams a file as the response body, without reading it into memory. Prefer
+     * this over {@link Res.file} for anything large.
+     *
+     * @param fileOrPath - An {@link XFile} or a path to one.
+     * @param disposition - `"inline"` to display in the browser, `"attachment"` to
+     * prompt a download under the file's own name.
+     * @returns This response, for chaining.
+     * @throws {@link Exception} with {@link Status.NOT_FOUND} when the file does
+     * not exist.
+     */
+    streamFile(fileOrPath: XFile | string, disposition: ContentDispositionDefinition["disposition"]): this;
+    /**
+     * Sends a file as the response body, read into memory so it can carry an exact
+     * `Content-Length`. Use {@link Res.streamFile} instead for large files.
+     *
+     * @param fileOrPath - An {@link XFile} or a path to one.
+     * @returns This response, for chaining.
+     * @throws {@link Exception} with {@link Status.NOT_FOUND} when the file does
+     * not exist.
+     */
+    file(fileOrPath: XFile | string): this;
+    /**
+     * Redirects the client to another URL.
+     *
+     * @param url - Where to send the client, absolute or relative.
+     * @param status - Which redirect to use. Defaults to {@link Status.FOUND}, a
+     * temporary redirect that browsers do not cache. See
+     * {@link Res.permanentRedirect}, {@link Res.temporaryRedirect} and
+     * {@link Res.seeOther} for the named alternatives.
+     * @returns This response, for chaining.
+     */
+    redirect(url: string | URL, status?: 301 | 302 | 303 | 307 | 308): this;
+    /**
+     * Redirects with {@link Status.MOVED_PERMANENTLY}, which browsers and search
+     * engines cache indefinitely. Use it only when the resource has really moved
+     * for good.
+     *
+     * @param url - Where to send the client.
+     * @returns This response, for chaining.
+     */
+    permanentRedirect(url: string | URL): this;
+    /**
+     * Redirects with {@link Status.TEMPORARY_REDIRECT}, which preserves the
+     * original method and body — unlike {@link Status.FOUND}, which clients
+     * commonly turn into a GET.
+     *
+     * @param url - Where to send the client.
+     * @returns This response, for chaining.
+     */
+    temporaryRedirect(url: string | URL): this;
+    /**
+     * Redirects with {@link Status.SEE_OTHER}, which explicitly switches the
+     * client to a GET. This is the correct redirect after a successful POST, since
+     * it stops a refresh from resubmitting the form.
+     *
+     * @param url - Where to send the client.
+     * @returns This response, for chaining.
+     */
+    seeOther(url: string | URL): this;
+}
+export { Res, Status };
+//# sourceMappingURL=index.d.ts.map

package/dist/Res/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Res/index.ts"],"names":[],"mappings":"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"}

package/dist/RouteBase/BundleRoute/index.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Serving for a directory of built front-end files: hashed assets, an entry
+ * document, and per-file-class caching.
+ *
+ * {@link BundleRoute} is the {@link RouteVariant.bundle} member of the
+ * {@link RouteBase} family. It serves any directory of servable files, deriving
+ * cache headers from what kind of file each one is — immutable for build-hashed
+ * assets, revalidated for the entry document, and a configurable fallback for
+ * everything else. Its distinguishing behaviour is the entry-document fallback:
+ * a path that resolves to no file is answered with the entry HTML instead of a
+ * 404, which is what makes a single-page app survive a hard refresh on a client
+ * route. That fallback is the main use, not the only one — {@link StaticRoute}
+ * remains the plainer choice when a bundle's caching and fallback behaviour is
+ * not wanted.
+ *
+ * ```ts
+ * new BundleRoute("/*", "./dist");
+ * ```
+ *
+ * @module BundleRoute
+ */
+import type { ContextHandler } from "../../Context";
+import { type CacheControlDefinition } from "../../Headers";
+import { Method } from "../../Request";
+import { type Res } from "../../Res";
+import { RouteBase, RouteVariant, type RouteConfig } from "..";
+import { type MaybePromise } from "../../utils/is";
+import { type Tuple } from "../../utils/tuple";
+import { XFile } from "../../XFile";
+/**
+ * A {@link CacheControlDefinition} that also names the path it applies to,
+ * relative to {@link BundleRoute.dir}.
+ */
+interface CacheControlDefinitionWithPath extends CacheControlDefinition {
+    /**
+     * Path relative to {@link BundleRoute.dir}. Falls back to the corresponding
+     * {@link DEFAULT_DEFINITION} value when omitted.
+     */
+    path?: string;
+}
+/**
+ * Describes the layout of a bundle directory and the caching policy for each
+ * class of file within it. See {@link DEFAULT_DEFINITION} for the values used
+ * when this is not supplied.
+ */
+interface BundleRouteDefinition {
+    /**
+     * The entry document — its path within the bundle, and how it should be
+     * cached. Also the file served by the fallback in
+     * {@link BundleRoute.resolveFile}.
+     */
+    indexHtml: CacheControlDefinitionWithPath;
+    /**
+     * The directory holding build-hashed assets, and how they should be cached.
+     * Files below it are matched by path segment, not by extension.
+     */
+    assetsDir: CacheControlDefinitionWithPath;
+    /**
+     * Caching for every file that is neither the entry document nor under the
+     * assets directory. Omit it to send no `Cache-Control` for those files.
+     */
+    fallback?: CacheControlDefinition;
+}
+/**
+ * What a {@link BundleRoute} handler resolves to: a stream for non-HTML files,
+ * bytes for HTML, or a string or {@link Res} when
+ * {@link BundleRoute.onFileNotFound} is overridden to return one.
+ */
+type BundleRouteRes = ReadableStream<Uint8Array> | Uint8Array | string | Res;
+/**
+ * Serves a directory of built files.
+ *
+ * Register it on a wildcard endpoint so every path below it reaches the route.
+ * A request resolves in three steps: the endpoint prefix is stripped to a
+ * sub-path by {@link BundleRoute.resolveSubPath}, the sub-path is joined onto
+ * {@link BundleRoute.dir} by {@link BundleRoute.resolveTargetPath}, and
+ * {@link BundleRoute.resolveFile} serves the result if it exists. When it does
+ * not and the request is not for an HTML file, the entry document named by
+ * {@link BundleRoute.indexHtmlPath} is served instead.
+ *
+ * Files are matched against {@link BundleRoute.definition} to pick their
+ * `Cache-Control`: the entry document, anything under
+ * {@link BundleRoute.assetsDirPath}, and everything else each get their own
+ * policy.
+ *
+ * Paths that escape {@link BundleRoute.dir} are rejected by
+ * {@link BundleRoute.isTraversalAttempt} before the filesystem is touched, so
+ * `..` segments cannot reach files outside the directory.
+ *
+ * @typeParam E - The literal endpoint type, carried so the endpoint stays
+ * narrowly typed at the call site.
+ */
+declare class BundleRoute<E extends string = string> extends RouteBase<never, never, never, BundleRouteRes, E> {
+    /**
+     * Creates a bundle route for subclasses, which declare
+     * {@link BundleRoute.endpoint} and {@link BundleRoute.dir} as class fields and
+     * call {@link RouteBase.register} themselves.
+     */
+    constructor();
+    /**
+     * Creates a bundle route and registers it on the nearest {@link App}.
+     *
+     * @param endpoint - The path to serve the directory under. Use a wildcard so
+     * nested paths reach the route.
+     * @param dir - Directory to serve from. Every resolved path is confined to it.
+     * @param definition - Optional {@link BundleRouteDefinition} overriding the
+     * bundle layout and caching policy. Defaults to {@link DEFAULT_DEFINITION}.
+     */
+    constructor(endpoint: E, dir: string, definition?: BundleRouteDefinition);
+    /**
+     * Directory the files are served from. Every path resolved by the route is
+     * confined to it.
+     */
+    dir: string;
+    /**
+     * Sub-paths that are answered with the entry document rather than the file
+     * they name. A trailing `*` makes a pattern a prefix match; leading slashes
+     * are optional.
+     *
+     * Useful when a client-side route collides with a real file in the directory,
+     * or to keep a build artefact from being reachable.
+     */
+    ignore: Array<string>;
+    /**
+     * The bundle's layout and caching policy. Defaults to
+     * {@link DEFAULT_DEFINITION}.
+     */
+    definition: BundleRouteDefinition;
+    /**
+     * Path of the entry document within {@link BundleRoute.dir}.
+     *
+     * @returns The path from {@link BundleRouteDefinition.indexHtml}, or the
+     * {@link DEFAULT_DEFINITION} value when it declares none.
+     */
+    get indexHtmlPath(): string;
+    /**
+     * Path of the hashed-assets directory within {@link BundleRoute.dir}.
+     *
+     * @returns The path from {@link BundleRouteDefinition.assetsDir}, or the
+     * {@link DEFAULT_DEFINITION} value when it declares none.
+     */
+    get assetsDirPath(): string;
+    /**
+     * Lists every file this route can serve, as sub-paths relative to
+     * {@link BundleRoute.dir}.
+     *
+     * Walks {@link BundleRoute.dir} recursively and returns each file's path
+     * with a leading `/`, matching what {@link BundleRoute.resolveSubPath} would
+     * produce for a request reaching that file. Useful for generating a sitemap
+     * or verifying what a deployed bundle actually contains.
+     *
+     * @returns The sub-paths of every file under {@link BundleRoute.dir}.
+     */
+    getEndpoints(): Array<string>;
+    /**
+     * Decides what to serve when a request resolves to no readable file — an HTML
+     * file that is genuinely missing, a directory with no entry document, or a
+     * path rejected by {@link BundleRoute.isTraversalAttempt}.
+     *
+     * Replace it to serve a custom 404 page or redirect instead of throwing.
+     *
+     * @param subPath - The request path with the endpoint prefix stripped, as the
+     * client asked for it.
+     * @returns The {@link BundleRouteRes} to send instead.
+     * @throws {@link Exception} with {@link Status.NOT_FOUND} by default.
+     */
+    onFileNotFound: (subPath: string) => MaybePromise<BundleRouteRes>;
+    /**
+     * Resolves a filesystem path to a readable {@link XFile}, applying the
+     * entry-document fallback.
+     *
+     * A missing non-HTML path falls back to the entry document, which is what
+     * serves client-side routes. A missing HTML path does not fall back — asking
+     * for a specific document that does not exist is a real 404 rather than a
+     * client route.
+     *
+     * @param targetPath - Path produced by {@link BundleRoute.resolveTargetPath}.
+     * @returns The {@link XFile} to serve, or `null` when nothing readable was
+     * found, which sends the request to {@link BundleRoute.onFileNotFound}.
+     */
+    protected resolveFile(targetPath: string): XFile | null;
+    /**
+     * Strips the route's own prefix from a request pathname, leaving the path
+     * relative to {@link BundleRoute.dir}.
+     *
+     * Both `/*` and `*` endpoint suffixes are handled, and a pathname that does
+     * not start with the prefix is returned untouched. The result is percent-decoded,
+     * since {@link URL.pathname} leaves escapes like `%20` intact and filesystem
+     * paths need the literal characters.
+     *
+     * @param pathname - The pathname of the incoming request.
+     * @returns The bundle-relative sub-path, `""` or `/` for the route root.
+     */
+    protected resolveSubPath(pathname: string): string;
+    /**
+     * Joins a sub-path onto {@link BundleRoute.dir} to get the file to read.
+     *
+     * The route root maps to the entry document, as does any sub-path matching
+     * {@link BundleRoute.ignore}. The result is not yet known to be safe —
+     * {@link BundleRoute.isTraversalAttempt} checks it before it is opened.
+     *
+     * @param subPath - The sub-path from {@link BundleRoute.resolveSubPath}.
+     * @returns The joined filesystem path.
+     */
+    protected resolveTargetPath(subPath: string): string;
+    /**
+     * Reports whether a resolved path escapes {@link BundleRoute.dir}.
+     *
+     * Both sides are fully resolved before comparison, so `..` segments and
+     * encoded variants are normalised away rather than matched textually. The
+     * separator check keeps a sibling directory sharing the root's name prefix
+     * from passing.
+     *
+     * @param targetPath - Path from {@link BundleRoute.resolveTargetPath}.
+     * @returns `true` when the path lies outside the served directory, in which
+     * case the request goes to {@link BundleRoute.onFileNotFound} without the file
+     * being opened.
+     */
+    protected isTraversalAttempt(targetPath: string): boolean;
+    /**
+     * Produces the response body and headers for a resolved file.
+     *
+     * `Cache-Control` is chosen by matching the file against
+     * {@link BundleRoute.definition}: the entry document first, then anything
+     * under {@link BundleRoute.assetsDirPath}, then
+     * {@link BundleRouteDefinition.fallback}. No fallback means no header.
+     *
+     * Non-HTML files are streamed and carry an inline
+     * `Content-Disposition`, so large assets are never buffered. HTML is read into
+     * memory instead, which lets it carry an exact `Content-Length` — the entry
+     * document is small and served constantly, so the length is worth more than
+     * the streaming.
+     *
+     * @param file - The {@link XFile} resolved for the request.
+     * @returns A {@link Tuple} of the body and the headers to set on
+     * {@link Res.headers}.
+     */
+    protected resolveResponseData(file: XFile): Tuple<ReadableStream | Uint8Array, Record<string, string>>;
+    /** Marks this route as {@link RouteVariant.bundle} for {@link App} route compilation. */
+    readonly variant: RouteVariant;
+    /** Bundles answer {@link Method.GET} only. */
+    readonly method: Method;
+    /**
+     * The path the directory is served under. Use a wildcard so nested paths reach
+     * the route; {@link BundleRoute.resolveSubPath} strips the wildcard suffix.
+     */
+    endpoint: E;
+    /**
+     * Bundles take no params, search or body, so no {@link RouteConfig} schemas
+     * apply.
+     */
+    readonly config?: RouteConfig<never, never, never, BundleRouteRes>;
+    /**
+     * Serves the file a request resolves to.
+     *
+     * Resolves the sub-path and target path, rejects traversal attempts, reads the
+     * file, then sets the headers from {@link BundleRoute.resolveResponseData} on
+     * {@link Context.res} and returns the body. Anything that fails to resolve
+     * goes to {@link BundleRoute.onFileNotFound}.
+     *
+     * @param c - The {@link Context} for the request.
+     * @returns The file body — a stream for non-HTML, bytes for HTML — or whatever
+     * {@link BundleRoute.onFileNotFound} produced.
+     */
+    handler: ContextHandler<never, never, never, BundleRouteRes>;
+}
+export { BundleRoute };
+//# sourceMappingURL=index.d.ts.map

package/dist/RouteBase/BundleRoute/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/RouteBase/BundleRoute/index.ts"],"names":[],"mappings":"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"}