@ozanarslan/corpus 0.0.1

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

@@ -0,0 +1,121 @@
+/**
+ * Serving a single file from a single endpoint.
+ *
+ * {@link FileRoute} is the {@link RouteVariant.file} member of the
+ * {@link RouteBase} family, and the narrowest of the file-serving routes: one
+ * endpoint, one file, no path resolution. Reach for {@link BundleRoute} to serve
+ * a whole directory, or {@link StaticRoute} when the file's contents feed a
+ * handler rather than being sent as-is.
+ *
+ * ```ts
+ * import { FileRoute } from "@ozanarslan/corpus";
+ *
+ * new FileRoute("GET /robots.txt", "./public/robots.txt");
+ * new FileRoute("GET /report", { filePath: "./report.pdf", disposition: "attachment" });
+ * ```
+ *
+ * @module FileRoute
+ */
+import type { ContextHandler } from "../../Context";
+import { type ContentDispositionDefinition, type CacheControlDefinition } from "../../Headers";
+import { Method } from "../../Request";
+import { RouteBase, type RouteAddress, RouteVariant, type RouteConfig } from "..";
+/**
+ * Describes the file a {@link FileRoute} serves and how it is sent. Pass a bare
+ * path string instead when the defaults suffice.
+ */
+interface FileRouteDefinition {
+    /** Path to the file, resolved when the request arrives rather than at registration. */
+    filePath: string;
+    /**
+     * The `Content-Disposition` to send. Setting it also switches the route to
+     * streaming — see {@link FileRoute.disposition}.
+     */
+    disposition?: ContentDispositionDefinition["disposition"];
+    /** Caching policy. Defaults to {@link FileRoute.cache}. */
+    cache?: CacheControlDefinition;
+}
+/**
+ * What a {@link FileRoute} handler resolves to: a stream when a disposition is
+ * set, bytes otherwise, or a string when {@link FileRoute.onFileNotFound} is
+ * overridden to return one.
+ */
+type FileRouteRes = ReadableStream<Uint8Array> | Uint8Array | string;
+/**
+ * Serves one file at one endpoint.
+ *
+ * The file is read per request, not at registration, so replacing it on disk
+ * takes effect without a restart — and a file that does not exist yet is not an
+ * error until someone asks for it.
+ *
+ * How the body is sent depends on {@link FileRoute.disposition}: with one set,
+ * the file is streamed and carries a `Content-Disposition`; without one, it is
+ * read into memory and carries an exact `Content-Length`.
+ *
+ * @typeParam E - The literal endpoint type, carried so the endpoint stays
+ * narrowly typed at the call site.
+ */
+declare class FileRoute<E extends string = string> extends RouteBase<never, never, never, FileRouteRes, E> {
+    /**
+     * Creates a file route for subclasses, which declare
+     * {@link FileRoute.endpoint} and {@link FileRoute.filePath} as class fields
+     * and call {@link RouteBase.register} themselves.
+     */
+    constructor();
+    /**
+     * Creates a file route and registers it on the nearest {@link App}.
+     *
+     * @param address - The {@link RouteAddress}: a `"METHOD /endpoint"` string or a
+     * method-and-endpoint pair.
+     * @param definition - A {@link FileRouteDefinition}, or just the file path when
+     * the default caching and inline sending are fine.
+     */
+    constructor(address: RouteAddress<E>, definition: FileRouteDefinition | string);
+    /** Path to the file to serve, read fresh on every request. */
+    filePath: string;
+    /**
+     * The `Content-Disposition` to send — `"inline"` to display in the browser,
+     * `"attachment"` to download under the file's own name.
+     *
+     * Setting it also switches the route to streaming, so large downloads are
+     * never buffered. Leaving it unset sends the bytes with a `Content-Length`
+     * instead, which suits small files a client may want to cache or range over.
+     */
+    disposition?: ContentDispositionDefinition["disposition"];
+    /**
+     * Caching policy, rendered into `Cache-Control` by
+     * {@link createCacheControlHeader}. Defaults to one hour of public caching.
+     */
+    cache: CacheControlDefinition;
+    /**
+     * Decides what to serve when {@link FileRoute.filePath} does not exist at
+     * request time. Replace it to serve a placeholder or redirect instead of
+     * throwing.
+     *
+     * @returns The {@link FileRouteRes} to send instead.
+     * @throws {@link Exception} with {@link Status.NOT_FOUND} by default.
+     */
+    onFileNotFound: () => Promise<FileRouteRes>;
+    /** Marks this route as {@link RouteVariant.file} for {@link App} route compilation. */
+    readonly variant: RouteVariant;
+    /** The method the file is served on. Taken from the {@link RouteAddress}; defaults to {@link Method.GET}. */
+    method: Method;
+    /** The path the file is served at. */
+    endpoint: E;
+    /**
+     * File routes take no params, search or body, so no {@link RouteConfig}
+     * schemas apply.
+     */
+    config?: RouteConfig<never, never, never, FileRouteRes> | undefined;
+    /**
+     * Reads the file and sends it, setting the content type, caching and length or
+     * disposition headers on {@link Context.res}.
+     *
+     * @param c - The {@link Context} for the request.
+     * @returns The file body — a stream when {@link FileRoute.disposition} is set,
+     * bytes otherwise — or whatever {@link FileRoute.onFileNotFound} produced.
+     */
+    handler: ContextHandler<never, never, never, FileRouteRes>;
+}
+export { FileRoute };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/RouteBase/FileRoute/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EACN,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,EAI3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EACN,SAAS,EACT,KAAK,YAAY,EAEjB,YAAY,EACZ,KAAK,WAAW,EAChB,MAAM,aAAa,CAAC;AAKrB;;;GAGG;AACH,UAAU,mBAAmB;IAC5B,uFAAuF;IACvF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,4BAA4B,CAAC,aAAa,CAAC,CAAC;IAC1D,2DAA2D;IAC3D,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAC/B;AAED;;;;GAIG;AACH,KAAK,YAAY,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,UAAU,GAAG,MAAM,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH,cAAM,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;IACjG;;;;OAIG;;IAEH;;;;;;;OAOG;gBACS,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,mBAAmB,GAAG,MAAM;IAmB9E,8DAA8D;IAC9D,QAAQ,EAAG,MAAM,CAAC;IAElB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,4BAA4B,CAAC,aAAa,CAAC,CAAC;IAE1D;;;OAGG;IACH,KAAK,EAAE,sBAAsB,CAI3B;IAEF;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAEzC;IAEF,uFAAuF;IACvF,SAAkB,OAAO,EAAE,YAAY,CAAqB;IAE5D,6GAA6G;IACpG,MAAM,EAAE,MAAM,CAAc;IAErC,sCAAsC;IAC7B,QAAQ,EAAG,CAAC,CAAC;IAEtB;;;OAGG;IACM,MAAM,CAAC,EAAE,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,GAAG,SAAS,CAAC;IAE7E;;;;;;;OAOG;IACM,OAAO,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CA0BjE;CACF;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

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

@@ -0,0 +1,83 @@
+/**
+ * The ordinary route: a method, an endpoint, and a handler.
+ *
+ * {@link Route} is the {@link RouteVariant.dynamic} member of the
+ * {@link RouteBase} family and the one most code uses. The others exist for
+ * responses the framework can produce itself — files, directories, socket
+ * upgrades — while this one just runs your function.
+ *
+ * ```ts
+ * import { Route } from "@ozanarslan/corpus";
+ *
+ * new Route("GET /users/:id", (c) => findUser(c.params.id));
+ * ```
+ *
+ * A {@link RouteConfig} adds schemas for the body, search and params, which both
+ * validate the request and type {@link Context}, so `c.params.id` is known to be
+ * whatever the schema says it is.
+ *
+ * @module Route
+ */
+import type { ContextHandler } from "../../Context";
+import { Method } from "../../Request";
+import { RouteBase, RouteVariant, type RouteAddress, type RouteConfig } from "..";
+/**
+ * A route handled by a function.
+ *
+ * Constructing one registers it on the nearest {@link App}, which compiles it
+ * into the server's route map at {@link App.listen} time along with whatever
+ * {@link Middleware} targets it.
+ *
+ * The type parameters are usually inferred from the {@link RouteConfig} rather
+ * than written out, and flow into the {@link Context} the handler receives.
+ *
+ * @typeParam B - Parsed {@link Context.body} type.
+ * @typeParam S - Parsed {@link Context.search} type.
+ * @typeParam P - Parsed {@link Context.params} type.
+ * @typeParam R - Response body type.
+ * @typeParam E - The literal endpoint type, carried so the endpoint stays
+ * narrowly typed at the call site.
+ */
+declare class Route<B = unknown, S = unknown, P = unknown, R = unknown, E extends string = string> extends RouteBase<B, S, P, R, E> {
+    /**
+     * Creates a route for subclasses, which declare
+     * {@link Route.method}, {@link Route.endpoint} and {@link Route.handler} as
+     * class fields and call {@link RouteBase.register} themselves.
+     */
+    constructor();
+    /**
+     * Creates a route and registers it on the nearest {@link App}.
+     *
+     * @param address - The {@link RouteAddress}: a `"METHOD /endpoint"` string or a
+     * method-and-endpoint pair.
+     * @param callback - The {@link ContextHandler} that answers the request.
+     * @param model - Optional {@link RouteConfig} declaring validation schemas and
+     * per-route limits. Its schemas also type the {@link Context} the handler
+     * receives.
+     */
+    constructor(address: RouteAddress<E>, callback: ContextHandler<B, S, P, R>, model?: RouteConfig<B, S, P, R>);
+    /** Marks this route as {@link RouteVariant.dynamic} for {@link App} route compilation. */
+    readonly variant: RouteVariant;
+    /** The {@link Method} this route answers, taken from the {@link RouteAddress}. */
+    readonly method: Method;
+    /**
+     * The path this route answers. Supports `:name` parameters and a trailing
+     * wildcard, both of which arrive in {@link Context.params}.
+     */
+    readonly endpoint: E;
+    /**
+     * Validation schemas and per-route limits. Absent means nothing is validated —
+     * and, since {@link getContextAccess} inspects it, absent schemas are one of
+     * the signals that a surface need not be parsed at all.
+     */
+    readonly config?: RouteConfig<B, S, P, R>;
+    /**
+     * The function that answers the request.
+     *
+     * Return a value to send it as the body, a {@link Res} to control the whole
+     * response, or nothing after mutating {@link Context.res} directly.
+     */
+    handler: ContextHandler<B, S, P, R>;
+}
+export { Route };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/RouteBase/Route/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAEN,SAAS,EACT,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;;;;;;;;GAgBG;AACH,cAAM,KAAK,CACV,CAAC,GAAG,OAAO,EACX,CAAC,GAAG,OAAO,EACX,CAAC,GAAG,OAAO,EACX,CAAC,GAAG,OAAO,EACX,CAAC,SAAS,MAAM,GAAG,MAAM,CACxB,SAAQ,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACjC;;;;OAIG;;IAEH;;;;;;;;;OASG;gBAEF,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EACxB,QAAQ,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACpC,KAAK,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAmBhC,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAwB;IAEtD,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAG,CAAC,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAa;IAEtD;;;;;OAKG;IACM,OAAO,EAAG,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAC9C;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}

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

@@ -0,0 +1,149 @@
+/**
+ * Serving a file read once at startup, optionally through a handler.
+ *
+ * {@link StaticRoute} is the {@link RouteVariant.static} member of the
+ * {@link RouteBase} family. Unlike {@link FileRoute}, which reads its file per
+ * request, this one reads at construction and holds the bytes — so the file is
+ * served from memory, and changes on disk are not picked up until the process
+ * restarts.
+ *
+ * The optional callback receives the file's contents as text, which is what
+ * makes this the route for templating: an HTML shell can have values injected
+ * into it before being sent.
+ *
+ * ```ts
+ * import { StaticRoute } from "@ozanarslan/corpus";
+ *
+ * new StaticRoute("GET /about", "./pages/about.html");
+ * new StaticRoute("GET /", "./pages/index.html", (c, html) => html.replace("{{title}}", title));
+ * ```
+ *
+ * @module StaticRoute
+ */
+import type { Context, ContextHandler } from "../../Context";
+import { type CacheControlDefinition } from "../../Headers";
+import { Method } from "../../Request";
+import { type Res } from "../../Res";
+import { RouteBase, RouteVariant, type RouteAddress, type RouteConfig } from "..";
+import { type Nullable, type MaybePromise } from "../../utils/is";
+import { XFile } from "../../XFile";
+/**
+ * Transforms a static file's contents before they are sent.
+ *
+ * @param context - The {@link Context} for the request.
+ * @param content - The file's contents, decoded as UTF-8 text.
+ * @returns What to send: a string, raw bytes, or a {@link Res} for full control
+ * over the response.
+ * @typeParam B - Parsed {@link Context.body} type.
+ * @typeParam S - Parsed {@link Context.search} type.
+ * @typeParam P - Parsed {@link Context.params} type.
+ */
+type StaticRouteCallback<B = unknown, S = unknown, P = unknown> = (context: Context<B, S, P, StaticRouteRes>, content: string) => MaybePromise<StaticRouteRes>;
+/**
+ * What a {@link StaticRoute} handler resolves to: the file's bytes when there is
+ * no callback, or whatever the {@link StaticRouteCallback} returned.
+ */
+type StaticRouteRes = Uint8Array | string | Res;
+/**
+ * A {@link RouteConfig} that also carries a caching policy.
+ *
+ * @typeParam B - Parsed {@link Context.body} type.
+ * @typeParam S - Parsed {@link Context.search} type.
+ * @typeParam P - Parsed {@link Context.params} type.
+ */
+interface StaticRouteConfig<B = unknown, S = unknown, P = unknown> extends RouteConfig<B, S, P, StaticRouteRes> {
+    /**
+     * Caching policy for the served file. Defaults to one hour of public caching.
+     */
+    cache?: CacheControlDefinition;
+}
+/**
+ * Serves a file held in memory, optionally passing it through a callback first.
+ *
+ * The file is read once during construction and kept as bytes, so every request
+ * is answered without touching the filesystem. A file that does not exist at
+ * that point is not an error — the route registers, and requests reach
+ * {@link StaticRoute.onFileNotFound} instead.
+ *
+ * @typeParam B - Parsed {@link Context.body} type.
+ * @typeParam S - Parsed {@link Context.search} type.
+ * @typeParam P - Parsed {@link Context.params} type.
+ * @typeParam E - The literal endpoint type, carried so the endpoint stays
+ * narrowly typed at the call site.
+ */
+declare class StaticRoute<B = unknown, S = unknown, P = unknown, E extends string = string> extends RouteBase<B, S, P, StaticRouteRes, E> {
+    /**
+     * Creates a static route for subclasses, which declare
+     * {@link StaticRoute.endpoint} and {@link StaticRoute.file} as class fields and
+     * call {@link RouteBase.register} themselves.
+     */
+    constructor();
+    /**
+     * Creates a static route, reads its file, and registers it on the nearest
+     * {@link App}.
+     *
+     * @param address - The {@link RouteAddress}: a `"METHOD /endpoint"` string or a
+     * method-and-endpoint pair.
+     * @param filePath - Path to the file, read now rather than per request.
+     * @param callback - Optional {@link StaticRouteCallback} to transform the
+     * contents before sending. Omit it to send the file as-is.
+     * @param config - Optional {@link StaticRouteConfig} with validation schemas
+     * and a caching policy.
+     */
+    constructor(address: RouteAddress<E>, filePath: string, callback?: StaticRouteCallback<B, S, P>, config?: StaticRouteConfig<B, S, P>);
+    /**
+     * The file this route serves. Kept for its mime type and name; the contents
+     * live in {@link StaticRoute.bytes}.
+     */
+    file: Nullable<XFile>;
+    /**
+     * The file's contents, read at construction. `null` when the file did not
+     * exist then, which is what sends requests to
+     * {@link StaticRoute.onFileNotFound}.
+     */
+    bytes: Nullable<Uint8Array>;
+    /**
+     * The `Cache-Control` value sent with the file, rendered from the config at
+     * construction rather than per request.
+     */
+    cacheHeader: string;
+    /**
+     * Transforms the file's contents before they are sent. Absent means the bytes
+     * are sent unchanged.
+     */
+    callback?: StaticRouteCallback<B, S, P>;
+    /**
+     * Decides what to serve when the file was missing at construction. Replace it
+     * to serve a placeholder or redirect instead of throwing.
+     *
+     * @returns The {@link StaticRouteRes} to send instead.
+     * @throws {@link Exception} with {@link Status.NOT_FOUND} by default.
+     */
+    onFileNotFound: () => Promise<StaticRouteRes>;
+    /** Marks this route as {@link RouteVariant.static} for {@link App} route compilation. */
+    readonly variant: RouteVariant;
+    /** The method the file is served on. Taken from the {@link RouteAddress}; defaults to {@link Method.GET}. */
+    method: Method;
+    /** The path the file is served at. */
+    endpoint: E;
+    /**
+     * Validation schemas for the route. The caching policy is stripped out during
+     * construction, so what remains is a plain {@link RouteConfig}.
+     */
+    config?: RouteConfig<B, S, P, StaticRouteRes>;
+    /**
+     * Sends the file, or the callback's transformation of it.
+     *
+     * The content type, caching and length headers are set from the file before
+     * the callback runs, so a callback that changes the content's length — or
+     * returns a {@link Res} of its own — should set those headers itself.
+     *
+     * @param c - The {@link Context} for the request.
+     * @returns The file's bytes, or whatever the {@link StaticRoute.callback}
+     * returned. Falls through to {@link StaticRoute.onFileNotFound} when the file
+     * was missing at construction.
+     */
+    handler: ContextHandler<B, S, P, StaticRouteRes>;
+}
+export { StaticRoute };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/RouteBase/StaticRoute/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAuC,KAAK,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAC7F,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAU,KAAK,GAAG,EAAE,MAAM,OAAO,CAAC;AACzC,OAAO,EAEN,SAAS,EACT,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,KAAK,QAAQ,EAAY,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,KAAK,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,IAAI,CACjE,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,EACzC,OAAO,EAAE,MAAM,KACX,YAAY,CAAC,cAAc,CAAC,CAAC;AAElC;;;GAGG;AACH,KAAK,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,GAAG,CAAC;AAEhD;;;;;;GAMG;AACH,UAAU,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,CAAE,SAAQ,WAAW,CACrF,CAAC,EACD,CAAC,EACD,CAAC,EACD,cAAc,CACd;IACA;;OAEG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAC/B;AAED;;;;;;;;;;;;;GAaG;AACH,cAAM,WAAW,CAChB,CAAC,GAAG,OAAO,EACX,CAAC,GAAG,OAAO,EACX,CAAC,GAAG,OAAO,EACX,CAAC,SAAS,MAAM,GAAG,MAAM,CACxB,SAAQ,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC;IAC9C;;;;OAIG;;IAEH;;;;;;;;;;;OAWG;gBAEF,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EACxB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACvC,MAAM,CAAC,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IA0BpC;;;OAGG;IACH,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAQ;IAE7B;;;;OAIG;IACH,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAQ;IAEnC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAM;IAEzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAExC;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAE3C;IAEF,yFAAyF;IACzF,SAAkB,OAAO,EAAE,YAAY,CAAuB;IAE9D,6GAA6G;IACpG,MAAM,EAAE,MAAM,CAAc;IAErC,sCAAsC;IAC7B,QAAQ,EAAG,CAAC,CAAC;IAEtB;;;OAGG;IACM,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,CAAC;IAEvD;;;;;;;;;;;OAWG;IACM,OAAO,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,CASvD;CACF;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}

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

@@ -0,0 +1,117 @@
+/**
+ * WebSocket endpoints.
+ *
+ * {@link WebSocketRoute} is the {@link RouteVariant.websocket} member of the
+ * {@link RouteBase} family. It is the one route kind that does not produce a
+ * response: {@link App.composeRoutes} sees the variant and upgrades the
+ * connection instead, storing the route itself as the socket's data so that
+ * every later event can be dispatched back to its callbacks.
+ *
+ * ```ts
+ * import { WebSocketRoute } from "@ozanarslan/corpus";
+ *
+ * new WebSocketRoute("/chat", {
+ *   onOpen: (ws) => ws.subscribe("room"),
+ *   onMessage: (ws, message) => ws.publish("room", message),
+ * });
+ * ```
+ *
+ * Since one route instance backs every connection to that endpoint, per-socket
+ * state belongs on the socket — through Bun's `subscribe`/`publish` or a map
+ * keyed by socket — not on the route.
+ *
+ * @module WebSocketRoute
+ */
+import type { ContextHandler } from "../../Context";
+import { Method } from "../../Request";
+import { RouteBase, RouteVariant, type RouteConfig } from "..";
+import type { ServerWebSocket } from "../../Server";
+import type { MaybePromise } from "../../utils/is";
+/**
+ * Runs once a connection has been upgraded and is ready.
+ *
+ * @param ws - The newly opened {@link ServerWebSocket}.
+ */
+type WebSocketOnOpen = (ws: ServerWebSocket) => MaybePromise<void>;
+/**
+ * Runs when a connection closes, whichever side ended it.
+ *
+ * @param ws - The closing {@link ServerWebSocket}.
+ * @param code - The WebSocket close code, when one was sent.
+ * @param reason - The accompanying reason, when one was sent.
+ */
+type WebSocketOnClose = (ws: ServerWebSocket, code?: number, reason?: string) => MaybePromise<void>;
+/**
+ * Runs for each message a client sends.
+ *
+ * @param ws - The {@link ServerWebSocket} the message arrived on.
+ * @param message - The payload: a string for text frames, a `Buffer` for binary
+ * ones.
+ */
+type WebSocketOnMessage = (ws: ServerWebSocket, message: string | Buffer) => MaybePromise<void>;
+/** The socket lifecycle callbacks a {@link WebSocketRoute} is built from. */
+interface WebSocketRouteDefinition {
+    /** Called once per connection, after the upgrade succeeds. */
+    onOpen?: WebSocketOnOpen;
+    /** Called once per connection, when it closes. */
+    onClose?: WebSocketOnClose;
+    /** Called for every message received. The only required callback — a socket that never reads has nothing to do. */
+    onMessage: WebSocketOnMessage;
+}
+/**
+ * A WebSocket endpoint.
+ *
+ * Constructing one registers it on the nearest {@link App}, which upgrades
+ * matching requests rather than responding to them. The callbacks are shared by
+ * every connection to the endpoint, and each event receives the socket it
+ * concerns.
+ *
+ * @typeParam E - The literal endpoint type, carried so the endpoint stays
+ * narrowly typed at the call site.
+ */
+declare class WebSocketRoute<E extends string = string> extends RouteBase<never, never, never, WebSocketRoute, E> {
+    /**
+     * Creates a websocket route for subclasses, which declare
+     * {@link WebSocketRoute.endpoint} and the callbacks as class fields and call
+     * {@link RouteBase.register} themselves.
+     */
+    constructor();
+    /**
+     * Creates a websocket route and registers it on the nearest {@link App}.
+     *
+     * @param endpoint - The path clients connect to.
+     * @param definition - The {@link WebSocketRouteDefinition} holding the socket
+     * lifecycle callbacks.
+     */
+    constructor(endpoint: E, definition: WebSocketRouteDefinition);
+    /**
+     * Marks this route as {@link RouteVariant.websocket}, which is what tells
+     * {@link App.composeRoutes} to upgrade rather than respond.
+     */
+    readonly variant: RouteVariant;
+    /** Always {@link Method.GET} — an upgrade handshake is a GET request. */
+    readonly method: Method;
+    /** The path clients connect to. */
+    endpoint: E;
+    /** No schemas apply: an upgrade request carries no body, search or params to validate. */
+    readonly config?: RouteConfig<never, never, never, WebSocketRoute<string>> | undefined;
+    /**
+     * Returns the route itself, which {@link App.composeRoutes} attaches to the
+     * socket as its data — that is how a message arriving minutes later finds its
+     * way back to {@link WebSocketRoute.onMessage}.
+     *
+     * The upgrade itself still happens in {@link App}; this handler only supplies
+     * what the socket carries.
+     *
+     * @returns This route.
+     */
+    readonly handler: ContextHandler<never, never, never, WebSocketRoute<string>>;
+    /** Called once per connection, after the upgrade succeeds. */
+    onOpen?: WebSocketOnOpen | undefined;
+    /** Called once per connection, when it closes. */
+    onClose?: WebSocketOnClose | undefined;
+    /** Called for every message received. */
+    onMessage: WebSocketOnMessage;
+}
+export { WebSocketRoute, type WebSocketOnMessage, type WebSocketOnClose, type WebSocketOnOpen, type WebSocketRouteDefinition, };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/RouteBase/WebSocketRoute/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,KAAK,eAAe,GAAG,CAAC,EAAE,EAAE,eAAe,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;AAEnE;;;;;;GAMG;AACH,KAAK,gBAAgB,GAAG,CAAC,EAAE,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;AAEpG;;;;;;GAMG;AACH,KAAK,kBAAkB,GAAG,CAAC,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;AAEhG,6EAA6E;AAC7E,UAAU,wBAAwB;IAEjC,8DAA8D;IAC9D,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,kDAAkD;IAClD,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,mHAAmH;IACnH,SAAS,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,cAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,SAAS,CAChE,KAAK,EACL,KAAK,EACL,KAAK,EACL,cAAc,EACd,CAAC,CACD;IACA;;;;OAIG;;IAEH;;;;;;OAMG;gBACS,QAAQ,EAAE,CAAC,EAAE,UAAU,EAAE,wBAAwB;IAc7D;;;OAGG;IACH,SAAkB,OAAO,EAAE,YAAY,CAA0B;IAEjE,yEAAyE;IACzE,SAAkB,MAAM,EAAE,MAAM,CAAc;IAE9C,mCAAmC;IAC1B,QAAQ,EAAG,CAAC,CAAC;IAEtB,0FAA0F;IAC1F,SAAkB,MAAM,CAAC,EAAE,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CACpF;IAGX;;;;;;;;;OASG;IACH,SAAkB,OAAO,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,CAChF;IAEN,8DAA8D;IAC9D,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAErC,kDAAkD;IAClD,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAEvC,yCAAyC;IACzC,SAAS,EAAG,kBAAkB,CAAC;CAC/B;AAED,OAAO,EACN,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,wBAAwB,GAC7B,CAAC"}