htmx-router 1.0.17 → 2.0.0

package/index.d.ts

@@ -1,6 +1,5 @@
 import type { ParameterShaper } from "./util/parameters.js";
 import type { RouteContext } from "./router.js";
-import { createRequestHandler } from "./internal/request/index.js";
 export type RenderFunction<T extends ParameterShaper = {}> = (ctx: RouteContext<T>) => Promise<Response | JSX.Element | null>;
 export type CatchFunction<T extends ParameterShaper = {}> = (ctx: RouteContext<T>, err: unknown) => Promise<Response | JSX.Element>;
 export type RouteModule<T extends ParameterShaper> = {
@@ -16,4 +15,4 @@ export type ClientIslandManifest<T> = {
 type ClientIsland<T> = T extends (props: infer P) => JSX.Element ? (props: P & {
     children?: JSX.Element;
 }) => JSX.Element : T;
-export { createRequestHandler, RouteContext };
+export { RouteContext };

package/index.js

@@ -1,2 +1 @@
-import { createRequestHandler } from "./internal/request/index.js";
-export { createRequestHandler };
+export {};

package/internal/request/compatibility/node.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { HtmxRouterServer } from "../server.js";
+export declare function NodeAdaptor(server: HtmxRouterServer, resolve404: boolean): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/internal/request/compatibility/node.js

@@ -0,0 +1,54 @@
+export function NodeAdaptor(server, resolve404) {
+    return async (req, res) => {
+        const request = CreateRequest(req);
+        const response = await server.resolve(request, resolve404);
+        if (response === null)
+            return;
+        ConsumeResponse(res, response);
+    };
+}
+function CreateRequest(req) {
+    const ctrl = new AbortController();
+    const headers = new Headers(req.headers);
+    const url = new URL(`http://${headers.get('host')}${req.originalUrl || req.url}`);
+    req.once('aborted', () => ctrl.abort());
+    const bodied = req.method !== "GET" && req.method !== "HEAD";
+    const request = new Request(url, {
+        headers,
+        method: req.method,
+        body: bodied ? req : undefined,
+        signal: ctrl.signal,
+        referrer: headers.get("referrer") || undefined,
+        // @ts-ignore
+        duplex: bodied ? 'half' : undefined
+    });
+    if (!request.headers.has("X-Real-IP")) {
+        const info = req.socket.address();
+        if ("address" in info)
+            request.headers.set("X-Real-IP", info.address);
+    }
+    return request;
+}
+async function ConsumeResponse(into, response) {
+    const headers = Object.fromEntries(response.headers);
+    { // handle multi-cookie setting
+        const cookies = response.headers.getSetCookie();
+        if (cookies.length > 0)
+            headers["set-cookie"] = cookies;
+    }
+    into.writeHead(response.status, headers);
+    if (response.body instanceof ReadableStream) {
+        const reader = response.body.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            into.write(value);
+        }
+        into.end();
+    }
+    else {
+        const rendered = await response.text();
+        into.end(rendered);
+    }
+}

package/internal/request/compatibility/vite/connectToWeb.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export { connectToWeb };
+import { GenericContext } from '../../../router.js';
+type NextFunction = (err?: unknown) => void;
+type ConnectMiddleware<PlatformRequest extends IncomingMessage = IncomingMessage, PlatformResponse extends ServerResponse = ServerResponse> = (req: PlatformRequest, res: PlatformResponse, next: NextFunction) => void;
+type WebHandler = (ctx: GenericContext) => Promise<Response | null>;
+/**
+ * Converts a Connect-style middleware to a web-compatible request handler.
+ *
+ * @param {ConnectMiddleware} handler - The Connect-style middleware function to be converted.
+ * @returns {WebHandler} A function that handles web requests and returns a Response or undefined.
+ */
+declare function connectToWeb(handler: ConnectMiddleware): WebHandler;

package/internal/request/compatibility/vite/connectToWeb.js

@@ -0,0 +1,59 @@
+import { Readable } from 'node:stream';
+export { connectToWeb };
+import { createServerResponse } from './createServerResponse.js';
+import { flattenHeaders } from './header-utils.js';
+const statusCodesWithoutBody = [
+    100, // Continue
+    101, // Switching Protocols
+    102, // Processing (WebDAV)
+    103, // Early Hints
+    204, // No Content
+    205, // Reset Content
+    304, // Not Modified
+];
+/**
+ * Converts a Connect-style middleware to a web-compatible request handler.
+ *
+ * @param {ConnectMiddleware} handler - The Connect-style middleware function to be converted.
+ * @returns {WebHandler} A function that handles web requests and returns a Response or undefined.
+ */
+function connectToWeb(handler) {
+    return async (ctx) => {
+        const req = createIncomingMessage(ctx.request);
+        const { res, onReadable } = createServerResponse(req);
+        return new Promise((resolve, reject) => {
+            onReadable(({ readable, headers, statusCode }) => {
+                const responseBody = statusCodesWithoutBody.includes(statusCode)
+                    ? null
+                    : Readable.toWeb(readable);
+                resolve(new Response(responseBody, {
+                    status: statusCode,
+                    headers: flattenHeaders(headers)
+                }));
+            });
+            const next = (error) => {
+                if (error)
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                else
+                    resolve(null);
+            };
+            Promise.resolve(handler(req, res, next)).catch(next);
+        });
+    };
+}
+/**
+ * Creates an IncomingMessage object from a web Request.
+ *
+ * @param {Request} request - The web Request object.
+ * @returns {IncomingMessage} An IncomingMessage-like object compatible with Node.js HTTP module.
+ */
+function createIncomingMessage(request) {
+    const parsedUrl = new URL(request.url, 'http://localhost');
+    const pathnameAndQuery = (parsedUrl.pathname || '') + (parsedUrl.search || '');
+    const body = request.body ? Readable.fromWeb(request.body) : Readable.from([]);
+    return Object.assign(body, {
+        url: pathnameAndQuery,
+        method: request.method,
+        headers: Object.fromEntries(request.headers)
+    });
+}

package/internal/request/compatibility/vite/createServerResponse.d.ts

@@ -0,0 +1,24 @@
+export { createServerResponse };
+import { ServerResponse, type IncomingMessage, type OutgoingHttpHeaders } from 'node:http';
+import { Readable } from 'node:stream';
+/**
+ * Creates a custom ServerResponse object that allows for intercepting and streaming the response.
+ *
+ * @param {IncomingMessage} incomingMessage - The incoming HTTP request message.
+ * @returns {{
+ *   res: ServerResponse;
+ *   onReadable: (cb: (result: { readable: Readable; headers: OutgoingHttpHeaders; statusCode: number }) => void) => void
+ * }}
+ * An object containing:
+ *   - res: The custom ServerResponse object.
+ *   - onReadable: A function that takes a callback. The callback is invoked when the response is readable,
+ *     providing an object with the readable stream, headers, and status code.
+ */
+declare function createServerResponse(incomingMessage: IncomingMessage): {
+    res: ServerResponse<IncomingMessage>;
+    onReadable: (cb: (result: {
+        readable: Readable;
+        headers: OutgoingHttpHeaders;
+        statusCode: number;
+    }) => void) => void;
+};

package/internal/request/compatibility/vite/createServerResponse.js

@@ -0,0 +1,63 @@
+// Taken From: https://github.com/vikejs/vike-server/blob/7bcb7805fa39ef945adc73f4faf5c89a81f3f7ec/packages/vike-node/src/runtime/adapters/createServerResponse.ts
+export { createServerResponse };
+import { ServerResponse } from 'node:http';
+import { PassThrough, Readable } from 'node:stream';
+/**
+ * Creates a custom ServerResponse object that allows for intercepting and streaming the response.
+ *
+ * @param {IncomingMessage} incomingMessage - The incoming HTTP request message.
+ * @returns {{
+ *   res: ServerResponse;
+ *   onReadable: (cb: (result: { readable: Readable; headers: OutgoingHttpHeaders; statusCode: number }) => void) => void
+ * }}
+ * An object containing:
+ *   - res: The custom ServerResponse object.
+ *   - onReadable: A function that takes a callback. The callback is invoked when the response is readable,
+ *     providing an object with the readable stream, headers, and status code.
+ */
+function createServerResponse(incomingMessage) {
+    const res = new ServerResponse(incomingMessage);
+    const passThrough = new PassThrough();
+    let handled = false;
+    const onReadable = (cb) => {
+        const handleReadable = () => {
+            if (handled)
+                return;
+            handled = true;
+            cb({ readable: Readable.from(passThrough), headers: res.getHeaders(), statusCode: res.statusCode });
+        };
+        passThrough.once('readable', handleReadable);
+        passThrough.once('end', handleReadable);
+    };
+    passThrough.once('finish', () => {
+        res.emit('finish');
+    });
+    passThrough.once('close', () => {
+        res.destroy();
+        res.emit('close');
+    });
+    passThrough.on('drain', () => {
+        res.emit('drain');
+    });
+    res.write = passThrough.write.bind(passThrough);
+    res.end = passThrough.end.bind(passThrough);
+    res.writeHead = function writeHead(statusCode, statusMessage, headers) {
+        res.statusCode = statusCode;
+        if (typeof statusMessage === 'object') {
+            headers = statusMessage;
+            statusMessage = undefined;
+        }
+        if (headers) {
+            Object.entries(headers).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    res.setHeader(key, value);
+                }
+            });
+        }
+        return res;
+    };
+    return {
+        res,
+        onReadable
+    };
+}

package/internal/request/compatibility/vite/header-utils.d.ts

@@ -0,0 +1,6 @@
+export { flattenHeaders, groupHeaders, parseHeaders };
+import type { OutgoingHttpHeaders } from 'node:http';
+type HeadersProvided = Record<string, string | string[] | undefined> | Headers;
+declare function groupHeaders(headers: [string, string][]): [string, string | string[]][];
+declare function flattenHeaders(headers: OutgoingHttpHeaders): [string, string][];
+declare function parseHeaders(headers: HeadersProvided): [string, string][];

package/internal/request/compatibility/vite/header-utils.js

@@ -0,0 +1,70 @@
+// Taken From: https://github.com/vikejs/vike-server/blob/7bcb7805fa39ef945adc73f4faf5c89a81f3f7ec/packages/vike-node/src/runtime/utils/header-utils.ts
+export { flattenHeaders, groupHeaders, parseHeaders };
+function groupHeaders(headers) {
+    const grouped = {};
+    headers.forEach(([key, value]) => {
+        if (grouped[key]) {
+            // If the key already exists, append the new value
+            if (Array.isArray(grouped[key])) {
+                ;
+                grouped[key].push(value);
+            }
+            else {
+                grouped[key] = [grouped[key], value];
+            }
+        }
+        else {
+            // If the key doesn't exist, add it to the object
+            grouped[key] = value;
+        }
+    });
+    // Convert the object back to an array
+    return Object.entries(grouped);
+}
+function flattenHeaders(headers) {
+    const flatHeaders = [];
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((v) => {
+                if (v != null) {
+                    flatHeaders.push([key, String(v)]);
+                }
+            });
+        }
+        else {
+            flatHeaders.push([key, String(value)]);
+        }
+    }
+    return flatHeaders;
+}
+function parseHeaders(headers) {
+    const result = [];
+    if (typeof headers.forEach === 'function') {
+        headers.forEach((value, key) => {
+            if (Array.isArray(value)) {
+                value.forEach((value_) => {
+                    result.push([key, value_]);
+                });
+            }
+            else {
+                result.push([key, value]);
+            }
+        });
+    }
+    else {
+        for (const [key, value] of Object.entries(headers)) {
+            if (Array.isArray(value)) {
+                value.forEach((value_) => {
+                    result.push([key, value_]);
+                });
+            }
+            else {
+                result.push([key, value]);
+            }
+        }
+    }
+    return result;
+}

package/internal/request/http.d.ts

@@ -6,5 +6,8 @@ type Config = {
     viteDevServer: ViteDevServer | null;
     render: GenericContext["render"];
 };
+/**
+ * @deprecated
+ */
 export declare function createRequestHandler(config: Config): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
 export {};

package/internal/request/http.js

@@ -1,11 +1,15 @@
 import { ServerOnlyWarning } from "../util.js";
 ServerOnlyWarning("http-request");
+import { CreateRequest } from "./compatibility/node.js";
 import { Resolve } from "./native.js";
+/**
+ * @deprecated
+ */
 export function createRequestHandler(config) {
     return async (req, res) => {
         try {
             const mod = typeof config.build === "function" ? await config.build() : await config.build;
-            const request = NativeRequest(req);
+            const request = CreateRequest(req);
             let { response, headers } = await Resolve(request, mod.tree, config);
             res.writeHead(response.status, headers);
             if (response.body instanceof ReadableStream) {
@@ -37,25 +41,3 @@ export function createRequestHandler(config) {
         }
     };
 }
-function NativeRequest(req) {
-    const ctrl = new AbortController();
-    const headers = new Headers(req.headers);
-    const url = new URL(`http://${headers.get('host')}${req.originalUrl || req.url}`);
-    req.once('aborted', () => ctrl.abort());
-    const bodied = req.method !== "GET" && req.method !== "HEAD";
-    const request = new Request(url, {
-        headers,
-        method: req.method,
-        body: bodied ? req : undefined,
-        signal: ctrl.signal,
-        referrer: headers.get("referrer") || undefined,
-        // @ts-ignore
-        duplex: bodied ? 'half' : undefined
-    });
-    if (!request.headers.has("X-Real-IP")) {
-        const info = req.socket.address();
-        if ("address" in info)
-            request.headers.set("X-Real-IP", info.address);
-    }
-    return request;
-}

package/internal/request/index.d.ts

@@ -1,17 +1,4 @@
-import type { ViteDevServer } from "vite";
-import type { GenericContext } from "../router.js";
 import type { RouteTree } from '../../router.js';
-import * as native from "./native.js";
-import * as http from "./http.js";
-export type Config = {
-    build: Promise<any> | (() => Promise<Record<string, any>>);
-    viteDevServer: ViteDevServer | null;
-    render: GenericContext["render"];
-};
 export type RouterModule = {
     tree: RouteTree;
 };
-export declare const createRequestHandler: {
-    http: typeof http.createRequestHandler;
-    native: typeof native.createRequestHandler;
-};

package/internal/request/index.js

@@ -1,8 +1,2 @@
 import { ServerOnlyWarning } from "../util.js";
 ServerOnlyWarning("request");
-import * as native from "./native.js";
-import * as http from "./http.js";
-export const createRequestHandler = {
-    http: http.createRequestHandler,
-    native: native.createRequestHandler
-};

package/internal/request/native.d.ts

@@ -1,11 +1,17 @@
 import type { Config } from './index.js';
 import type { RouteTree } from '../../router.js';
+/**
+ * @deprecated
+ */
 export declare function createRequestHandler(config: Config): (req: Request) => Promise<{
     response: Response;
     headers: {
         [key: string]: string | string[];
     };
 }>;
+/**
+ * @deprecated
+ */
 export declare function Resolve(request: Request, tree: RouteTree, config: Config): Promise<{
     response: Response;
     headers: {

package/internal/request/native.js

@@ -2,12 +2,18 @@ import { ServerOnlyWarning } from "../util.js";
 ServerOnlyWarning("native-request");
 import { GenericContext } from "../router.js";
 import { MakeStatus } from "../../status.js";
+/**
+ * @deprecated
+ */
 export function createRequestHandler(config) {
     return async (req) => {
         const mod = typeof config.build === "function" ? await config.build() : await config.build;
         return await Resolve(req, mod.tree, config);
     };
 }
+/**
+ * @deprecated
+ */
 export async function Resolve(request, tree, config) {
     const ctx = new GenericContext(request, new URL(request.url), config.render);
     let response;

package/internal/request/server.d.ts

@@ -0,0 +1,37 @@
+import type { ViteDevServer } from "vite";
+import { connectToWeb } from "./compatibility/vite/connectToWeb.js";
+import { GenericContext } from "../router.js";
+import { RouterModule } from "./index.js";
+export type Config = {
+    build: () => Promise<RouterModule> | Promise<RouterModule>;
+    render: GenericContext["render"];
+    viteDevServer: ViteDevServer | null;
+};
+type ServerBindType = "pre" | "post";
+type ServerBind = (ctx: GenericContext) => Promise<Response | null> | Response | null;
+export declare class HtmxRouterServer {
+    #private;
+    readonly vite: {
+        handler: ReturnType<typeof connectToWeb>;
+        server: Config["viteDevServer"];
+    } | null;
+    readonly render: Config["render"];
+    readonly build: Config["build"];
+    constructor(config: Config);
+    /**
+     * Add a middleware to resolve requests before/after the route tree attempts to resolve
+     */
+    use(type: ServerBindType, binding: ServerBind): void;
+    resolve<T extends boolean>(request: Request, resolve404?: T): Promise<T extends true ? Response : (Response | null)>;
+    /**
+     * Use the top level error handler in the route tree to render an error
+     * @param ctx The context the error came from
+     * @param e The error that caused it (if undefined, will be a 404 response)
+     */
+    error(ctx: Request | GenericContext, e: unknown | undefined): Promise<Response>;
+    /**
+     * Create a closure for use with the classic express.js like servers
+     */
+    nodeAdaptor(resolve404?: boolean): (req: import("http").IncomingMessage, res: import("http").ServerResponse) => Promise<void>;
+}
+export {};

package/internal/request/server.js

@@ -0,0 +1,144 @@
+import { ServerOnlyWarning } from "../util.js";
+ServerOnlyWarning("request/server");
+import { connectToWeb } from "./compatibility/vite/connectToWeb.js";
+import { GenericContext } from "../router.js";
+import { NodeAdaptor } from "./compatibility/node.js";
+import { MakeStatus } from "../../status.js";
+function UrlCleaner({ url }) {
+    const i = url.pathname.lastIndexOf("/");
+    if (i === 0)
+        return null;
+    if (i !== url.pathname.length - 1)
+        return null;
+    url.pathname = url.pathname.slice(0, -1);
+    return new Response("", MakeStatus("Permanent Redirect", {
+        headers: { location: url.toString() }
+    }));
+}
+export class HtmxRouterServer {
+    vite;
+    render;
+    build;
+    #binding;
+    constructor(config) {
+        this.vite = config.viteDevServer ? {
+            handler: connectToWeb(config.viteDevServer.middlewares),
+            server: config.viteDevServer
+        } : null;
+        this.render = config.render;
+        this.build = config.build;
+        this.#binding = {
+            pre: [UrlCleaner],
+            post: []
+        };
+        if (config.viteDevServer) {
+            const handler = connectToWeb(config.viteDevServer.middlewares);
+            this.#binding.post.push(handler);
+        }
+    }
+    /**
+     * Add a middleware to resolve requests before/after the route tree attempts to resolve
+     */
+    use(type, binding) {
+        if (type === "pre") {
+            this.#binding.pre.push(binding);
+            return;
+        }
+        if (type === "post") {
+            this.#binding.post.push(binding);
+            return;
+        }
+        throw new Error(`Unknown binding type "${type}"`);
+    }
+    async resolve(request, resolve404 = true) {
+        const url = new URL(request.url);
+        const ctx = new GenericContext(request, url, this.render);
+        { // pre-binding
+            const res = await this.#applyBindings("pre", ctx);
+            if (res)
+                return res;
+        }
+        const tree = await this.#getTree();
+        { // route
+            const res = await this.#resolveRoute(ctx, tree);
+            if (res)
+                return res;
+        }
+        { // post-binding
+            const res = await this.#applyBindings("post", ctx);
+            if (res)
+                return res;
+        }
+        if (resolve404)
+            return await this.error(ctx, undefined);
+        return null;
+    }
+    /**
+     * Use the top level error handler in the route tree to render an error
+     * @param ctx The context the error came from
+     * @param e The error that caused it (if undefined, will be a 404 response)
+     */
+    async error(ctx, e) {
+        if (e === undefined)
+            e = new Response("No Route", MakeStatus("Not Found"));
+        if (ctx instanceof Request)
+            ctx = new GenericContext(ctx, new URL(ctx.url), this.render);
+        const tree = await this.#getTree();
+        return await tree.unwrap(ctx, e);
+    }
+    /**
+     * Create a closure for use with the classic express.js like servers
+     */
+    nodeAdaptor(resolve404 = true) {
+        return NodeAdaptor(this, resolve404);
+    }
+    async #getTree() {
+        const mod = typeof this.build === "function" ? await this.build() : await this.build;
+        return mod.tree;
+    }
+    async #resolveRoute(ctx, tree) {
+        let response;
+        try {
+            const x = ctx.url.pathname.slice(1);
+            const fragments = x === "" ? [] : x.split("/");
+            const res = await tree.resolve(fragments, ctx);
+            if (res === null)
+                return null;
+            response = res;
+        }
+        catch (e) {
+            if (e instanceof Error)
+                this.vite?.server?.ssrFixStacktrace(e);
+            console.error(e);
+            response = await tree.unwrap(ctx, e);
+        }
+        // context merge headers if divergent
+        if (response.headers !== ctx.headers) {
+            for (const [key, value] of ctx.headers) {
+                if (key === "content-type")
+                    continue;
+                response.headers.set(key, value);
+            }
+        }
+        // merge in cookie changes
+        const cookies = ctx.cookie.export();
+        for (const cookie of cookies)
+            response.headers.append("Set-Cookie", cookie);
+        return response;
+    }
+    async #applyBindings(type, ctx) {
+        const set = this.#binding[type];
+        if (!set)
+            throw new Error(`Unknown binding type "${type}"`);
+        try {
+            for (const bind of set) {
+                const res = bind(ctx);
+                if (res)
+                    return res;
+            }
+        }
+        catch (e) {
+            return this.error(ctx.request, e);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "htmx-router",
-	"version": "1.0.17",
+	"version": "2.0.0",
 	"description": "A lightweight SSR framework with server+client islands",
 	"keywords": [
 		"htmx",

package/router.d.ts

@@ -30,7 +30,7 @@ export declare class RouteTree {
     private resolveNext;
     private resolveWild;
     private resolveSlug;
-    private unwrap;
+    unwrap(ctx: GenericContext, res: unknown): Promise<Response>;
 }
 declare class RouteLeaf {
     private module;

package/server.d.ts

@@ -0,0 +1,2 @@
+import { HtmxRouterServer, Config } from "./internal/request/server.js";
+export declare function createHtmxServer(config: Config): HtmxRouterServer;

package/server.js

@@ -0,0 +1,4 @@
+import { HtmxRouterServer } from "./internal/request/server.js";
+export function createHtmxServer(config) {
+    return new HtmxRouterServer(config);
+}

package/status.d.ts

@@ -67,8 +67,4 @@ type Definitions = typeof dictionary;
 export type StatusCode = keyof Definitions;
 export type StatusText = Definitions[StatusCode];
 export declare function MakeStatus(lookup: StatusCode | StatusText, init?: ResponseInit | Headers): ResponseInit;
-/**
- * @deprecated
- */
-export type Status = StatusCode;
 export {};

package/status.js

@@ -97,3 +97,4 @@ function SetStatus(into = {}, status, statusText) {
     into.status = status;
     return into;
 }
+;