htmx-router 1.0.0-pre1 → 1.0.0-pre2

package/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/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/cli/index.d.ts

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

package/cli/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+"use strict";
+import chalk from 'chalk';
+import { readFile, writeFile } from "fs/promises";
+import * as components from "../internal/component/index.js";
+import { CompileManifest } from "../internal/compile/manifest.js";
+import { ReadConfig } from "./config.js";
+const config = await ReadConfig();
+console.info("");
+if (config.client) {
+    console.info(`Generating ${chalk.green("client island")} manifest`);
+    const source = await readFile(config.client.source, "utf8");
+    await writeFile(config.client.output.server, CompileManifest(config.framework, source, true));
+    console.log(`  - ${chalk.cyan("server")} ${chalk.gray(config.client.output.server)}`);
+    await writeFile(config.client.output.client, CompileManifest(config.framework, source, false));
+    console.log(`  - ${chalk.cyan("client")} ${chalk.gray(config.client.output.client)}`);
+    console.log("");
+}
+if (config.component) {
+    console.info(`Generating ${chalk.green("components")} for ${chalk.cyan(config.framework)}`);
+    const padding = Math.max(...Object.keys(config.component).map(x => x.length)) || 0;
+    for (const key in config.component) {
+        const prefix = `  - ${chalk.cyan(key)}` + " ".repeat(padding + 1 - key.length);
+        const component = components[key];
+        if (!component) {
+            console.log(prefix + chalk.red("unknown component"));
+            continue;
+        }
+        const source = component[config.framework] || component["*"];
+        if (!source) {
+            console.log(prefix + chalk.red("unable to find definition for ") + chalk.cyan(config.framework));
+            continue;
+        }
+        const output = config.component[key];
+        await writeFile(output, source);
+        console.log(prefix + chalk.gray(output));
+    }
+}

package/cookies.d.ts

@@ -0,0 +1,29 @@
+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 source;
+    private config;
+    private map;
+    constructor(source?: Document | string | null);
+    private parse;
+    get(name: string): string | null;
+    entries(): Array<[string, string]>;
+    [Symbol.iterator](): IterableIterator<[string, string]>;
+    has(name: string): boolean;
+    set(name: string, value: string, options?: CookieOptions): void;
+    unset(name: string): void;
+    /** Creates the response headers required to make the changes done to these cookies */
+    export(): string[];
+}

package/cookies.js

@@ -0,0 +1,80 @@
+/**
+ * Helper provided in the Generic and RouteContext which provides reading and updating cookies
+ */
+export class Cookies {
+    source;
+    config;
+    map;
+    constructor(source) {
+        this.source = source || null;
+        this.config = {};
+        this.map = {};
+    }
+    parse() {
+        if (this.source === null)
+            return;
+        const source = typeof this.source === "object" ? this.source.cookie : this.source;
+        for (const line of source.split("; ")) {
+            const [name, value] = line.split("=");
+            this.map[name] = value;
+        }
+        // keep source it document
+        if (typeof this.source === "string")
+            this.source = null;
+    }
+    get(name) {
+        this.parse();
+        return this.map[name] || null;
+    }
+    entries() {
+        this.parse();
+        return Object.entries(this.map);
+    }
+    *[Symbol.iterator]() {
+        this.parse();
+        for (const [key, value] of Object.entries(this.map)) {
+            yield [key, value];
+        }
+    }
+    has(name) {
+        this.parse();
+        return name in this.map;
+    }
+    set(name, value, options = {}) {
+        this.parse();
+        options.path ||= "/";
+        this.config[name] = options;
+        this.map[name] = value;
+        if (typeof this.source === "object")
+            document.cookie = `${name}=${value}`;
+    }
+    unset(name) {
+        this.parse();
+        return this.set(name, "", { maxAge: 0 });
+    }
+    /** Creates the response headers required to make the changes done to these cookies */
+    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

@@ -0,0 +1,21 @@
+import { RouteContext } from "./index.js";
+/**
+ * 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 Style {
+    readonly name: string;
+    readonly style: string;
+    readonly hash: string;
+    constructor(name: string, style: string);
+    toString(): string;
+}
+export declare function GetSheetUrl(): string;
+/**
+ * RouteTree mounting point
+ */
+export declare const path = "_/style/$hash";
+export declare const parameters: {
+    hash: StringConstructor;
+};
+export declare function loader(ctx: RouteContext<typeof parameters>): Promise<Response | null>;

package/css.js

@@ -0,0 +1,60 @@
+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 Style {
+    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 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;
+}
+function GetSheet() {
+    return cache || BuildSheet();
+}
+export function GetSheetUrl() {
+    const sheet = GetSheet();
+    return `/_/style/${sheet.hash}.css`;
+}
+/**
+ * RouteTree mounting point
+ */
+export const path = "_/style/$hash";
+export const parameters = {
+    hash: String
+};
+export async function loader(ctx) {
+    const build = GetSheet();
+    if (!ctx.params.hash.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 });
+}

package/defer.d.ts

@@ -0,0 +1,14 @@
+import { Parameterized, Parameterizer, ParameterShaper } from "./util/parameters.js";
+import { RenderFunction } from "./index.js";
+import { RouteContext } from "./router.js";
+export declare function RegisterDeferral<T extends ParameterShaper>(shape: T, func: RenderFunction<T>, converter?: Parameterizer<T>): string;
+export declare function Deferral<T extends ParameterShaper>(func: RenderFunction<T>, params?: Parameterized<T>): string;
+/**
+ * RouteTree mounting point
+ */
+export declare const path = "_/defer/$";
+export declare const parameters: {
+    $: StringConstructor;
+};
+export declare function loader(ctx: RouteContext<typeof parameters>): Promise<Response | null>;
+export declare const action: typeof loader;

package/defer.js

@@ -0,0 +1,80 @@
+import { ServerOnlyWarning } from "./internal/util.js";
+ServerOnlyWarning("dynamic-ref");
+import { RouteContext } from "./router.js";
+import { QuickHash } from "./internal/util.js";
+const registry = new Map();
+const index = new Map();
+function MakeIdentity(func) {
+    const hash = QuickHash(String(func));
+    const name = `${encodeURIComponent(func.name)}-${hash}`;
+    const url = `/_/defer/${name}`;
+    return { name, url };
+}
+export function RegisterDeferral(shape, func, converter) {
+    const existing = index.get(func);
+    if (existing)
+        return existing.url;
+    const { url, name } = MakeIdentity(func);
+    registry.set(name, func);
+    index.set(func, { url, shape, converter });
+    return url;
+}
+export function Deferral(func, params) {
+    const entry = index.get(func);
+    let url;
+    if (!entry) {
+        const identity = MakeIdentity(func);
+        console.warn(`Warn: Function ${identity.name} has not registered before use`);
+        url = identity.url;
+    }
+    else {
+        url = entry.url;
+    }
+    if (!params)
+        return url;
+    const query = new URLSearchParams();
+    if (entry?.converter) {
+        const convert = entry.converter;
+        for (const key in convert) {
+            if (!(key in params))
+                throw new Error(`Missing parameter ${key}`);
+            const raw = params[key];
+            const str = convert[key](raw);
+            query.set(key, str);
+        }
+    }
+    else {
+        for (const key in params)
+            query.set(key, String(params[key]));
+    }
+    return url + "?" + query.toString();
+}
+/**
+ * RouteTree mounting point
+ */
+export const path = "_/defer/$";
+export const parameters = {
+    "$": String
+};
+export async function loader(ctx) {
+    const endpoint = registry.get(ctx.params["$"]);
+    if (!endpoint)
+        return null;
+    const prelude = {};
+    for (const [key, value] of ctx.url.searchParams)
+        prelude[key] = value;
+    const entry = index.get(endpoint);
+    if (!entry) {
+        console.warn(`Warn: Function ${endpoint.name} was not registered for defer use`);
+        return null;
+    }
+    const forward = new RouteContext(ctx, prelude, entry.shape);
+    const res = await endpoint(forward);
+    if (res instanceof Response)
+        return res;
+    if (res === null)
+        return null;
+    ctx.headers.set("X-Partial", "true");
+    return ctx.render(res);
+}
+export const action = loader;

package/endpoint.d.ts

@@ -0,0 +1,20 @@
+import type { RenderFunction, RouteContext } 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<{}>;
+    readonly name: string;
+    readonly url: string;
+    constructor(render: RenderFunction<{}>, name?: string);
+}
+/**
+ * RouteTree mounting point
+ */
+export declare const path = "_/endpoint/$";
+export declare const parameters: {
+    $: StringConstructor;
+};
+export declare function loader(ctx: RouteContext<typeof parameters>): Promise<Response | null>;
+export declare const action: typeof loader;

package/endpoint.js

@@ -0,0 +1,40 @@
+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.name;
+        const hash = QuickHash(String(render));
+        this.name = name ? `${encodeURIComponent(name)}-${hash}` : hash;
+        this.url = `/_/endpoint/${this.name}`;
+        registry.set(this.name, this);
+    }
+}
+/**
+ * RouteTree mounting point
+ */
+export const path = "_/endpoint/$";
+export const parameters = {
+    "$": String
+};
+export async function loader(ctx) {
+    const endpoint = registry.get(ctx.params["$"]);
+    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);
+}
+export const action = loader;

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,116 @@
+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.add(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)
+            register.delete(this);
+        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 EventSourceSet();
+function CloseAll() {
+    register.closeAll();
+}
+if (process) {
+    process.on('SIGTERM', CloseAll);
+    process.on('SIGTERM', CloseAll);
+}

package/index.d.ts

@@ -0,0 +1,19 @@
+import type { ParameterShaper } from "./util/parameters.js";
+import type { RouteContext } from "./router.js";
+import { createRequestHandler } from "./internal/request/index.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>;
+export type RouteModule<T extends ParameterShaper> = {
+    parameters?: T;
+    loader?: RenderFunction<T>;
+    action?: RenderFunction<T>;
+    error?: CatchFunction<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, RouteContext };

package/index.js

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

package/internal/client.d.ts

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

package/internal/client.js

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

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