htmx-router 1.0.0-pre1 → 1.0.0-pre2

package/response.js

@@ -0,0 +1,46 @@
+export function text(text, init) {
+    init ||= {};
+    init.statusText ||= "ok";
+    init.status ||= 200;
+    const res = new Response(text, init);
+    res.headers.set("Content-Type", "text/plain");
+    res.headers.set("X-Caught", "true");
+    return res;
+}
+export function json(data, init) {
+    init ||= {};
+    init.statusText ||= "ok";
+    init.status ||= 200;
+    const res = new Response(JSON.stringify(data), init);
+    res.headers.set("Content-Type", "application/json");
+    res.headers.set("X-Caught", "true");
+    return res;
+}
+export function redirect(url, init) {
+    init ||= {};
+    init.statusText ||= "Temporary Redirect";
+    init.status ||= 307;
+    const res = new Response("", init);
+    if (!init?.clientOnly)
+        res.headers.set("Location", url);
+    res.headers.set("HX-Location", url); // use hx-boost if applicable
+    return res;
+}
+export function revalidate(init) {
+    init ||= {};
+    init.statusText ||= "ok";
+    init.status ||= 200;
+    const res = new Response("", init);
+    res.headers.set("HX-Location", "");
+    return res;
+}
+export function refresh(init) {
+    init ||= {};
+    init.statusText ||= "ok";
+    init.status ||= 200;
+    const res = new Response("", init);
+    if (!init?.clientOnly)
+        res.headers.set("Refresh", "0"); // fallback
+    res.headers.set("HX-Refresh", "true");
+    return res;
+}

package/router.d.ts

@@ -0,0 +1,33 @@
+import type { GenericContext } from "./internal/router.js";
+import { Parameterized, ParameterPrelude, ParameterShaper } from './util/parameters.js';
+import { RouteModule } from "./index.js";
+import { Cookies } from './cookies.js';
+export declare function GenerateRouteTree(props: {
+    modules: Record<string, unknown>;
+    scope: string;
+}): RouteTree;
+export declare class RouteContext<T extends ParameterShaper = {}> {
+    readonly request: Request;
+    readonly headers: Headers;
+    readonly cookie: Cookies;
+    readonly params: Parameterized<T>;
+    readonly url: URL;
+    render: (res: JSX.Element) => Response;
+    constructor(base: GenericContext | RouteContext, params: ParameterPrelude<T>, shape: T);
+}
+export declare class RouteTree {
+    private nested;
+    private index;
+    private slug;
+    private wild;
+    private wildCard;
+    constructor();
+    ingest(path: string | string[], module: RouteModule<any>): void;
+    resolve(fragments: string[], ctx: GenericContext): Promise<Response | null>;
+    private _resolve;
+    private resolveIndex;
+    private resolveNext;
+    private resolveWild;
+    private resolveSlug;
+    private unwrap;
+}

package/router.js

@@ -0,0 +1,206 @@
+import { ServerOnlyWarning } from "./internal/util.js";
+ServerOnlyWarning("router");
+// builtin routes
+import * as endpoint from './endpoint.js';
+import * as dynamic from './defer.js';
+import * as mount from './internal/mount.js';
+import * as css from './css.js';
+export function GenerateRouteTree(props) {
+    if (!props.scope.endsWith("/"))
+        props.scope += "/";
+    const tree = new RouteTree();
+    for (const path in props.modules) {
+        const mod = props.modules[path];
+        const tail = path.lastIndexOf(".");
+        const url = path.slice(props.scope.length, tail);
+        tree.ingest(url, mod);
+        if (mod.route)
+            mod.route(url);
+    }
+    // ingest router builtins
+    tree.ingest(endpoint.path, endpoint);
+    tree.ingest(dynamic.path, dynamic);
+    tree.ingest(mount.path, mount);
+    tree.ingest(css.path, css);
+    return tree;
+}
+export class RouteContext {
+    request;
+    headers; // response headers
+    cookie;
+    params;
+    url;
+    render;
+    constructor(base, params, shape) {
+        this.cookie = base.cookie;
+        this.headers = base.headers;
+        this.request = base.request;
+        this.render = base.render;
+        this.url = base.url;
+        this.params = {};
+        for (const key in shape) {
+            if (!(key in params))
+                console.warn(`Parameter ${key} not present in route, but defined in parameters`);
+            const func = shape[key];
+            const val = func(params[key] || "");
+            // NaN moment
+            if (func === Number && typeof val === "number" && isNaN(val))
+                throw new Error("Invalid Number");
+            this.params[key] = val;
+        }
+    }
+}
+export class RouteTree {
+    nested;
+    // Leaf nodes
+    index; // _index.tsx
+    // Wild card routes
+    slug; // $
+    wild; // e.g. $userID
+    wildCard;
+    constructor() {
+        this.nested = new Map();
+        this.index = null;
+        this.wildCard = "";
+        this.wild = null;
+        this.slug = null;
+    }
+    ingest(path, module) {
+        if (!Array.isArray(path))
+            path = path.split("/");
+        if (path.length === 0 || (path.length == 1 && path[0] === "_index")) {
+            this.index = new RouteLeaf(module);
+            return;
+        }
+        if (path[0] === "$") {
+            this.slug = new RouteLeaf(module);
+            return;
+        }
+        if (path[0][0] === "$") {
+            const wildCard = path[0].slice(1);
+            // Check wildcard isn't being changed
+            if (!this.wild) {
+                this.wildCard = wildCard;
+                this.wild = new RouteTree();
+            }
+            else if (wildCard !== this.wildCard) {
+                throw new Error(`Redefinition of wild card ${this.wildCard} to ${wildCard}`);
+            }
+            path.splice(0, 1);
+            this.wild.ingest(path, module);
+            return;
+        }
+        let next = this.nested.get(path[0]);
+        if (!next) {
+            next = new RouteTree();
+            this.nested.set(path[0], next);
+        }
+        path.splice(0, 1);
+        next.ingest(path, module);
+    }
+    async resolve(fragments, ctx) {
+        if (!this.slug)
+            return await this._resolve(fragments, ctx);
+        try {
+            return await this._resolve(fragments, ctx);
+        }
+        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 (100 <= res.status && res.status <= 399)
+                return res;
+            if (res.headers.has("X-Caught"))
+                return res;
+            return this.unwrap(ctx, res);
+        }
+        return res;
+    }
+    async resolveIndex(fragments, ctx) {
+        if (fragments.length > 0)
+            return null;
+        if (!this.index)
+            return null;
+        return await this.index.resolve(ctx);
+    }
+    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) {
+        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 = this.slug.resolve
+            ? await this.slug.resolve(ctx)
+            : null;
+        return res;
+    }
+    async unwrap(ctx, res) {
+        if (!this.slug)
+            throw res;
+        const caught = await this.slug.error(ctx, res);
+        caught.headers.set("X-Caught", "true");
+        return caught;
+    }
+}
+class RouteLeaf {
+    module;
+    constructor(module) {
+        this.module = module;
+    }
+    async resolve(ctx) {
+        const res = await this.renderWrapper(ctx);
+        if (res === null)
+            return null;
+        if (res instanceof Response)
+            return res;
+        return ctx.render(res);
+    }
+    async error(ctx, e) {
+        if (!this.module.error)
+            throw e;
+        const res = await this.module.error(ctx, e);
+        if (res instanceof Response)
+            return res;
+        return ctx.render(res);
+    }
+    async renderWrapper(ctx) {
+        try {
+            if (!this.module.loader && !this.module.action)
+                return null;
+            const context = ctx.shape(this.module.parameters || {});
+            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", { status: 405, statusText: "Method not Allowed", headers: ctx.headers });
+        }
+        catch (e) {
+            return await this.error(ctx, e);
+        }
+        return null;
+    }
+}

package/shell.d.ts

@@ -0,0 +1,120 @@
+export type ShellOptions<D = {}> = D & MetaDescriptor;
+export declare function ApplyMetaDefaults(options: ShellOptions, defaults: Readonly<Partial<ShellOptions>>): void;
+export type InferShellOptions<F> = F extends (jsx: any, options: infer U) => any ? U : never;
+export type MetaDescriptor = {
+    title?: string;
+    description?: string;
+    meta?: Record<string, string>;
+    og?: OpenGraph<string>;
+    jsonLD?: LdJsonObject[];
+};
+export declare function RenderMetaDescriptor<T>(options: ShellOptions<T>): string;
+export type LdJsonObject = {
+    [Key in string]?: LdJsonValue | undefined;
+};
+type LdJsonArray = LdJsonValue[] | readonly LdJsonValue[];
+type LdJsonPrimitive = string | number | boolean | null;
+type LdJsonValue = LdJsonPrimitive | LdJsonObject | LdJsonArray;
+export type OpenGraphType = "website" | "article" | "book" | "profile" | "music.song" | "music.album" | "music.playlist" | "music.radio_station" | "video.movie" | "video.episode" | "video.tv_show" | "video.other" | string;
+export type OpenGraph<T extends OpenGraphType = string> = {
+    type?: T;
+    title?: string;
+    description?: string;
+    determiner?: string;
+    url?: string;
+    secure_url?: string;
+    locale?: string | {
+        base: string;
+        alternative: string[];
+    };
+    image?: OpenGraphImage[];
+    video?: OpenGraphVideo[];
+    audio?: OpenGraphAudio[];
+} & (T extends "music.song" ? OpenGraphSong : T extends "music.album" ? OpenGraphAlbum : T extends "music.playlist" ? OpenGraphPlaylist : T extends "music.radio_station" ? OpenGraphRadioStation : T extends "video.movie" ? OpenGraphMovie : T extends "video.episode" ? OpenGraphEpisode : T extends "video.tv_show" ? OpenGraphTvShow : T extends "video.other" ? OpenGraphVideoOther : T extends "article" ? OpenGraphArticle : T extends "book" ? OpenGraphBook : T extends "profile" ? OpenGraphProfile : {});
+export type OpenGraphImage = {
+    url: string;
+    secure_url?: string;
+    type?: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+};
+export type OpenGraphVideo = {
+    url: string;
+    type?: string;
+    secure_url?: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+};
+export type OpenGraphAudio = {
+    url: string;
+    type?: string;
+    secure_url?: string;
+};
+type OpenGraphSong = {
+    duration?: number;
+    album?: Array<string | {
+        url: string;
+        disc?: number;
+        track?: number;
+    }>;
+    musician?: string[];
+};
+type OpenGraphAlbum = {
+    songs?: Array<string | {
+        url: string;
+        disc?: number;
+        track?: number;
+    }>;
+    musician?: string[];
+    release_date?: Date;
+};
+type OpenGraphPlaylist = {
+    songs?: Array<string | {
+        url: string;
+        disc?: number;
+        track?: number;
+    }>;
+    creator?: string[];
+};
+type OpenGraphRadioStation = {
+    creator?: string[];
+};
+type OpenGraphMovie = {
+    actors?: Array<string | {
+        url: string;
+        role: string;
+    }>;
+    directors?: string[];
+    writers?: string[];
+    duration?: number;
+    release_date?: Date;
+    tag: string[];
+};
+type OpenGraphEpisode = OpenGraphMovie & {
+    series?: string;
+};
+type OpenGraphTvShow = OpenGraphMovie;
+type OpenGraphVideoOther = OpenGraphMovie;
+type OpenGraphArticle = {
+    published_time?: Date;
+    modified_time?: Date;
+    expiration_time?: Date;
+    authors?: string[];
+    section?: string;
+    tag?: string;
+};
+type OpenGraphBook = {
+    authors?: string[];
+    isbn?: string;
+    release_date?: Date;
+    tag?: string;
+};
+type OpenGraphProfile = {
+    first_name?: string;
+    last_name?: string;
+    username?: string;
+    gender?: "male" | "female";
+};
+export {};

package/shell.js

@@ -0,0 +1,261 @@
+import { ServerOnlyWarning } from "./internal/util.js";
+ServerOnlyWarning("shell");
+export function ApplyMetaDefaults(options, defaults) {
+    if (defaults.title && !options.title)
+        options.title = defaults.title;
+    if (defaults.description && !options.description)
+        options.description = defaults.description;
+    if (defaults.meta && !options.meta)
+        options.meta = defaults.meta;
+    if (defaults.og && !options.og)
+        options.og = defaults.og;
+    if (defaults.jsonLD && !options.jsonLD)
+        options.jsonLD = defaults.jsonLD;
+}
+export function RenderMetaDescriptor(options) {
+    let out = "";
+    if (options.title)
+        out += `<title>${EscapeHTML(options.title)}</title>`;
+    if (options.description)
+        out += `<meta name="description" content="${EscapeHTML(options.description)}">\n`;
+    if (options.meta)
+        for (const key in options.meta) {
+            out += `<meta name="${EscapeHTML(key)}" content="${EscapeHTML(options.meta[key])}">\n`;
+        }
+    if (options.jsonLD)
+        for (const json of options.jsonLD) {
+            out += `<script type="application/ld+json">${JSON.stringify(json)}</script>\n`;
+        }
+    // Apply open graphs
+    if (options.og) {
+        // Infer from meta if not present
+        if (!options.og.title)
+            options.og.title = options.title;
+        if (!options.og.description)
+            options.og.title = options.description;
+        out += RenderOpenGraph(options.og);
+    }
+    else {
+        // Auto apply og:title + og:description if og not present
+        if (options.title)
+            out += `<meta property="og:title" content="${EscapeHTML(options.title)}">\n`;
+        if (options.description)
+            out += `<meta property="og:description" content="${EscapeHTML(options.description)}">\n`;
+    }
+    return out;
+}
+function RenderOpenGraph(og) {
+    // Manually encoding everything rather than using a loop to ensure they are in the correct order
+    // And to ensure extra values can't leak in creating unsafe og tags
+    const type = og.type || "website";
+    let out = RenderProperty("og:type", type);
+    if (og.title)
+        out += RenderProperty("og:title", og.title);
+    if (og.description)
+        out += RenderProperty("og:description", og.description);
+    if (og.determiner)
+        out += RenderProperty("og:determiner", og.determiner);
+    if (og.url)
+        out += RenderProperty("og:url", og.url);
+    if (og.secure_url)
+        out += RenderProperty("og:secure_url", og.secure_url);
+    if (og.locale) {
+        if (typeof og.locale === "string")
+            out += RenderProperty("og:locale", og.locale);
+        else {
+            out += RenderProperty("og:locale", og.locale.base);
+            for (const l of og.locale.alternative)
+                out += RenderProperty("og:locale:alternative", l);
+        }
+    }
+    if (og.image)
+        for (const img of og.image) {
+            out += RenderProperty("og:image", img.url);
+            if (img.secure_url)
+                out += RenderProperty("og:image:secure_url", img.secure_url);
+            if (img.type)
+                out += RenderProperty("og:image:type", img.type);
+            if (img.width)
+                out += RenderProperty("og:image:width", img.width.toString());
+            if (img.height)
+                out += RenderProperty("og:image:height", img.height.toString());
+            if (img.alt)
+                out += RenderProperty("og:image:alt", img.alt);
+        }
+    if (og.video)
+        for (const vid of og.video) {
+            out += RenderProperty("og:video", vid.url);
+            if (vid.secure_url)
+                out += RenderProperty("og:video:secure_url", vid.secure_url);
+            if (vid.type)
+                out += RenderProperty("og:video:type", vid.type);
+            if (vid.width)
+                out += RenderProperty("og:video:width", vid.width.toString());
+            if (vid.height)
+                out += RenderProperty("og:video:height", vid.height.toString());
+            if (vid.alt)
+                out += RenderProperty("og:video:alt", vid.alt);
+        }
+    if (og.audio)
+        for (const audio of og.audio) {
+            out += RenderProperty("og:audio", audio.url);
+            if (audio.secure_url)
+                out += RenderProperty("og:audio:secure_url", audio.secure_url);
+            if (audio.type)
+                out += RenderProperty("og:audio:type", audio.type);
+        }
+    return out + RenderOpenGraphExtras(og);
+}
+function RenderProperty(name, value) {
+    return `<meta property="${name}" content="${EscapeHTML(value)}">\n`;
+}
+function RenderOpenGraphExtras(og) {
+    let out = "";
+    if (og.type === "music.song") {
+        const g = og;
+        if (g.duration)
+            out += RenderProperty("og:music:duration", g.duration.toString());
+        if (g.album)
+            for (const album of g.album) {
+                if (typeof album === "string")
+                    out += RenderProperty("og:music:album", album);
+                else {
+                    out += RenderProperty("og:music:album", album.url);
+                    if (album.disc)
+                        out += RenderProperty("og:music:album:disc", album.disc.toString());
+                    if (album.track)
+                        out += RenderProperty("og:music:album:track", album.track.toString());
+                }
+            }
+        if (g.musician)
+            for (const profile of g.musician)
+                out += RenderProperty("og:music:musician", profile);
+        return out;
+    }
+    if (og.type === "music.album") {
+        const g = og;
+        if (g.songs)
+            for (const song of g.songs) {
+                if (typeof song === "string")
+                    out += RenderProperty("og:music:song", song);
+                else {
+                    out += RenderProperty("og:music:song", song.url);
+                    if (song.disc)
+                        out += RenderProperty("og:music:song:disc", song.disc.toString());
+                    if (song.track)
+                        out += RenderProperty("og:music:song:track", song.track.toString());
+                }
+            }
+        if (g.musician)
+            for (const profile of g.musician)
+                out += RenderProperty("og:music:musician", profile);
+        if (g.release_date)
+            out += RenderProperty("og:music:release_date", g.release_date.toISOString());
+        return out;
+    }
+    if (og.type === "music.playlist") {
+        const g = og;
+        if (g.songs)
+            for (const song of g.songs) {
+                if (typeof song === "string")
+                    out += RenderProperty("og:music:song", song);
+                else {
+                    out += RenderProperty("og:music:song", song.url);
+                    if (song.disc)
+                        out += RenderProperty("og:music:song:disc", song.disc.toString());
+                    if (song.track)
+                        out += RenderProperty("og:music:song:track", song.track.toString());
+                }
+            }
+        if (g.creator)
+            for (const profile of g.creator)
+                out += RenderProperty("og:music:creator", profile);
+        return out;
+    }
+    if (og.type === "music.radio_station") {
+        const g = og;
+        if (g.creator)
+            for (const profile of g.creator)
+                out += RenderProperty("og:music:creator", profile);
+        return out;
+    }
+    if (og.type === "video.movie" || og.type === "video.episode" || og.type === "video.tv_show" || og.type === "video.other") {
+        const g = og;
+        if (g.actors)
+            for (const actor of g.actors) {
+                if (typeof actor === "string")
+                    out += RenderProperty("og:video:actor", actor);
+                else {
+                    out += RenderProperty("og:video:actor", actor.url);
+                    out += RenderProperty("og:video:actor:role", actor.role);
+                }
+            }
+        if (g.directors)
+            for (const profile of g.directors)
+                out += RenderProperty("og:video:director", profile);
+        if (g.writers)
+            for (const profile of g.writers)
+                out += RenderProperty("og:video:writer", profile);
+        if (g.duration)
+            out += RenderProperty("og:video:duration", g.duration.toString());
+        if (g.release_date)
+            out += RenderProperty("og:video:release_date", g.release_date.toISOString());
+        if (g.tag)
+            for (const tag of g.tag)
+                out += RenderProperty("og:video:tag", tag);
+        if (g.series)
+            out += RenderProperty("og:video:series", g.series);
+    }
+    if (og.type === "article") {
+        const g = og;
+        if (g.published_time)
+            out += RenderProperty("og:article:published_time", g.published_time.toISOString());
+        if (g.modified_time)
+            out += RenderProperty("og:article:modified_time", g.modified_time.toISOString());
+        if (g.expiration_time)
+            out += RenderProperty("og:article:expiration_time", g.expiration_time.toISOString());
+        if (g.authors)
+            for (const profile of g.authors)
+                out += RenderProperty("og:article:author", profile);
+        if (g.section)
+            out += RenderProperty("og:article:section", g.section);
+        if (g.tag)
+            for (const tag of g.tag)
+                out += RenderProperty("og:video:tag", tag);
+    }
+    if (og.type === "book") {
+        const g = og;
+        if (g.authors)
+            for (const profile of g.authors)
+                out += RenderProperty("og:article:author", profile);
+        if (g.isbn)
+            out += RenderProperty("og:book:isbn", g.isbn);
+        if (g.release_date)
+            out += RenderProperty("og:book:release_date", g.release_date.toISOString());
+        if (g.tag)
+            for (const tag of g.tag)
+                out += RenderProperty("og:video:tag", tag);
+    }
+    if (og.type === "profile") {
+        const g = og;
+        if (g.first_name)
+            out += RenderProperty("og:profile:first_name", g.first_name);
+        if (g.last_name)
+            out += RenderProperty("og:profile:last_name", g.last_name);
+        if (g.username)
+            out += RenderProperty("og:profile:username", g.username);
+        if (g.gender)
+            out += RenderProperty("og:profile:gender", g.gender);
+    }
+    return "";
+}
+const escapeTo = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    "\"": "&quot;",
+    "'": "&#39;",
+};
+function EscapeHTML(str) {
+    return str.replace(/[&<>"']/g, (match) => escapeTo[match] || match);
+}

package/util/parameters.d.ts

@@ -0,0 +1,10 @@
+export type ParameterShaper = Record<string, (val: string) => any>;
+export type ParameterPrelude<T extends ParameterShaper> = {
+    [K in keyof T]: string;
+};
+export type Parameterized<T extends ParameterShaper> = {
+    [K in keyof T]: ReturnType<T[K]>;
+};
+export type Parameterizer<T extends ParameterShaper> = {
+    [K in keyof T]: (val: ReturnType<T[K]>) => string;
+};

package/util/parameters.js

@@ -0,0 +1 @@
+export {};

package/util/path-builder.d.ts

@@ -0,0 +1 @@
+export {};