@async/framework 0.4.0 → 0.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@async/framework",
-  "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.",
+  "version": "0.6.0",
+  "description": "No-build Loader app runtime with signals, command events, server calls, route partials, cache split, SSR activation, and streaming boundaries.",
   "type": "module",
   "packageManager": "pnpm@11.1.0",
   "engines": {
@@ -28,21 +28,49 @@
     "web-framework"
   ],
   "license": "MIT",
-  "unpkg": "./framework.js",
+  "types": "./framework.d.ts",
+  "unpkg": "./framework.umd.min.js",
+  "jsdelivr": "./framework.umd.min.js",
   "exports": {
     ".": {
-      "unpkg": "./framework.js",
+      "types": "./framework.d.ts",
+      "unpkg": "./framework.umd.min.js",
       "browser": "./framework.js",
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
-    "./framework.js": "./framework.js",
+    "./framework.js": {
+      "types": "./framework.d.ts",
+      "default": "./framework.js"
+    },
+    "./framework.min.js": {
+      "types": "./framework.d.ts",
+      "default": "./framework.min.js"
+    },
+    "./framework.umd.js": {
+      "types": "./framework.d.ts",
+      "default": "./framework.umd.js"
+    },
+    "./framework.umd.min.js": {
+      "types": "./framework.d.ts",
+      "default": "./framework.umd.min.js"
+    },
+    "./framework.ts": {
+      "types": "./framework.d.ts",
+      "default": "./framework.ts"
+    },
+    "./framework.d.ts": "./framework.d.ts",
     "./package.json": "./package.json"
   },
   "files": [
     "CHANGELOG.md",
     "README.md",
+    "framework.d.ts",
     "framework.js",
+    "framework.min.js",
+    "framework.umd.js",
+    "framework.umd.min.js",
+    "framework.ts",
     "src",
     "examples",
     "LICENSE",
@@ -68,6 +96,7 @@
     "pipeline:sync:generate": "async-pipeline sync generate",
     "pipeline:task:docs.site": "async-pipeline run-task docs.site",
     "pipeline:verify": "async-pipeline run verify",
+    "registry:lint": "node scripts/registry-lint.js",
     "release:check": "pnpm run pipeline:verify -- --force && pnpm run pipeline:pages -- --force && pnpm run pipeline:sync:check && pnpm run pipeline:github:check",
     "test": "node --test tests/*.test.js"
   },

package/src/app.js

@@ -1,7 +1,7 @@
 import { createCacheRegistry } from "./cache.js";
 import { createComponentRegistry } from "./component.js";
 import { createHandlerRegistry } from "./handlers.js";
-import { AsyncLoader } from "./loader.js";
+import { Loader } from "./loader.js";
 import { createPartialRegistry } from "./partials.js";
 import { createRouteRegistry, createRouter } from "./router.js";
 import { createServerRegistry } from "./server.js";
@@ -101,7 +101,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
       started = true;
 
       if (target !== "server") {
-        loader = loader ?? AsyncLoader({
+        loader = loader ?? Loader({
           root: options.root,
           signals,
           handlers,

package/src/async-signal.js

@@ -82,7 +82,18 @@ export function asyncSignal(id, fn) {
         signals: registry,
         id: registeredId,
         get server() {
-          return registry._context?.().server;
+          const context = registry._context?.() ?? {};
+          const server = context.server;
+          if (typeof server?._withContext === "function") {
+            return server._withContext({
+              signals: registry,
+              router: context.router,
+              loader: context.loader,
+              cache: context.cache,
+              abort: activeAbort
+            });
+          }
+          return server;
         },
         get router() {
           return registry._context?.().router;

package/src/cache.js

@@ -34,6 +34,11 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now(), r
       return registryApi;
     },
 
+    unregister(id) {
+      assertId(id);
+      return definitions.delete(id);
+    },
+
     resolve(id) {
       assertId(id);
       return definitions.get(id);

package/src/component.js

@@ -1,4 +1,5 @@
-import { rawHtml, renderTemplate } from "./html.js";
+import { attributeName } from "./attributes.js";
+import { escapeHtml, rawHtml, renderTemplate } from "./html.js";
 import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 
 const componentKind = Symbol.for("@async/framework.component");
@@ -44,6 +45,13 @@ export function createComponentRegistry(initialMap = {}, options = {}) {
       return registry;
     },
 
+    unregister(id) {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new TypeError("Component id must be a non-empty string.");
+      }
+      return entries.delete(id);
+    },
+
     resolve(id) {
       if (typeof id !== "string" || id.length === 0) {
         throw new TypeError("Component id must be a non-empty string.");
@@ -75,29 +83,32 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
   const visibleHooks = [];
   const destroyHooks = [];
   const bindingIds = [];
-  const context = createComponentContext({
-    runtime,
-    scope,
-    cleanups,
-    attachHooks,
-    visibleHooks,
-    destroyHooks
-  });
-
-  const output = Component.call(context, props);
-  const html = renderTemplate(output, {
+  const templateOptions = {
     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.");
+        throw new Error("Inline template bindings require a Loader.");
       }
       bindingIds.push(id);
       return id;
     }
+  };
+  const renderScopedTemplate = (value) => renderTemplate(value, templateOptions);
+  const context = createComponentContext({
+    runtime,
+    scope,
+    cleanups,
+    attachHooks,
+    visibleHooks,
+    destroyHooks,
+    renderScopedTemplate
   });
 
+  const output = Component.call(context, props);
+  const html = renderScopedTemplate(output);
+
   return {
     html,
     attach(target) {
@@ -133,7 +144,7 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
   };
 }
 
-function createComponentContext({ runtime, scope, cleanups, attachHooks, visibleHooks, destroyHooks }) {
+function createComponentContext({ runtime, scope, cleanups, attachHooks, visibleHooks, destroyHooks, renderScopedTemplate }) {
   const { signals, handlers, loader, server, router, cache } = runtime;
   const generatedHandlers = new WeakMap();
   let generatedHandlerCounter = 0;
@@ -149,14 +160,27 @@ function createComponentContext({ runtime, scope, cleanups, attachHooks, visible
 
     signal(name, initial) {
       if (arguments.length === 1) {
-        return signals.ensure(scoped(scope, `signal.${++generatedSignalCounter}`), name);
+        const id = scoped(scope, `signal.${++generatedSignalCounter}`);
+        const ref = signals.ensure(id, name);
+        cleanups.push(() => signals.unregister?.(id));
+        return ref;
+      }
+      const id = scoped(scope, name);
+      const created = !signals.has(id);
+      const ref = signals.ensure(id, initial);
+      if (created) {
+        cleanups.push(() => signals.unregister?.(id));
       }
-      return signals.ensure(scoped(scope, name), initial);
+      return ref;
     },
 
     computed(name, fn) {
       const id = scoped(scope, name);
+      const created = !signals.has(id);
       const ref = signals.ensure(id, undefined);
+      if (created) {
+        cleanups.push(() => signals.unregister?.(id));
+      }
       const cleanup = signals.effect(() => {
         signals.set(id, fn.call(context));
       });
@@ -166,9 +190,13 @@ function createComponentContext({ runtime, scope, cleanups, attachHooks, visible
 
     asyncSignal(name, fn) {
       const id = scoped(scope, name);
+      const created = !signals.has(id);
       if (!signals.has(id)) {
         signals.asyncSignal(id, fn);
       }
+      if (created) {
+        cleanups.push(() => signals.unregister?.(id));
+      }
       return signals.ref(id);
     },
 
@@ -202,6 +230,26 @@ function createComponentContext({ runtime, scope, cleanups, attachHooks, visible
       return rawHtml(child.html);
     },
 
+    suspense(signalRef, views) {
+      const id = signalRef?.id;
+      if (!id) {
+        throw new TypeError("this.suspense(signalRef, views) requires a signal ref.");
+      }
+
+      const normalized = normalizeSuspenseViews(views);
+      const chunks = [];
+      for (const state of ["loading", "ready", "error"]) {
+        const view = normalized[state];
+        if (!view) {
+          continue;
+        }
+        const attr = attributeName(runtime.attributes, "async", state);
+        const body = renderScopedTemplate(view.call(context, signalRef));
+        chunks.push(`<template ${attr}="${escapeHtml(id)}">${body}</template>`);
+      }
+      return rawHtml(chunks.join(""));
+    },
+
     on(eventName, fn) {
       if (typeof eventName !== "string" || eventName.length === 0) {
         throw new TypeError("Component lifecycle event must be a non-empty string.");
@@ -241,6 +289,7 @@ function createComponentContext({ runtime, scope, cleanups, attachHooks, visible
     handlers.register(id, function runComponentHandler(handlerContext) {
       return fn.call({ ...context, ...handlerContext }, handlerContext);
     });
+    cleanups.push(() => handlers.unregister?.(id));
     return id;
   }
 }
@@ -252,6 +301,21 @@ function scoped(scope, name) {
   return `${scope}.${name}`;
 }
 
+function normalizeSuspenseViews(views) {
+  const normalized = typeof views === "function" ? { ready: views } : views;
+  if (!normalized || typeof normalized !== "object" || Array.isArray(normalized)) {
+    throw new TypeError("this.suspense(signalRef, views) requires views to be a function or object.");
+  }
+
+  for (const state of ["loading", "ready", "error"]) {
+    if (Object.hasOwn(normalized, state) && normalized[state] !== undefined && typeof normalized[state] !== "function") {
+      throw new TypeError(`this.suspense(signalRef, views) view "${state}" must be a function.`);
+    }
+  }
+
+  return normalized;
+}
+
 function componentName(Component) {
   return Component.displayName || Component.name || "anonymous";
 }

package/src/handlers.js

@@ -6,11 +6,10 @@ import {
 } from "./server.js";
 import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 
-const builtInTokens = new Set(["preventDefault", "stopPropagation", "stopImmediatePropagation"]);
+const builtInTokens = new Set(["prevent", "preventDefault", "stopPropagation", "stopImmediatePropagation"]);
 const builtInHandlers = {
-  preventDefault() {
-    this.event?.preventDefault?.();
-  },
+  prevent: preventDefault,
+  preventDefault,
   stopPropagation() {
     this.event?.stopPropagation?.();
   },
@@ -19,6 +18,10 @@ const builtInHandlers = {
   }
 };
 
+function preventDefault() {
+  this.event?.preventDefault?.();
+}
+
 export function createHandlerRegistry(initialMap = {}, options = {}) {
   const registryStore = options.registry ?? createRegistryStore();
   const type = options.type ?? "handler";
@@ -44,6 +47,11 @@ export function createHandlerRegistry(initialMap = {}, options = {}) {
       return registry;
     },
 
+    unregister(id) {
+      assertId(id);
+      return handlers.delete(id);
+    },
+
     resolve(id) {
       assertId(id);
       return handlers.get(id);

package/src/index.js

@@ -6,7 +6,7 @@ export { component, createComponentRegistry, defineComponent } from "./component
 export { delay } from "./delay.js";
 export { createHandlerRegistry } from "./handlers.js";
 export { html } from "./html.js";
-export { AsyncLoader } from "./loader.js";
+export { Loader, AsyncLoader } from "./loader.js";
 export { createPartialRegistry } from "./partials.js";
 export { createRegistryStore } from "./registry-store.js";
 export { createRouteRegistry, createRouter, defineRoute, route } from "./router.js";

package/src/loader.js

@@ -5,7 +5,7 @@ import { matchAttribute, normalizeAttributeConfig, readAttribute } from "./attri
 
 const inlineBindingPrefix = "__async:inline:";
 
-export function AsyncLoader({ root, signals, handlers, server, router, cache, attributes } = {}) {
+export function Loader({ root, signals, handlers, server, router, cache, attributes } = {}) {
   const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
   const rootNode = root ?? documentRef;
   const signalRegistry = signals ?? createSignalRegistry();
@@ -19,6 +19,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
   const boundaryState = new WeakMap();
   const renderingBoundaries = new WeakSet();
   const inlineBindings = new Map();
+  const scopedCleanups = new WeakMap();
   let inlineBindingCounter = 0;
   let destroyed = false;
 
@@ -53,6 +54,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
       if (!boundary) {
         throw new Error(`Boundary "${boundaryId}" was not found.`);
       }
+      cleanupChildren(boundary);
       boundary.replaceChildren(toFragment(fragmentOrTemplate, documentRef));
       api.scan(boundary);
       return boundary;
@@ -69,11 +71,12 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
         cache: api.cache,
         attributes: attributeConfig
       });
+      cleanupChildren(target);
       target.replaceChildren(toFragment(rendered.html, target.ownerDocument));
       api.scan(target);
       rendered.mount(target);
       rendered.visible(target, api._observeVisible);
-      cleanups.add(rendered.cleanup);
+      addCleanup(rendered.cleanup, target, "children");
       return rendered;
     },
 
@@ -83,7 +86,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
       }
       destroyed = true;
       for (const cleanup of [...cleanups]) {
-        cleanup();
+        runCleanup(cleanup);
       }
       cleanups.clear();
     },
@@ -104,6 +107,13 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
   };
 
   signalRegistry._setContext?.({ server: api.server, router: api.router, loader: api, cache: api.cache });
+  api.server?._setContext?.({
+    signals: signalRegistry,
+    handlers: handlerRegistry,
+    loader: api,
+    router: api.router,
+    cache: api.cache
+  });
 
   function bindEventAttributes(scope) {
     for (const element of elementsIn(scope)) {
@@ -152,7 +162,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
     };
 
     element.addEventListener(eventName, listener);
-    cleanups.add(() => element.removeEventListener(eventName, listener));
+    addCleanup(() => element.removeEventListener(eventName, listener), element);
   }
 
   function bindSignalAttributes(scope) {
@@ -187,6 +197,12 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
           bindSignal(element, `attr:${attr}:${path}`, path, (value) => updateAttribute(element, attr, value));
           continue;
         }
+        if (signalName.startsWith("prop:")) {
+          const prop = signalName.slice("prop:".length);
+          const path = element.getAttribute(name);
+          bindSignal(element, `prop:${prop}:${path}`, path, (value) => updateProperty(element, prop, value));
+          continue;
+        }
         if (signalName.startsWith("class:")) {
           const className = signalName.slice("class:".length);
           const path = element.getAttribute(name);
@@ -255,7 +271,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
 
     const read = () => readBinding(path, options);
     apply(read());
-    cleanups.add(subscribeBinding(path, () => apply(read())));
+    addCleanup(subscribeBinding(path, () => apply(read())), element);
   }
 
   function bindValueWriter(element, path) {
@@ -319,7 +335,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
           cleanup: signalRegistry.subscribe(`${id}.$status`, () => renderBoundary(boundary))
         };
         boundaryState.set(boundary, state);
-        cleanups.add(state.cleanup);
+        addCleanup(state.cleanup, boundary);
       }
       renderBoundary(boundary);
     }
@@ -335,6 +351,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
     if (!template) {
       return;
     }
+    cleanupChildren(boundary);
     boundary.replaceChildren(template.content.cloneNode(true));
     renderingBoundaries.add(boundary);
     try {
@@ -368,7 +385,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
         continue;
       }
       visibleElements.add(element);
-      cleanups.add(observeVisible(element, () => runPseudo(element, ref)));
+      addCleanup(observeVisible(element, () => runPseudo(element, ref)), element);
     }
   }
 
@@ -398,7 +415,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
       });
       for (const result of results) {
         if (typeof result === "function") {
-          cleanups.add(result);
+          addCleanup(result, element);
         }
       }
     } catch (error) {
@@ -430,13 +447,72 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
 
   function assertActive() {
     if (destroyed) {
-      throw new Error("AsyncLoader has been destroyed.");
+      throw new Error("Loader has been destroyed.");
+    }
+  }
+
+  function addCleanup(cleanup, owner, mode = "self") {
+    if (typeof cleanup !== "function") {
+      return cleanup;
+    }
+    cleanups.add(cleanup);
+    if (owner) {
+      const records = scopedCleanups.get(owner) ?? [];
+      records.push({ cleanup, mode });
+      scopedCleanups.set(owner, records);
+    }
+    return cleanup;
+  }
+
+  function runCleanup(cleanup) {
+    if (typeof cleanup !== "function" || !cleanups.has(cleanup)) {
+      return;
+    }
+    cleanups.delete(cleanup);
+    cleanup();
+  }
+
+  function cleanupChildren(container) {
+    runScopedCleanups(container, "children");
+    for (const child of [...(container.childNodes ?? [])]) {
+      cleanupNode(child);
+    }
+  }
+
+  function cleanupNode(node) {
+    if (node.nodeType !== 1) {
+      return;
+    }
+    for (const element of elementsIn(node)) {
+      runScopedCleanups(element);
+    }
+  }
+
+  function runScopedCleanups(element, mode) {
+    const records = scopedCleanups.get(element);
+    if (!records) {
+      return;
+    }
+    const remaining = [];
+    for (const record of records) {
+      if (mode && record.mode !== mode) {
+        remaining.push(record);
+        continue;
+      }
+      runCleanup(record.cleanup);
+    }
+    if (remaining.length > 0) {
+      scopedCleanups.set(element, remaining);
+    } else {
+      scopedCleanups.delete(element);
     }
   }
 
   return api;
 }
 
+export const AsyncLoader = Loader;
+
 function normalizeClassTokens(value, tokens = new Set()) {
   if (value == null || value === false) {
     return tokens;
@@ -581,6 +657,14 @@ function updateAttribute(element, attr, value) {
   }
 }
 
+function updateProperty(element, prop, value) {
+  if (value == null) {
+    element[prop] = "";
+    return;
+  }
+  element[prop] = value;
+}
+
 function selectAll(scope, selector) {
   const elements = [];
   if (scope?.nodeType === 1 && scope.matches?.(selector)) {

package/src/partials.js

@@ -26,6 +26,11 @@ export function createPartialRegistry(initialMap = {}, options = {}) {
       return registry;
     },
 
+    unregister(id) {
+      assertId(id);
+      return entries.delete(id);
+    },
+
     resolve(id) {
       assertId(id);
       return entries.get(id);

package/src/registry-store.js

@@ -34,6 +34,10 @@ export function createRegistryStore(initial = {}, options = {}) {
       return value;
     },
 
+    unregister(type, id) {
+      return registry.delete(type, id);
+    },
+
     delete(type, id) {
       return registry._map(type).delete(id);
     },

package/src/router.js

@@ -1,4 +1,4 @@
-import { AsyncLoader } from "./loader.js";
+import { Loader } from "./loader.js";
 import { createHandlerRegistry } from "./handlers.js";
 import { createSignalRegistry } from "./signals.js";
 import { applyServerResult } from "./server.js";
@@ -41,6 +41,15 @@ export function createRouteRegistry(initialMap = {}, options = {}) {
       return registry;
     },
 
+    unregister(pattern) {
+      assertPattern(pattern);
+      const index = routes.findIndex((candidate) => candidate.pattern === pattern);
+      if (index !== -1) {
+        routes.splice(index, 1);
+      }
+      return entries.delete(pattern);
+    },
+
     match(url) {
       const path = toUrl(url).pathname;
       for (const candidate of routes) {
@@ -119,7 +128,7 @@ export function createRouter({
   const attributeConfig = normalizeAttributeConfig(attributes ?? loader?.attributes);
   const loaderInstance =
     loader ??
-    AsyncLoader({
+    Loader({
       root: rootNode,
       signals: signalRegistry,
       handlers: handlerRegistry,