@async/framework 0.9.0 → 0.10.0

package/src/browser.js

@@ -5,8 +5,10 @@ export { createBoundaryReceiver } from "./boundary-receiver.js";
 export { createCacheRegistry, defineCache } from "./cache.js";
 export { component, createComponentRegistry, defineComponent } from "./component.js";
 export { delay } from "./delay.js";
+export { defineAsyncContainerElement, defineAsyncSuspenseElement } from "./elements.js";
 export { createHandlerRegistry } from "./handlers.js";
 export { html } from "./html.js";
+export { createLazyRegistry, defineRegistrySnapshot } from "./lazy-registry.js";
 export { Loader, AsyncLoader } from "./loader.js";
 export { createPartialRegistry } from "./partials.js";
 export { createRegistryStore } from "./registry-store.js";

package/src/component.js

@@ -1,6 +1,7 @@
 import { attributeName } from "./attributes.js";
 import { escapeHtml, rawHtml, renderTemplate } from "./html.js";
 import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
+import { createLazyRegistry, isLazyDescriptor } from "./lazy-registry.js";
 
 const componentKind = Symbol.for("@async/framework.component");
 let componentCounter = 0;
@@ -22,13 +23,15 @@ export function createComponentRegistry(initialMap = {}, options = {}) {
   const registryStore = options.registry ?? createRegistryStore();
   const type = options.type ?? "component";
   const entries = registryStore._map(type);
+  const lazyRegistry = options.lazyRegistry ?? createLazyRegistry(options);
+  const lazyComponents = new Map();
 
   const registry = attachRegistryInspection({
     register(id, Component) {
       if (typeof id !== "string" || id.length === 0) {
         throw new TypeError("Component id must be a non-empty string.");
       }
-      if (!isComponent(Component) && typeof Component !== "function") {
+      if (!isComponent(Component) && typeof Component !== "function" && !isLazyDescriptor(Component)) {
         throw new TypeError(`Component "${id}" must be a component function.`);
       }
       if (entries.has(id)) {
@@ -49,6 +52,7 @@ export function createComponentRegistry(initialMap = {}, options = {}) {
       if (typeof id !== "string" || id.length === 0) {
         throw new TypeError("Component id must be a non-empty string.");
       }
+      lazyComponents.delete(id);
       return entries.delete(id);
     },
 
@@ -56,7 +60,20 @@ export function createComponentRegistry(initialMap = {}, options = {}) {
       if (typeof id !== "string" || id.length === 0) {
         throw new TypeError("Component id must be a non-empty string.");
       }
-      return entries.get(id);
+      const Component = entries.get(id);
+      if (!isLazyDescriptor(Component)) {
+        return Component;
+      }
+      if (!lazyComponents.has(id)) {
+        lazyComponents.set(id, async function LazyComponent(...args) {
+          const resolved = await lazyRegistry.resolve(type, id, Component);
+          if (typeof resolved !== "function") {
+            throw new TypeError(`Component "${id}" did not resolve to a function.`);
+          }
+          return resolved.apply(this, args);
+        });
+      }
+      return lazyComponents.get(id);
     },
 
     _adoptMany() {

package/src/elements.js

@@ -0,0 +1,63 @@
+import { Async } from "./app.js";
+
+export function defineAsyncContainerElement(options = {}) {
+  const tagName = options.tagName ?? "async-container";
+  const registry = options.customElements ?? globalThis.customElements;
+  if (!registry) {
+    throw new Error("defineAsyncContainerElement(...) requires customElements.");
+  }
+  const existing = registry.get(tagName);
+  if (existing) {
+    return existing;
+  }
+  const app = options.app ?? options.Async ?? Async;
+  const HTMLElementBase = options.HTMLElement ?? options.window?.HTMLElement ?? globalThis.HTMLElement;
+  if (!HTMLElementBase) {
+    throw new Error("defineAsyncContainerElement(...) requires HTMLElement.");
+  }
+
+  class AsyncContainerElement extends HTMLElementBase {
+    connectedCallback() {
+      if (this.__asyncAttached) {
+        return;
+      }
+      const runtime = app.runtime ?? app.start?.();
+      runtime?.attachRoot?.(this);
+      this.__asyncRuntime = runtime;
+      this.__asyncAttached = true;
+    }
+
+    disconnectedCallback() {
+      if (!this.__asyncAttached) {
+        return;
+      }
+      this.__asyncRuntime?.detachRoot?.(this);
+      this.__asyncRuntime = undefined;
+      this.__asyncAttached = false;
+    }
+  }
+
+  registry.define(tagName, AsyncContainerElement);
+  return AsyncContainerElement;
+}
+
+export function defineAsyncSuspenseElement(options = {}) {
+  const tagName = options.tagName ?? "async-suspense";
+  const registry = options.customElements ?? globalThis.customElements;
+  if (!registry) {
+    throw new Error("defineAsyncSuspenseElement(...) requires customElements.");
+  }
+  const existing = registry.get(tagName);
+  if (existing) {
+    return existing;
+  }
+  const HTMLElementBase = options.HTMLElement ?? options.window?.HTMLElement ?? globalThis.HTMLElement;
+  if (!HTMLElementBase) {
+    throw new Error("defineAsyncSuspenseElement(...) requires HTMLElement.");
+  }
+
+  class AsyncSuspenseElement extends HTMLElementBase {}
+
+  registry.define(tagName, AsyncSuspenseElement);
+  return AsyncSuspenseElement;
+}

package/src/handlers.js

@@ -5,6 +5,7 @@ import {
   unwrapServerResult
 } from "./server.js";
 import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
+import { createLazyRegistry, isLazyDescriptor } from "./lazy-registry.js";
 
 const builtInTokens = new Set(["prevent", "preventDefault", "stopPropagation", "stopImmediatePropagation"]);
 const builtInHandlers = {
@@ -26,11 +27,13 @@ export function createHandlerRegistry(initialMap = {}, options = {}) {
   const registryStore = options.registry ?? createRegistryStore();
   const type = options.type ?? "handler";
   const handlers = registryStore._map(type);
+  const lazyRegistry = options.lazyRegistry ?? createLazyRegistry(options);
+  const lazyHandlers = new Map();
 
   const registry = attachRegistryInspection({
     register(id, fn) {
       assertId(id);
-      if (typeof fn !== "function") {
+      if (typeof fn !== "function" && !isLazyDescriptor(fn)) {
         throw new TypeError(`Handler "${id}" must be a function.`);
       }
       if (handlers.has(id)) {
@@ -49,12 +52,26 @@ export function createHandlerRegistry(initialMap = {}, options = {}) {
 
     unregister(id) {
       assertId(id);
+      lazyHandlers.delete(id);
       return handlers.delete(id);
     },
 
     resolve(id) {
       assertId(id);
-      return handlers.get(id);
+      const handler = handlers.get(id);
+      if (!isLazyDescriptor(handler)) {
+        return handler;
+      }
+      if (!lazyHandlers.has(id)) {
+        lazyHandlers.set(id, async function runLazyHandler(...args) {
+          const resolved = await lazyRegistry.resolve(type, id, handler);
+          if (typeof resolved !== "function") {
+            throw new TypeError(`Handler "${id}" did not resolve to a function.`);
+          }
+          return resolved.apply(this, args);
+        });
+      }
+      return lazyHandlers.get(id);
     },
 
     async run(ref, context = {}) {

package/src/index.js

@@ -5,8 +5,10 @@ export { createBoundaryReceiver } from "./boundary-receiver.js";
 export { createCacheRegistry, defineCache } from "./cache.js";
 export { component, createComponentRegistry, defineComponent } from "./component.js";
 export { delay } from "./delay.js";
+export { defineAsyncContainerElement, defineAsyncSuspenseElement } from "./elements.js";
 export { createHandlerRegistry } from "./handlers.js";
 export { html } from "./html.js";
+export { createLazyRegistry, defineRegistrySnapshot } from "./lazy-registry.js";
 export { Loader, AsyncLoader } from "./loader.js";
 export { createPartialRegistry } from "./partials.js";
 export { createRegistryStore } from "./registry-store.js";

package/src/lazy-registry.js

@@ -0,0 +1,204 @@
+const descriptorTypes = new Set(["handler", "component", "asyncSignal", "partial", "route"]);
+const defaultBaseUrl = "_async";
+
+export function defineRegistrySnapshot(snapshot = {}) {
+  if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) {
+    throw new TypeError("defineRegistrySnapshot(snapshot) requires an object.");
+  }
+  return snapshot;
+}
+
+export function createLazyRegistry(options = {}) {
+  const registryAssets = normalizeRegistryAssets(options.registryAssets ?? options.assets);
+  const importModule = options.importModule ?? ((url) => import(url));
+  const moduleCache = new Map();
+  const exportCache = new Map();
+
+  return {
+    registryAssets,
+
+    resolveUrl(type, id, descriptor) {
+      return resolveDescriptorUrl(type, id, descriptor, registryAssets);
+    },
+
+    async resolve(type, id, descriptor) {
+      if (!isLazyDescriptor(descriptor)) {
+        return descriptor;
+      }
+      const cacheKey = `${type}:${id}`;
+      if (exportCache.has(cacheKey)) {
+        return exportCache.get(cacheKey);
+      }
+
+      const resolved = resolveDescriptorUrl(type, id, descriptor, registryAssets);
+      let modulePromise = moduleCache.get(resolved.moduleUrl);
+      if (!modulePromise) {
+        modulePromise = Promise.resolve(importModule(resolved.moduleUrl));
+        moduleCache.set(resolved.moduleUrl, modulePromise);
+      }
+      const module = await modulePromise;
+      const value = resolveExport(module, resolved.exportNames, type, id);
+      exportCache.set(cacheKey, value);
+      return value;
+    },
+
+    inspect() {
+      return {
+        registryAssets,
+        modules: [...moduleCache.keys()],
+        exports: [...exportCache.keys()]
+      };
+    }
+  };
+}
+
+export function normalizeRegistryAssets(options = {}) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultBaseUrl);
+  const paths = {
+    component: "component",
+    handler: "handler",
+    asyncSignal: "asyncSignal",
+    partial: "partial",
+    route: "route",
+    ...(options.paths ?? {})
+  };
+
+  for (const [type, value] of Object.entries(paths)) {
+    if (!descriptorTypes.has(type)) {
+      continue;
+    }
+    if (typeof value !== "string" || value.length === 0) {
+      throw new TypeError(`Registry asset path for "${type}" must be a non-empty string.`);
+    }
+  }
+
+  return {
+    baseUrl,
+    paths
+  };
+}
+
+export function isLazyDescriptor(value) {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      typeof value.url === "string"
+  );
+}
+
+export function sameRegistryValue(left, right) {
+  if (left === right) {
+    return true;
+  }
+  if (isLazyDescriptor(left) && isLazyDescriptor(right)) {
+    return stableStringify(left) === stableStringify(right);
+  }
+  return false;
+}
+
+export function publicRegistryValue(value, id) {
+  if (isLazyDescriptor(value)) {
+    return { ...value };
+  }
+  return { id };
+}
+
+function resolveDescriptorUrl(type, id, descriptor, registryAssets) {
+  if (!descriptorTypes.has(type)) {
+    throw new Error(`Registry type "${type}" does not support lazy descriptors.`);
+  }
+  if (!isLazyDescriptor(descriptor)) {
+    throw new TypeError(`Registry descriptor for "${type}:${id}" requires a url.`);
+  }
+
+  const { path, hash } = splitHash(descriptor.url);
+  const moduleUrl = resolveModuleUrl(type, path, registryAssets);
+  const exportNames = hash
+    ? [hash]
+    : inferredExportNames(id, path);
+
+  return {
+    moduleUrl,
+    exportNames,
+    url: hash ? `${moduleUrl}#${hash}` : moduleUrl
+  };
+}
+
+function resolveModuleUrl(type, path, registryAssets) {
+  if (isAbsoluteUrl(path) || path.startsWith("/") || path.startsWith("./") || path.startsWith("../")) {
+    return path;
+  }
+  const typePath = registryAssets.paths[type] ?? type;
+  return joinUrl(registryAssets.baseUrl, typePath, path);
+}
+
+function resolveExport(module, exportNames, type, id) {
+  for (const name of exportNames) {
+    if (name in module) {
+      return module[name];
+    }
+  }
+  throw new Error(`Lazy ${type} "${id}" did not export ${exportNames.map((name) => `"${name}"`).join(", ")}.`);
+}
+
+function inferredExportNames(id, path) {
+  const names = [];
+  const leaf = id.split(".").filter(Boolean).at(-1);
+  const basename = path
+    .split("/")
+    .filter(Boolean)
+    .at(-1)
+    ?.replace(/\.[^.]+$/, "");
+  for (const name of [leaf, basename, "default"]) {
+    if (name && !names.includes(name)) {
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+function splitHash(url) {
+  const index = url.indexOf("#");
+  if (index === -1) {
+    return { path: url, hash: "" };
+  }
+  return {
+    path: url.slice(0, index),
+    hash: url.slice(index + 1)
+  };
+}
+
+function normalizeBaseUrl(baseUrl) {
+  if (typeof baseUrl !== "string" || baseUrl.length === 0) {
+    throw new TypeError("registryAssets.baseUrl must be a non-empty string.");
+  }
+  if (isAbsoluteUrl(baseUrl) || baseUrl.startsWith("/") || baseUrl.startsWith("./") || baseUrl.startsWith("../")) {
+    return stripTrailingSlash(baseUrl);
+  }
+  return `/${stripSlashes(baseUrl)}`;
+}
+
+function joinUrl(...parts) {
+  const [first, ...rest] = parts;
+  return [stripTrailingSlash(first), ...rest.map(stripSlashes)].filter(Boolean).join("/");
+}
+
+function stripSlashes(value) {
+  return String(value).replace(/^\/+|\/+$/g, "");
+}
+
+function stripTrailingSlash(value) {
+  return String(value).replace(/\/+$/g, "");
+}
+
+function isAbsoluteUrl(value) {
+  return /^[A-Za-z][A-Za-z\d+.-]*:/.test(value);
+}
+
+function stableStringify(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+  return JSON.stringify(Object.keys(value).sort().map((key) => [key, value[key]]));
+}

package/src/loader.js

@@ -335,7 +335,7 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
       if (renderingBoundaries.has(boundary)) {
         continue;
       }
-      const id = readAttribute(boundary, attributeConfig, "async", "boundary");
+      const id = boundaryIdFor(boundary, attributeConfig);
       if (id == null) {
         continue;
       }
@@ -652,19 +652,26 @@ function writeClassTokens(element, tokens) {
 function collectBoundaryTemplates(boundary, id, attributeConfig) {
   const templates = {};
   for (const template of [...boundary.children].filter((child) => child.tagName === "TEMPLATE")) {
-    if (readAttribute(template, attributeConfig, "async", "loading") === id) {
+    if (templateMatchesState(template, "loading", id, boundary, attributeConfig)) {
       templates.loading = template;
     }
-    if (readAttribute(template, attributeConfig, "async", "ready") === id) {
+    if (templateMatchesState(template, "ready", id, boundary, attributeConfig)) {
       templates.ready = template;
     }
-    if (readAttribute(template, attributeConfig, "async", "error") === id) {
+    if (templateMatchesState(template, "error", id, boundary, attributeConfig)) {
       templates.error = template;
     }
   }
   return templates;
 }
 
+function templateMatchesState(template, state, id, boundary, attributeConfig) {
+  if (readAttribute(template, attributeConfig, "async", state) === id) {
+    return true;
+  }
+  return isAsyncSuspense(boundary) && template.hasAttribute?.(state);
+}
+
 function chooseBoundaryTemplate(templates, status) {
   if (status === "ready") {
     return templates.ready ?? templates.loading ?? templates.error;
@@ -712,13 +719,24 @@ function elementsIn(scope) {
 
 function findBoundary(root, boundaryId, attributeConfig) {
   for (const element of elementsIn(root)) {
-    if (readAttribute(element, attributeConfig, "async", "boundary") === String(boundaryId)) {
+    if (boundaryIdFor(element, attributeConfig) === String(boundaryId)) {
       return element;
     }
   }
   return null;
 }
 
+function boundaryIdFor(element, attributeConfig) {
+  if (isAsyncSuspense(element) && element.hasAttribute?.("for")) {
+    return element.getAttribute("for");
+  }
+  return readAttribute(element, attributeConfig, "async", "boundary");
+}
+
+function isAsyncSuspense(element) {
+  return element?.tagName === "ASYNC-SUSPENSE";
+}
+
 function toFragment(value, documentRef) {
   if (value?.nodeType === 11) {
     return value;

package/src/partials.js

@@ -1,15 +1,18 @@
 import { isTemplateResult, renderTemplate } from "./html.js";
 import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
+import { createLazyRegistry, isLazyDescriptor } from "./lazy-registry.js";
 
 export function createPartialRegistry(initialMap = {}, options = {}) {
   const registryStore = options.registry ?? createRegistryStore();
   const type = options.type ?? "partial";
   const entries = registryStore._map(type);
+  const lazyRegistry = options.lazyRegistry ?? createLazyRegistry(options);
+  const lazyPartials = new Map();
 
   const registry = attachRegistryInspection({
     register(id, fn) {
       assertId(id);
-      if (typeof fn !== "function") {
+      if (typeof fn !== "function" && !isLazyDescriptor(fn)) {
         throw new TypeError(`Partial "${id}" must be a function.`);
       }
       if (entries.has(id)) {
@@ -28,12 +31,26 @@ export function createPartialRegistry(initialMap = {}, options = {}) {
 
     unregister(id) {
       assertId(id);
+      lazyPartials.delete(id);
       return entries.delete(id);
     },
 
     resolve(id) {
       assertId(id);
-      return entries.get(id);
+      const partial = entries.get(id);
+      if (!isLazyDescriptor(partial)) {
+        return partial;
+      }
+      if (!lazyPartials.has(id)) {
+        lazyPartials.set(id, async function runLazyPartial(...args) {
+          const resolved = await lazyRegistry.resolve(type, id, partial);
+          if (typeof resolved !== "function") {
+            throw new TypeError(`Partial "${id}" did not resolve to a function.`);
+          }
+          return resolved.apply(this, args);
+        });
+      }
+      return lazyPartials.get(id);
     },
 
     async render(id, props = {}, context = {}) {

package/src/registry-store.js

@@ -1,4 +1,6 @@
-const declarationTypes = new Set(["signal", "handler", "server", "partial", "route", "component"]);
+import { publicRegistryValue } from "./lazy-registry.js";
+
+const declarationTypes = new Set(["signal", "handler", "server", "partial", "route", "component", "asyncSignal"]);
 const cacheTypes = new Set(["cache.browser", "cache.server"]);
 const cacheEntryTypes = new Set(["cache.browser.entries", "cache.server.entries"]);
 const allTypes = new Set([...declarationTypes, ...cacheTypes, ...cacheEntryTypes]);
@@ -85,11 +87,12 @@ export function createRegistryStore(initial = {}, options = {}) {
       const snapshotTarget = snapshotOptions.target ?? target;
       return {
         signal: snapshotSignals(backing.signal),
-        handler: snapshotDescriptors(backing.handler, "handler"),
-        server: snapshotDescriptors(backing.server, "server"),
-        partial: snapshotDescriptors(backing.partial, "partial"),
+        handler: snapshotDescriptors(backing.handler),
+        server: snapshotDescriptors(backing.server),
+        partial: snapshotDescriptors(backing.partial),
         route: snapshotPlain(backing.route),
-        component: snapshotDescriptors(backing.component, "component"),
+        component: snapshotDescriptors(backing.component),
+        asyncSignal: snapshotDescriptors(backing.asyncSignal),
         cache: {
           browser: snapshotPlain(backing.cache.browser),
           server: snapshotPlain(backing.cache.server)
@@ -109,6 +112,7 @@ export function createRegistryStore(initial = {}, options = {}) {
         partial: Object.fromEntries(backing.partial),
         route: Object.fromEntries(backing.route),
         component: Object.fromEntries(backing.component),
+        asyncSignal: Object.fromEntries(backing.asyncSignal),
         cache: {
           browser: Object.fromEntries(backing.cache.browser),
           server: Object.fromEntries(backing.cache.server)
@@ -168,6 +172,7 @@ function createBacking() {
     partial: new Map(),
     route: new Map(),
     component: new Map(),
+    asyncSignal: new Map(),
     cache: {
       browser: new Map(),
       server: new Map()
@@ -186,6 +191,7 @@ function applyInitial(registry, initial = {}) {
   registry.registerMany("partial", initial.partial);
   registry.registerMany("route", initial.route);
   registry.registerMany("component", initial.component);
+  registry.registerMany("asyncSignal", initial.asyncSignal);
   registry.registerMany("cache.browser", initial.cache?.browser);
   registry.registerMany("cache.server", initial.cache?.server);
 
@@ -213,7 +219,7 @@ function assertId(type, id) {
 
 function publicValue(type, id, value, options) {
   if (type === "server" && options.target === "browser") {
-    return { id, kind: "server" };
+    return publicRegistryValue(value, id);
   }
   if (cacheEntryTypes.has(type)) {
     return value?.value;
@@ -233,10 +239,10 @@ function snapshotSignals(map) {
   return snapshot;
 }
 
-function snapshotDescriptors(map, kind) {
+function snapshotDescriptors(map) {
   const snapshot = {};
-  for (const id of map.keys()) {
-    snapshot[id] = { id, kind };
+  for (const [id, value] of map) {
+    snapshot[id] = publicRegistryValue(value, id);
   }
   return snapshot;
 }