htmx-router 2.1.5 → 2.2.0

package/dist/event-source.d.ts

@@ -5,6 +5,7 @@ type Render = (jsx: JSX.Element) => string;
  */
 export declare class EventSource<JsxEnabled extends boolean = false> {
     #private;
+    readonly _signal: AbortSignal;
     readonly response: Response;
     readonly createdAt: number;
     get updatedAt(): number;
@@ -20,11 +21,15 @@ export declare class EventSource<JsxEnabled extends boolean = false> {
      * For internal use only
      * @deprecated
      */
-    _keepAlive(): boolean;
+    pulse(): boolean;
     dispatch(type: string, data: JsxEnabled extends true ? (JSX.Element | string) : string): boolean;
     close(): boolean;
 }
 export declare class EventSourceSet<JsxEnabled extends boolean = false> extends Set<EventSource<JsxEnabled>> {
+    private onAbort;
+    constructor();
+    add(stream: EventSource<JsxEnabled>): this;
+    delete(stream: EventSource<JsxEnabled>): boolean;
     /**
      * Send update to all EventSources, auto closing failed dispatches
      * @returns number of successful sends
@@ -35,6 +40,11 @@ export declare class EventSourceSet<JsxEnabled extends boolean = false> extends
      * @returns number of connections closed
      */
     cull(): number;
+    /**
+     * INTERNAL: Send keep-alive to all EventSources
+     * @deprecated
+     */
+    pulse(): number;
     /**
      * Close all connections
      * @returns number of connections closed

package/dist/event-source.js

@@ -1,5 +1,7 @@
 var _a;
 import { ServerOnlyWarning } from "./internal/util.js";
+import { MakeStatus } from './status.js';
+import { Lifecycle } from "./event.js";
 ServerOnlyWarning("event-source");
 // global for easy reuse
 const encoder = new TextEncoder();
@@ -17,8 +19,8 @@ const headers = {
  * Includes a keep alive empty packet sent every 30sec (because Chrome implodes at 120sec, and can be unreliable at 60sec)
  */
 export class EventSource {
+    _signal;
     #controller;
-    #signal;
     #state;
     #render;
     response;
@@ -38,21 +40,26 @@ export class EventSource {
     constructor(request, render) {
         this.#controller = null;
         this.#state = _a.CONNECTING;
+        this._signal = request.signal;
         this.#render = render;
         this.withCredentials = request.mode === "cors";
         this.url = request.url;
         this.createdAt = Date.now();
         this.#updatedAt = 0;
+        if (Lifecycle.isShuttingDown()) {
+            this.response = new Response('Server is shutting down', MakeStatus('Service Unavailable'));
+            this.#state = _a.CLOSED;
+            return;
+        }
         // immediate prepare for abortion
-        this.#signal = request.signal;
-        const cancel = () => { this.close(); this.#signal.removeEventListener("abort", cancel); };
-        this.#signal.addEventListener('abort', cancel);
+        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 });
         keepAlive.add(this);
     }
-    isAborted() { return this.#signal.aborted; }
+    isAborted() { return this._signal.aborted; }
     #sendBytes(chunk, active) {
         if (this.#state === _a.CLOSED) {
             const err = new Error(`Warn: Attempted to send data on closed stream for: ${this.url}`);
@@ -83,7 +90,7 @@ export class EventSource {
      * For internal use only
      * @deprecated
      */
-    _keepAlive() {
+    pulse() {
         return this.#sendText("\n\n", false);
     }
     dispatch(type, data) {
@@ -119,6 +126,19 @@ export class EventSource {
 }
 _a = EventSource;
 export class EventSourceSet extends Set {
+    onAbort;
+    constructor() {
+        super();
+        this.onAbort = () => this.cull();
+    }
+    add(stream) {
+        stream._signal.addEventListener('abort', this.onAbort);
+        return super.add(stream);
+    }
+    delete(stream) {
+        stream._signal.removeEventListener('abort', this.onAbort);
+        return super.delete(stream);
+    }
     /**
      * Send update to all EventSources, auto closing failed dispatches
      * @returns number of successful sends
@@ -126,8 +146,8 @@ export class EventSourceSet extends Set {
     dispatch(type, data) {
         let count = 0;
         for (const stream of this) {
-            if (stream.readyState === 0)
-                continue; // skip initializing
+            if (stream.readyState !== EventSource.OPEN)
+                continue; // skip closed
             const success = stream.dispatch(type, data);
             if (success)
                 count++;
@@ -143,12 +163,27 @@ export class EventSourceSet extends Set {
     cull() {
         const count = this.size;
         for (const stream of this) {
-            if (stream.readyState !== 2)
+            if (stream.readyState !== EventSource.CLOSED)
                 continue;
             this.delete(stream);
         }
         return count;
     }
+    /**
+     * INTERNAL: Send keep-alive to all EventSources
+     * @deprecated
+     */
+    pulse() {
+        let count = 0;
+        for (const stream of this) {
+            if (stream.readyState !== EventSource.OPEN)
+                continue; // skip closed
+            const success = stream.pulse();
+            if (success)
+                count++;
+        }
+        return count;
+    }
     /**
      * Close all connections
      * @returns number of connections closed
@@ -171,8 +206,8 @@ export class SharedEventSource {
     #cache;
     #rules;
     constructor(props) {
-        this.#pool = new EventSourceSet();
         this.#render = props?.render || undefined;
+        this.#pool = new EventSourceSet();
         this.#cache = {};
         this.#rules = {};
     }
@@ -221,18 +256,9 @@ export class SharedEventSource {
 }
 // Auto close all SSE streams when shutdown requested
 // Without this graceful shutdowns will hang indefinitely
-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', Shutdown);
-    process.on('SIGHUP', Shutdown);
-}
+const keepAlive = new EventSourceSet();
+const interval = setInterval(() => { keepAlive.pulse(); }, 10_000);
+// Lifecycle.addEventListener('shutdown', () => {
+// 	clearInterval(interval);
+// 	keepAlive.closeAll();
+// });

package/dist/event.d.ts

@@ -0,0 +1,31 @@
+declare global {
+    const Deno: {
+        build: {
+            os: 'windows' | 'linux' | 'darwin' | string;
+        };
+        addSignalListener: (signal: string, handler: () => void) => void;
+    } | undefined;
+}
+export declare class ShutdownEvent extends CustomEvent<{
+    signal: string;
+}> {
+    constructor(signal: string);
+}
+/**
+ * Controller for handling graceful shutdowns across Windows, Linux, and Browsers.
+ *
+ * @example
+ * ```ts
+ * Lifecycle.addEventListener('shutdown', (e) => {
+ *   console.log('Stopping because of:', e.detail.signal);
+ *   server.close();
+ * });
+ * ```
+ */
+declare class LifecycleController extends EventTarget {
+    #private;
+    constructor();
+    isShuttingDown(): boolean;
+}
+export declare const Lifecycle: LifecycleController;
+export {};

package/dist/event.js

@@ -0,0 +1,52 @@
+export class ShutdownEvent extends CustomEvent {
+    constructor(signal) {
+        super('shutdown', { detail: { signal } });
+    }
+}
+/**
+ * Controller for handling graceful shutdowns across Windows, Linux, and Browsers.
+ *
+ * @example
+ * ```ts
+ * Lifecycle.addEventListener('shutdown', (e) => {
+ *   console.log('Stopping because of:', e.detail.signal);
+ *   server.close();
+ * });
+ * ```
+ */
+class LifecycleController extends EventTarget {
+    #shuttingDown = false;
+    constructor() {
+        super();
+        this.#bindEvents();
+    }
+    isShuttingDown() { return this.#shuttingDown; }
+    // Bind to whatever environment we are running in
+    #bindEvents() {
+        const trigger = (sig) => this.#trigger(sig);
+        if (globalThis.window && globalThis.window.addEventListener) {
+            // BROWSER: Tab closing / Refreshing
+            globalThis.window.addEventListener('beforeunload', () => trigger('BEFOREUNLOAD'));
+        }
+        if (process) {
+            process.on('SIGINT', () => trigger('SIGINT'));
+            process.on('SIGTERM', () => trigger('SIGTERM'));
+            process.on('SIGHUP', () => trigger('SIGHUP'));
+        }
+        if (Deno) {
+            if (Deno.build.os !== "windows") {
+                Deno.addSignalListener('SIGTERM', () => trigger('SIGTERM'));
+            }
+            Deno.addSignalListener("SIGHUP", () => trigger('SIGHUP'));
+            Deno.addSignalListener("SIGINT", () => trigger('SIGTERM'));
+        }
+    }
+    #trigger(signal) {
+        if (this.#shuttingDown)
+            return;
+        this.#shuttingDown = true;
+        console.log(`\n🛑 Shutdown Signal received: ${signal}`);
+        this.dispatchEvent(new ShutdownEvent(signal));
+    }
+}
+export const Lifecycle = new LifecycleController();

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { ParameterShaper } from "./util/parameters.js";
+import type { GenericContext } from "./internal/router.js";
 import type { RouteContext } from "./router.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>;
@@ -15,4 +16,4 @@ export type ClientIslandManifest<T> = {
 type ClientIsland<T> = T extends (props: infer P) => JSX.Element ? (props: P & {
     children?: JSX.Element;
 }) => JSX.Element : T;
-export { RouteContext };
+export { RouteContext, GenericContext };

package/dist/internal/component/defer.js

@@ -11,6 +11,8 @@ export function Defer<T extends ParameterShaper>(props: {
 		hx-get={Deferral(props.loader, props.params)}
 		hx-trigger="load"
 		hx-swap="outerHTML transition:true"
+		hx-replace-url="false"
+		hx-push-url="false"
 		style={{ display: "contents" }}
 	>{props.children ? props.children : ""}</div>
 }`;

package/dist/internal/request/server.js

@@ -1,17 +1,24 @@
 import { ServerOnlyWarning } from "../util.js";
 ServerOnlyWarning("request/server");
 import { connectToWeb } from "./compatibility/vite/connectToWeb.js";
+import { RouteResolver } from "../../router.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("/");
+    let i = url.pathname.lastIndexOf("/");
     if (i === 0)
         return null;
     if (i !== url.pathname.length - 1)
         return null;
-    url.pathname = url.pathname.slice(0, -1);
+    i--;
+    while (url.pathname[i] === '/' && i > 0)
+        i--;
+    if (i === 0)
+        url.pathname = '/';
+    else
+        url.pathname = url.pathname.slice(0, i);
     return redirect(url.toString(), { permanent: true });
 }
 export class HtmxRouterServer {
@@ -110,7 +117,8 @@ export class HtmxRouterServer {
         if (ctx instanceof Request)
             ctx = new GenericContext(ctx, new URL(ctx.url), this);
         const tree = await this.#getTree();
-        const res = await tree.unwrap(ctx, e);
+        const chain = new RouteResolver(ctx, [], tree);
+        const res = await chain.unwind(e, 0);
         return await this.transform(ctx, res);
     }
     /**
@@ -125,10 +133,11 @@ export class HtmxRouterServer {
     }
     async #resolveRoute(ctx, tree) {
         let response;
+        const x = ctx.url.pathname.slice(1);
+        const fragments = x === "" ? [] : x.split("/");
+        const chain = new RouteResolver(ctx, fragments, tree);
         try {
-            const x = ctx.url.pathname.slice(1);
-            const fragments = x === "" ? [] : x.split("/");
-            const res = await tree.resolve(fragments, ctx);
+            const res = await chain.resolve();
             if (res === null)
                 return null;
             response = res;
@@ -137,7 +146,7 @@ export class HtmxRouterServer {
             if (e instanceof Error)
                 this.vite?.ssrFixStacktrace(e);
             console.error(e);
-            response = await tree.unwrap(ctx, e);
+            response = await chain.unwind(e, 0);
         }
         // context merge headers if divergent
         if (response.headers !== ctx.headers) {

package/dist/response.js

@@ -108,17 +108,29 @@ export function AssertETagStale(request, headers, etag, options) {
             headers.append("Cache-Control", `max-age=${options.revalidate}`);
     }
     headers.append("Cache-Control", "must-revalidate");
-    headers.set("ETag", `"${encodeURIComponent(etag.trim())}"`);
-    const client = request.headers.get("if-none-match");
-    if (client !== etag)
+    etag = encodeURIComponent(etag.trim()); // safely handle any special characters
+    headers.set("ETag", `"${etag}"`);
+    const rules = request.headers.get("if-none-match");
+    if (!rules || !MatchEtags(rules.trim(), etag))
         return;
-    const res = new Response(null, {
-        status: 304, statusText: "Not Modified",
-        headers
-    });
+    const res = new Response(null, { headers, status: 304, statusText: "Not Modified" });
     res.headers.set("X-Caught", "true");
     throw res;
 }
+function MatchEtags(header, etag) {
+    if (header === "*")
+        return true;
+    for (const term of header.split(/,\s*/)) {
+        let s = term.startsWith('W/') ? 'W/'.length : 0;
+        let e = term.endsWith('"') ? term.length - 1 : term.length;
+        if (term.startsWith('"', s))
+            s++;
+        const tag = term.slice(s, e);
+        if (etag === tag)
+            return true;
+    }
+    return false;
+}
 /**
  * This is to fix issues with deno
  * When you try and change the statusText on a Response object

package/dist/router.d.ts

@@ -18,6 +18,15 @@ export declare class RouteContext<T extends ParameterShaper = {}> {
     render: GenericContext["render"];
     constructor(base: GenericContext | RouteContext, params: ParameterPrelude<T>, shape: T, path: string);
 }
+export declare class RouteResolver {
+    private stack;
+    private slugs;
+    readonly ctx: GenericContext;
+    constructor(ctx: GenericContext, fragments: string[], tree: RouteTree);
+    push(leaf: RouteLeaf, slug?: string): void;
+    resolve(): Promise<Response | null>;
+    unwind(e: unknown, offset: number): Promise<Response>;
+}
 export declare class RouteTree {
     private nested;
     private index;
@@ -26,20 +35,11 @@ export declare class RouteTree {
     private wildCard;
     constructor();
     ingest(node: RouteLeaf, path?: string[]): void;
-    resolve(fragments: string[], ctx: GenericContext): Promise<Response | null>;
-    private _resolve;
-    private resolveIndex;
-    private resolveNext;
-    private resolveWild;
-    private resolveSlug;
-    unwrap(ctx: GenericContext, res: unknown): Promise<Response>;
+    _applyChain(out: RouteResolver, fragments: string[], offset?: number): void;
 }
 declare class RouteLeaf {
-    private module;
+    readonly module: RouteModule<any>;
     readonly path: string;
     constructor(module: RouteModule<any>, path: string);
-    resolve(ctx: GenericContext): Promise<Response | null>;
-    error(ctx: GenericContext, e: unknown): Promise<Response>;
-    private response;
 }
 export {};

package/dist/router.js

@@ -1,4 +1,4 @@
-import { AssertUnreachable, ServerOnlyWarning } from "./internal/util.js";
+import { ServerOnlyWarning } from "./internal/util.js";
 ServerOnlyWarning("router");
 import { MakeStatus } from "./status.js";
 // builtin routes
@@ -59,6 +59,78 @@ export class RouteContext {
         }
     }
 }
+export class RouteResolver {
+    // using two seperate arrays to reduce object creation
+    // since these values are just pointers
+    stack;
+    slugs;
+    ctx;
+    constructor(ctx, fragments, tree) {
+        this.stack = [];
+        this.slugs = [];
+        this.ctx = ctx;
+        tree._applyChain(this, fragments, 0);
+    }
+    push(leaf, slug) {
+        this.stack.push(leaf);
+        this.slugs.push(slug);
+    }
+    async resolve() {
+        const pull = this.ctx.request.method === "HEAD" || this.ctx.request.method === "GET";
+        for (let i = this.stack.length - 1; i >= 0; i--) {
+            const node = this.stack[i];
+            // Determine the resolving function
+            const resolver = pull ? node.module.loader : node.module.action;
+            if (!resolver) {
+                if (pull)
+                    continue;
+                return this.unwind(new Response("Method not Allowed", MakeStatus("Method Not Allowed", this.ctx.headers)), i);
+            }
+            // Apply the slug pseudo parameter if necessary
+            if (this.slugs[i])
+                this.ctx.params['$'] = this.slugs[i];
+            try {
+                const context = this.ctx.shape(node.module.parameters || {}, node.path);
+                const jsx = await resolver(context);
+                if (jsx === null)
+                    continue;
+                if (jsx instanceof Response)
+                    return jsx;
+                const res = this.ctx.render(jsx);
+                return html(res, { headers: this.ctx.headers });
+            }
+            catch (e) {
+                return await this.unwind(e, i);
+            }
+        }
+        return null;
+    }
+    async unwind(e, offset) {
+        for (let i = this.stack.length - 1; i >= 0; i--) {
+            const node = this.stack[i];
+            if (!node.module.error)
+                continue;
+            try {
+                const jsx = await node.module.error(this.ctx.shape({}, node.path), e);
+                let caught;
+                if (jsx instanceof Response)
+                    caught = jsx;
+                else
+                    caught = this.ctx.render(jsx);
+                if (caught instanceof Response) {
+                    caught.headers.set("X-Caught", "true");
+                    return caught;
+                }
+                this.ctx.headers.set("X-Caught", "true");
+                return html(caught, e instanceof Response ? e : MakeStatus("Internal Server Error", this.ctx.headers));
+            }
+            catch (next) {
+                e = next;
+            }
+        }
+        throw e;
+    }
+}
 export class RouteTree {
     nested;
     // Leaf nodes
@@ -105,75 +177,23 @@ export class RouteTree {
         }
         next.ingest(node, path.slice(1));
     }
-    async resolve(fragments, ctx) {
-        if (!this.slug)
-            return await this._resolve(fragments, ctx);
-        try {
-            return await this._resolve(fragments, ctx);
+    _applyChain(out, fragments, offset = 0) {
+        if (this.slug) {
+            const slug = fragments.slice(offset).join('/');
+            out.push(this.slug, slug);
         }
-        catch (e) {
-            return this.unwrap(ctx, e);
-        }
-    }
-    async _resolve(fragments, ctx) {
-        let res = await this.resolveIndex(fragments, ctx)
-            || await this.resolveNext(fragments, ctx)
-            || await this.resolveWild(fragments, ctx)
-            || await this.resolveSlug(fragments, ctx);
-        if (res instanceof Response) {
-            if (res.ok)
-                return res;
-            if (100 <= res.status && res.status <= 399)
-                return res;
-            if (res.headers.has("X-Caught"))
-                return res;
-            return this.unwrap(ctx, res);
+        if (offset === fragments.length) {
+            if (this.index)
+                out.push(this.index, undefined);
+            return;
         }
-        return res;
-    }
-    async resolveIndex(fragments, ctx) {
-        if (fragments.length > 0)
-            return null;
-        if (!this.index)
-            return null;
-        const res = await this.index.resolve(ctx);
-        if (res instanceof Response)
-            return res;
-        if (res === null)
-            return null;
-        AssertUnreachable(res);
-    }
-    async resolveNext(fragments, ctx) {
-        if (fragments.length < 1)
-            return null;
-        const next = this.nested.get(fragments[0]);
-        if (!next)
-            return null;
-        return await next.resolve(fragments.slice(1), ctx);
-    }
-    async resolveWild(fragments, ctx) {
+        const keyed = this.nested.get(fragments[offset]);
+        if (keyed)
+            return keyed._applyChain(out, fragments, offset + 1);
         if (!this.wild)
-            return null;
-        if (fragments.length < 1)
-            return null;
-        ctx.params[this.wildCard] = fragments[0];
-        return this.wild.resolve(fragments.slice(1), ctx);
-    }
-    async resolveSlug(fragments, ctx) {
-        if (!this.slug)
-            return null;
-        ctx.params["$"] = fragments.join("/");
-        const res = await this.slug.resolve(ctx);
-        if (res instanceof Response)
-            return res;
-        if (res === null)
-            return null;
-        AssertUnreachable(res);
-    }
-    unwrap(ctx, res) {
-        if (!this.slug)
-            throw res;
-        return this.slug.error(ctx, res);
+            return;
+        out.ctx.params[this.wildCard] = fragments[offset];
+        return this.wild._applyChain(out, fragments, offset + 1);
     }
 }
 class RouteLeaf {
@@ -183,51 +203,4 @@ class RouteLeaf {
         this.module = module;
         this.path = path;
     }
-    async resolve(ctx) {
-        const jsx = await this.response(ctx);
-        if (jsx === null)
-            return null;
-        if (jsx instanceof Response)
-            return jsx;
-        const res = ctx.render(jsx);
-        return html(res, { headers: ctx.headers });
-    }
-    async error(ctx, e) {
-        if (!this.module.error)
-            throw e;
-        const jsx = await this.module.error(ctx.shape({}, this.path), e);
-        let caught;
-        if (jsx instanceof Response)
-            caught = jsx;
-        else
-            caught = ctx.render(jsx);
-        if (caught instanceof Response) {
-            caught.headers.set("X-Caught", "true");
-            return caught;
-        }
-        ctx.headers.set("X-Caught", "true");
-        return html(caught, e instanceof Response ? e : MakeStatus("Internal Server Error", ctx.headers));
-    }
-    async response(ctx) {
-        try {
-            if (!this.module.loader && !this.module.action)
-                return null;
-            const context = ctx.shape(this.module.parameters || {}, this.path);
-            if (ctx.request.method === "HEAD" || ctx.request.method === "GET") {
-                if (this.module.loader)
-                    return await this.module.loader(context);
-                else
-                    return null;
-            }
-            if (this.module.action)
-                return await this.module.action(context);
-            throw new Response("Method not Allowed", MakeStatus("Method Not Allowed", ctx.headers));
-        }
-        catch (e) {
-            if (e instanceof Response && e.headers.has("X-Caught"))
-                return e;
-            return await this.error(ctx, e);
-        }
-        return null;
-    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "htmx-router",
-	"version": "2.1.5",
+	"version": "2.2.0",
 	"description": "A lightweight SSR framework with server+client islands",
 	"keywords": [ "htmx", "router", "client islands", "ssr", "vite" ],
 	"type": "module",
@@ -14,6 +14,7 @@
 		"./css":          "./dist/css.js",
 		"./defer":        "./dist/defer.js",
 		"./endpoint":     "./dist/endpoint.js",
+		"./event":        "./dist/event.js",
 		"./event-source": "./dist/event-source.js",
 		"./navigate":     "./dist/navigate.js",
 		"./response":     "./dist/response.js",