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

package/package.json

@@ -1,19 +1,17 @@
 {
 	"name": "htmx-router",
-	"version": "1.0.0-alpha.6",
-	"description": "A simple SSR framework with dynamic+client islands",
+	"version": "1.0.0-pre1",
+	"description": "A lightweight SSR framework with server+client islands",
 	"keywords": [
-		"htmx",
-		"router",
-		""
+		"htmx", "router", "client islands", "ssr", "vite"
 	],
 	"main": "./index.js",
 	"type": "module",
 	"scripts": {
-		"build": "tsc && tsc-alias"
+		"build": "tsc"
 	},
 	"bin": {
-		"htmx-router": "./cli/index.js"
+		"htmx-router": "cli/index.js"
 	},
 	"repository": {
 		"type": "git",
@@ -31,8 +29,8 @@
 	},
 	"devDependencies": {
 		"@types/node": "^20.4.5",
+		"chalk": "^5.4.1",
 		"ts-node": "^10.9.1",
-		"tsc-alias": "^1.8.10",
 		"typescript": "^5.1.6"
 	}
 }

package/readme.md

@@ -1,5 +1,22 @@
-# htmx Router
+# HTMX Router
 
-A simple file based router with support for: dynamic + client islands; route-less endpoints; client/server bundle spitting, and built in CSS sheet generation.
+A lightweight file based router built on vite+htmx for SSR generation of full pages and html partials
 
-> Apologies the docs have not yet been updated for this version, please wait for the final release for actual docs.
+Features:
+
+  - BYO jsx templating
+  - File base routing
+  - Typesafe url path parameters
+  - Dynamic route fallthrough
+  - Server + Client Islands
+  - Route-less points
+  - CSS sheet generation
+  - [html](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta), [opengraph](https://ogp.me/), and [json+ld](https://json-ld.org/) metadata generation
+  - Bundle splitting for filtering out server code from the client
+  - Server-Side EventSource creation for SSE event dispatch
+
+## Documentation
+See https://htmx-router.ajanibilby.com/
+
+## API
+See https://htmx-router.ajanibilby.com/api

package/cookies.d.ts

@@ -1,25 +0,0 @@
-export interface CookieOptions {
-    domain?: string | undefined;
-    expires?: Date;
-    httpOnly?: boolean;
-    maxAge?: number;
-    partitioned?: boolean;
-    path?: string;
-    priority?: "low" | "medium" | "high";
-    sameSite?: "lax" | "strict" | "none";
-    secure?: boolean;
-}
-/**
- * Helper provided in the Generic and RouteContext which provides reading and updating cookies
- */
-export declare class Cookies {
-    private map;
-    private config;
-    constructor(headers: Headers);
-    get(name: string): string | null;
-    has(name: string): boolean;
-    set(name: string, value: string, options?: CookieOptions): void;
-    flash(name: string, value: string): void;
-    unset(name: string): void;
-    export(): string[];
-}

package/cookies.js

@@ -1,60 +0,0 @@
-/**
- * Helper provided in the Generic and RouteContext which provides reading and updating cookies
- */
-export class Cookies {
-    map;
-    config;
-    constructor(headers) {
-        this.config = {};
-        this.map = {};
-        const cookie = headers.get("Cookie");
-        if (!cookie)
-            return;
-        for (const line of cookie.split("; ")) {
-            const [name, value] = line.split("=");
-            this.map[name] = value;
-        }
-    }
-    get(name) {
-        return this.map[name] || null;
-    }
-    has(name) {
-        return name in this.map;
-    }
-    set(name, value, options = {}) {
-        if (!options['path'])
-            options['path'] = "/";
-        this.config[name] = options;
-        this.map[name] = value;
-    }
-    flash(name, value) {
-        return this.set(name, value, { maxAge: 0 });
-    }
-    unset(name) {
-        return this.set(name, "", { maxAge: 0 });
-    }
-    export() {
-        const headers = new Array();
-        for (const name in this.config) {
-            let config = "";
-            for (const opt in this.config[name]) {
-                const prop = opt === "maxAge"
-                    ? "Max-Age"
-                    : opt[0].toUpperCase() + opt.slice(1);
-                const raw = this.config[name][opt];
-                if (raw === true) {
-                    config += `; ${prop}`;
-                    continue;
-                }
-                if (raw === false)
-                    continue;
-                let value = String(raw);
-                value = value[0].toUpperCase() + value.slice(1);
-                config += `; ${prop}=${value}`;
-            }
-            const cookie = name + "=" + this.map[name] + config + ";";
-            headers.push(cookie);
-        }
-        return headers;
-    }
-}

package/css.d.ts

@@ -1,13 +0,0 @@
-/**
- * Create a new css class to be included in the sheet
- * Use .this as your class name in the source, and it will be replaced with a unique name
- */
-export declare class StyleClass {
-    readonly name: string;
-    readonly style: string;
-    readonly hash: string;
-    constructor(name: string, style: string);
-    toString(): string;
-}
-export declare function GetSheetUrl(): string;
-export declare function _resolve(fragments: string[]): Response | null;

package/css.js

@@ -1,55 +0,0 @@
-import { QuickHash } from "./internal/util.js";
-const classNamePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
-const registry = new Map();
-let cache = null;
-/**
- * Create a new css class to be included in the sheet
- * Use .this as your class name in the source, and it will be replaced with a unique name
- */
-export class StyleClass {
-    name; // unique name generated based on the original name and hash of the style
-    style; // the mutated source
-    hash;
-    constructor(name, style) {
-        if (!name.match(classNamePattern))
-            throw new Error("Cannot use given name for CSS class");
-        this.hash = QuickHash(style);
-        this.name = `${name}-${this.hash}`;
-        style = style.replaceAll(".this", "." + this.name);
-        this.style = style;
-        registry.set(this.name, this);
-        cache = null;
-    }
-    toString() {
-        return this.name;
-    }
-}
-function GetSheet() {
-    return cache || BuildSheet();
-}
-export function GetSheetUrl() {
-    const sheet = GetSheet();
-    return `/_/style/${sheet.hash}.css`;
-}
-export function _resolve(fragments) {
-    if (!fragments[2])
-        return null;
-    const build = GetSheet();
-    if (!fragments[2].startsWith(build.hash))
-        return null;
-    const headers = new Headers();
-    headers.set("Content-Type", "text/css");
-    headers.set("Cache-Control", "public, max-age=604800");
-    return new Response(build.sheet, { headers });
-}
-function BuildSheet() {
-    let composite = "";
-    let sheet = "";
-    for (const [key, def] of registry) {
-        composite += key;
-        sheet += def.style;
-    }
-    const hash = QuickHash(composite);
-    cache = { hash, sheet };
-    return cache;
-}

package/dynamic.d.ts

@@ -1,5 +0,0 @@
-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/dynamic.js

@@ -1,42 +0,0 @@
-import { ServerOnlyWarning } from "./internal/util.js";
-ServerOnlyWarning("dynamic-ref");
-import { QuickHash } from "./internal/util.js";
-const registry = new Map();
-const index = new Map();
-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}`;
-    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;
-    const endpoint = registry.get(fragments[2]);
-    if (!endpoint)
-        return null;
-    const props = {};
-    for (const [key, value] of ctx.url.searchParams)
-        props[key] = value;
-    ctx.headers.set("X-Partial", "true");
-    const res = await endpoint(ctx, props);
-    if (res instanceof Response)
-        return res;
-    return ctx.render(res);
-}

package/endpoint.d.ts

@@ -1,13 +0,0 @@
-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)
- */
-export declare class Endpoint {
-    readonly render: RenderFunction<GenericContext>;
-    readonly name: string;
-    readonly url: string;
-    constructor(render: RenderFunction<GenericContext>, name?: string);
-}
-export declare function _resolve(fragments: string[], ctx: GenericContext): Promise<Response | null>;

package/endpoint.js

@@ -1,34 +0,0 @@
-import { ServerOnlyWarning } from "./internal/util.js";
-ServerOnlyWarning("endpoint");
-import { QuickHash } from "./internal/util.js";
-const registry = new Map();
-/**
- * Create a route-less endpoint
- * The name is optional and will be inferred from the function if not given (helpful for network waterfalls)
- */
-export class Endpoint {
-    render;
-    name;
-    url;
-    constructor(render, name) {
-        this.render = render;
-        name ||= render.constructor.name;
-        const hash = QuickHash(String(render));
-        this.name = name ? `${encodeURIComponent(name)}-${hash}` : hash;
-        this.url = `/_/endpoint/${this.name}`;
-        registry.set(this.name, this);
-    }
-}
-export async function _resolve(fragments, ctx) {
-    if (!fragments[2])
-        return null;
-    const endpoint = registry.get(fragments[2]);
-    if (!endpoint)
-        return null;
-    const res = await endpoint.render(ctx);
-    if (res === null)
-        return null;
-    if (res instanceof Response)
-        return res;
-    return ctx.render(res);
-}

package/event-source.d.ts

@@ -1,26 +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 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

@@ -1,123 +0,0 @@
-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/index.d.ts

@@ -1,19 +0,0 @@
-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

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

package/internal/cli/config.d.ts

@@ -1,13 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/internal/cli/index.js

@@ -1,15 +0,0 @@
-#!/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

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

package/internal/client.js

@@ -1,14 +0,0 @@
-import { ServerOnlyWarning } from "./util.js";
-ServerOnlyWarning("client-url");
-import { readFile } from "fs/promises";
-export async function GetClientEntryURL() {
-    if (process.env.NODE_ENV !== "production")
-        return "/app/entry.client.ts";
-    const config = JSON.parse(await readFile("./dist/client/.vite/manifest.json", "utf8"));
-    for (const key in config) {
-        const def = config[key];
-        if (!def.isEntry)
-            continue;
-        return "/" + def.file;
-    }
-}

package/internal/compile/manifest.d.ts

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