@nextwebwg/htmlkit 1.0.0-alpha.53 → 1.0.0-alpha.54

package/dist/server.d.ts

@@ -0,0 +1,162 @@
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { type ComponentDefinition } from "@nextwebwg/html-next";
+import { type PageAssets } from "./document.js";
+import { type HeadSource } from "./head.js";
+import type { ApplicationRoute, ApplicationServer, EndpointModule, EndpointRoute, ManifestRedirect, Middleware, NavigationItem, NavigationNode, NavigationQuery, PagerLinks, RedirectStatus, RenderedHead, RenderedLayer, RouteParam, ServerApplication, ServerModule, StartOptions } from "./types.js";
+export { setRenderWorkers } from "@nextwebwg/html-next/server";
+export type { ApplicationServer, EndpointContext, EndpointHandler, EndpointModule, Middleware, ServerApplication, StartOptions } from "./types.js";
+/** A route as navigation and matching read it, without its source files. */
+export type NavigationRoute = Omit<ApplicationRoute, "component" | "server" | "layouts">;
+type Params = Readonly<Record<string, RouteParam>>;
+/** navigation(), navigationTree(), breadcrumbs(), and pager() over routes and each concrete page URL's route. */
+export declare function createNavigation(base: string, routes: readonly NavigationRoute[], concrete: () => Promise<ReadonlyMap<string, NavigationRoute>>): {
+    navigation: (query?: NavigationQuery) => Promise<readonly NavigationItem[]>;
+    navigationTree: (query?: NavigationQuery) => Promise<readonly NavigationNode[]>;
+    breadcrumbs: (query?: NavigationQuery) => Promise<readonly NavigationItem[]>;
+    pager: (query?: NavigationQuery) => Promise<PagerLinks>;
+};
+export type Navigation = ReturnType<typeof createNavigation>;
+/** A page or layout, ready to render: its component, head metadata, and loader. */
+export interface RenderLayer {
+    readonly definition: ComponentDefinition;
+    readonly metadata: HeadSource;
+    readonly module: () => Promise<ServerModule>;
+    /** What diagnostics name: the loader file, or the component when a plugin supplies the loader module. */
+    readonly origin: string;
+}
+export interface RenderInput {
+    readonly base: string;
+    readonly route: NavigationRoute;
+    readonly params: Params;
+    readonly url: URL;
+    /** The request a server-rendered page answers; prerendering has none. */
+    readonly request?: Request;
+    readonly signal: AbortSignal;
+    readonly layers: readonly RenderLayer[];
+    /** Every component the layers use, for HTML Next's renderer. */
+    readonly definitions: readonly ComponentDefinition[];
+    readonly scripts: readonly string[];
+    readonly navigation: Navigation;
+    /** What starts an alias page's canonical link: the configured origin, or "" without one. */
+    readonly canonicalOrigin: string;
+    /** For the error page: the failure, whose fields it takes as the props it declares. */
+    readonly failure?: Failure;
+}
+/** What app/error.html receives: the status and its standard reason phrase, never the error itself. */
+export interface Failure {
+    readonly status: 500;
+    readonly message: string;
+}
+export declare const serverFailure: Failure;
+/** The page for a failure without app/error.html, or when it fails too. */
+export declare function failurePage({ status, message }: Failure, scripts: readonly string[]): {
+    status: 500;
+    head: RenderedHead;
+    body: string;
+    html: string;
+};
+export type Rendered = {
+    readonly kind: "page";
+    readonly status: number;
+    readonly headers: Headers;
+    readonly body: string;
+    readonly css: string;
+    readonly head: RenderedHead;
+    readonly layers: readonly RenderedLayer[];
+} | {
+    readonly kind: "redirect";
+    readonly status: RedirectStatus;
+    readonly location: string;
+    readonly headers: Headers;
+} | {
+    readonly kind: "notFound";
+    readonly headers: Headers;
+};
+/** Run the layers' loaders, outermost first, and render their invocations through HTML Next. */
+export declare function renderRoute(input: RenderInput): Promise<Rendered>;
+/** A page's answer: a redirect with its redirect page, its document, or for a payload request its payload (404 when it has none). */
+export declare function pageResponse(page: {
+    readonly status: number;
+    readonly location?: string;
+    readonly body: string;
+    readonly head: RenderedHead;
+    readonly layers: readonly RenderedLayer[];
+    readonly headers?: Headers;
+}, request: Request, payload: boolean, assets?: PageAssets): Response;
+/** How an application answers requests: its routes and endpoints, and how it answers a page. */
+export interface Pipeline<Route extends NavigationRoute> {
+    readonly base: string;
+    /** Redirects by deployment pathname with a trailing slash. */
+    readonly redirects: ReadonlyMap<string, {
+        readonly location: string;
+        readonly status: RedirectStatus;
+    }>;
+    readonly routes: readonly Route[];
+    readonly endpoints: readonly EndpointRoute[];
+    endpoint(route: EndpointRoute): Promise<EndpointModule>;
+    readonly middleware?: () => Promise<Middleware>;
+    /** A matched page's document or payload. */
+    page(route: Route, params: Params, request: Request, payload: boolean): Promise<Response>;
+    /** A path no page or endpoint answers. */
+    notFound(request: Request, payload: boolean): Promise<Response>;
+}
+/** Answer a request: its payload URL becomes the page's, then middleware, then redirects, endpoints, and pages. */
+export declare function respond<Route extends NavigationRoute>(app: Pipeline<Route>, request: Request): Promise<Response>;
+/** A build's request server data, which the build writes into _htmlkit/server/entry.js. */
+export interface ServerData {
+    readonly version: 1;
+    readonly base: string;
+    readonly redirects: readonly ManifestRedirect[];
+    readonly routes: readonly NavigationRoute[];
+    /** Each concrete page URL and its route's index, for navigation. */
+    readonly catalog: readonly (readonly [string, number])[];
+    readonly scripts: readonly string[];
+    /** What starts an alias page's canonical link: the configured origin, or "" without one. */
+    readonly canonicalOrigin: string;
+    /** Each server-rendered route, by its index in routes. */
+    readonly pages: Readonly<Record<string, ServerPage>>;
+    /** app/error.html, which answers a failed request, when anything renders on request. */
+    readonly error?: ServerPage & {
+        readonly route: NavigationRoute;
+    };
+    readonly endpoints: readonly (EndpointRoute & {
+        readonly module: string;
+    })[];
+    readonly middleware?: string;
+}
+/** A route the server renders: each layer's component, head metadata, and loader module, every component they use, and their browser delivery. */
+export interface ServerPage {
+    readonly layers: readonly {
+        readonly definition: ComponentDefinition;
+        readonly metadata: HeadSource;
+        readonly module?: string;
+        readonly origin: string;
+    }[];
+    readonly definitions: readonly ComponentDefinition[];
+    readonly assets: PageAssets;
+}
+export declare const mime: Readonly<Record<string, string>>;
+/**
+ * What a path names in a build's output: a file, a directory's index.html (page), a directory without its
+ * trailing slash ("slash"), an undecodable path ("invalid"), or nothing. Nothing outside the output resolves.
+ */
+export declare function outputPath(output: string, base: string, pathname: string): Promise<{
+    readonly file: string;
+    readonly page: boolean;
+} | "slash" | "invalid" | undefined>;
+/**
+ * The application a build's server entry exports: data and module loaders the build wrote, and the
+ * output directory two levels above the entry. Prerendered pages and assets come from the output's files.
+ */
+export declare function serverApplication(entry: string, data: ServerData, modules: Readonly<Record<string, () => Promise<unknown>>>): Promise<ServerApplication>;
+/** A native Request for a Node request: its method, URL, headers, and body, aborted when the response closes. */
+export declare function nodeRequest(incoming: IncomingMessage, outgoing: ServerResponse): Request;
+/** Write a Response to a Node response, streaming its body. */
+export declare function sendResponse(response: Response, outgoing: ServerResponse): Promise<void>;
+export declare function listen(server: Server, options: {
+    readonly host?: string;
+    readonly port?: number;
+}, base: string): Promise<ApplicationServer>;
+/** Serve a build's server entry on Node: `htmlkit start`. */
+export declare function startApplication(options?: StartOptions): Promise<ApplicationServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoC,KAAK,eAAe,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAOrH,OAAO,EAA4C,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAI1G,OAAO,EAAuD,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AACrG,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAGpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAA6B,gBAAgB,EAAE,UAAU,EAAE,cAAc,EACvJ,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1K,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEnJ,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC;AACzF,KAAK,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;AAEnD,iHAAiH;AACjH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,eAAe,EAAE,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;yBAoB7G,eAAe,KAAQ,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC;6BA4CrD,eAAe,KAAQ,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC;0BAjB5D,eAAe,KAAQ,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC;oBAwD/D,eAAe,KAAQ,OAAO,CAAC,UAAU,CAAC;EAOvE;AACD,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AA+C7D,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7C,yGAAyG;IACzG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AACD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,uFAAuF;IACvF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AACD,uGAAuG;AACvG,MAAM,WAAW,OAAO;IAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC3E,eAAO,MAAM,aAAa,EAAE,OAA0E,CAAC;AACvG,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE;;;;;EAInF;AACD,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,GAClM;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACpH;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAE7D,gGAAgG;AAChG,wBAAsB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2EvE;AAiBD,qIAAqI;AACrI,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC3I,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAE,UAAwC,GAAG,QAAQ,CAezK;AAED,gGAAgG;AAChG,MAAM,WAAW,QAAQ,CAAC,KAAK,SAAS,eAAe;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IACxG,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAChD,4CAA4C;IAC5C,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1F,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACjE;AAID,mHAAmH;AACnH,wBAAsB,OAAO,CAAC,KAAK,SAAS,eAAe,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsBtH;AAoCD,2FAA2F;AAC3F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;IACzD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IACrD,wFAAwF;IACxF,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;KAAE,CAAC;IAClE,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,aAAa,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAC;IAC7E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AACD,kJAAkJ;AAClJ,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3J,QAAQ,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,eAAO,MAAM,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGrB,CAAC;AAE9B;;;GAGG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC,CAqB7K;AAGD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8E9J;AAED,iHAAiH;AACjH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAWxF;AAED,+DAA+D;AAC/D,wBAAsB,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAS9F;AAED,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAOlJ;AAED,6DAA6D;AAC7D,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmB7F"}