htmx-router 2.0.5 → 2.1.1

package/dist/event-source.d.ts

@@ -0,0 +1,61 @@
+type Render = (jsx: JSX.Element) => string;
+/**
+ * Helper for Server-Sent-Events, with auto close on SIGTERM and SIGHUP messages
+ * Includes a keep alive empty packet sent every 30sec (because Chrome implodes at 120sec, and can be unreliable at 60sec)
+ */
+export declare class EventSource<JsxEnabled extends boolean = false> {
+    #private;
+    readonly response: Response;
+    readonly createdAt: number;
+    get updatedAt(): number;
+    readonly withCredentials: boolean;
+    readonly url: string;
+    get readyState(): number;
+    static CONNECTING: number;
+    static OPEN: number;
+    static CLOSED: number;
+    constructor(request: Request, render: JsxEnabled extends true ? Render : undefined);
+    isAborted(): boolean;
+    /**
+     * For internal use only
+     * @deprecated
+     */
+    _keepAlive(): boolean;
+    dispatch(type: string, data: JsxEnabled extends true ? (JSX.Element | string) : string): boolean;
+    close(unlink?: boolean): boolean;
+}
+export declare class EventSourceSet<JsxEnabled extends boolean = false> extends Set<EventSource<JsxEnabled>> {
+    /** Send update to all EventSources, auto closing failed dispatches */
+    dispatch(type: string, data: string): void;
+    /** Cull all closed connections */
+    cull(): void;
+    /** Close all connections */
+    closeAll(): void;
+}
+type SharedEventSourceCacheRule = {
+    limit: number;
+    ttl: number;
+} | {
+    limit?: number;
+    ttl: number;
+} | {
+    limit: number;
+    ttl?: number;
+};
+/**
+ * DO NOT USE: Experimental
+ * @deprecated
+ */
+export declare class SharedEventSource<JsxEnabled extends boolean = false> {
+    #private;
+    constructor(props: {
+        cache?: Record<string, SharedEventSourceCacheRule>;
+    } & (JsxEnabled extends true ? {
+        render: Render;
+    } : {}));
+    create(request: Request): EventSource<JsxEnabled>;
+    dispatch(type: string, data: JsxEnabled extends true ? (JSX.Element | string) : string): void;
+    isEmpty(): boolean;
+    close(): void;
+}
+export {};

package/{event-source.js → dist/event-source.js}

@@ -1,3 +1,4 @@
+var _a;
 import { ServerOnlyWarning } from "./internal/util.js";
 ServerOnlyWarning("event-source");
 // global for easy reuse
@@ -18,8 +19,8 @@ const headers = {
 export class EventSource {
     #controller;
     #signal;
-    #timer;
     #state;
+    #render;
     response;
     // activity timestamps, in unix time for minimal storage
     // since most use cases won't need the Date object anyway
@@ -34,26 +35,26 @@ export class EventSource {
     static CONNECTING = 0;
     static OPEN = 1;
     static CLOSED = 2;
-    constructor(request, keepAlive = 30_000) {
+    constructor(request, render) {
         this.#controller = null;
-        this.#state = EventSource.CONNECTING;
+        this.#state = _a.CONNECTING;
+        this.#render = render;
         this.withCredentials = request.mode === "cors";
         this.url = request.url;
         this.createdAt = Date.now();
         this.#updatedAt = 0;
         // immediate prepare for abortion
-        const cancel = () => { this.close(); request.signal.removeEventListener("abort", cancel); };
-        request.signal.addEventListener('abort', cancel);
         this.#signal = request.signal;
-        const start = (c) => { this.#controller = c; this.#state = EventSource.OPEN; };
+        const cancel = () => { this.close(); this.#signal.removeEventListener("abort", cancel); };
+        this.#signal.addEventListener('abort', cancel);
+        const start = (c) => { this.#controller = c; this.#state = _a.OPEN; };
         const stream = new ReadableStream({ start, cancel }, { highWaterMark: 0 });
         this.response = new Response(stream, { headers });
-        this.#timer = setInterval(() => this.keepAlive(), keepAlive);
-        register.add(this);
+        keepAlive.add(this);
     }
     isAborted() { return this.#signal.aborted; }
-    sendBytes(chunk, active) {
-        if (this.#state === EventSource.CLOSED) {
+    #sendBytes(chunk, active) {
+        if (this.#state === _a.CLOSED) {
             const err = new Error(`Warn: Attempted to send data on closed stream for: ${this.url}`);
             console.warn(err);
         }
@@ -75,14 +76,26 @@ export class EventSource {
             return false;
         }
     }
-    sendText(chunk, simulated) {
-        return this.sendBytes(encoder.encode(chunk), simulated);
+    #sendText(chunk, simulated) {
+        return this.#sendBytes(encoder.encode(chunk), simulated);
     }
-    keepAlive() {
-        return this.sendText("\n\n", false);
+    /**
+     * For internal use only
+     * @deprecated
+     */
+    _keepAlive() {
+        return this.#sendText("\n\n", false);
     }
     dispatch(type, data) {
-        return this.sendText(`event: ${type}\ndata: ${data}\n\n`, true);
+        let html;
+        if (typeof data === "string")
+            html = data;
+        else {
+            if (!this.#render)
+                throw new Error(`Cannot render to JSX when no renderer provided during class initialization`);
+            html = this.#render(data);
+        }
+        return this.#sendText(`event: ${type}\ndata: ${html}\n\n`, true);
     }
     close(unlink = true) {
         if (this.#controller) {
@@ -95,18 +108,16 @@ export class EventSource {
             this.#controller = null;
         }
         // Cleanup
-        if (this.#timer)
-            clearInterval(this.#timer);
-        if (unlink)
-            register.delete(this);
+        keepAlive.delete(this);
         // was already closed
-        if (this.#state === EventSource.CLOSED)
+        if (this.#state === _a.CLOSED)
             return false;
         // Mark closed
-        this.#state = EventSource.CLOSED;
+        this.#state = _a.CLOSED;
         return true;
     }
 }
+_a = EventSource;
 export class EventSourceSet extends Set {
     /** Send update to all EventSources, auto closing failed dispatches */
     dispatch(type, data) {
@@ -133,13 +144,78 @@ export class EventSourceSet extends Set {
         this.clear();
     }
 }
+/**
+ * DO NOT USE: Experimental
+ * @deprecated
+ */
+export class SharedEventSource {
+    #pool;
+    #render;
+    #cache;
+    #rules;
+    constructor(props) {
+        this.#pool = new EventSourceSet();
+        this.#render = props?.render || undefined;
+        this.#cache = {};
+        this.#rules = {};
+    }
+    create(request) {
+        const source = new EventSource(request, this.#render);
+        const buffer = [];
+        for (const name in this.#cache)
+            buffer.push(...this.#cache[name].map(x => ({ t: name, x })));
+        buffer.sort((a, b) => b.x.t - a.x.t);
+        for (const e of buffer)
+            source.dispatch(e.t, e.x.s);
+        return source;
+    }
+    dispatch(type, data) {
+        let html;
+        if (typeof data === "string")
+            html = data;
+        else {
+            if (!this.#render)
+                throw new Error(`Cannot render to JSX when no renderer provided during class initialization`);
+            html = this.#render(data);
+        }
+        this.#pool.dispatch(type, html);
+        // Cache management
+        const rule = this.#rules[type];
+        if (!rule)
+            return;
+        const t = Date.now();
+        this.#cache[type] ||= [];
+        const queue = this.#cache[type];
+        queue.push({ t, s: html });
+        // Purge Cache
+        let i = rule.limit ? Math.max(0, queue.length - rule.limit) : 0;
+        if (rule.ttl) {
+            const window = t - rule.ttl;
+            for (; i < queue.length; i++)
+                if (queue[i].t > window)
+                    break;
+        }
+        this.#cache[type] = queue.slice(i);
+    }
+    isEmpty() {
+        return this.#pool.size < 1;
+    }
+    close() { this.#pool.closeAll(); }
+}
 // Auto close all SSE streams when shutdown requested
 // Without this graceful shutdowns will hang indefinitely
-const register = new EventSourceSet();
-function CloseAll() {
-    register.closeAll();
-}
+const keepAlive = new Set();
+const interval = setInterval(() => {
+    for (const e of keepAlive) {
+        if (e.readyState === EventSource.CLOSED) {
+            keepAlive.delete(e);
+            continue;
+        }
+        e._keepAlive();
+    }
+}, 10_000);
+function Shutdown() { clearInterval(interval); }
 if (process) {
-    process.on('SIGTERM', CloseAll);
-    process.on('SIGTERM', CloseAll);
+    process.on('SIGTERM', Shutdown);
+    process.on('SIGHUP', Shutdown);
 }

package/{internal → dist/internal}/request/server.d.ts

@@ -3,25 +3,34 @@ import { GenericContext } from "../router.js";
 import { RouterModule } from "./index.js";
 export type Config = {
     build: () => Promise<RouterModule> | Promise<RouterModule>;
-    render: GenericContext["render"];
+    render: (res: JSX.Element) => string;
     viteDevServer: ViteDevServer | null;
+    headers?: Headers;
     poweredBy?: boolean;
     timers?: boolean;
 };
 type ServerBindType = "pre" | "post";
 type ServerBind = (ctx: GenericContext) => Promise<Response | null> | Response | null;
+type Transformer = (ctx: GenericContext, res: Response) => Promise<Response | void> | Response | void;
 export declare class HtmxRouterServer {
     #private;
     readonly vite: Config["viteDevServer"];
     readonly render: Config["render"];
     readonly build: Config["build"];
-    readonly poweredBy: boolean;
+    readonly headers: Headers;
     readonly timers: boolean;
     constructor(config: Config);
     /**
      * Add a middleware to resolve requests before/after the route tree attempts to resolve
      */
     use(type: ServerBindType, binding: ServerBind): void;
+    /**
+     * Be careful with your transformers, there is no error unwrapping built in
+     * @param binding
+     * @returns
+     */
+    useTransform(binding: Transformer): void;
+    transform(ctx: GenericContext, res: Response): Promise<Response>;
     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

package/{internal → dist/internal}/request/server.js

@@ -4,6 +4,7 @@ import { connectToWeb } from "./compatibility/vite/connectToWeb.js";
 import { GenericContext } from "../router.js";
 import { NodeAdaptor } from "./compatibility/node.js";
 import { MakeStatus } from "../../status.js";
+import { redirect } from "../../response.js";
 function UrlCleaner({ url }) {
     const i = url.pathname.lastIndexOf("/");
     if (i === 0)
@@ -11,26 +12,29 @@ function UrlCleaner({ url }) {
     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() }
-    }));
+    return redirect(url.toString(), { permanent: true });
 }
 export class HtmxRouterServer {
     vite;
     render;
     build;
-    poweredBy;
+    headers;
     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.headers = config.headers || new Headers();
+        if (config.poweredBy !== false && !this.headers.has("Powered-By"))
+            this.headers.set("X-Powered-By", "htmx-router");
+        if (!this.headers.has("Content-Type"))
+            this.headers.set("Content-Type", "text/html; charset=UTF-8");
         this.#binding = {
             pre: [UrlCleaner],
-            post: []
+            post: [],
+            transform: []
         };
         if (this.vite) {
             const handler = connectToWeb(this.vite.middlewares);
@@ -51,24 +55,45 @@ export class HtmxRouterServer {
         }
         throw new Error(`Unknown binding type "${type}"`);
     }
+    /**
+     * Be careful with your transformers, there is no error unwrapping built in
+     * @param binding
+     * @returns
+     */
+    useTransform(binding) {
+        this.#binding.transform.push(binding);
+        return;
+    }
+    async transform(ctx, res) {
+        if (this.#binding.transform.length < 0)
+            return res;
+        ctx.timer.checkpoint("transform");
+        for (const process of this.#binding.transform) {
+            const next = process(ctx, res);
+            if (next instanceof Response)
+                res = next;
+        }
+        ctx.finalize(res);
+        return res;
+    }
     async resolve(request, resolve404 = true) {
         const url = new URL(request.url);
         const ctx = new GenericContext(request, url, this);
         { // pre-binding
             const res = await this.#applyBindings("pre", ctx);
             if (res)
-                return ctx.finalize(res);
+                return await this.transform(ctx, res);
         }
-        const tree = await this.#getTree();
         { // route
+            const tree = await this.#getTree();
             const res = await this.#resolveRoute(ctx, tree);
             if (res)
-                return ctx.finalize(res);
+                return await this.transform(ctx, res);
         }
         { // post-binding
             const res = await this.#applyBindings("post", ctx);
             if (res)
-                return ctx.finalize(res);
+                return await this.transform(ctx, res);
         }
         if (resolve404)
             return await this.error(ctx, undefined);
@@ -86,7 +111,7 @@ export class HtmxRouterServer {
             ctx = new GenericContext(ctx, new URL(ctx.url), this);
         const tree = await this.#getTree();
         const res = await tree.unwrap(ctx, e);
-        return ctx.finalize(res);
+        return await this.transform(ctx, res);
     }
     /**
      * Create a closure for use with the classic express.js like servers

package/{internal → dist/internal}/router.d.ts

@@ -3,20 +3,18 @@ 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: {
+    readonly scope: HtmxRouterServer;
+    readonly request: Request;
+    readonly headers: Headers;
+    readonly cookie: Cookies;
+    readonly params: {
         [key: string]: string;
     };
-    timer: RequestTimer;
-    url: URL;
+    readonly timer: RequestTimer;
+    readonly url: URL;
+    readonly render: HtmxRouterServer["render"];
     constructor(request: GenericContext["request"], url: GenericContext["url"], scope: HtmxRouterServer);
-    render(res: JSX.Element, headers: Headers): Promise<Rendered> | Rendered;
-    finalize(res: Response): Response;
+    finalize(res: Response): void;
     shape<T extends ParameterShaper>(shape: T, path: string): RouteContext<T>;
 }
-export {};

package/{internal → dist/internal}/router.js

@@ -4,34 +4,25 @@ import { RouteContext } from "../router.js";
 import { RequestTimer } from "../timer.js";
 import { Cookies } from '../cookies.js';
 export class GenericContext {
+    scope;
     request;
     headers; // response headers
     cookie;
     params;
     timer;
     url;
-    #server;
+    render;
     constructor(request, url, scope) {
-        this.#server = scope;
         this.cookie = new Cookies(request.headers.get("cookie"));
-        this.headers = new Headers();
+        this.headers = new Headers(scope.headers);
         this.request = request;
         this.params = {};
         this.url = url;
         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;
+        this.scope = scope;
+        this.render = scope.render;
     }
+    finalize(res) { this.timer.writeTo(res.headers); }
     shape(shape, path) {
         return new RouteContext(this, this.params, shape, path);
     }

package/{response.d.ts → dist/response.d.ts}

@@ -19,7 +19,7 @@ export declare function refresh(init?: ResponseInit & {
  *
  * @param {Request} request - The incoming HTTP request object
  * @param {Headers} headers - The response headers object to modify
- * @param {string} etag - The current ETag value for the resource
+ * @param {string} etag - The current ETag value for the resource (do not quote)
  * @param {Object} [options] - Optional caching configuration
  * @param {number} [options.revalidate] - client must revalidate their etag at this interval in seconds
  * @param {boolean} [options.public] - cache visibility scope:
@@ -53,6 +53,8 @@ export declare function refresh(init?: ResponseInit & {
  *   // This code only runs if client needs updated content
  *   return new Response(generateContent(), { headers });
  * }
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag | ETag - MDN Web Docs }
  */
 export declare function AssertETagStale(request: Request, headers: Headers, etag: string, options?: {
     revalidate?: number;

package/{response.js → dist/response.js}

@@ -59,7 +59,7 @@ export function refresh(init) {
  *
  * @param {Request} request - The incoming HTTP request object
  * @param {Headers} headers - The response headers object to modify
- * @param {string} etag - The current ETag value for the resource
+ * @param {string} etag - The current ETag value for the resource (do not quote)
  * @param {Object} [options] - Optional caching configuration
  * @param {number} [options.revalidate] - client must revalidate their etag at this interval in seconds
  * @param {boolean} [options.public] - cache visibility scope:
@@ -93,6 +93,8 @@ export function refresh(init) {
  *   // This code only runs if client needs updated content
  *   return new Response(generateContent(), { headers });
  * }
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag | ETag - MDN Web Docs }
  */
 export function AssertETagStale(request, headers, etag, options) {
     if (options) {
@@ -105,9 +107,9 @@ export function AssertETagStale(request, headers, etag, options) {
             headers.append("Cache-Control", `max-age=${options.revalidate}`);
     }
     headers.append("Cache-Control", "must-revalidate");
-    headers.set("ETag", etag);
+    headers.set("ETag", `"${etag}"`);
     const client = request.headers.get("if-none-match");
-    if (client === etag)
+    if (client !== etag)
         return;
     const res = new Response(null, {
         status: 304, statusText: "Not Modified",

package/{router.js → dist/router.js}

@@ -189,17 +189,21 @@ class RouteLeaf {
             return null;
         if (jsx instanceof Response)
             return jsx;
-        const res = await ctx.render(jsx, ctx.headers);
-        if (res instanceof Response)
-            return res;
+        ctx.timer.checkpoint("render");
+        const res = ctx.render(jsx);
         return html(res, { headers: ctx.headers });
     }
     async error(ctx, e) {
         if (!this.module.error)
             throw e;
-        let jsx = await this.module.error(ctx.shape({}, this.path), e);
-        const caught = jsx instanceof Response ? jsx
-            : await ctx.render(jsx, ctx.headers);
+        const jsx = await this.module.error(ctx.shape({}, this.path), e);
+        let caught;
+        if (jsx instanceof Response)
+            caught = jsx;
+        else {
+            ctx.timer.checkpoint("render");
+            caught = ctx.render(jsx);
+        }
         if (caught instanceof Response) {
             caught.headers.set("X-Caught", "true");
             return caught;

package/{timer.d.ts → dist/timer.d.ts}

@@ -45,4 +45,9 @@ export declare class RequestTimer {
      */
     checkpoint(name: string): void;
     writeTo(headers: Headers): void;
+    /**
+     * This action is non-reversible
+     * It will clear all timers for the request, and ensure they aren't included in the response
+     */
+    disable(): void;
 }

package/{timer.js → dist/timer.js}

@@ -72,6 +72,11 @@ export class RequestTimer {
         const last = this.#checkpoints[limit];
         headers.set(`X-Time-${last.name}`, String(end - last.time));
     }
+    /**
+     * This action is non-reversible
+     * It will clear all timers for the request, and ensure they aren't included in the response
+     */
+    disable() { this.#checkpoints = null; }
 }
 class Checkpoint {
     time;

package/package.json

@@ -1,19 +1,34 @@
 {
 	"name": "htmx-router",
-	"version": "2.0.5",
+	"version": "2.1.1",
 	"description": "A lightweight SSR framework with server+client islands",
-	"keywords": [
-		"htmx",
-		"router",
-		"client islands",
-		"ssr",
-		"vite"
-	],
-	"main": "./index.js",
+	"keywords": [ "htmx", "router", "client islands", "ssr", "vite" ],
 	"type": "module",
 	"scripts": {
 		"build": "tsc"
 	},
+	"main": "./index.js",
+	"exports": {
+		".":              "./dist/index.js",
+		"./cookies":      "./dist/cookies.js",
+		"./css":          "./dist/css.js",
+		"./defer":        "./dist/defer.js",
+		"./endpoint":     "./dist/endpoint.js",
+		"./event-source": "./dist/event-source.js",
+		"./navigate":     "./dist/navigate.js",
+		"./response":     "./dist/response.js",
+		"./router":       "./dist/router.js",
+		"./server":       "./dist/server.js",
+		"./shell":        "./dist/shell.js",
+		"./status":       "./dist/status.js",
+		"./timer":        "./dist/timer.js",
+		"./vite":         "./dist/vite/index.js",
+
+		"./util/parameters": "./dist/util/parameters.js",
+
+		"./internal/client": "./dist/internal/client.js",
+		"./internal/mount":  "./dist/internal/mount.js"
+	},
 	"bin": {
 		"htmx-router": "cli/index.js"
 	},

package/event-source.d.ts

@@ -1,31 +0,0 @@
-/**
- * Helper for Server-Sent-Events, with auto close on SIGTERM and SIGHUP messages
- * Includes a keep alive empty packet sent every 30sec (because Chrome implodes at 120sec, and can be unreliable at 60sec)
- */
-export declare class EventSource {
-    #private;
-    readonly response: Response;
-    readonly createdAt: number;
-    get updatedAt(): number;
-    readonly withCredentials: boolean;
-    readonly url: string;
-    get readyState(): number;
-    static CONNECTING: number;
-    static OPEN: number;
-    static CLOSED: number;
-    constructor(request: Request, keepAlive?: number);
-    isAborted(): boolean;
-    private sendBytes;
-    private sendText;
-    private keepAlive;
-    dispatch(type: string, data: string): boolean;
-    close(unlink?: boolean): boolean;
-}
-export declare class EventSourceSet extends Set<EventSource> {
-    /** Send update to all EventSources, auto closing failed dispatches */
-    dispatch(type: string, data: string): void;
-    /** Cull all closed connections */
-    cull(): void;
-    /** Close all connections */
-    closeAll(): void;
-}