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

package/readme.md

@@ -1,217 +1,5 @@
 # htmx Router
 
-A simple file based router with support for dynamic + client islands, route-less endpoints, and built in CSS sheet generation.
+A simple file based router with support for: dynamic + client islands; route-less endpoints; client/server bundle spitting, and built in CSS sheet generation.
 
-- [htmx Router](#htmx-router)
-	- [Setup](#setup)
-	- [Routing](#routing)
-		- [Route Module](#route-module)
-		- [Nested Route Rendering](#nested-route-rendering)
-		- [JSX Rendering](#jsx-rendering)
-	- [Route Contexts](#route-contexts)
-		- [Params](#params)
-		- [Cookies](#cookies)
-		- [Headers](#headers)
-		- [Request](#request)
-		- [URL](#url)
-	- [Style Sheets](#style-sheets)
-	- [Route-less Endpoint](#route-less-endpoint)
-	- [Islands](#islands)
-		- [Dynamic](#dynamic)
-		- [Client](#client)
-
-
-## Setup
-
-Create a `htmx-router.json` in the root of your project defining where you want your router file to be placed, and where your routes are.
-You can also define where you want to create your client component bindings, and for what target framework.
-```json
-{
-	"router": {
-		"folder": "./source/routes",
-		"output": "./source/router.tsx"
-	},
-	"client": {
-		"adapter": "react",
-		"source": "./source/client.tsx"
-	}
-}
-```
-
-Once you have done this, run `npx htmx-router` to generate the artifacts to start development.
-We recommand you copy the setup from `examples/react` for your `server.js`, `entry.server.ts`, and `entry.client.ts`.
-
-Don't forget that in all rendered routes you must include the `<RouterHeader/>` component in your head for hydration and `StyleClass`s to apply affectively.
-
-
-## Routing
-
-Routing applies in a depth first order, where it will match in order:
-  1. The `_index`
-  2. Static sub-routes
-  3. Url path-param wildcards
-  4. Catchall slug
-
-This allows for easy overriding and fallback behaviour. For instance with the routes.
-```
-/user/$id.tsx
-/user/me.tsx
-/user/$.tsx
-```
-
-It will match on the `/user/me` route if applicable, and otherwise will fallback to attempt to match on `/user/$id`, and if the wildcard route fails, it will try the generic slug route `/user/$.tsx`.
-
-If a route returns `null` the router will continue the depth first search, allowing for dynamic flow through of the routes.
-
-### Route Module
-
-A route module must define a `parameters` export, which defines how the url path params should be parsed when attempting to match the route.
-You can use any function which takes a string, and returns something as the parser. You can also simply use JS-Builtin functions for this, and there is a special case with the `Number` function so it will reject on `NaN` values.
-```js
-export const parameters = { id: Number };
-```
-
-A route can additionally define a loader, which is called on `GET` and `HEAD` requests
-```ts
-export async function loader({}: RouteContext<typeof parameters>);
-```
-
-With the `action` function being called for all other methods
-```ts
-export async function action({}: RouteContext<typeof parameters>);
-```
-
-If any value is thrown by the parameter parsing, or the render functions (`loader`/`action`) it will boil up, attempting first to call an error function is supplied in the route, and otherwise boiling up to the nearest slug route's `error` function.
-```ts
-export async function error(ctx: GenericContext, error: unknown);
-```
-
-### Nested Route Rendering
-
-The router will not do nested layouts, if that behaviour is required we recommend using the slug-shell pattern.
-Where you define a slug route, and export a `shell` function which takes the `JSX` rendered result from the sub route, and renders the upper route around it.
-
-This allows flexibility at runtime on how nested route rendering behaves, and can also allow you to ensure you are not reloading data from the db which is already loaded by a sub-route based on how you parse up data through your slug shells.
-
-We recommend you look at [Predictable Bot](https://github.com/AjaniBilby/predictable) as an example of this pattern performed simply.
-
-
-### JSX Rendering
-
-htmx-router is jsx templating agnostic for SSR, instead only requiring a definition provided when creating your request handler, allowing you to BYO JSX templating.
-```js
-// @kitajs/html
-app.use('*', createRequestHandler.http({
-	build,
-	viteDevServer,
-	render: (res) => {
-		const headers = new Headers();
-		headers.set("Content-Type", "text/html; charset=UTF-8");
-		return new Response(String(res), { headers });
-	}
-}));
-
-// React
-app.use('*', createRequestHandler.http({
-	build,
-	viteDevServer,
-	render: (res) => {
-		const headers = new Headers();
-		headers.set("Content-Type", "text/html; charset=UTF-8");
-		return new Response(renderToString(res), { headers });
-	}
-}));
-```
-
-## Route Contexts
-
-There are two kinds of route context, the `RouteContext<T>` which is the resolved route with parameterization, and the `GenericContext` which is used by error functions, and dynamic loads.
-
-### Params
-
-In the `GenericContext` this will simply be an object with string key value pairs for the parameters, and only the `RouteContext<T>` for `loader` and `action` will have the parameters pre-parsed by your `parameters` definition.
-
-### Cookies
-
-The `RouteContext` and `GenericContext`s both provide a `cookie` object, with the cookie's pre-parsed from the request headers.
-It also has a built in `set(name, value, options)` function which will add the appropriate headers to the response for the cookie changes.
-
-### Headers
-
-This is a header object useful for adding response headers when you haven't fully finished generating your response yet.
-These headers will merge with the response object created by the provided `render` function, with response headers overriding any conflicting `ctx.headers` values.
-
-### Request
-
-This is the original request object, including request headers.
-
-### URL
-
-The parsed `URL` object of the incoming request.
-
-## Style Sheets
-
-htmx-router includes a `StyleClass` object, which can be used to define CSS classes without needing a unique name.
-StyleClasses should only be defined at the top level of a file, and not created within a function, or dynamically during runtime.
-
-```ts
-const myClass = new StyleClass(`myClass`, `
-.this:hover {
-	background-color: red;
-}
-`).name;
-```
-
-## Route-less Endpoint
-
-This should be defined at the top level of your file, these endpoints can optionally be given an name which will help for debugging network requests, but they do not need to be unique.
-```ts
-const endpoint_url = new Endpoint((ctx: GenericContext) => {
-	return new Response("Hello World");
-}, "hello-world").url;
-```
-
-## Islands
-
-> Tip: Don't forget to wrap your islands in a hx-preserve to prevent losing state. And use `display: contents;` to make that wrapping div transparent for grid and other layout features.
-
-### Dynamic
-
-A dynamic component takes params which will be converted into the props of the loader function, these props may only be string key string value pairs as they are encoded the the query string to allow for browser side caching.
-
-The body of a dynamic component is the pre-rendered infill that will display while the client is loading the dynamic content.
-
-```tsx
-async function MyProfile(params: {}, ctx: GenericContext): Promise<JSX.Element> {
-	ctx.headers.set('Cache-Control', "private, max-age=120");
-	const userID = ctx.cookie.get('userID');
-	if (!userID) return <></>;
-
-	const user = await GetUser(userID);
-	if (!user) return <></>;
-
-	return <a href={`/user/${userID}`}>
-		<div safe>{user.name}</div>
-	</a>
-}
-
-export async function loader({ params }: RouteContext<typeof parameters>) {
-	return <Dynamic params={{}} loader={MyProfile}>
-		put your ssr pre-rendered skeleton here
-	</Dynamic>
-}
-```
-
-### Client
-
-Import all of the components you want to be able to use on the client side into your `client.tsx`, if you are running a dev server this file will automatically generate the clientized version, otherwise use the `npx htmx-router` command to regenerate these artifacts.
-
-Once a component has been clientized you can import it as use it like normal, however the body is now overwritten to it will render immediately on the server, and then all props will parsed to the client for it to be rendered properly in the browser.
-
-```tsx
-<Client.Counter>
-	<button>No yet hydrated...</button> {/* this will be overwritten in the browser once hydrated */}
-</Client.Counter>
-```
-
-It is very important that you ensure your `Client` component has a single child element, if there are multiple child components the browser will only mount to the last child causing artifacting.
+> Apologies the docs have not yet been updated for this version, please wait for the final release for actual docs.

package/{bin/request → request}/http.d.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "http";
 import type { ViteDevServer } from "vite";
-import { GenericContext } from "../router.js";
+import type { GenericContext } from "~/router.js";
 type Config = {
     build: Promise<any> | (() => Promise<Record<string, any>>);
     viteDevServer: ViteDevServer | null;

package/{bin/request → request}/http.js

@@ -1,4 +1,4 @@
-import { Resolve } from "../request/native.js";
+import { Resolve } from "~/request/native.js";
 export function createRequestHandler(config) {
     return async (req, res) => {
         try {
@@ -6,8 +6,20 @@ export function createRequestHandler(config) {
             const request = NativeRequest(req);
             let { response, headers } = await Resolve(request, mod.tree, config);
             res.writeHead(response.status, headers);
-            let rendered = await response.text();
-            res.end(rendered);
+            if (response.body instanceof ReadableStream) {
+                const reader = response.body.getReader();
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    res.write(value); // `value` is a Uint8Array.
+                }
+                res.end();
+            }
+            else {
+                const rendered = await response.text();
+                res.end(rendered);
+            }
         }
         catch (e) {
             res.statusCode = 500;
@@ -29,7 +41,7 @@ function NativeRequest(req) {
     const url = new URL(`http://${headers.get('host')}${req.originalUrl || req.url}`);
     req.once('aborted', () => ctrl.abort());
     const bodied = req.method !== "GET" && req.method !== "HEAD";
-    return new Request(url, {
+    const request = new Request(url, {
         headers,
         method: req.method,
         body: bodied ? req : undefined,
@@ -38,4 +50,10 @@ function NativeRequest(req) {
         // @ts-ignore
         duplex: bodied ? 'half' : undefined
     });
+    if (!request.headers.has("X-Real-IP")) {
+        const info = req.socket.address();
+        if ("address" in info)
+            request.headers.set("X-Real-IP", info.address);
+    }
+    return request;
 }

package/request/index.d.ts

@@ -0,0 +1,13 @@
+import type { ViteDevServer } from "vite";
+import type { GenericContext, RouteTree } from '~/router.js';
+import * as native from "~/request/native.js";
+import * as http from "~/request/http.js";
+export type Config = {
+    build: Promise<any> | (() => Promise<Record<string, any>>);
+    viteDevServer: ViteDevServer | null;
+    render: GenericContext["render"];
+};
+export type RouterModule = {
+    tree: RouteTree;
+};
+export { http, native };

package/request/index.js

@@ -0,0 +1,3 @@
+import * as native from "~/request/native.js";
+import * as http from "~/request/http.js";
+export { http, native };

package/request/native.d.ts

@@ -0,0 +1,9 @@
+import { type RouteTree } from '~/router.js';
+import type { Config } from '~/request/index.js';
+export declare function createRequestHandler(config: Config): (req: Request) => Promise<Response>;
+export declare function Resolve(request: Request, tree: RouteTree, config: Config): Promise<{
+    response: Response;
+    headers: {
+        [key: string]: string | string[];
+    };
+}>;

package/{bin/request → request}/native.js

@@ -1,4 +1,4 @@
-import { GenericContext } from '../router.js';
+import { GenericContext } from '~/router.js';
 export function createRequestHandler(config) {
     return async (req) => {
         try {
@@ -30,7 +30,7 @@ export async function Resolve(request, tree, config) {
     // Override with context headers
     if (response.headers !== ctx.headers) {
         for (const [key, value] of ctx.headers) {
-            if (ctx.headers.has(key))
+            if (response.headers.has(key))
                 continue;
             response.headers.set(key, value);
         }

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

@@ -1,7 +1,9 @@
 export declare function text(text: string, init?: ResponseInit): Response;
-export declare function json<T>(data: T, init?: ResponseInit): Omit<Response, "json"> & {
+export type TypedResponse<T> = Omit<Response, "json"> & {
     json(): Promise<T>;
 };
+export type TypedJson<U extends TypedResponse<any>> = U extends TypedResponse<infer T> ? T : never;
+export declare function json<T>(data: T, init?: ResponseInit): TypedResponse<T>;
 export declare function redirect(url: string, init?: ResponseInit & {
     clientOnly?: boolean;
 }): Response;

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

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

package/{bin/router.d.ts → router.d.ts}

@@ -1,6 +1,7 @@
 import { Parameterized, ParameterShaper } from './util/parameters.js';
-import { RouteModule } from "./types.js";
-import { Cookies } from './util/cookies.js';
+import { RouteModule } from "./index.js";
+import { Cookies } from './cookies.js';
+export declare function GenerateRouteTree(modules: Record<string, unknown>): RouteTree;
 export declare class GenericContext {
     request: Request;
     headers: Headers;
@@ -13,7 +14,7 @@ export declare class GenericContext {
     constructor(request: GenericContext["request"], url: GenericContext["url"], renderer: GenericContext["render"]);
     shape<T extends ParameterShaper>(shape: T): RouteContext<T>;
 }
-export declare class RouteContext<T extends ParameterShaper> {
+export declare class RouteContext<T extends ParameterShaper = {}> {
     request: Request;
     headers: Headers;
     cookie: Cookies;
@@ -22,13 +23,6 @@ export declare class RouteContext<T extends ParameterShaper> {
     render: (res: JSX.Element) => Response;
     constructor(base: GenericContext, shape: T);
 }
-export declare class RouteLeaf {
-    module: RouteModule<any>;
-    constructor(module: RouteModule<any>);
-    resolve(ctx: GenericContext): Promise<Response | null>;
-    error(ctx: GenericContext, e: unknown): Promise<Response>;
-    private renderWrapper;
-}
 export declare class RouteTree {
     root: boolean;
     nested: Map<string, RouteTree>;
@@ -47,3 +41,11 @@ export declare class RouteTree {
     private resolveNative;
     private unwrap;
 }
+declare class RouteLeaf {
+    module: RouteModule<any>;
+    constructor(module: RouteModule<any>);
+    resolve(ctx: GenericContext): Promise<Response | null>;
+    error(ctx: GenericContext, e: unknown): Promise<Response>;
+    private renderWrapper;
+}
+export {};

package/{bin/router.js → router.js}

@@ -1,9 +1,23 @@
-import * as endpoint from './util/endpoint.js';
-import * as dynamic from './util/dynamic.js';
-import * as mount from './client/mount.js';
-import * as css from './util/css.js';
+import { ServerOnlyWarning } from "./internal/util.js";
+ServerOnlyWarning("router");
+import * as endpoint from './endpoint.js';
+import * as dynamic from './dynamic.js';
+import * as mount from './internal/mount.js';
+import * as css from './css.js';
 import { Parameterize } from './util/parameters.js';
-import { Cookies } from './util/cookies.js';
+import { Cookies } from './cookies.js';
+export function GenerateRouteTree(modules) {
+    const tree = new RouteTree();
+    for (const path in modules) {
+        const mod = modules[path];
+        const tail = path.lastIndexOf(".");
+        const url = path.slice(9, tail);
+        tree.ingest(url, mod);
+        if (mod.route)
+            mod.route(url);
+    }
+    return tree;
+}
 export class GenericContext {
     request;
     headers; // response headers
@@ -40,48 +54,6 @@ export class RouteContext {
         this.url = base.url;
     }
 }
-export 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;
-    }
-}
 export class RouteTree {
     root;
     nested;
@@ -206,6 +178,48 @@ export class RouteTree {
         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;
+    }
+}
 async function ResolveNatively(fragments, ctx) {
     switch (fragments[1]) {
         case "dynamic": return dynamic._resolve(fragments, ctx);

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

@@ -1,3 +1,5 @@
+import { ServerOnlyWarning } from "./internal/util.js";
+ServerOnlyWarning("shell");
 export function ApplyMetaDescriptorDefaults(options, defaults) {
     if (defaults.title && !options.title)
         options.title = defaults.title;
@@ -22,7 +24,7 @@ export function RenderMetaDescriptor(options) {
         }
     if (options.jsonLD)
         for (const json of options.jsonLD) {
-            out += `<script>${EscapeHTML(JSON.stringify(json))}</script>\n`;
+            out += `<script type="application/ld+json">${JSON.stringify(json)}</script>\n`;
         }
     // Auto apply og:title + og:description if not present
     if (options.title && !options.og?.title)

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

@@ -1,6 +1,3 @@
-/**
- * This is used by GenericContext to convert itself to a RouteContext<T>
- */
 export type Parameterized<T extends ParameterShaper> = {
     [K in keyof T]: ReturnType<T[K]>;
 };

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

@@ -1,6 +1,3 @@
-/**
- * This is used by GenericContext to convert itself to a RouteContext<T>
- */
 export function Parameterize(params, shape) {
     const out = {};
     for (const key in shape) {

package/{bin/util → util}/path-builder.js

@@ -1,3 +1,5 @@
+import { ServerOnlyWarning } from "../internal/util.js";
+ServerOnlyWarning("path-builder");
 import { relative } from "path";
 /*
 // This feature is disabled because vite doesn't compile import.meta.url to the original url when making the SSR build

package/util/route.d.ts

@@ -0,0 +1,2 @@
+import { ParameterShaper } from "./parameters.js";
+export declare function RoutePath<T extends ParameterShaper>(): (params: { [K in keyof T]: string; }) => string;

package/util/route.js

@@ -0,0 +1,58 @@
+import { ServerOnlyWarning } from "../internal/util.js";
+ServerOnlyWarning("route-path");
+export function RoutePath() {
+    const frags = new Array();
+    return (params) => {
+        const t = params;
+        if (typeof t === "string") {
+            Compile("/" + t, frags);
+            return "";
+        }
+        return Parse(frags, params);
+    };
+}
+const indexRoute = "/_index";
+function Compile(url, into) {
+    let cursor = 0;
+    let i = 1;
+    for (; i < url.length; i++) {
+        if (url[i] !== "$")
+            continue;
+        if (url[i - 1] !== "/")
+            continue;
+        let e = url.indexOf("/", i + 1);
+        if (e === -1)
+            e = url.length;
+        into.push(url.slice(cursor, i));
+        into.push(url.slice(i, e));
+        cursor = e;
+        i = e - 1;
+    }
+    // remainder
+    if (cursor != i)
+        into.push(url.slice(cursor));
+    // remove _index from end if present
+    const lastI = into.length - 1;
+    const last = into[lastI];
+    if (last && last.endsWith(indexRoute)) {
+        if (last.length === indexRoute.length)
+            into.length--;
+        else
+            into[lastI] = last.slice(0, -indexRoute.length);
+    }
+}
+function Parse(fragments, params) {
+    let out = "";
+    for (const frag of fragments) {
+        if (!frag.startsWith("$")) {
+            out += frag;
+            continue;
+        }
+        const key = frag.slice(1);
+        const param = params[key];
+        if (!param)
+            throw new Error(`Missing ${key} parameter required for route`);
+        out += param;
+    }
+    return out;
+}

package/vite/bundle-splitter.d.ts

@@ -0,0 +1,4 @@
+import type { UserConfig } from "vite";
+type Plugin = NonNullable<UserConfig["plugins"]>[number];
+export declare function BundleSplitter(): Plugin;
+export {};