htmx-router 1.0.0-alpha.4 → 1.0.0-alpha.6

package/{bin/util/css.js → css.js}

@@ -1,4 +1,4 @@
-import { QuickHash } from "../util/hash.js";
+import { QuickHash } from "./internal/util.js";
 const classNamePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
 const registry = new Map();
 let cache = null;

package/dynamic.d.ts

@@ -0,0 +1,5 @@
+import type { GenericContext } from "./router.js";
+type Loader<T> = (ctx: GenericContext, params: T) => Promise<JSX.Element | Response>;
+export declare function DynamicReference<T extends Record<string, string>>(loader: Loader<T>, params?: T): string;
+export declare function _resolve(fragments: string[], ctx: GenericContext): Promise<Response | null>;
+export {};

package/{bin/util/dynamic.js → dynamic.js}

@@ -1,20 +1,30 @@
-/**
- * This whole file is only for internal use but the generated router for the <Dynamic> component
- */
-import { QuickHash } from "../util/hash.js";
+import { ServerOnlyWarning } from "./internal/util.js";
+ServerOnlyWarning("dynamic-ref");
+import { QuickHash } from "./internal/util.js";
 const registry = new Map();
 const index = new Map();
-export function RegisterDynamic(load) {
+function Register(load) {
     const existing = index.get(load);
     if (existing)
         return existing;
     const hash = QuickHash(String(load));
     const name = `${encodeURIComponent(load.name)}-${hash}`;
     registry.set(name, load);
-    const url = `/_/dynamic/${name}?`;
+    const url = `/_/dynamic/${name}`;
     index.set(load, url);
     return url;
 }
+export function DynamicReference(loader, params) {
+    let url = Register(loader);
+    if (params) {
+        const query = new URLSearchParams();
+        if (params)
+            for (const key in params)
+                query.set(key, params[key]);
+        url += "?" + query.toString();
+    }
+    return url;
+}
 export async function _resolve(fragments, ctx) {
     if (!fragments[2])
         return null;
@@ -25,5 +35,8 @@ export async function _resolve(fragments, ctx) {
     for (const [key, value] of ctx.url.searchParams)
         props[key] = value;
     ctx.headers.set("X-Partial", "true");
-    return ctx.render(await endpoint(props, ctx));
+    const res = await endpoint(ctx, props);
+    if (res instanceof Response)
+        return res;
+    return ctx.render(res);
 }

package/{bin/util/endpoint.d.ts → endpoint.d.ts}

@@ -1,5 +1,5 @@
-import { RenderFunction } from "../types.js";
-import { GenericContext } from "../router.js";
+import type { GenericContext } from "./router.js";
+import type { RenderFunction } from "./index.js";
 /**
  * Create a route-less endpoint
  * The name is optional and will be inferred from the function if not given (helpful for network waterfalls)

package/{bin/util/endpoint.js → endpoint.js}

@@ -1,4 +1,6 @@
-import { QuickHash } from "../util/hash.js";
+import { ServerOnlyWarning } from "./internal/util.js";
+ServerOnlyWarning("endpoint");
+import { QuickHash } from "./internal/util.js";
 const registry = new Map();
 /**
  * Create a route-less endpoint

package/event-source.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 controller;
+    private timer;
+    private state;
+    readonly response: Response;
+    readonly url: string;
+    constructor(request: Request, keepAlive?: number);
+    get readyState(): number;
+    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;
+}

package/event-source.js

@@ -0,0 +1,123 @@
+import { ServerOnlyWarning } from "./internal/util.js";
+ServerOnlyWarning("event-source");
+/**
+ * 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 class EventSource {
+    controller;
+    timer;
+    state;
+    response;
+    url; // just to make it polyfill
+    constructor(request, keepAlive = 30_000) {
+        this.controller = null;
+        this.state = 0;
+        this.url = request.url;
+        const stream = new ReadableStream({
+            start: (c) => { this.controller = c; this.state = 1; },
+            cancel: () => { this.close(); }
+        });
+        request.signal.addEventListener('abort', () => this.close());
+        this.response = new Response(stream, { headers });
+        this.timer = setInterval(() => this.keepAlive(), keepAlive);
+        register.push(this);
+    }
+    get readyState() {
+        return this.state;
+    }
+    sendBytes(chunk) {
+        if (!this.controller)
+            return false;
+        try {
+            this.controller.enqueue(chunk);
+            return true;
+        }
+        catch (e) {
+            console.error(e);
+            this.close(); // unbind on failure
+            return false;
+        }
+    }
+    sendText(chunk) {
+        return this.sendBytes(encoder.encode(chunk));
+    }
+    keepAlive() {
+        return this.sendText("\n\n");
+    }
+    dispatch(type, data) {
+        return this.sendText(`event: ${type}\ndata: ${data}\n\n`);
+    }
+    close(unlink = true) {
+        if (this.state === 2)
+            return false;
+        if (unlink) {
+            const i = register.indexOf(this);
+            if (i !== -1)
+                register.splice(i, 1);
+        }
+        try {
+            this.controller?.close();
+        }
+        catch (e) {
+            console.error(e);
+            this.controller = null;
+            return false;
+        }
+        // Cleanup
+        if (this.timer)
+            clearInterval(this.timer);
+        this.controller = null;
+        this.state = 2;
+        return true;
+    }
+}
+export class EventSourceSet extends Set {
+    /** Send update to all EventSources, auto closing failed dispatches */
+    dispatch(type, data) {
+        for (const stream of this) {
+            if (stream.readyState === 0)
+                continue; // skip initializing
+            const success = stream.dispatch(type, data);
+            if (!success)
+                this.delete(stream);
+        }
+    }
+    /** Cull all closed connections */
+    cull() {
+        for (const stream of this) {
+            if (stream.readyState !== 2)
+                continue;
+            this.delete(stream);
+        }
+    }
+    /** Close all connections */
+    closeAll() {
+        for (const stream of this)
+            stream.close();
+        this.clear();
+    }
+}
+// global for easy reuse
+const encoder = new TextEncoder();
+const headers = new Headers();
+// Chunked encoding with immediate forwarding by proxies (i.e. nginx)
+headers.set("X-Accel-Buffering", "no");
+headers.set("Transfer-Encoding", "chunked");
+headers.set("Content-Type", "text/event-stream");
+headers.set("Keep-Alive", "timeout=120"); // the maximum keep alive chrome shouldn't ignore
+headers.set("Connection", "keep-alive");
+// Auto close all SSE streams when shutdown requested
+// Without this graceful shutdowns will hang indefinitely
+const register = new Array();
+function CloseAll() {
+    for (const connection of register)
+        connection.close(false); // don't waste time unregistering
+}
+if (process) {
+    process.on('SIGTERM', CloseAll);
+    process.on('SIGHUP', CloseAll);
+}
+else {
+    console.warn("htmx-router's EventSource has been unsafely loaded on the client");
+}

package/example/eventdim-react/package.json

@@ -0,0 +1,67 @@
+{
+	"name": "eventdim-react",
+	"private": "true",
+	"version": "1.0.0",
+	"main": "index.js",
+	"type": "module",
+	"scripts": {
+		"prepare": "npx htmx-router && prisma generate && prisma migrate deploy",
+		"docker": "docker compose up -d",
+		"dev": "node ./server.js",
+		"build": "run-s build:*",
+		"build:router": "npx htmx-router",
+		"build:prisma": "npx prisma generate",
+		"build:client": "vite build",
+		"build:server": "vite build --ssr app/entry.server.ts --outDir dist/server",
+		"validate": "run-s validate:*",
+		"validate:typecheck": "tsc --noEmit",
+		"validate:lint": "eslint --ignore-path .gitignore --cache --cache-location ./node_modules/.cache/eslint .",
+		"preview": "cross-env NODE_ENV=production node ./server.js"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "ISC",
+	"description": "",
+	"dependencies": {
+		"@fortawesome/free-brands-svg-icons": "^6.7.2",
+		"@fortawesome/free-solid-svg-icons": "^6.7.2",
+		"@fortawesome/react-fontawesome": "^0.2.2",
+		"@prisma/client": "^6.1.0",
+		"bcryptjs": "^2.4.3",
+		"cbor2": "^1.8.0",
+		"cross-env": "^7.0.3",
+		"dotenv": "^16.4.7",
+		"express": "^4.21.2",
+		"htmx-router": "^1.0.0-alpha.5",
+		"morgan": "^1.10.0",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"tiny-invariant": "^1.3.3",
+		"zxcvbn": "^4.4.2"
+	},
+	"devDependencies": {
+		"@types/bcryptjs": "^2.4.6",
+		"@types/express": "^4.17.21",
+		"@types/nodemailer": "^6.4.15",
+		"@types/react": "^18.2.20",
+		"@types/react-dom": "^18.2.7",
+		"@types/zxcvbn": "^4.4.4",
+		"@typescript-eslint/eslint-plugin": "^6.7.4",
+		"@typescript-eslint/parser": "^6.7.4",
+		"eslint": "^8.38.0",
+		"eslint-import-resolver-typescript": "^3.6.1",
+		"eslint-plugin-import": "^2.28.1",
+		"eslint-plugin-jsx-a11y": "^6.7.1",
+		"eslint-plugin-react": "^7.33.2",
+		"eslint-plugin-react-hooks": "^4.6.0",
+		"npm-run-all": "^4.1.5",
+		"prisma": "^6.1.0",
+		"typed-htmx": "^0.3.1",
+		"typescript": "^5.5.4",
+		"vite-tsconfig-paths": "^5.1.3",
+		"vite": "^6.0.1"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	}
+}

package/example/eventdim-react/server.js

@@ -0,0 +1,90 @@
+/// <reference types="node" />
+/* eslint-disable */
+import 'dotenv/config'
+import * as path from "path";
+import { createRequestHandler } from 'htmx-router';
+import { renderToString } from 'react-dom/server';
+import express from 'express';
+import morgan from "morgan";
+
+const port = process.env.PORT || 3000;
+const app = express();
+
+const viteDevServer =
+	process.env.NODE_ENV === "production"
+		? null
+		: await import("vite").then((vite) =>
+				vite.createServer({
+					server: { middlewareMode: true },
+					appType: 'custom'
+				})
+			);
+
+app.use(
+	viteDevServer
+		? viteDevServer.middlewares
+		: express.static("./dist/client")
+);
+
+// logging
+app.use(morgan("tiny"));
+
+const build = viteDevServer
+	? () => viteDevServer.ssrLoadModule('./app/entry.server.ts')
+	: await import('./dist/server/entry.server.js');
+
+app.use('*', createRequestHandler.http({
+	build, viteDevServer,
+	render: (res) => {
+		const headers = new Headers();
+		headers.set("Content-Type", "text/html; charset=UTF-8");
+		headers.set("Cache-Control", "no-cache");
+
+		const stream = renderToString(res);
+		return new Response(stream, { headers });
+	}
+}));
+
+// Start http server
+app.listen(port, () => {
+	console.log(`Server started at http://localhost:${port}`)
+})
+
+
+ // Reload pages on file change
+if (viteDevServer) {
+	const focus = path.resolve("./app");
+	viteDevServer.watcher.on('change', (file) => {
+		if (!file.startsWith(focus)) return;
+		console.log(`File changed: ${path.relative("./app", file)}`);
+
+		console.log('Triggering full page reload');
+		viteDevServer.ws.send({ type: 'full-reload' });
+	});
+}
+
+const shutdown = () => {
+	console.log("Shutting down server...");
+
+	// Close the server gracefully
+	server.close((err) => {
+		if (err) {
+			console.error("Error during server shutdown:", err);
+			process.exit(1);
+		}
+		console.log("Server shut down gracefully.");
+		process.exit(0);
+	});
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGHUP', shutdown);
+
+
+process .on('unhandledRejection', (reason, p) => {
+	console.error(reason, 'Unhandled Rejection at Promise', p);
+})
+.on('uncaughtException', err => {
+	console.error(err, 'Uncaught Exception thrown');
+	process.exit(1);
+});

package/example/island-react/global.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react';
+
+declare global {
+	namespace JSX {
+		type Element = ReactNode;
+		interface HTMLAttributes extends HtmxAttributes {}
+	}
+}

package/example/island-react/package.json

@@ -0,0 +1,38 @@
+{
+	"type": "module",
+	"scripts": {
+		"prepare": "npx htmx-router",
+		"dev": "node ./server.js",
+		"build": "run-s build:*",
+		"build:router": "npx htmx-router",
+		"build:client": "vite build",
+		"build:server": "vite build --ssr app/entry.server.ts --outDir dist/server",
+		"preview": "cross-env NODE_ENV=production node ./server.js",
+		"validate": "npx tsc -noEmit"
+	},
+	"license": "MIT",
+	"dependencies": {
+		"cross-env": "^7.0.3",
+		"dotenv": "^16.3.1",
+		"express": "^4.21.1",
+		"morgan": "^1.10.0",
+		"npm-run-all": "^4.1.5",
+		"htmx-router": "^1.0.0-alpha.1",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"serve-static": "^1.16.2",
+		"tsconfig-paths": "^4.2.0"
+	},
+	"devDependencies": {
+		"@types/express": "^5.0.0",
+		"@types/node": "^20.4.5",
+		"@types/react-dom": "^19.0.2",
+		"@types/react": "^19.0.1",
+		"@types/serve-static": "^1.15.7",
+		"ts-node": "^10.9.1",
+		"typed-htmx": "^0.3.1",
+		"typescript": "^5.1.6",
+		"vite-tsconfig-paths": "^5.1.3",
+		"vite": "^6.0.1"
+	}
+}

package/example/island-react/server.js

@@ -0,0 +1,58 @@
+import { createRequestHandler } from 'htmx-router';
+import { renderToString } from 'react-dom/server';
+import express from 'express';
+import morgan from "morgan";
+
+const port = process.env.PORT || 5173;
+const app = express();
+
+
+const viteDevServer =
+	process.env.NODE_ENV === "production"
+		? null
+		: await import("vite").then((vite) =>
+				vite.createServer({
+					server: { middlewareMode: true },
+					appType: 'custom'
+				})
+			);
+
+app.use(
+	viteDevServer
+		? viteDevServer.middlewares
+		: express.static("./dist/client")
+);
+
+// logging
+app.use(morgan("tiny"));
+
+const build = viteDevServer
+	? () => viteDevServer.ssrLoadModule('./app/entry.server.ts')
+	: await import('./dist/server/entry.server.js');
+
+app.use('*', createRequestHandler.http({
+	build, viteDevServer,
+	render: (res) => {
+		const headers = new Headers();
+		headers.set("Content-Type", "text/html; charset=UTF-8");
+
+		const stream = renderToString(res);
+		return new Response(stream, { headers });
+	}
+}));
+
+
+// Start http server
+app.listen(port, () => {
+	console.log(`Server started at http://localhost:${port}`)
+})
+
+
+ // Reload pages on file change
+if (viteDevServer)
+	viteDevServer.watcher.on('change', (file) => {
+	console.log(`File changed: ${file}`);
+
+	console.log('Triggering full page reload');
+	viteDevServer.ws.send({ type: 'full-reload' });
+});

package/global.d.ts

@@ -0,0 +1,7 @@
+declare namespace JSX {
+	interface Element {}
+	interface IntrinsicElements {
+		[elementName: string]: any;
+	}
+	interface Fragment {}
+}

package/index.d.ts

@@ -0,0 +1,19 @@
+import type { GenericContext, RouteContext } from "./router.js";
+import type { ParameterShaper } from "./util/parameters.js";
+import { createRequestHandler } from "./internal/request/index.js";
+export type RenderFunction<T> = (args: T) => Promise<Response | JSX.Element | null>;
+export type CatchFunction<T> = (args: T, err: unknown) => Promise<Response | JSX.Element>;
+export type RouteModule<T extends ParameterShaper> = {
+    parameters?: T;
+    loader?: RenderFunction<RouteContext<T>>;
+    action?: RenderFunction<RouteContext<T>>;
+    error?: CatchFunction<RouteContext<T>>;
+    route?: (params: Record<string, string>) => string;
+};
+export type ClientIslandManifest<T> = {
+    [K in keyof T]: ClientIsland<T[K]>;
+};
+type ClientIsland<T> = T extends (props: infer P) => JSX.Element ? (props: P & {
+    children?: JSX.Element;
+}) => JSX.Element : T;
+export { createRequestHandler, GenericContext, RouteContext };

package/index.js

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

package/internal/cli/config.d.ts

@@ -0,0 +1,13 @@
+type Config = {
+    framework: string;
+    client?: {
+        source: string;
+        output: {
+            server: string;
+            client: string;
+        };
+    };
+    component?: Record<string, string>;
+};
+export declare function ReadConfig(): Promise<Config>;
+export {};

package/internal/cli/config.js

@@ -0,0 +1,11 @@
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+const DEFAULT = {
+    framework: "generic"
+};
+export async function ReadConfig() {
+    const path = process.argv[2] || "./htmx.config.json";
+    if (!existsSync(path))
+        return DEFAULT;
+    return JSON.parse(await readFile(path, "utf-8"));
+}

package/internal/cli/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+"use strict";
+import { readFile, writeFile } from "fs/promises";
+import { CompileManifest } from "../compile/manifest.js";
+import { ReadConfig } from "../cli/config.js";
+const config = await ReadConfig();
+if (config.client) {
+    console.info("Building client island manifest");
+    const source = await readFile(config.client.source, "utf8");
+    await writeFile(config.client.output.server, CompileManifest(config.framework, source, true));
+    await writeFile(config.client.output.client, CompileManifest(config.framework, source, false));
+}
+if (config.component) {
+    console.info("Building components");
+}

package/internal/client.d.ts

@@ -0,0 +1 @@
+export declare function GetClientEntryURL(): Promise<string | undefined>;

package/{bin/client/entry.js → internal/client.js}

@@ -1,3 +1,5 @@
+import { ServerOnlyWarning } from "./util.js";
+ServerOnlyWarning("client-url");
 import { readFile } from "fs/promises";
 export async function GetClientEntryURL() {
     if (process.env.NODE_ENV !== "production")
@@ -7,6 +9,6 @@ export async function GetClientEntryURL() {
         const def = config[key];
         if (!def.isEntry)
             continue;
-        return def.file;
+        return "/" + def.file;
     }
 }

package/internal/compile/manifest.d.ts

@@ -0,0 +1 @@
+export declare function CompileManifest(adapter: string, source: string, ssr: boolean): string;