htmx-router 2.0.2 → 2.0.4

package/internal/request/server.d.ts

@@ -5,6 +5,8 @@ export type Config = {
     build: () => Promise<RouterModule> | Promise<RouterModule>;
     render: GenericContext["render"];
     viteDevServer: ViteDevServer | null;
+    poweredBy?: boolean;
+    timers?: boolean;
 };
 type ServerBindType = "pre" | "post";
 type ServerBind = (ctx: GenericContext) => Promise<Response | null> | Response | null;
@@ -13,6 +15,8 @@ export declare class HtmxRouterServer {
     readonly vite: Config["viteDevServer"];
     readonly render: Config["render"];
     readonly build: Config["build"];
+    readonly poweredBy: boolean;
+    readonly timers: boolean;
     constructor(config: Config);
     /**
      * Add a middleware to resolve requests before/after the route tree attempts to resolve

package/internal/request/server.js

@@ -19,9 +19,13 @@ export class HtmxRouterServer {
     vite;
     render;
     build;
+    poweredBy;
+    timers;
     #binding;
     constructor(config) {
         this.vite = config.viteDevServer;
+        this.poweredBy = config.poweredBy === undefined ? true : config.poweredBy;
+        this.timers = config.timers === undefined ? !!config.viteDevServer : config.timers;
         this.render = config.render;
         this.build = config.build;
         this.#binding = {
@@ -49,22 +53,22 @@ export class HtmxRouterServer {
     }
     async resolve(request, resolve404 = true) {
         const url = new URL(request.url);
-        const ctx = new GenericContext(request, url, this.render);
+        const ctx = new GenericContext(request, url, this);
         { // pre-binding
             const res = await this.#applyBindings("pre", ctx);
             if (res)
-                return res;
+                return ctx.finalize(res);
         }
         const tree = await this.#getTree();
         { // route
             const res = await this.#resolveRoute(ctx, tree);
             if (res)
-                return res;
+                return ctx.finalize(res);
         }
         { // post-binding
             const res = await this.#applyBindings("post", ctx);
             if (res)
-                return res;
+                return ctx.finalize(res);
         }
         if (resolve404)
             return await this.error(ctx, undefined);
@@ -79,9 +83,10 @@ export class HtmxRouterServer {
         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);
+            ctx = new GenericContext(ctx, new URL(ctx.url), this);
         const tree = await this.#getTree();
-        return await tree.unwrap(ctx, e);
+        const res = await tree.unwrap(ctx, e);
+        return ctx.finalize(res);
     }
     /**
      * Create a closure for use with the classic express.js like servers

package/internal/router.d.ts

@@ -1,17 +1,22 @@
+import type { HtmxRouterServer } from "./request/server.js";
 import { ParameterShaper } from '../util/parameters.js';
 import { RouteContext } from "../router.js";
+import { RequestTimer } from "../timer.js";
 import { Cookies } from '../cookies.js';
 type Rendered = Response | BodyInit;
 export declare class GenericContext {
+    #private;
     request: Request;
     headers: Headers;
     cookie: Cookies;
     params: {
         [key: string]: string;
     };
+    timer: RequestTimer;
     url: URL;
-    render: (res: JSX.Element, headers: Headers) => Promise<Rendered> | Rendered;
-    constructor(request: GenericContext["request"], url: GenericContext["url"], renderer: GenericContext["render"]);
+    constructor(request: GenericContext["request"], url: GenericContext["url"], scope: HtmxRouterServer);
+    render(res: JSX.Element, headers: Headers): Promise<Rendered> | Rendered;
+    finalize(res: Response): Response;
     shape<T extends ParameterShaper>(shape: T, path: string): RouteContext<T>;
 }
 export {};

package/internal/router.js

@@ -1,24 +1,37 @@
 import { ServerOnlyWarning } from "./util.js";
 ServerOnlyWarning("internal/router");
 import { RouteContext } from "../router.js";
+import { RequestTimer } from "../timer.js";
 import { Cookies } from '../cookies.js';
 export class GenericContext {
     request;
     headers; // response headers
     cookie;
     params;
+    timer;
     url;
-    render;
-    constructor(request, url, renderer) {
+    #server;
+    constructor(request, url, scope) {
+        this.#server = scope;
         this.cookie = new Cookies(request.headers.get("cookie"));
         this.headers = new Headers();
         this.request = request;
         this.params = {};
         this.url = url;
-        this.render = renderer;
+        this.timer = new RequestTimer(scope.timers);
+        if (scope.poweredBy)
+            this.headers.set("X-Powered-By", "htmx-router");
         this.headers.set("x-powered-by", "htmx-router");
         this.headers.set("content-type", "text/html");
     }
+    render(res, headers) {
+        this.timer.checkpoint("render");
+        return this.#server.render(res, headers);
+    }
+    finalize(res) {
+        this.timer.writeTo(res.headers);
+        return res;
+    }
     shape(shape, path) {
         return new RouteContext(this, this.params, shape, path);
     }

package/package.json

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

package/response.js

@@ -1,55 +1,60 @@
 export function text(text, init) {
-    init ||= {};
-    init.statusText ||= "ok";
-    init.status ||= 200;
+    init = FillResponseInit(200, "Ok", init);
     const res = new Response(text, init);
     res.headers.set("Content-Type", "text/plain");
     res.headers.set("X-Caught", "true");
     return res;
 }
 export function html(text, init) {
-    init ||= {};
-    init.statusText ||= "ok";
-    init.status ||= 200;
+    init = FillResponseInit(200, "Ok", init);
     const res = new Response(text, init);
     res.headers.set("Content-Type", "text/html; charset=UTF-8");
     res.headers.set("X-Caught", "true");
     return res;
 }
 export function json(data, init) {
-    init ||= {};
-    init.statusText ||= "ok";
-    init.status ||= 200;
+    init = FillResponseInit(200, "Ok", init);
     const res = new Response(JSON.stringify(data), init);
     res.headers.set("Content-Type", "application/json");
     res.headers.set("X-Caught", "true");
     return res;
 }
 export function redirect(url, init) {
-    init ||= {};
-    init.statusText ||= "Temporary Redirect";
-    init.status ||= 307;
+    init = FillResponseInit(307, "Temporary Redirect", init);
     const res = new Response("", init);
     if (!init?.clientOnly)
         res.headers.set("Location", url);
     res.headers.set("HX-Location", url); // use hx-boost if applicable
+    res.headers.set("X-Caught", "true");
     return res;
 }
 export function revalidate(init) {
-    init ||= {};
-    init.statusText ||= "ok";
-    init.status ||= 200;
+    init = FillResponseInit(200, "Ok", init);
     const res = new Response("", init);
     res.headers.set("HX-Location", "");
+    res.headers.set("HX-Replace-Url", "");
+    res.headers.set("X-Caught", "true");
     return res;
 }
 export function refresh(init) {
-    init ||= {};
-    init.statusText ||= "ok";
-    init.status ||= 200;
+    init = FillResponseInit(200, "Ok", init);
     const res = new Response("", init);
     if (!init?.clientOnly)
         res.headers.set("Refresh", "0"); // fallback
     res.headers.set("HX-Refresh", "true");
+    res.headers.set("X-Caught", "true");
     return res;
 }
+/**
+ * This is to fix issues with deno
+ * When you try and change the statusText on a Response object
+ */
+function FillResponseInit(status, statusText, init) {
+    if (init === undefined)
+        init = {};
+    if (init.statusText === undefined)
+        init.statusText = statusText;
+    if (init.status === undefined)
+        init.status = status;
+    return init;
+}

package/router.d.ts

@@ -1,4 +1,5 @@
 import type { GenericContext } from "./internal/router.js";
+import type { RequestTimer } from "./timer.js";
 import { Parameterized, ParameterPrelude, ParameterShaper } from './util/parameters.js';
 import { RouteModule } from "./index.js";
 import { Cookies } from './cookies.js';
@@ -13,6 +14,7 @@ export declare class RouteContext<T extends ParameterShaper = {}> {
     readonly cookie: Cookies;
     readonly params: Parameterized<T>;
     readonly url: URL;
+    readonly timer: RequestTimer;
     render: GenericContext["render"];
     constructor(base: GenericContext | RouteContext, params: ParameterPrelude<T>, shape: T, path: string);
 }

package/router.js

@@ -36,6 +36,7 @@ export class RouteContext {
     cookie;
     params;
     url;
+    timer;
     render;
     constructor(base, params, shape, path) {
         this.path = path;
@@ -43,6 +44,7 @@ export class RouteContext {
         this.headers = base.headers;
         this.request = base.request;
         this.render = base.render;
+        this.timer = base.timer;
         this.url = base.url;
         this.params = {};
         for (const key in shape) {

package/timer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tracks timing checkpoints during request processing and writes performance
+ * metrics to HTTP response headers.
+ *
+ * **HTTP Headers Generated:**
+ * - `X-Time-Total`: Total request processing time in milliseconds
+ * - `X-Time-{name}`: Duration for each checkpoint in milliseconds
+ *
+ * **Default Checkpoints:**
+ * - `route`: Automatically created when timer is enabled (marks start of request)
+ * - `render`: Automatically triggered when JSX gets rendered to a string
+ */
+export declare class RequestTimer {
+    #private;
+    constructor(enabled: boolean);
+    /**
+     * Creates a timing checkpoint with the given name.
+     *
+     * Each checkpoint measures the time elapsed since the previous checkpoint.
+     * The resulting duration is written to the `X-Time-{name}` HTTP header.
+     *
+     * **Common Usage Pattern:**
+     * ```ts
+     * timer.checkpoint("auth");        // -> X-Time-auth: time from auth to fetch
+     * timer.checkpoint("fetch");       // -> X-Time-auth: time from fetch to transform
+     * timer.checkpoint("transform");   // -> X-Time-fetch: time from transform to render
+     * // render checkpoint added automatically during JSX rendering
+     * //                              // -> X-Time-render: time from render to response
+     * ```
+     *
+     * @param name - The name of the checkpoint (used in the HTTP header)
+     *
+     * @example
+     * ```ts
+     * export async function loader({ timer }: RouteContext) {
+     *   timer.checkpoint("auth");
+     *   await authenticate();
+     *
+     *   timer.checkpoint("fetch");
+     *   const data = await fetchData();
+     *
+     *   return json(data);
+     * }
+     * ```
+     */
+    checkpoint(name: string): void;
+    writeTo(headers: Headers): void;
+}

package/timer.js

@@ -0,0 +1,83 @@
+/**
+ * Tracks timing checkpoints during request processing and writes performance
+ * metrics to HTTP response headers.
+ *
+ * **HTTP Headers Generated:**
+ * - `X-Time-Total`: Total request processing time in milliseconds
+ * - `X-Time-{name}`: Duration for each checkpoint in milliseconds
+ *
+ * **Default Checkpoints:**
+ * - `route`: Automatically created when timer is enabled (marks start of request)
+ * - `render`: Automatically triggered when JSX gets rendered to a string
+ */
+export class RequestTimer {
+    #checkpoints;
+    constructor(enabled) {
+        if (!enabled) {
+            this.#checkpoints = null;
+            return;
+        }
+        this.#checkpoints = [];
+        this.checkpoint("route");
+    }
+    /**
+     * Creates a timing checkpoint with the given name.
+     *
+     * Each checkpoint measures the time elapsed since the previous checkpoint.
+     * The resulting duration is written to the `X-Time-{name}` HTTP header.
+     *
+     * **Common Usage Pattern:**
+     * ```ts
+     * timer.checkpoint("auth");        // -> X-Time-auth: time from auth to fetch
+     * timer.checkpoint("fetch");       // -> X-Time-auth: time from fetch to transform
+     * timer.checkpoint("transform");   // -> X-Time-fetch: time from transform to render
+     * // render checkpoint added automatically during JSX rendering
+     * //                              // -> X-Time-render: time from render to response
+     * ```
+     *
+     * @param name - The name of the checkpoint (used in the HTTP header)
+     *
+     * @example
+     * ```ts
+     * export async function loader({ timer }: RouteContext) {
+     *   timer.checkpoint("auth");
+     *   await authenticate();
+     *
+     *   timer.checkpoint("fetch");
+     *   const data = await fetchData();
+     *
+     *   return json(data);
+     * }
+     * ```
+     */
+    checkpoint(name) {
+        if (this.#checkpoints === null)
+            return;
+        this.#checkpoints.push(new Checkpoint(name));
+    }
+    writeTo(headers) {
+        if (this.#checkpoints === null)
+            return;
+        if (this.#checkpoints.length < 1)
+            return;
+        const end = Date.now();
+        const first = this.#checkpoints[0];
+        headers.set(`X-Time-Total`, String(end - first.time));
+        const limit = this.#checkpoints.length - 1;
+        for (let i = 0; i < limit; i++) {
+            const c = this.#checkpoints[i];
+            const n = this.#checkpoints[i + 1];
+            headers.set(`X-Time-${c.name}`, String(n.time - c.time));
+        }
+        const last = this.#checkpoints[limit];
+        headers.set(`X-Time-${last.name}`, String(end - last.time));
+    }
+}
+class Checkpoint {
+    time;
+    name;
+    constructor(name) {
+        this.time = Date.now();
+        this.name = name;
+    }
+}