redweb 0.9.0 → 0.11.0

package/src/htmx/metadata.js

@@ -0,0 +1,349 @@
+const PAGE_METADATA = new WeakMap();
+const STATE_METADATA = new WeakMap();
+const ACTION_METADATA = new WeakMap();
+const RESOLVED_STATE = new WeakMap();
+const RESOLVED_ACTION = new WeakMap();
+const STANDARD_ACTIONS = new WeakMap();
+const VIEW_METADATA = new WeakMap();
+const RESOLVED_VIEW = new WeakMap();
+const STANDARD_VIEWS = new WeakMap();
+const PAGE_ROOTS = new WeakMap();
+const PAGE_STYLESHEET_ROOTS = new WeakMap();
+const COMPONENT_CLASSES = new WeakSet();
+const { decoratorDirectory } = require('./sourceRoot');
+const synchronous = require('./synchronous');
+let metadataVersion = 0;
+
+function assertDecoratorTarget(target, label) {
+    if (!target || typeof target !== 'object' || typeof target.constructor !== 'function') {
+        throw new TypeError(`${label} must decorate a class member.`);
+    }
+    return target.constructor;
+}
+
+function hierarchy(PageClass) {
+    const classes = [];
+    for (let current = PageClass; typeof current === 'function' && current !== Function.prototype; current = Object.getPrototypeOf(current)) {
+        classes.unshift(current);
+    }
+    return classes;
+}
+
+function registerState(PageClass, property, config) {
+    const properties = new Map(STATE_METADATA.get(PageClass) || []);
+    const existing = properties.get(property);
+    if (existing?.writable === config.writable) return;
+    properties.set(property, config);
+    STATE_METADATA.set(PageClass, properties);
+    metadataVersion += 1;
+}
+
+function registerAction(PageClass, method, implementation) {
+    const methods = new Map(ACTION_METADATA.get(PageClass) || []);
+    if (methods.get(method) === implementation) return;
+    methods.set(method, implementation);
+    ACTION_METADATA.set(PageClass, methods);
+    metadataVersion += 1;
+}
+
+function registerStandardAction(PageClass, method, implementation) {
+    const methods = new Map(STANDARD_ACTIONS.get(PageClass) || []);
+    if (methods.get(method) === implementation) return;
+    methods.set(method, implementation);
+    STANDARD_ACTIONS.set(PageClass, methods);
+    metadataVersion += 1;
+}
+
+function registerView(store, PageClass, stateName, method, implementation) {
+    const views = new Map(store.get(PageClass) || []);
+    const existing = views.get(stateName);
+    if (existing?.method === method && existing.implementation === implementation) return;
+    views.set(stateName, Object.freeze({ method, implementation }));
+    store.set(PageClass, views);
+    metadataVersion += 1;
+}
+
+function resolvedState(PageClass) {
+    const cached = RESOLVED_STATE.get(PageClass);
+    if (cached?.version === metadataVersion) return cached.value;
+    const value = new Map();
+    hierarchy(PageClass).forEach(CurrentClass => {
+        STATE_METADATA.get(CurrentClass)?.forEach((config, property) => value.set(property, config));
+    });
+    RESOLVED_STATE.set(PageClass, { version: metadataVersion, value });
+    return value;
+}
+
+function resolvedAction(PageClass) {
+    const cached = RESOLVED_ACTION.get(PageClass);
+    if (cached?.version === metadataVersion) return cached.value;
+    const value = new Map();
+    hierarchy(PageClass).forEach(CurrentClass => {
+        const own = new Map(ACTION_METADATA.get(CurrentClass) || []);
+        STANDARD_ACTIONS.get(CurrentClass)?.forEach((implementation, method) => {
+            if (CurrentClass.prototype[method] === implementation) own.set(method, implementation);
+        });
+        value.forEach((_implementation, method) => {
+            if (Object.prototype.hasOwnProperty.call(CurrentClass.prototype, method) && !own.has(method)) value.delete(method);
+        });
+        own.forEach((implementation, method) => value.set(method, implementation));
+    });
+    RESOLVED_ACTION.set(PageClass, { version: metadataVersion, value });
+    return value;
+}
+
+function resolvedView(PageClass) {
+    const cached = RESOLVED_VIEW.get(PageClass);
+    if (cached?.version === metadataVersion) return cached.value;
+    const value = new Map();
+    hierarchy(PageClass).forEach(CurrentClass => {
+        const own = new Map(VIEW_METADATA.get(CurrentClass) || []);
+        STANDARD_VIEWS.get(CurrentClass)?.forEach((entry, stateName) => {
+            if (CurrentClass.prototype[entry.method] === entry.implementation) own.set(stateName, entry);
+        });
+        value.forEach((entry, stateName) => {
+            if (Object.prototype.hasOwnProperty.call(CurrentClass.prototype, entry.method) && !own.has(stateName)) value.delete(stateName);
+        });
+        own.forEach((entry, stateName) => value.set(stateName, entry));
+    });
+    RESOLVED_VIEW.set(PageClass, { version: metadataVersion, value });
+    return value;
+}
+
+function pageHead(value) {
+    if (value === undefined) return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('Page head must be an object.');
+    const allowed = new Set(['title', 'description', 'canonical', 'image', 'robots']);
+    const unknown = Object.keys(value).find(name => !allowed.has(name));
+    if (unknown) throw new TypeError(`Unknown page head option: ${unknown}.`);
+    const head = {};
+    for (const name of ['title', 'description', 'robots']) {
+        if (value[name] !== undefined && (typeof value[name] !== 'string' || !value[name])) {
+            throw new TypeError(`Page head ${name} must be a non-empty string.`);
+        }
+        if (value[name] !== undefined) head[name] = value[name];
+    }
+    for (const name of ['canonical', 'image']) {
+        if (value[name] === undefined) continue;
+        if (typeof value[name] !== 'string' || !value[name]) throw new TypeError(`Page head ${name} must be an absolute HTTP(S) URL.`);
+        let parsed;
+        try { parsed = new URL(value[name]); }
+        catch { throw new TypeError(`Page head ${name} must be an absolute HTTP(S) URL.`); }
+        if (!['http:', 'https:'].includes(parsed.protocol)) throw new TypeError(`Page head ${name} must be an absolute HTTP(S) URL.`);
+        head[name] = parsed.href;
+    }
+    return Object.freeze(head);
+}
+
+function pageCache(value, live) {
+    if (value === undefined) return undefined;
+    if (live) throw new TypeError('Page cache is available only when live is false.');
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('Page cache must be an object.');
+    const allowed = new Set(['maxAge', 'staleWhileRevalidate', 'immutable']);
+    const unknown = Object.keys(value).find(name => !allowed.has(name));
+    if (unknown) throw new TypeError(`Unknown page cache option: ${unknown}.`);
+    const { maxAge = 0, staleWhileRevalidate = 0, immutable = false } = value;
+    if (!Number.isInteger(maxAge) || maxAge < 0) throw new TypeError('Page cache maxAge must be a non-negative integer.');
+    if (!Number.isInteger(staleWhileRevalidate) || staleWhileRevalidate < 0) {
+        throw new TypeError('Page cache staleWhileRevalidate must be a non-negative integer.');
+    }
+    if (typeof immutable !== 'boolean') throw new TypeError('Page cache immutable must be a boolean.');
+    return Object.freeze({ maxAge, staleWhileRevalidate, immutable });
+}
+
+function page(routePath, options = {}) {
+    const templateRoot = decoratorDirectory();
+    if (typeof routePath !== 'string' || !routePath.startsWith('/')) {
+        throw new TypeError('A page path beginning with "/" is required.');
+    }
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError('Page options must be an object.');
+    }
+    const { template, css, shared, scope = shared ? 'shared' : 'connection', live = true, layout } = options;
+    if (template !== undefined && (typeof template !== 'string' || !template)) {
+        throw new TypeError('Page template must be a non-empty path.');
+    }
+    const stylesheets = css === undefined ? undefined : [...new Set(Array.isArray(css) ? css : [css])];
+    if (stylesheets && (stylesheets.length === 0 || stylesheets.some(file => typeof file !== 'string' || !file))) {
+        throw new TypeError('Page css must be a non-empty path or array of non-empty paths.');
+    }
+    if (shared !== undefined && typeof shared !== 'boolean') {
+        throw new TypeError('Page shared must be a boolean.');
+    }
+    if (shared !== undefined && options.scope !== undefined && (scope === 'shared') !== shared) {
+        throw new TypeError('Page scope and shared options conflict.');
+    }
+    if (!['connection', 'shared'].includes(scope)) {
+        throw new TypeError('Page scope must be "connection" or "shared".');
+    }
+    if (typeof live !== 'boolean') throw new TypeError('Page live must be a boolean.');
+    if (layout !== undefined && typeof layout !== 'function') throw new TypeError('Page layout must be a function.');
+    const head = pageHead(options.head);
+    const cache = pageCache(options.cache, live);
+    return PageClass => {
+        if (typeof PageClass !== 'function') throw new TypeError('page() must decorate a class.');
+        PAGE_METADATA.set(PageClass, Object.freeze({
+            path: routePath,
+            template,
+            scope,
+            ...(live === false && { live: false }),
+            ...(head && { head }),
+            ...(cache && { cache }),
+            ...(stylesheets && { css: Object.freeze(stylesheets) }),
+            ...(layout && { layout }),
+        }));
+        PAGE_ROOTS.set(PageClass, templateRoot);
+        return PageClass;
+    };
+}
+
+function component(render) {
+    if (render !== undefined) {
+        if (typeof render !== 'function') throw new TypeError('component() requires a render function.');
+        return function FunctionalComponent(properties) {
+            const result = synchronous(render(properties), 'Function components must render synchronously.');
+            const { isHtml } = require('./Html');
+            if (!isHtml(result)) throw new TypeError('Function components must return html.');
+            return result;
+        };
+    }
+    return ComponentClass => {
+        if (typeof ComponentClass !== 'function') throw new TypeError('component() must decorate a class.');
+        COMPONENT_CLASSES.add(ComponentClass);
+        return ComponentClass;
+    };
+}
+
+function isComponentClass(ComponentClass) {
+    return hierarchy(ComponentClass).some(CurrentClass => COMPONENT_CLASSES.has(CurrentClass));
+}
+
+function state(options = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError('State options must be an object.');
+    }
+    const { writable = false } = options;
+    if (typeof writable !== 'boolean') throw new TypeError('State writable must be a boolean.');
+    const config = Object.freeze({ writable });
+    return (target, property) => {
+        if (property?.kind === 'field') {
+            if (property.static || property.private || typeof property.name !== 'string' || !property.name) {
+                throw new TypeError('state() requires a public instance field with a string name.');
+            }
+            property.addInitializer(function registerStandardState() {
+                registerState(this.constructor, property.name, config);
+            });
+            return initialValue => initialValue;
+        }
+        const PageClass = assertDecoratorTarget(target, 'state()');
+        if (typeof property !== 'string' || !property) throw new TypeError('State property must be a non-empty string.');
+        registerState(PageClass, property, config);
+    };
+}
+
+function action() {
+    return (target, method, descriptor) => {
+        if (method?.kind === 'method') {
+            if (method.static || method.private || typeof method.name !== 'string' || !method.name || typeof target !== 'function') {
+                throw new TypeError('action() requires a public instance method with a string name.');
+            }
+            method.addInitializer(function registerStandardActionInitializer() {
+                if (this[method.name] === target) registerStandardAction(this.constructor, method.name, target);
+            });
+            return target;
+        }
+        const PageClass = assertDecoratorTarget(target, 'action()');
+        if (typeof method !== 'string' || !method || typeof descriptor?.value !== 'function') {
+            throw new TypeError('action() must decorate a method.');
+        }
+        registerAction(PageClass, method, descriptor.value);
+        return descriptor;
+    };
+}
+
+function view(stateName) {
+    if (typeof stateName !== 'string' || !stateName) throw new TypeError('view() requires a non-empty state name.');
+    return (target, method, descriptor) => {
+        if (method?.kind === 'method') {
+            if (method.static || method.private || typeof method.name !== 'string' || !method.name || typeof target !== 'function') {
+                throw new TypeError('view() requires a public instance method with a string name.');
+            }
+            method.addInitializer(function registerStandardViewInitializer() {
+                if (this[method.name] === target) registerView(STANDARD_VIEWS, this.constructor, stateName, method.name, target);
+            });
+            return target;
+        }
+        const PageClass = assertDecoratorTarget(target, 'view()');
+        if (typeof method !== 'string' || !method || typeof descriptor?.value !== 'function') {
+            throw new TypeError('view() must decorate a method.');
+        }
+        registerView(VIEW_METADATA, PageClass, stateName, method, descriptor.value);
+        return descriptor;
+    };
+}
+
+function getPageMetadata(PageClass) {
+    return PAGE_METADATA.get(PageClass);
+}
+
+function getPageTemplateRoot(PageClass) {
+    return PAGE_ROOTS.get(PageClass);
+}
+
+function getPageStylesheetRoots(PageClass) {
+    return PAGE_STYLESHEET_ROOTS.get(PageClass);
+}
+
+function setPageStylesheetRoots(PageClass, roots) {
+    PAGE_STYLESHEET_ROOTS.set(PageClass, Object.freeze([...roots]));
+}
+
+function getStateMetadata(PageClass) {
+    return new Map(resolvedState(PageClass));
+}
+
+function getActionMetadata(PageClass) {
+    return new Set(resolvedAction(PageClass).keys());
+}
+
+function getStateConfig(PageClass, property) {
+    return resolvedState(PageClass).get(property);
+}
+
+function forEachState(PageClass, callback) {
+    resolvedState(PageClass).forEach(callback);
+}
+
+function getActionImplementation(PageClass, method) {
+    return resolvedAction(PageClass).get(method);
+}
+
+function getViewImplementation(PageClass, stateName) {
+    return getViewMetadata(PageClass, stateName)?.implementation;
+}
+
+function getViewMetadata(PageClass, stateName) {
+    return resolvedView(PageClass).get(stateName);
+}
+
+module.exports = {
+    action,
+    component,
+    forEachState,
+    getActionImplementation,
+    getActionMetadata,
+    getPageMetadata,
+    getPageStylesheetRoots,
+    getPageTemplateRoot,
+    getStateConfig,
+    getStateMetadata,
+    getViewImplementation,
+    getViewMetadata,
+    isComponentClass,
+    page,
+    pageCache,
+    pageHead,
+    setPageStylesheetRoots,
+    state,
+    view,
+};

package/src/htmx/sourceRoot.js

@@ -0,0 +1,28 @@
+const path = require('path');
+const { fileURLToPath } = require('url');
+
+function filePath(fileName) {
+    return fileName.startsWith('file:') ? fileURLToPath(fileName) : fileName;
+}
+
+function callerDirectory(frames, internalDirectory) {
+    const caller = frames.find(frame => {
+        const fileName = frame.getFileName?.();
+        return fileName && path.dirname(filePath(fileName)) !== internalDirectory;
+    });
+    return caller ? path.dirname(filePath(caller.getFileName())) : process.cwd();
+}
+
+function decoratorDirectory() {
+    const prepareStackTrace = Error.prepareStackTrace;
+    try {
+        Error.prepareStackTrace = (_error, frames) => frames;
+        const error = new Error();
+        Error.captureStackTrace(error, decoratorDirectory);
+        return callerDirectory(error.stack, __dirname);
+    } finally {
+        Error.prepareStackTrace = prepareStackTrace;
+    }
+}
+
+module.exports = { callerDirectory, decoratorDirectory, filePath };

package/src/htmx/start.js

@@ -0,0 +1,17 @@
+const LiveHtmlServer = require('./LiveHtmlServer');
+
+function start(pageOrPages, options = {}) {
+    const pages = Array.isArray(pageOrPages) ? pageOrPages : [pageOrPages];
+    if (!pages.length || pages.some(PageClass => typeof PageClass !== 'function')) {
+        throw new TypeError('start() requires a page class or a non-empty array of page classes.');
+    }
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError('start() options must be an object.');
+    }
+    return new LiveHtmlServer({
+        ...options,
+        pages,
+    });
+}
+
+module.exports = { start };

package/src/htmx/synchronous.js

@@ -0,0 +1,9 @@
+function synchronous(result, message) {
+    if (result && typeof result.then === 'function') {
+        Promise.resolve(result).catch(() => {});
+        throw new TypeError(message);
+    }
+    return result;
+}
+
+module.exports = synchronous;

package/src/http/BaseHttpServer.js

@@ -1,8 +1,6 @@
 const express = require('express');
 const path = require('path');
 const cors = require('cors');
-const fs = require('fs');
-const HtmxRenderer = require('../htmx/HtmxRenderer'); // Import the HtmxRenderer module
 const { validateListenerOptions } = require('../serverLifecycle');
 
 /**
@@ -24,7 +22,6 @@ const { validateListenerOptions } = require('../serverLifecycle');
  * @property {string} [ssl.cert] - Path to the SSL certificate file.
  * @property {import('express').Application} [server] - Existing Express application to configure.
  * @property {import('cors').CorsOptions} [corsOptions] - The CORS Options.
- * @property {boolean} [enableHtmxRendering=false] - Enable dynamic HTMX file rendering.
  */
 
 const ENCODINGS = { json: 'json', urlencoded: 'urlencoded' };
@@ -39,7 +36,6 @@ const HTTP_OPTIONS = {
     ssl: null,
     server: undefined,
     corsOptions: undefined,
-    enableHtmxRendering: false, // New option for HTMX rendering
     exposeErrors: false,
     logger: console,
 };
@@ -75,11 +71,6 @@ function assertOptions(options) {
     }
 }
 
-function isWithin(root, candidate) {
-    const relative = path.relative(root, candidate);
-    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
-}
-
 /**
  * Base HTTP Server
  * @param {RedWebOptions} options - Configuration options for RedWeb.
@@ -113,32 +104,6 @@ function BaseHttpServer(options = {}) {
         this.app.use(cors(this.options.corsOptions));
     }
 
-    // Enable HTMX rendering if the flag is set
-    if (this.enableHtmxRendering) {
-        this.app.get('*.htmx', (req, res) => {
-            const match = this.publicPaths
-                .map(publicPath => {
-                    const root = path.resolve(process.cwd(), publicPath);
-                    const filePath = path.resolve(root, `.${req.path}`);
-                    return { root, filePath };
-                })
-                .find(({ root, filePath }) => isWithin(root, filePath) && fs.existsSync(filePath));
-    
-            if (!match) {
-                return res.status(404).send('HTMX template not found');
-            }
-    
-            try {
-                const renderedContent = HtmxRenderer.render(match.filePath, { rootDir: match.root });
-                res.type('html').send(renderedContent);
-            } catch (error) {
-                const message = this.exposeErrors ? `Error rendering HTMX file: ${error.message}` : 'Unable to render HTMX template';
-                res.status(500).send(message);
-            }
-        });
-    }
-    
-
     // Serve static files from public paths
     this.publicPaths.forEach((publicPath) =>
         this.app.use(express.static(path.resolve(process.cwd(), publicPath)))

package/src/ws/BaseSocketServer.js

@@ -95,6 +95,10 @@ class BaseSocketServer {
   }
 
   handleUpgrade(req, sock, head) {
+    // Upgrade sockets are detached from Node's HTTP request lifecycle. A peer
+    // may reset one while admission is pending or after a rejection response;
+    // consume that transport-level event so it cannot crash the process.
+    if (typeof sock.on === 'function') sock.on('error', Function.prototype);
     // Some websocket clients (e.g., certain UE plugins) are finicky about the
     // HTTP upgrade path they send. Normalise the path and fall back to a default
     // route so we can still complete the upgrade instead of tearing the socket down.

package/src/htmx/HtmxRenderer.js

@@ -1,73 +0,0 @@
-const fs = require('fs');
-const vm = require('vm');
-const path = require('path');
-
-class HtmxRenderer {
-    /**
-     * Render an .htmx file as JavaScript with embedded print statements.
-     * @param {string} filePath - Path to the .htmx file.
-     * @returns {string} Rendered HTML string with normalized whitespace.
-     */
-    static render(filePath, { rootDir = path.dirname(path.resolve(filePath)), timeoutMs = 1000 } = {}) {
-        if (!fs.existsSync(filePath)) {
-            throw new Error(`Template file not found: ${filePath}`);
-        }
-
-        let output = '';
-        const templateContent = fs.readFileSync(filePath, 'utf-8');
-
-        // Transform <@ ... @/> blocks into print() calls
-        const transformedTemplate = templateContent.replace(
-            /<@>([\s\S]*?)<@\/>/g,
-            (_, content) => `print(\`${content.replace(/{{\s*(.*?)\s*}}/g, '${$1}')}\`);`
-        );
-
-        // Wrap the script in an IIFE
-        const wrappedScript = `
-        (() => {
-            const print = (html) => output += html;
-            ${transformedTemplate}
-            return output;
-        })();
-        `;
-
-        // Create a custom require function that resolves paths relative to the template
-        const resolvedRoot = path.resolve(rootDir);
-        const customRequire = (modulePath) => {
-            if (typeof modulePath !== 'string' || !modulePath.startsWith('.')) {
-                throw new Error('Templates may only require relative modules');
-            }
-            const absolutePath = path.resolve(path.dirname(filePath), modulePath);
-            const relative = path.relative(resolvedRoot, absolutePath);
-            if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-                throw new Error('Template module is outside the allowed root');
-            }
-            return require(absolutePath);
-        };
-
-        // Execute the script in a sandbox
-        const script = new vm.Script(wrappedScript);
-        const sandbox = {
-            output: '',
-            require: customRequire, // Add custom require
-            __dirname: path.dirname(filePath),
-            __filename: filePath,
-        };
-        vm.createContext(sandbox);
-
-        // Get the rendered output
-        let result = script.runInContext(sandbox, { timeout: timeoutMs });
-
-        // Normalize spaces but preserve those in content
-        result = result
-            .replace(/>\s+</g, '><')       // Remove spaces between tags
-            .replace(/\s+/g, ' ')         // Collapse multiple spaces to one
-            .replace(/>\s+/g, '>')        // Remove spaces after tags
-            .replace(/\s+</g, '<')        // Remove spaces before tags
-            .trim();                      // Trim leading and trailing spaces
-
-        return result;
-    }
-}
-
-module.exports = HtmxRenderer;

package/src/htmx/RedWebHtmxComponent.js

@@ -1,11 +0,0 @@
-class RedWebHtmxComponent {
-    constructor(props = {}) {
-        this.props = props;
-    }
-
-    render() {
-        throw new Error('Render method must be implemented in derived components');
-    }
-}
-
-module.exports = RedWebHtmxComponent;