redweb 0.9.0 → 0.10.0

package/index.d.ts

@@ -2,6 +2,7 @@ declare module 'redweb' {
     import { Application } from 'express';
     import { CorsOptions } from 'cors';
     import { Server as NodeHttpServer } from 'http';
+    import { Server as NodeHttpsServer } from 'https';
     import { WebSocket, ServerOptions } from 'ws';
     import { Buffer } from 'buffer';
     import { EventEmitter } from 'events';
@@ -21,7 +22,6 @@ declare module 'redweb' {
         ssl?: { key: string; cert: string };
         server?: Application;
         corsOptions?: CorsOptions | false;
-        enableHtmxRendering?: boolean;
         exposeErrors?: boolean;
         logger?: RedWebLogger | null;
     }
@@ -402,6 +402,224 @@ declare module 'redweb' {
         shutdown(): Promise<void>;
     }
 
+    /** ─────────────────── LIVE HTML ─────────────────── */
+
+    const htmlFragmentBrand: unique symbol;
+    const htmlAttributeBrand: unique symbol;
+    const htmlUrlBrand: unique symbol;
+
+    export interface HtmlFragment {
+        readonly [htmlFragmentBrand]: true;
+        toString(): string;
+    }
+
+    export interface HtmlAttribute {
+        readonly [htmlAttributeBrand]: true;
+    }
+
+    export interface HtmlUrl {
+        readonly [htmlUrlBrand]: true;
+    }
+
+    export interface LivePageRequest {
+        readonly path: string;
+        readonly url: string;
+        readonly method: string;
+        readonly headers: import('http').IncomingHttpHeaders;
+        readonly params: Readonly<Record<string, string>>;
+        readonly query: Readonly<Record<string, unknown>>;
+        readonly body: unknown;
+        get(name: string): string | undefined;
+    }
+
+    export interface LivePageRequestContext {
+        request: LivePageRequest;
+        params: Readonly<Record<string, string>>;
+        query: Readonly<Record<string, unknown>>;
+        body: unknown;
+        principal?: string | number | bigint | boolean;
+        signal: AbortSignal;
+    }
+
+    export interface LivePageConnectionContext {
+        socket: RedWebSocket;
+        signal?: AbortSignal;
+        principal?: string | number | bigint | boolean;
+    }
+
+    export abstract class LivePage {
+        protected readonly _connections: Set<RedWebSocket>;
+        loading?(context: LivePageRequestContext): void | Promise<void>;
+        render?(context: LivePageRequestContext): string | HtmlFragment | Promise<string | HtmlFragment>;
+        connected?(context: LivePageConnectionContext): void | Promise<void>;
+        disconnected?(context: { socket: RedWebSocket }): void | Promise<void>;
+        disposed?(): void | Promise<void>;
+        dispose(): Promise<boolean>;
+    }
+
+    export interface PageOptions {
+        template?: string;
+        css?: string | readonly string[];
+        scope?: 'connection' | 'shared';
+        shared?: boolean;
+        live?: boolean;
+        head?: PageHead;
+        cache?: PageCache;
+        layout?: PageLayout;
+    }
+
+    export type PageLayout = (content: HtmlFragment, context: LivePageRequestContext) => HtmlFragment;
+
+    export interface PageHead {
+        title?: string;
+        description?: string;
+        canonical?: string;
+        image?: string;
+        robots?: string;
+    }
+
+    export interface PageCache {
+        maxAge?: number;
+        staleWhileRevalidate?: number;
+        immutable?: boolean;
+    }
+
+    export interface StateOptions {
+        writable?: boolean;
+    }
+
+    export interface LiveStateDecorator {
+        (target: object, propertyKey: string): void;
+        <This, Value>(value: undefined, context: ClassFieldDecoratorContext<This, Value>):
+            (this: This, initialValue: Value) => Value;
+    }
+
+    export interface LiveActionDecorator {
+        (target: object, propertyKey: string, descriptor: PropertyDescriptor): void | PropertyDescriptor;
+        <This, Value extends (this: This, ...args: any[]) => any>(
+            value: Value,
+            context: ClassMethodDecoratorContext<This, Value>
+        ): Value;
+    }
+
+    export interface LiveViewDecorator {
+        (target: object, propertyKey: string, descriptor: PropertyDescriptor): void | PropertyDescriptor;
+        <This, Value extends (this: This, item: any, index: number) => HtmlFragment>(
+            value: Value,
+            context: ClassMethodDecoratorContext<This, Value>
+        ): Value;
+    }
+
+    export function page(path: string, options?: PageOptions): ClassDecorator;
+    export function component(): ClassDecorator;
+    export function component<Props = void>(render: (properties: Props) => HtmlFragment):
+        (properties: Props) => HtmlFragment;
+    export function state(options?: StateOptions): LiveStateDecorator;
+    export function action(): LiveActionDecorator;
+    export function view(stateName: string): LiveViewDecorator;
+    export function html(strings: TemplateStringsArray, ...values: unknown[]): HtmlFragment;
+    export function attribute(value: string | number | bigint | boolean): HtmlAttribute;
+    export function url(value: string): HtmlUrl;
+    export function each<Item>(items: readonly Item[], render: (item: Item, index: number) => HtmlFragment): HtmlFragment;
+    export function codeBlock(code: unknown, options?: {
+        language?: string;
+        label?: string;
+        highlight?: (source: string, language: string) => HtmlFragment;
+    }): HtmlFragment;
+
+    export type LivePageClass = new () => object;
+
+    export interface LiveHtmlServerOptions extends Omit<RedWebOptions, 'enableHtmxRendering'> {
+        pages: readonly LivePageClass[];
+        templateRoot?: string;
+        livePaths?: {
+            socket?: string;
+            client?: string;
+            runtime?: string;
+            css?: string;
+        };
+        sessionTtlMs?: number;
+        maxSessions?: number;
+        maxConcurrentRenders?: number;
+        shutdownTimeoutMs?: number;
+        heartbeat?: HeartbeatOptions;
+        authenticate?(request: import('http').IncomingMessage | import('express').Request):
+            string | number | bigint | boolean | false | null | undefined |
+            Promise<string | number | bigint | boolean | false | null | undefined>;
+        origins?: string[] | ((origin: string | undefined, request: import('http').IncomingMessage) => boolean | Promise<boolean>);
+    }
+
+    export class LiveHtmlServer {
+        app: Application;
+        server: NodeHttpServer | NodeHttpsServer;
+        http: HttpServer | HttpsServer;
+        sockets: SocketServer | null;
+        constructor(options: LiveHtmlServerOptions);
+        shutdown(): Promise<void>;
+    }
+
+    export function start(
+        pageOrPages: LivePageClass | readonly LivePageClass[],
+        options?: Omit<LiveHtmlServerOptions, 'pages'>
+    ): LiveHtmlServer;
+
+    export interface StaticExportOptions {
+        outDir: string;
+        templateRoot?: string;
+        logger?: RedWebLogger | null;
+    }
+
+    export interface StaticExportResult {
+        readonly pages: readonly string[];
+        readonly assets: readonly string[];
+    }
+
+    export function exportStatic(
+        pageOrPages: LivePageClass | readonly LivePageClass[],
+        options: StaticExportOptions
+    ): Promise<StaticExportResult>;
+
+    export interface SiteOptions {
+        origin?: string;
+        css?: string | readonly string[];
+        head?: PageHead;
+        cache?: PageCache;
+        layout?: PageLayout;
+    }
+
+    export interface SitePageOptions extends Omit<PageOptions, 'live'> {
+        live?: false;
+    }
+
+    export interface SiteExportOptions extends StaticExportOptions {
+        publicDir?: string;
+    }
+
+    export interface StaticSite {
+        page(path: string, options?: SitePageOptions): ClassDecorator;
+        export(
+            pageOrPages: LivePageClass | readonly LivePageClass[],
+            options: SiteExportOptions
+        ): Promise<StaticExportResult>;
+    }
+
+    export function defineSite(options?: SiteOptions): StaticSite;
+
+    export class HtmlRenderer {
+        static template(filePath: string, rootDir: string): string;
+        static stylesheet(filePath: string, rootDir: string): string;
+        static render(source: string, page: object, options?: { live?: boolean }): string;
+        static collection(page: object, name: string, value: unknown): string;
+        static statePayload(name: string, value: unknown, page?: object): { name: string; value: string; html: boolean };
+        static head(metadata?: PageHead): string;
+        static document(
+            markup: string,
+            config?: (Record<string, unknown> & { runtimePath: string }) | null,
+            stylesheets?: string[],
+            metadata?: PageHead
+        ): string;
+    }
+
     /** ─────────────────── CONSTANTS ─────────────────── */
 
     export const METHODS: {

package/index.js

@@ -16,6 +16,7 @@ const {
 const { BaseHandler } = require('./src/ws/BaseHandler');
 const HttpServer = require('./src/http/HttpServer');
 const HttpsServer = require('./src/http/HttpsServer');
+const { action, attribute, codeBlock, component, defineSite, each, exportStatic, html, HtmlRenderer, LiveHtmlServer, LivePage, page, start, state, url, view } = require('./src/htmx');
 module.exports = {
     HttpServer,
     HttpsServer,
@@ -34,5 +35,21 @@ module.exports = {
     SOCKET_OPTIONS,
     HTTP_OPTIONS,
     ENCODINGS,
-    METHODS
+    METHODS,
+    action,
+    attribute,
+    codeBlock,
+    component,
+    defineSite,
+    each,
+    exportStatic,
+    html,
+    HtmlRenderer,
+    LiveHtmlServer,
+    LivePage,
+    page,
+    start,
+    state,
+    url,
+    view
 };

package/package.json

@@ -1,17 +1,26 @@
 {
   "name": "redweb",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A way to quickly set up an express server",
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {
-    "pretest": "node scripts/generate-protocol-types.js --check && tsc -p tests/types/tsconfig.json",
+    "pretest": "node scripts/build-live-html-examples.js --check && node scripts/generate-protocol-types.js --check && tsc -p tests/types/tsconfig.json && tsc -p tests/types/tsconfig.standard.json",
+    "prepack": "node scripts/build-live-html-examples.js --check",
+    "example:counter": "node examples/live-html/counter.js",
+    "example:chatroom": "node examples/live-html/chatroom.js",
+    "example:cards": "node examples/live-html/cards.js",
+    "example:components": "node examples/live-html/components.js",
     "generate:protocol-types": "node scripts/generate-protocol-types.js",
     "verify:overhead": "node scripts/verify-disabled-overhead.js",
     "verify:soak": "node --expose-gc scripts/verify-soak.js",
     "verify:memory": "node scripts/verify-memory-overhead.js",
     "verify:load": "node scripts/verify-load.js",
     "verify:recovery": "node --expose-gc scripts/verify-recovery.js",
+    "verify:live-html": "node scripts/build-live-html-examples.js --check && npx jest tests/integration/live-html.integration.test.js --runInBand --coverage=false",
+    "verify:live-html:browser": "node scripts/build-live-html-examples.js --check && node scripts/verify-live-html-browser.js",
+    "verify:live-html:load": "node scripts/build-live-html-examples.js --check && node --expose-gc scripts/verify-live-html-load.js",
+    "verify:live-html:package": "node scripts/verify-live-html-package.js",
     "test": "npx jest"
   },
   "files": [
@@ -20,7 +29,8 @@
     "client.d.ts",
     "CHANGELOG.md",
     "index.d.ts",
-    "docs"
+    "docs",
+    "examples/live-html"
   ],
   "keywords": [],
   "author": "",
@@ -35,6 +45,7 @@
     "@types/ws": "^8.18.1",
     "cors": "^2.8.5",
     "express": "^4.22.2",
+    "redweb-client": "^0.1.0",
     "ws": "^8.21.3"
   },
   "devDependencies": {

package/src/htmx/Html.js

@@ -0,0 +1,133 @@
+const HTML_FRAGMENT = Symbol('redweb.htmlFragment');
+const HTML_ATTRIBUTE = Symbol('redweb.htmlAttribute');
+const HTML_URL = Symbol('redweb.htmlUrl');
+const HTML_RENDERERS = new WeakMap();
+const URL_ATTRIBUTES = new Set(['action', 'background', 'cite', 'data', 'formaction', 'href', 'manifest', 'ping', 'poster', 'src', 'xlink:href']);
+const FORBIDDEN_ATTRIBUTES = new Set(['srcdoc', 'srcset', 'style']);
+const { interpolationContext } = require('./HtmlSyntax');
+const synchronous = require('./synchronous');
+
+function escapeHtml(value) {
+    return String(value ?? '')
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+
+function isHtml(value) {
+    if (Array.isArray(value)) return value.every(isHtml);
+    return Boolean(value?.[HTML_FRAGMENT]) || Boolean(value && typeof value === 'object' && HTML_RENDERERS.has(value));
+}
+
+function markHtml(value, toString) {
+    HTML_RENDERERS.set(value, toString);
+    return value;
+}
+
+function trustedHtml(value) {
+    const fragment = {};
+    markHtml(fragment, () => String(value));
+    return Object.freeze(fragment);
+}
+
+function trustedValue(brand, value) {
+    return Object.freeze({ [brand]: true, value: String(value) });
+}
+
+function attribute(value) {
+    if (!['string', 'number', 'bigint', 'boolean'].includes(typeof value)) {
+        throw new TypeError('attribute() requires a string, number, bigint, or boolean.');
+    }
+    return trustedValue(HTML_ATTRIBUTE, value);
+}
+
+function safeUrl(value) {
+    if (typeof value !== 'string' || !value || value !== value.trim() || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new TypeError('url() requires a non-empty URL without surrounding whitespace or control characters.');
+    }
+    if (value.startsWith('//') || value.includes('\\')) throw new TypeError('url() does not allow protocol-relative or backslash URLs.');
+    const protocol = /^[A-Za-z][A-Za-z0-9+.-]*:/.exec(value)?.[0].toLowerCase();
+    if (protocol && !['http:', 'https:', 'mailto:', 'tel:'].includes(protocol)) {
+        throw new TypeError(`url() does not allow the ${protocol} protocol.`);
+    }
+    return trustedValue(HTML_URL, value);
+}
+
+function renderValue(value) {
+    if (Array.isArray(value)) {
+        if (!isHtml(value)) throw new TypeError('Only arrays of HtmlFragment values can be rendered as HTML.');
+        return value.map(renderValue).join('');
+    }
+    if (HTML_RENDERERS.has(value)) return HTML_RENDERERS.get(value).call(value);
+    return isHtml(value) ? value.toString() : escapeHtml(value);
+}
+
+function renderInterpolation(source, value) {
+    const context = interpolationContext(source);
+    if (context.kind === 'attribute') {
+        const name = context.name;
+        if (name.startsWith('on') || FORBIDDEN_ATTRIBUTES.has(name)) {
+            throw new TypeError(`Dynamic ${name} attributes are not allowed.`);
+        }
+        if (URL_ATTRIBUTES.has(name)) {
+            if (!value?.[HTML_URL]) {
+                if (value?.[HTML_ATTRIBUTE]) throw new TypeError(`The ${name} attribute requires url().`);
+                value = safeUrl(value);
+            }
+        } else if (!value?.[HTML_ATTRIBUTE]) {
+            if (value?.[HTML_URL]) throw new TypeError(`The ${name} attribute requires attribute().`);
+            if (isHtml(value)) throw new TypeError(`The ${name} attribute requires a primitive value.`);
+            value = attribute(value);
+        }
+        return escapeHtml(value.value);
+    }
+    if (context.kind !== 'text') throw new TypeError('html interpolations are only allowed in element text.');
+    if (value?.[HTML_ATTRIBUTE] || value?.[HTML_URL]) {
+        throw new TypeError('attribute() and url() values may only be used in matching quoted attributes.');
+    }
+    return renderValue(value);
+}
+
+function html(strings, ...values) {
+    if (!Array.isArray(strings) || !Object.prototype.hasOwnProperty.call(strings, 'raw')) {
+        throw new TypeError('html must be used as a tagged template literal.');
+    }
+    const rendered = strings.reduce((result, part, index) => {
+        const next = result + part;
+        if (index >= values.length) return next;
+        return next + renderInterpolation(next, values[index]);
+    }, '');
+    return Object.freeze({ [HTML_FRAGMENT]: true, toString: () => rendered });
+}
+
+function each(items, render) {
+    if (!Array.isArray(items)) throw new TypeError('each() requires an array.');
+    if (typeof render !== 'function') throw new TypeError('each() requires a render function.');
+    const fragments = items.map((item, index) => render(item, index));
+    if (!fragments.every(isHtml)) throw new TypeError('each() render functions must return html fragments.');
+    return Object.freeze({ [HTML_FRAGMENT]: true, toString: () => fragments.map(renderValue).join('') });
+}
+
+function codeBlock(code, options = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError('codeBlock() options must be an object.');
+    }
+    const { language = 'text', label = language, highlight } = options;
+    if (typeof language !== 'string' || !/^[A-Za-z0-9_+-]{1,32}$/.test(language)) {
+        throw new TypeError('codeBlock() language must be a safe name of at most 32 characters.');
+    }
+    if (typeof label !== 'string') throw new TypeError('codeBlock() label must be a string.');
+    if (highlight !== undefined && typeof highlight !== 'function') throw new TypeError('codeBlock() highlight must be a function.');
+    const caption = label ? html`<figcaption>${label}</figcaption>` : html``;
+    let content = isHtml(code) ? code : String(code ?? '');
+    if (highlight) {
+        if (isHtml(code)) throw new TypeError('codeBlock() cannot highlight an HtmlFragment.');
+        content = synchronous(highlight(content, language), 'codeBlock() highlight must render synchronously.');
+        if (!isHtml(content)) throw new TypeError('codeBlock() highlight must return an HtmlFragment.');
+    }
+    return html`<figure class="redweb-code">${caption}<pre><code class="${attribute(`language-${language}`)}">${content}</code></pre></figure>`;
+}
+
+module.exports = { attribute, codeBlock, each, escapeHtml, html, isHtml, markHtml, renderValue, safeUrl, trustedHtml };

package/src/htmx/HtmlRenderer.js

@@ -0,0 +1,88 @@
+const { escapeHtml, isHtml, renderValue } = require('./Html');
+const PageAssetLoader = require('./PageAssetLoader');
+const TemplateRenderer = require('./TemplateRenderer');
+const { getStateConfig, getViewMetadata } = require('./metadata');
+
+function serializeJson(value) {
+    return JSON.stringify(value).replaceAll('<', '\\u003c');
+}
+
+function meta(attribute, name, content) {
+    return `<meta ${attribute}="${escapeHtml(name)}" content="${escapeHtml(content)}">`;
+}
+
+class HtmlRenderer {
+    static file(filePath, rootDir, kind) {
+        return new PageAssetLoader().load(filePath, rootDir, kind).content;
+    }
+
+    static template(filePath, rootDir) {
+        return HtmlRenderer.file(filePath, rootDir, 'template');
+    }
+
+    static stylesheet(filePath, rootDir) {
+        return HtmlRenderer.file(filePath, rootDir, 'stylesheet');
+    }
+
+    static render(source, page, options = {}) {
+        if (typeof source !== 'string') throw new TypeError('Page markup must be a string.');
+        if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Render options must be an object.');
+        const { live = true } = options;
+        if (typeof live !== 'boolean') throw new TypeError('Render live must be a boolean.');
+        return new TemplateRenderer(source, page, HtmlRenderer.collection, live).render();
+    }
+
+    static collection(page, name, value) {
+        if (!getStateConfig(page.constructor, name)) throw new Error(`Page collection "${name}" is missing @state metadata.`);
+        if (!Array.isArray(value)) throw new TypeError(`Page collection "${name}" must be an array.`);
+        const view = getViewMetadata(page.constructor, name);
+        if (!view) throw new Error(`Page collection "${name}" is missing @view metadata.`);
+        if (page[view.method] !== view.implementation) throw new Error(`View for page collection "${name}" was replaced.`);
+        return value.map((item, index) => {
+            const rendered = view.implementation.call(page, item, index);
+            if (!isHtml(rendered)) throw new TypeError(`View for page collection "${name}" must return html.`);
+            return renderValue(rendered);
+        }).join('');
+    }
+
+    static statePayload(name, value, page) {
+        if (page && getViewMetadata(page.constructor, name)) {
+            return { name, value: HtmlRenderer.collection(page, name, value), html: true };
+        }
+        return { name, value: isHtml(value) ? renderValue(value) : String(value ?? ''), html: isHtml(value) };
+    }
+
+    static head(metadata = {}) {
+        const tags = [];
+        if (metadata.title) tags.push(`<title>${escapeHtml(metadata.title)}</title>`, meta('property', 'og:title', metadata.title), meta('name', 'twitter:title', metadata.title));
+        if (metadata.description) tags.push(meta('name', 'description', metadata.description), meta('property', 'og:description', metadata.description), meta('name', 'twitter:description', metadata.description));
+        if (metadata.canonical) tags.push(`<link rel="canonical" href="${escapeHtml(metadata.canonical)}">`, meta('property', 'og:url', metadata.canonical));
+        if (metadata.image) tags.push(meta('property', 'og:image', metadata.image), meta('name', 'twitter:image', metadata.image));
+        if (metadata.robots) tags.push(meta('name', 'robots', metadata.robots));
+        if (metadata.title || metadata.description || metadata.image) tags.push(meta('name', 'twitter:card', metadata.image ? 'summary_large_image' : 'summary'));
+        return tags.join('');
+    }
+
+    static document(markup, config = null, stylesheets = [], metadata = {}) {
+        const bootstrap = config ? `<script type="application/json" id="__redweb_page">${serializeJson(config)}</script>` +
+            `<script type="module" src="${escapeHtml(config.runtimePath)}"></script>` : '';
+        const links = stylesheets.map(href => `<link rel="stylesheet" href="${escapeHtml(href)}">`).join('');
+        const headMarkup = HtmlRenderer.head(metadata) + links;
+        const body = TemplateRenderer.closingTag(markup, 'body');
+        if (body >= 0) {
+            const head = TemplateRenderer.closingTag(markup, 'head');
+            const insertions = [{ position: body, value: bootstrap }];
+            if (head >= 0) {
+                if (headMarkup) insertions.push({ position: head, value: headMarkup });
+            } else if (headMarkup) {
+                const bodyOpen = TemplateRenderer.openingTag(markup, 'body');
+                insertions.push({ position: Math.max(0, bodyOpen), value: `<head>${headMarkup}</head>` });
+            }
+            return insertions.sort((left, right) => right.position - left.position)
+                .reduce((result, insertion) => result.slice(0, insertion.position) + insertion.value + result.slice(insertion.position), markup);
+        }
+        return `<!doctype html><html><head>${headMarkup}</head><body><main data-rw-root>${markup}</main>${bootstrap}</body></html>`;
+    }
+}
+
+module.exports = HtmlRenderer;