@async/framework 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@async/framework",
-  "version": "0.4.0",
+  "version": "0.5.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",

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,17 +83,7 @@ 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) {
@@ -96,8 +94,21 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
       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/loader.js

@@ -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) {
@@ -434,6 +451,63 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
     }
   }
 
+  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;
 }
 
@@ -581,6 +655,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

@@ -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) {

package/src/server.js

@@ -28,6 +28,11 @@ export function createServerRegistry(initialMap = {}, options = {}) {
       return registry;
     },
 
+    unregister(id) {
+      assertServerId(id);
+      return entries.delete(id);
+    },
+
     resolve(id) {
       assertServerId(id);
       return entries.get(id);
@@ -43,7 +48,7 @@ export function createServerRegistry(initialMap = {}, options = {}) {
       let runContext;
       const server = createServerNamespace((childId, childArgs, childContext = {}) => {
         return registry.run(childId, childArgs, { ...runContext, ...childContext });
-      });
+      }, {}, () => runContext);
 
       const mergedContext = {
         ...defaults,
@@ -76,7 +81,7 @@ export function createServerRegistry(initialMap = {}, options = {}) {
   }, registryStore, type);
 
   registry.registerMany(initialMap);
-  return createServerNamespace((id, args, context) => registry.run(id, args, context), registry);
+  return createServerNamespace((id, args, context) => registry.run(id, args, context), registry, () => defaults);
 }
 
 export function createServerProxy({
@@ -127,7 +132,7 @@ export function createServerProxy({
     _setContext(context = {}) {
       Object.assign(defaults, context);
     }
-  });
+  }, () => defaults);
 }
 
 export function resolveServerCommandArguments(args, context = {}) {
@@ -205,7 +210,7 @@ export function defaultInput(context = {}) {
   };
 }
 
-function createServerNamespace(run, root = {}) {
+function createServerNamespace(run, root = {}, contextProvider = () => ({})) {
   const cache = new Map();
 
   function namespace(parts) {
@@ -214,11 +219,14 @@ function createServerNamespace(run, root = {}) {
       return cache.get(cacheKey);
     }
 
-    const callable = (...args) => {
+    const callable = async (...args) => {
       if (parts.length === 0) {
         throw new Error("Server namespace is not directly callable.");
       }
-      return Promise.resolve(run(parts.join("."), args)).then(unwrapServerResult);
+      const context = contextProvider() ?? {};
+      const result = await run(parts.join("."), args, context);
+      await applyServerResult(result, context);
+      return unwrapServerResult(result);
     };
 
     const proxy = new Proxy(callable, {
@@ -229,6 +237,18 @@ function createServerNamespace(run, root = {}) {
         if (prop in _target) {
           return _target[prop];
         }
+        if (parts.length === 0 && prop === "_withContext") {
+          return (context = {}) => createServerNamespace(run, root, () => ({
+            ...(contextProvider() ?? {}),
+            ...context
+          }));
+        }
+        if (parts.length === 0 && prop === "run" && typeof root.run === "function") {
+          return (id, args = [], context = {}) => root.run(id, args, {
+            ...(contextProvider() ?? {}),
+            ...context
+          });
+        }
         if (parts.length === 0 && Object.hasOwn(root, prop)) {
           return root[prop];
         }

package/src/signals.js

@@ -121,7 +121,7 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
   const registryStore = options.registry ?? createRegistryStore();
   const type = options.type ?? "signal";
   const entries = registryStore._map(type);
-  const registryCleanups = new Set();
+  const registryCleanups = new Map();
   const runtimeContext = {};
   const boundEntries = new Set();
 
@@ -144,6 +144,19 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
       return registry;
     },
 
+    unregister(id) {
+      assertId(id);
+      if (!entries.has(id)) {
+        return false;
+      }
+      registryCleanups.get(id)?.();
+      registryCleanups.delete(id);
+      entries.get(id)?._dispose?.();
+      entries.delete(id);
+      boundEntries.delete(id);
+      return true;
+    },
+
     ensure(id, initial) {
       assertId(id);
       if (!entries.has(id)) {
@@ -256,7 +269,7 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
     },
 
     destroy() {
-      for (const cleanup of registryCleanups) {
+      for (const cleanup of registryCleanups.values()) {
         cleanup();
       }
       registryCleanups.clear();
@@ -313,7 +326,7 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
     boundEntries.add(id);
     const cleanup = entry._bindRegistry(registry, id);
     if (typeof cleanup === "function") {
-      registryCleanups.add(cleanup);
+      registryCleanups.set(id, cleanup);
     }
   }
 }