redweb 0.16.1 → 0.16.3

package/src/cli/arguments.js

@@ -1,15 +1,17 @@
 'use strict';
 
-const { TEMPLATES } = require('./templates');
+const { CAPABILITIES, TEMPLATES } = require('./templates');
 const { KINDS } = require('./ProjectAddition');
 
 const USAGE = [
-    `Usage: redweb init [directory] [--template ${TEMPLATES.join('|')}] [--existing] [--dry-run] [--json]`,
+    `Usage: redweb init [directory] [--with ${CAPABILITIES.join(',')}] [--template ${TEMPLATES.join('|')}] [--bare] [--existing] [--dry-run] [--json]`,
     '       redweb doctor [directory] [--port number] [--json]',
     `       redweb add <${KINDS.join('|')}> <name> [directory] [--config file] [--source-dir dir] [--test-dir dir] [--dry-run] [--json]`,
     '       redweb --help | --version',
     '',
     '--existing creates only a missing tsconfig.json; no starter or package changes.',
+    '--with adds neutral capability dependencies without generating example-domain code.',
+    '--bare omits generated tests; templates remain explicit examples.',
     '--dry-run reports planned files without writing anything.',
     'doctor inspects configuration without executing application code or repairing files.',
 ].join('\n') + '\n';
@@ -38,6 +40,7 @@ function parseArguments(args) {
         seen.add(value);
         if (value === '--json') result.json = true;
         else if (value === '--existing' && command === 'init') result.existing = true;
+        else if (value === '--bare' && command === 'init') result.bare = true;
         else if (value === '--dry-run' && ['init', 'add'].includes(command)) result.dryRun = true;
         else if (command === 'add' && ['--config', '--source-dir', '--test-dir'].includes(value)) {
             const argument = rest[++i];
@@ -49,13 +52,22 @@ function parseArguments(args) {
             if (!TEMPLATES.includes(template)) throw new Error(`--template must be one of: ${TEMPLATES.join(', ')}.`);
             result.template = template;
         }
+        else if (value === '--with' && command === 'init') {
+            const raw = rest[++i];
+            if (!raw || raw.startsWith('-')) throw new Error('--with requires a comma-separated capability list.');
+            const capabilities = raw.split(',');
+            if (capabilities.some(capability => !CAPABILITIES.includes(capability)) || new Set(capabilities).size !== capabilities.length) {
+                throw new Error(`--with must contain unique capabilities from: ${CAPABILITIES.join(', ')}.`);
+            }
+            result.with = capabilities;
+        }
         else if (value === '--port' && command === 'doctor') {
             const port = rest[++i];
             if (!/^\d+$/.test(port) || Number(port) > 65535) throw new Error('--port must be an integer from 0 through 65535.');
             result.port = Number(port);
         } else throw new Error(`Unknown option for ${command}: ${value}`);
     }
-    if (result.existing && result.template) throw new Error('--existing and --template cannot be combined.');
+    if (result.existing && (result.template || result.with || result.bare)) throw new Error('--existing cannot be combined with --template, --with, or --bare.');
     return result;
 }
 

package/src/cli/run.js

@@ -36,9 +36,18 @@ async function run(args, cwd, version) {
             return { exitCode: 0, stdout: `${output}\n`, stderr: '' };
         }
         const result = new ProjectInitializer(version).initialize(root, options);
-        const report = { schemaVersion: 1, operation: 'init', dryRun: options.dryRun, ...result };
+        const report = {
+            schemaVersion: 1,
+            operation: 'init',
+            dryRun: options.dryRun,
+            foundation: options.template ?? 'default',
+            capabilities: options.with ?? [],
+            tests: !options.bare,
+            ...result,
+        };
         const output = options.json ? JSON.stringify(report) : [
             `${options.dryRun ? 'Planned initialization' : 'Initialization complete'} in ${result.root}`,
+            `Foundation: ${options.template ? `example template "${options.template}"` : 'neutral default'}; capabilities: ${options.with?.join(', ') || 'base'}; tests: ${options.bare ? 'omitted' : 'included'}.`,
             `Created: ${result.created.join(', ')}`,
             `Kept existing: ${result.skipped.join(', ')}`,
             `Planned: ${result.planned.join(', ')}`,

package/src/cli/templates.js

@@ -5,10 +5,17 @@ const path = require('path');
 
 const json = value => `${JSON.stringify(value, null, 2)}\n`;
 const TEMPLATES = Object.freeze(['realtime', 'chat', 'site', 'socket', 'dashboard', 'http-ws']);
+const CAPABILITIES = Object.freeze(['auth', 'multiplayer']);
 
-function projectFiles(version, template = 'realtime', root = path.resolve(__dirname, '../..')) {
-    if (!TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
-    const { devDependencies, dependencies, overrides } = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+function projectFiles(version, template = null, root = path.resolve(__dirname, '../..'), options = {}) {
+    if (template !== null && !TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
+    if (options.with !== undefined && !Array.isArray(options.with)) throw new TypeError('Initializer capabilities must be an array.');
+    const capabilities = new Set(options.with || []);
+    if ([...capabilities].some(capability => !CAPABILITIES.includes(capability))) throw new Error('Unknown initializer capability.');
+    const selected = template ?? 'foundation';
+    const authenticated = template === 'dashboard' || capabilities.has('auth');
+    const multiplayer = capabilities.has('multiplayer');
+    const { devDependencies, dependencies, overrides } = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
     const read = relative => fs.readFileSync(path.join(root, 'recipes', relative), 'utf8');
     const manifest = {
         name: 'redweb-app', private: true, version: '0.0.0',
@@ -16,18 +23,22 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             build: 'tsc && node scripts/copy-assets.cjs',
             start: 'node dist/app.js',
             dev: 'nodemon',
-            test: 'npm run build && node --test test/app.test.cjs test/lifecycle.test.cjs',
-            'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/lifecycle.test.cjs',
+            ...(!options.bare ? {
+                test: 'npm run build && node --test test/app.test.cjs test/lifecycle.test.cjs',
+                'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/lifecycle.test.cjs',
+            } : {}),
         },
         dependencies: {
             redweb: `^${version}`,
-            ...(['chat', 'socket', 'dashboard'].includes(template) ? { zod: devDependencies.zod } : {}),
-            ...(template === 'dashboard' ? { express: dependencies.express } : {}),
+            ...(['chat', 'socket', 'dashboard'].includes(template) || authenticated || multiplayer ? { zod: devDependencies.zod } : {}),
+            ...(authenticated ? { express: dependencies.express } : {}),
+            ...(multiplayer ? { 'redweb-client': dependencies['redweb-client'] } : {}),
         },
-        overrides,
-        devDependencies: {
-            typescript: devDependencies.typescript, nodemon: devDependencies.nodemon, ws: dependencies.ws, c8: devDependencies.c8,
-            ...(template === 'dashboard' ? {
+        overrides,
+        devDependencies: {
+            typescript: devDependencies.typescript, nodemon: devDependencies.nodemon, ws: dependencies.ws,
+            ...(!options.bare ? { c8: devDependencies.c8 } : {}),
+            ...(authenticated ? {
                 '@types/node': devDependencies['redweb-dashboard-types'].replace('npm:@types/node@', ''),
                 '@types/express': dependencies['@types/express'],
             } : {}),
@@ -40,10 +51,10 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             delay: 200,
         },
     };
+    if (authenticated) manifest.engines = { node: '>=22.13.0' };
     if (template === 'dashboard') {
-        manifest.engines = { node: '>=22.13.0' };
         manifest.scripts['add-user'] = 'npm run build && node dist/admin.js';
-        manifest.scripts['test:coverage'] += ' test/rate-window.test.cjs';
+        if (!options.bare) manifest.scripts['test:coverage'] += ' test/rate-window.test.cjs';
     }
     const files = [
         { path: 'package.json', content: json(manifest) },
@@ -52,13 +63,15 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             compilerOptions: { rootDir: 'src', outDir: 'dist', sourceMap: true },
             include: ['src/**/*.ts', 'src/**/*.tsx'],
         }) },
-        { path: 'src/app.tsx', content: read(`${template}/app.tsx`) },
-        { path: 'src/app.css', content: read(`${template === 'dashboard' ? template : 'shared'}/app.css`) },
+        { path: 'src/app.tsx', content: read(`${selected}/app.tsx`) },
+        { path: 'src/app.css', content: read(`${selected === 'dashboard' ? selected : 'shared'}/app.css`) },
         { path: 'scripts/copy-assets.cjs', content: read('shared/copy-assets.cjs') },
-        { path: 'test/network.cjs', content: read('shared/network.cjs') },
-        { path: 'test/app.test.cjs', content: read(`${template}/app.test.cjs`) },
-        { path: 'test/lifecycle.test.cjs', content: read('shared/lifecycle.test.cjs') },
-        { path: 'README.md', content: `${read('shared/README.md')}\n${read(`${template}/README.md`)}` },
+        ...(!options.bare ? [
+            { path: 'test/network.cjs', content: read('shared/network.cjs') },
+            { path: 'test/app.test.cjs', content: read(`${selected}/app.test.cjs`) },
+            { path: 'test/lifecycle.test.cjs', content: read('shared/lifecycle.test.cjs') },
+        ] : []),
+        { path: 'README.md', content: `${read('shared/README.md')}\n${read(`${selected}/README.md`)}` },
         { path: '.gitignore', content: 'node_modules/\ndist/\ncoverage/\n.env\ndata/\n*.sqlite\n*.sqlite-wal\n*.sqlite-shm\n' },
     ];
     if (template === 'chat') {
@@ -75,7 +88,7 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
     }
     if (template === 'dashboard') {
         files.push({ path: '.npmrc', content: 'engine-strict=true\n' });
-        files.push({ path: 'test/rate-window.test.cjs', content: read('dashboard/rate-window.test.cjs') });
+        if (!options.bare) files.push({ path: 'test/rate-window.test.cjs', content: read('dashboard/rate-window.test.cjs') });
         for (const name of ['store.ts', 'auth.ts', 'cards.tsx', 'admin.ts']) {
             files.push({ path: `src/${name}`, content: read(`dashboard/${name}`) });
         }
@@ -83,4 +96,4 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
     return Object.freeze(files.map(Object.freeze));
 }
 
-module.exports = { projectFiles, TEMPLATES };
+module.exports = { projectFiles, CAPABILITIES, TEMPLATES };

package/src/docs/Documentation.js

@@ -89,6 +89,16 @@ class Documentation {
             : fence(`npx --yes redweb@${this.channel} init my-${template} --template ${template}\ncd my-${template}\nnpm install --save-exact redweb@${this.channel}\n${acceptance}`, 'sh');
     }
 
+    foundationSetup() {
+        return this.channel === 'unreleased'
+            ? [
+                'Replace `TARBALL` with the absolute path to the matching Redweb tarball produced by `npm pack` (quoted if it contains spaces):',
+                fence('npx --yes --package TARBALL redweb init my-app\ncd my-app\nnpm install --save-exact TARBALL\nnpm test\nnpm run dev', 'sh'),
+                'This prerelease Redweb artifact is development-only until its release checks finish.',
+            ].join('\n\n')
+            : fence(`npx --yes redweb@${this.channel} init my-app\ncd my-app\nnpm install --save-exact redweb@${this.channel}\nnpm test\nnpm run dev`, 'sh');
+    }
+
     recipe(template) {
         const files = projectFiles(this.manifest.version, template, this.root).map(file => ({ ...file, content: normalize(file.content) }));
         const source = `recipes/${template}/README.md`;
@@ -104,28 +114,28 @@ class Documentation {
         return { id: `recipes/${template}`, title: `${template[0].toUpperCase()}${template.slice(1)} starter`, summary: explanation.split('\n').find(line => line && !line.startsWith('#')), source, markdown, files };
     }
 
-    recipeCode(entry) {
+    recipeCode(entry) {
         const files = projectFiles(this.manifest.version, entry.template, this.root);
         const file = files.find(file => file.path === entry.file);
         if (!file) throw new Error(`Unknown documentation recipe file: ${entry.template}/${entry.file}`);
-        return normalize(file.content);
-    }
-
-    code(entry, field) {
-        return entry.recipe ? this.recipeCode(entry.recipe) : entry.codeSource ? this.read(entry.codeSource) : entry[field];
-    }
+        return normalize(file.content);
+    }
+
+    code(entry, field) {
+        return entry.recipe ? this.recipeCode(entry.recipe) : entry.codeSource ? this.read(entry.codeSource) : entry[field];
+    }
 
     topic(topic) {
-        let markdown = `${this.notice()}\n\n${this.links(this.read(topic.source), topic.source)}`;
-        markdown = markdown.replace(/<!-- source: ([\w./-]+) -->/g,
-            (_match, file) => fence(this.read(file), language(file)));
+        let markdown = `${this.notice()}\n\n${this.links(this.read(topic.source), topic.source)}`;
+        markdown = markdown.replace(/<!-- source: ([\w./-]+) -->/g,
+            (_match, file) => fence(this.read(file), language(file)));
         if (topic.recipe) {
             const { template, file } = topic.recipe;
             markdown += [
                 '\n## Build and run the complete application', this.setup(template),
-                `The [complete ${template} recipe](${this.basePath}/recipes/${template}.md) contains every generated file, its real acceptance tests, and deployment instructions.`,
-                ...(topic.codeSource ? [] : [`The source below is one of those files, not a standalone program; initialize the whole project before modifying it.`,
-                    `## Source walkthrough: ${file}`, fence(this.recipeCode(topic.recipe), language(file))]),
+                `The [complete ${template} recipe](${this.basePath}/recipes/${template}.md) contains every generated file, its real acceptance tests, and deployment instructions.`,
+                ...(topic.codeSource ? [] : [`The source below is one of those files, not a standalone program; initialize the whole project before modifying it.`,
+                    `## Source walkthrough: ${file}`, fence(this.recipeCode(topic.recipe), language(file))]),
             ].join('\n\n') + '\n';
         }
         return { ...topic, markdown };
@@ -135,8 +145,8 @@ class Documentation {
         const pages = this.topics.map(topic => this.topic(topic));
         pages.push(...TEMPLATES.map(template => this.recipe(template)));
         const reference = this.reference;
-        const api = reference.api.map(section => ({ ...section, usage: this.code(section, 'usage') }));
-        const examples = reference.examples.map(example => ({ ...example, code: this.code(example, 'code') }));
+        const api = reference.api.map(section => ({ ...section, usage: this.code(section, 'usage') }));
+        const examples = reference.examples.map(example => ({ ...example, code: this.code(example, 'code') }));
         for (const example of examples) {
             pages.push({ id: `examples/${example.id}`, title: example.title, summary: example.summary, source: 'docs/reference.json', markdown: [
                 `# ${example.title}`, this.notice(), example.summary,

package/src/htmx/Jsx.js

@@ -83,13 +83,13 @@ function renderComponent(Component, properties) {
 
 function createElement(type, properties, key) {
     const reactive = ReactiveRenderer.jsx();
-    const props = properties == null ? {} : properties;
+    const props = properties == null ? {} : properties;
     if (!props || typeof props !== 'object' || Array.isArray(props)) {
         throw new TypeError('JSX properties must be an object.');
     }
     let result;
     if (type === Fragment) result = trustedHtml(renderChild(props.children));
-    else if (typeof type === 'string') result = renderIntrinsic(type, require('./SocketAction').attributes(props));
+    else if (typeof type === 'string') result = renderIntrinsic(type, require('./SocketAction').attributes(props));
     else if (typeof type === 'function') result = renderComponent(type, props);
     else throw new TypeError('JSX element types must be intrinsic names or function components.');
     const elementKey = key ?? props.key;

package/src/htmx/LiveHtmlServer.js

@@ -28,10 +28,12 @@ class LiveHtmlServer {
             maxSessions,
             maxConcurrentRenders,
             shutdownTimeoutMs = 1000,
+            uploadTimeoutMs,
             heartbeat,
             authenticate,
             authenticationTimeoutMs,
             origins,
+            providers,
             development,
             server: suppliedApp,
             ...httpOptions
@@ -54,10 +56,12 @@ class LiveHtmlServer {
             maxSessions,
             maxConcurrentRenders,
             shutdownTimeoutMs,
+            uploadTimeoutMs,
             heartbeat,
             authenticate,
             authenticationTimeoutMs,
             origins,
+            providers,
             logger: httpOptions.logger,
         });
         if (this._inspection) this.manager.Renderer = this._inspection.Renderer;
@@ -71,7 +75,7 @@ class LiveHtmlServer {
             if (this.manager.hasLivePages || socketRoutes.length) {
                 this.sockets = new SocketServer({
                     server: this.http.server,
-                    routes: [...(this.manager.hasLivePages ? [this.manager.route()] : []), ...require('./PageSocketRoute').bindRoutes(this.manager, socketRoutes)],
+                    routes: [...(this.manager.hasLivePages ? [this.manager.route()] : []), ...require('./PageSocketRoute').bindRoutes(this.manager, socketRoutes)],
                     listen,
                     port: this.http.port,
                     bind: this.http.bind,

package/src/htmx/LivePage.js

@@ -5,7 +5,8 @@ const ReactiveRenderer = require('./ReactiveRenderer');
 const dataProperty = require('../dataProperty');
 const { ActionInputError } = require('./ActionDefinition');
 const { isHtml, markHtml, renderValue } = require('./Html');
-const { forEachState, getActionImplementation, getActionDefinition, getStateConfig, isComponentClass } = require('./metadata');
+const { forEachState, getActionImplementation, getActionDefinition, getResourceMetadata, getStateConfig, isComponentClass } = require('./metadata');
+const { LiveResource } = require('./LiveResource');
 
 const RUNTIME = new WeakMap();
 const COMPONENT_RENDER_CONTEXT = new AsyncLocalStorage();
@@ -159,6 +160,7 @@ class LivePage {
             });
         });
         internal.stateActive = true;
+        getResourceMetadata(this.constructor).forEach((config, name) => config.resource.bind(this, name, config.select));
         Object.keys(this).forEach(name => {
             const value = this[name];
             if (isComponentClass(value?.constructor) && getStateConfig(this.constructor, name)) {
@@ -226,6 +228,7 @@ class LivePage {
 
     _stateChanged(name, value) {
         if (!getStateConfig(this.constructor, name)) return false;
+        LiveResource.refresh(this);
         const payload = LivePage.statePayload(this, name, value, true);
         runtime(this).connections.forEach(socket => {
             const session = socket.__redwebPageSession;
@@ -261,6 +264,7 @@ class LivePage {
         const internal = runtime(this);
         if (internal.disposePromise) return internal.disposePromise;
         internal.disposed = true;
+        LiveResource.release(this);
         internal.connections.clear();
         internal.disposePromise = Promise.resolve().then(async () => {
             const tasks = [...internal.children.values()].map(component => LivePage.dispose(component));

package/src/htmx/LiveResource.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const PAGE_BINDINGS = new WeakMap();
+const UNBOUND = Symbol('unbound');
+
+function key(value) {
+    if (value === undefined || value === null || value === '') return UNBOUND;
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'bigint' || typeof value === 'boolean') return value;
+    throw new TypeError('Live resource keys must be non-empty strings, finite numbers, bigints, booleans, null, or undefined.');
+}
+
+function safeProperty(value) {
+    if (typeof value !== 'string' || !value || value.length > 128 || ['__proto__', 'prototype', 'constructor'].includes(value)) {
+        throw new TypeError('Live resource properties must be safe non-empty names of at most 128 characters.');
+    }
+    return value;
+}
+
+class LiveResource {
+    constructor() {
+        this.subscribers = new Map();
+    }
+
+    publish(resourceKey, value) {
+        const resolved = key(resourceKey);
+        if (resolved === UNBOUND) throw new TypeError('Live resources cannot publish without a key.');
+        const subscribers = [...(this.subscribers.get(resolved) || [])];
+        subscribers.forEach(binding => {
+            if (!binding.active || binding.key !== resolved) return;
+            binding.page[binding.property] = value;
+        });
+        return subscribers.length;
+    }
+
+    bind(page, property, select) {
+        if (!page || typeof page !== 'object') throw new TypeError('Live resources bind to page instances.');
+        safeProperty(property);
+        if (typeof select !== 'function') throw new TypeError('Live resources require a key selector.');
+        const binding = { resource: this, page, property, select, key: UNBOUND, active: true };
+        const bindings = PAGE_BINDINGS.get(page) || new Set();
+        bindings.add(binding);
+        PAGE_BINDINGS.set(page, bindings);
+        try { this.refresh(binding); }
+        catch (error) {
+            this.release(binding);
+            throw error;
+        }
+        return binding;
+    }
+
+    refresh(binding) {
+        if (!binding.active) return false;
+        const next = key(binding.select(binding.page));
+        if (Object.is(next, binding.key)) return false;
+        if (binding.key !== UNBOUND) {
+            const subscribers = this.subscribers.get(binding.key);
+            subscribers?.delete(binding);
+            if (subscribers?.size === 0) this.subscribers.delete(binding.key);
+        }
+        binding.key = next;
+        if (next !== UNBOUND) {
+            const subscribers = this.subscribers.get(next) || new Set();
+            subscribers.add(binding);
+            this.subscribers.set(next, subscribers);
+        }
+        return true;
+    }
+
+    release(binding) {
+        if (!binding?.active) return false;
+        binding.active = false;
+        if (binding.key !== UNBOUND) {
+            const subscribers = this.subscribers.get(binding.key);
+            subscribers?.delete(binding);
+            if (subscribers?.size === 0) this.subscribers.delete(binding.key);
+        }
+        const bindings = PAGE_BINDINGS.get(binding.page);
+        bindings?.delete(binding);
+        if (bindings?.size === 0) PAGE_BINDINGS.delete(binding.page);
+        return true;
+    }
+
+    static refresh(page) {
+        PAGE_BINDINGS.get(page)?.forEach(binding => binding.resource.refresh(binding));
+    }
+
+    static release(page) {
+        [...(PAGE_BINDINGS.get(page) || [])].forEach(binding => binding.resource.release(binding));
+    }
+}
+
+function liveResource() { return new LiveResource(); }
+
+module.exports = { LiveResource, liveResource };