@async/framework 0.2.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@async/framework",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "No-build AsyncLoader app runtime with signals, command events, server calls, route partials, cache split, SSR activation, and streaming boundaries.",
   "type": "module",
   "packageManager": "pnpm@11.1.0",
@@ -28,12 +28,21 @@
     "web-framework"
   ],
   "license": "MIT",
+  "unpkg": "./framework.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "unpkg": "./framework.js",
+      "browser": "./framework.js",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./framework.js": "./framework.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "CHANGELOG.md",
     "README.md",
+    "framework.js",
     "src",
     "examples",
     "LICENSE",
@@ -41,10 +50,12 @@
   ],
   "scripts": {
     "async-pipeline": "async-pipeline",
+    "bundle": "node scripts/build-framework-bundle.js",
+    "bundle:check": "node scripts/build-framework-bundle.js --check",
     "docs:build": "node scripts/build-pages.js",
     "examples": "node --test tests/examples.test.js",
     "examples:check": "node --test tests/examples.test.js",
-    "pack:check": "npm pack --dry-run --ignore-scripts",
+    "pack:check": "pnpm run bundle:check && npm pack --dry-run --ignore-scripts",
     "pipeline:github:check": "async-pipeline github check",
     "pipeline:github:generate": "async-pipeline github generate",
     "pipeline:pages": "async-pipeline run pages",

package/src/app.js

@@ -6,17 +6,21 @@ import { createPartialRegistry } from "./partials.js";
 import { createRouteRegistry, createRouter } from "./router.js";
 import { createServerRegistry } from "./server.js";
 import { createSignal, createSignalRegistry } from "./signals.js";
+import { createRegistryStore } from "./registry-store.js";
+import { attributeName, normalizeAttributeConfig } from "./attributes.js";
 
 const registryTypes = new Set(["signal", "handler", "server", "partial", "route", "component"]);
 
 export function defineApp(initial) {
-  const declarations = emptyDeclarations();
+  const registry = createRegistryStore(undefined, { target: "browser" });
   const runtimes = new Set();
 
   const app = {
+    registry,
+
     use(typeOrModule, entries) {
       const normalized = normalizeUse(typeOrModule, entries);
-      appendDeclarations(declarations, normalized);
+      appendDeclarations(registry, normalized);
       for (const runtime of runtimes) {
         runtime._applyUse(normalized);
       }
@@ -24,7 +28,7 @@ export function defineApp(initial) {
     },
 
     snapshot() {
-      return cloneDeclarations(declarations);
+      return registry.rawSnapshot();
     },
 
     start(options = {}) {
@@ -53,15 +57,16 @@ export function defineApp(initial) {
 export function createApp(appOrDefinition = Async, options = {}) {
   const app = isAppHub(appOrDefinition) ? appOrDefinition : defineApp(appOrDefinition ?? {});
   const target = options.target ?? "browser";
-  const snapshot = app.snapshot();
-  const signals = options.signals ?? createSignalRegistry(snapshot.signal);
-  const handlers = options.handlers ?? createHandlerRegistry(snapshot.handler);
-  const serverCache = createCacheRegistry(snapshot.cache.server);
-  const browserCache = createCacheRegistry(snapshot.cache.browser);
-  const server = options.server ?? createServerRegistry(snapshot.server);
-  const partials = options.partials ?? createPartialRegistry(snapshot.partial);
-  const routes = options.routes ?? createRouteRegistry(snapshot.route);
-  const components = options.components ?? createComponentRegistry(snapshot.component);
+  const attributes = normalizeAttributeConfig(options.attributes);
+  const registry = options.registry ?? app.registry.view({ target });
+  const signals = options.signals ?? createSignalRegistry(undefined, { registry, type: "signal" });
+  const handlers = options.handlers ?? createHandlerRegistry(undefined, { registry, type: "handler" });
+  const serverCache = createCacheRegistry(undefined, { registry, type: "cache.server" });
+  const browserCache = createCacheRegistry(undefined, { registry, type: "cache.browser" });
+  const server = options.server ?? createServerRegistry(undefined, { registry, type: "server" });
+  const partials = options.partials ?? createPartialRegistry(undefined, { registry, type: "partial" });
+  const routes = options.routes ?? createRouteRegistry(undefined, { registry, type: "route" });
+  const components = options.components ?? createComponentRegistry(undefined, { registry, type: "component" });
   let loader = options.loader;
   let router = options.router;
   let detach = () => {};
@@ -73,6 +78,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
 
   const runtime = {
     app,
+    registry,
     target,
     signals,
     handlers,
@@ -85,6 +91,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
     },
     loader,
     router,
+    attributes,
 
     start() {
       assertActive();
@@ -99,7 +106,8 @@ export function createApp(appOrDefinition = Async, options = {}) {
           signals,
           handlers,
           server,
-          cache: browserCache
+          cache: browserCache,
+          attributes
         });
         runtime.loader = loader;
 
@@ -121,7 +129,8 @@ export function createApp(appOrDefinition = Async, options = {}) {
             cache: browserCache,
             partials,
             fetch: options.fetch,
-            routeEndpoint: options.routeEndpoint
+            routeEndpoint: options.routeEndpoint,
+            attributes
           });
           runtime.router = router;
           loader.router = router;
@@ -148,7 +157,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
       const matched = routes.match(url);
       if (!matched) {
         return {
-          html: renderDocument("", { status: 404, signals, browserCache, boundary: options.boundary ?? "route" }),
+          html: renderDocument("", { status: 404, signals, browserCache, boundary: options.boundary ?? "route", attributes }),
           status: 404,
           signals: signals.snapshot(),
           cache: { browser: browserCache.snapshot() }
@@ -182,7 +191,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
 
       const status = result.status ?? 200;
       return {
-        html: renderDocument(result.html, { status, signals, browserCache, boundary: result.boundary ?? options.boundary ?? "route" }),
+        html: renderDocument(result.html, { status, signals, browserCache, boundary: result.boundary ?? options.boundary ?? "route", attributes }),
         status,
         signals: signals.snapshot(),
         cache: { browser: browserCache.snapshot() }
@@ -233,16 +242,25 @@ export function createApp(appOrDefinition = Async, options = {}) {
 export const Async = defineApp();
 
 function applyUseToRuntime(runtime, normalized) {
-  runtime.signals.registerMany(normalized.signal);
-  runtime.handlers.registerMany(normalized.handler);
-  if (typeof runtime.server.registerMany === "function") {
-    runtime.server.registerMany(normalized.server);
+  applyRegistryUse(runtime.signals, runtime.registry, normalized.signal);
+  applyRegistryUse(runtime.handlers, runtime.registry, normalized.handler);
+  applyRegistryUse(runtime.server, runtime.registry, normalized.server);
+  applyRegistryUse(runtime.partials, runtime.registry, normalized.partial);
+  applyRegistryUse(runtime.routes, runtime.registry, normalized.route);
+  applyRegistryUse(runtime.components, runtime.registry, normalized.component);
+  applyRegistryUse(runtime.browser.cache, runtime.registry, normalized.cache.browser);
+  applyRegistryUse(runtime.server.cache, runtime.registry, normalized.cache.server);
+}
+
+function applyRegistryUse(registry, runtimeRegistry, entries) {
+  if (!entries || Object.keys(entries).length === 0) {
+    return;
+  }
+  if (registry?.registry === runtimeRegistry) {
+    registry._adoptMany?.(entries);
+    return;
   }
-  runtime.partials.registerMany(normalized.partial);
-  runtime.routes.registerMany(normalized.route);
-  runtime.components.registerMany(normalized.component);
-  runtime.browser.cache.registerMany(normalized.cache.browser);
-  runtime.server.cache.registerMany(normalized.cache.server);
+  registry?.registerMany?.(entries);
 }
 
 function emptyDeclarations() {
@@ -267,7 +285,7 @@ function normalizeUse(typeOrModule, entries) {
     if (!registryTypes.has(typeOrModule)) {
       throw new Error(`Unknown Async registry type "${typeOrModule}".`);
     }
-    normalized[typeOrModule] = { ...(entries ?? {}) };
+    normalized[typeOrModule] = normalizeEntries(typeOrModule, entries);
     return normalized;
   }
 
@@ -284,7 +302,7 @@ function normalizeUse(typeOrModule, entries) {
     if (!registryTypes.has(type)) {
       throw new Error(`Unknown Async registry type "${type}".`);
     }
-    normalized[type] = { ...(value ?? {}) };
+    normalized[type] = normalizeEntries(type, value);
   }
 
   return normalized;
@@ -292,38 +310,20 @@ function normalizeUse(typeOrModule, entries) {
 
 function appendDeclarations(target, source) {
   for (const type of registryTypes) {
-    addEntries(target[type], source[type], type);
+    addEntries(target, type, source[type]);
   }
-  addEntries(target.cache.browser, source.cache.browser, "cache.browser");
-  addEntries(target.cache.server, source.cache.server, "cache.server");
+  addEntries(target, "cache.browser", source.cache.browser);
+  addEntries(target, "cache.server", source.cache.server);
 }
 
-function addEntries(target, source, label) {
+function addEntries(registry, type, source) {
   for (const [id, value] of Object.entries(source ?? {})) {
-    if (Object.hasOwn(target, id)) {
-      throw new Error(`${label} "${id}" is already registered.`);
-    }
-    target[id] = value;
+    registry.register(type, id, value);
   }
 }
 
-function cloneDeclarations(source) {
-  return {
-    signal: { ...source.signal },
-    handler: { ...source.handler },
-    server: { ...source.server },
-    partial: { ...source.partial },
-    route: { ...source.route },
-    component: { ...source.component },
-    cache: {
-      browser: { ...source.cache.browser },
-      server: { ...source.cache.server }
-    }
-  };
-}
-
 function isAppHub(value) {
-  return Boolean(value && typeof value.use === "function" && typeof value.snapshot === "function");
+  return Boolean(value && typeof value.use === "function" && typeof value.snapshot === "function" && value.registry);
 }
 
 function applySnapshot(signals, browserCache, snapshot = {}) {
@@ -353,6 +353,24 @@ function attachServerCache(server, cache) {
   }
 }
 
+function normalizeEntries(type, entries = {}) {
+  if (type !== "signal") {
+    return { ...(entries ?? {}) };
+  }
+  const normalized = {};
+  for (const [id, value] of Object.entries(entries ?? {})) {
+    normalized[id] = normalizeSignalDeclaration(value);
+  }
+  return normalized;
+}
+
+function normalizeSignalDeclaration(value) {
+  if (value && typeof value === "object" && typeof value.subscribe === "function") {
+    return value;
+  }
+  return createSignal(value);
+}
+
 function isLocalServerRegistry(server) {
   return typeof server?.registerMany === "function";
 }
@@ -361,14 +379,16 @@ function shouldStartRouter(routes, options) {
   return Boolean(options.routerOptions || options.mode || routes.entries().length > 0);
 }
 
-function renderDocument(routeHtml, { signals, browserCache, boundary }) {
+function renderDocument(routeHtml, { signals, browserCache, boundary, attributes }) {
   const snapshot = {
     signals: signals.snapshot(),
     cache: {
       browser: browserCache.snapshot()
     }
   };
-  return `<section data-async-boundary="${escapeAttribute(boundary)}">${routeHtml ?? ""}</section><script type="application/json" data-async-snapshot>${escapeScriptJson(snapshot)}</script>`;
+  const boundaryAttr = attributeName(attributes, "async", "boundary");
+  const snapshotAttr = attributeName(attributes, "async", "snapshot");
+  return `<section ${boundaryAttr}="${escapeAttribute(boundary)}">${routeHtml ?? ""}</section><script type="application/json" ${snapshotAttr}>${escapeScriptJson(snapshot)}</script>`;
 }
 
 function escapeAttribute(value) {

package/src/attributes.js

@@ -0,0 +1,52 @@
+const defaultPrefixes = Object.freeze({
+  async: ["async:"],
+  class: ["class:"],
+  signal: ["signal:"],
+  on: ["on:"]
+});
+
+export function defineAttributeConfig(config = {}) {
+  return normalizeAttributeConfig(config);
+}
+
+export function normalizeAttributeConfig(config = {}) {
+  return {
+    async: normalizePrefixes(config.async, defaultPrefixes.async),
+    class: normalizePrefixes(config.class, defaultPrefixes.class),
+    signal: normalizePrefixes(config.signal, defaultPrefixes.signal),
+    on: normalizePrefixes(config.on, defaultPrefixes.on)
+  };
+}
+
+export function attributeName(attributes, type, name) {
+  return normalizeAttributeConfig(attributes)[type][0] + name;
+}
+
+export function readAttribute(element, attributes, type, name) {
+  for (const prefix of normalizeAttributeConfig(attributes)[type]) {
+    const attr = `${prefix}${name}`;
+    if (element.hasAttribute?.(attr)) {
+      return element.getAttribute(attr);
+    }
+  }
+  return null;
+}
+
+export function matchAttribute(name, attributes, type) {
+  for (const prefix of normalizeAttributeConfig(attributes)[type]) {
+    if (name.startsWith(prefix)) {
+      return name.slice(prefix.length);
+    }
+  }
+  return null;
+}
+
+function normalizePrefixes(value, fallback) {
+  const prefixes = value == null ? fallback : Array.isArray(value) ? value : [value];
+  return prefixes.map((prefix) => {
+    if (typeof prefix !== "string" || prefix.length === 0) {
+      throw new TypeError("Attribute prefixes must be non-empty strings.");
+    }
+    return prefix;
+  });
+}

package/src/cache.js

@@ -1,3 +1,5 @@
+import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
+
 const cacheDefinitionKind = Symbol.for("@async/framework.cacheDefinition");
 
 export function defineCache(options = {}) {
@@ -9,11 +11,12 @@ export function defineCache(options = {}) {
   };
 }
 
-export function createCacheRegistry(initialMap = {}, { now = () => Date.now() } = {}) {
-  const definitions = new Map();
-  const entries = new Map();
+export function createCacheRegistry(initialMap = {}, { now = () => Date.now(), registry, type = "cache.browser" } = {}) {
+  const registryStore = registry ?? createRegistryStore();
+  const definitions = registryStore._map(type);
+  const entries = registryStore._map(`${type}.entries`);
 
-  const registry = {
+  const registryApi = attachRegistryInspection({
     register(id, definition = defineCache()) {
       assertId(id);
       const normalized = normalizeDefinition(definition);
@@ -26,9 +29,9 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now() }
 
     registerMany(map) {
       for (const [id, definition] of Object.entries(map ?? {})) {
-        registry.register(id, definition);
+        registryApi.register(id, definition);
       }
-      return registry;
+      return registryApi;
     },
 
     resolve(id) {
@@ -64,12 +67,12 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now() }
       if (typeof fn !== "function") {
         throw new TypeError("cache.getOrSet(key, fn) requires a function.");
       }
-      const cached = registry.get(key);
+      const cached = registryApi.get(key);
       if (cached !== undefined) {
         return cached;
       }
       const value = await fn();
-      registry.set(key, value, options);
+      registryApi.set(key, value, options);
       return value;
     },
 
@@ -81,20 +84,20 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now() }
     clear(prefix) {
       if (prefix === undefined) {
         entries.clear();
-        return registry;
+        return registryApi;
       }
       for (const key of [...entries.keys()]) {
         if (key.startsWith(prefix)) {
           entries.delete(key);
         }
       }
-      return registry;
+      return registryApi;
     },
 
     snapshot() {
       const snapshot = {};
       for (const [key] of entries) {
-        const value = registry.get(key);
+        const value = registryApi.get(key);
         if (value !== undefined) {
           snapshot[key] = value;
         }
@@ -104,14 +107,26 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now() }
 
     restore(snapshot = {}) {
       for (const [key, value] of Object.entries(snapshot ?? {})) {
-        registry.set(key, value);
+        registryApi.set(key, value);
       }
-      return registry;
+      return registryApi;
+    },
+
+    entryKeys() {
+      return [...entries.keys()];
+    },
+
+    entryEntries() {
+      return registryStore.entries(`${type}.entries`);
+    },
+
+    _adoptMany() {
+      return registryApi;
     }
-  };
+  }, registryStore, type);
 
-  registry.registerMany(initialMap);
-  return registry;
+  registryApi.registerMany(initialMap);
+  return registryApi;
 
   function resolvePolicy(key, explicitId) {
     if (explicitId !== undefined) {

package/src/component.js

@@ -1,4 +1,5 @@
 import { rawHtml, renderTemplate } from "./html.js";
+import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 
 const componentKind = Symbol.for("@async/framework.component");
 let componentCounter = 0;
@@ -16,10 +17,12 @@ export function defineComponent(fn) {
 
 export const component = defineComponent;
 
-export function createComponentRegistry(initialMap = {}) {
-  const entries = new Map();
+export function createComponentRegistry(initialMap = {}, options = {}) {
+  const registryStore = options.registry ?? createRegistryStore();
+  const type = options.type ?? "component";
+  const entries = registryStore._map(type);
 
-  const registry = {
+  const registry = attachRegistryInspection({
     register(id, Component) {
       if (typeof id !== "string" || id.length === 0) {
         throw new TypeError("Component id must be a non-empty string.");
@@ -46,8 +49,12 @@ export function createComponentRegistry(initialMap = {}) {
         throw new TypeError("Component id must be a non-empty string.");
       }
       return entries.get(id);
+    },
+
+    _adoptMany() {
+      return registry;
     }
-  };
+  }, registryStore, type);
 
   registry.registerMany(initialMap);
   return registry;
@@ -64,29 +71,46 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
 
   const scope = `${parentScope}.${componentName(Component)}.${++componentCounter}`;
   const cleanups = [];
-  const mountHooks = [];
+  const attachHooks = [];
   const visibleHooks = [];
+  const destroyHooks = [];
+  const bindingIds = [];
   const context = createComponentContext({
     runtime,
     scope,
     cleanups,
-    mountHooks,
-    visibleHooks
+    attachHooks,
+    visibleHooks,
+    destroyHooks
   });
 
   const output = Component.call(context, props);
-  const html = renderTemplate(output);
+  const html = renderTemplate(output, {
+    attributes: runtime.attributes,
+    signals: runtime.signals,
+    bind(value) {
+      const id = runtime.loader?._registerBinding?.(value);
+      if (!id) {
+        throw new Error("Inline template bindings require an AsyncLoader.");
+      }
+      bindingIds.push(id);
+      return id;
+    }
+  });
 
   return {
     html,
-    mount(target) {
-      for (const hook of mountHooks) {
+    attach(target) {
+      for (const hook of attachHooks) {
         const cleanup = hook(target);
         if (typeof cleanup === "function") {
           cleanups.push(cleanup);
         }
       }
     },
+    mount(target) {
+      this.attach(target);
+    },
     visible(target, observeVisible) {
       for (const hook of visibleHooks) {
         const cleanup = observeVisible(target, hook);
@@ -96,15 +120,24 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
       }
     },
     cleanup() {
+      while (destroyHooks.length > 0) {
+        destroyHooks.pop()?.();
+      }
       while (cleanups.length > 0) {
         cleanups.pop()?.();
       }
+      while (bindingIds.length > 0) {
+        runtime.loader?._releaseBinding?.(bindingIds.pop());
+      }
     }
   };
 }
 
-function createComponentContext({ runtime, scope, cleanups, mountHooks, visibleHooks }) {
+function createComponentContext({ runtime, scope, cleanups, attachHooks, visibleHooks, destroyHooks }) {
   const { signals, handlers, loader, server, router, cache } = runtime;
+  const generatedHandlers = new WeakMap();
+  let generatedHandlerCounter = 0;
+  let generatedSignalCounter = 0;
   const context = {
     scope,
     signals,
@@ -115,6 +148,9 @@ function createComponentContext({ runtime, scope, cleanups, mountHooks, visibleH
     cache,
 
     signal(name, initial) {
+      if (arguments.length === 1) {
+        return signals.ensure(scoped(scope, `signal.${++generatedSignalCounter}`), name);
+      }
       return signals.ensure(scoped(scope, name), initial);
     },
 
@@ -143,31 +179,70 @@ function createComponentContext({ runtime, scope, cleanups, mountHooks, visibleH
     },
 
     handler(name, fn) {
-      const id = scoped(scope, name);
-      handlers.register(id, function runComponentHandler(handlerContext) {
-        return fn.call({ ...context, ...handlerContext }, handlerContext);
-      });
-      return id;
+      if (typeof name === "function" && fn === undefined) {
+        const inlineFn = name;
+        if (generatedHandlers.has(inlineFn)) {
+          return generatedHandlers.get(inlineFn);
+        }
+        const id = registerScopedHandler(`handler.${++generatedHandlerCounter}`, inlineFn);
+        generatedHandlers.set(inlineFn, id);
+        return id;
+      }
+      if (typeof fn !== "function") {
+        throw new TypeError("this.handler(name, fn) or this.handler(fn) requires a function.");
+      }
+      return registerScopedHandler(name, fn);
     },
 
     render(Child, childProps = {}) {
       const child = renderComponent(Child, childProps, runtime, scope);
       cleanups.push(child.cleanup);
-      mountHooks.push((target) => child.mount(target));
+      attachHooks.push((target) => child.attach(target));
       visibleHooks.push((target) => child.visible(target, loader._observeVisible));
       return rawHtml(child.html);
     },
 
+    on(eventName, fn) {
+      if (typeof eventName !== "string" || eventName.length === 0) {
+        throw new TypeError("Component lifecycle event must be a non-empty string.");
+      }
+      if (typeof fn !== "function") {
+        throw new TypeError(`Component lifecycle "${eventName}" requires a function.`);
+      }
+      const event = eventName === "mount" ? "attach" : eventName;
+      if (event === "attach") {
+        attachHooks.push((target) => fn.call(context, target));
+        return;
+      }
+      if (event === "visible") {
+        visibleHooks.push((target) => fn.call(context, target));
+        return;
+      }
+      if (event === "destroy") {
+        destroyHooks.push(() => fn.call(context));
+        return;
+      }
+      throw new Error(`Unsupported component lifecycle event "${eventName}".`);
+    },
+
     onMount(fn) {
-      mountHooks.push((target) => fn.call(context, target));
+      context.on("attach", fn);
     },
 
     onVisible(fn) {
-      visibleHooks.push((target) => fn.call(context, target));
+      context.on("visible", fn);
     }
   };
 
   return context;
+
+  function registerScopedHandler(name, fn) {
+    const id = scoped(scope, name);
+    handlers.register(id, function runComponentHandler(handlerContext) {
+      return fn.call({ ...context, ...handlerContext }, handlerContext);
+    });
+    return id;
+  }
 }
 
 function scoped(scope, name) {