@async/framework 0.8.0 → 0.10.0

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;
 }

package/src/scheduler.js

@@ -162,6 +162,10 @@ export function createScheduler(options = {}) {
       return api;
     },
 
+    isScopeDestroyed(scope) {
+      return scope !== undefined && destroyedScopes.has(scope);
+    },
+
     inspect() {
       const counts = {};
       for (const [phase, queue] of queues) {

package/src/signals.js

@@ -1,5 +1,6 @@
 import { asyncSignal as createAsyncSignal, isAsyncSignal } from "./async-signal.js";
 import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
+import { createLazyRegistry, isLazyDescriptor } from "./lazy-registry.js";
 
 const signalKind = Symbol.for("@async/framework.signal");
 const computedKind = Symbol.for("@async/framework.computed");
@@ -122,6 +123,8 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
   const registryStore = options.registry ?? createRegistryStore();
   const type = options.type ?? "signal";
   const entries = registryStore._map(type);
+  const asyncDescriptors = registryStore._map("asyncSignal");
+  const lazyRegistry = options.lazyRegistry ?? createLazyRegistry(options);
   const registryCleanups = new Map();
   const runtimeContext = {};
   const boundEntries = new Set();
@@ -162,6 +165,7 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
 
     ensure(id, initial) {
       assertId(id);
+      materializeAsyncSignal(id);
       if (!entries.has(id)) {
         registry.register(id, createSignal(initial));
       }
@@ -169,18 +173,18 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
     },
 
     has(id) {
-      return entries.has(id);
+      return entries.has(id) || asyncDescriptors.has(id);
     },
 
     get(path) {
-      const parsed = parsePath(path, entries);
+      const parsed = parseRegistryPath(path);
       track(parsed.path);
       const entry = requireEntry(entries, parsed.id);
       return readEntry(entry, parsed.parts);
     },
 
     set(path, value) {
-      const parsed = parsePath(path, entries);
+      const parsed = parseRegistryPath(path);
       const entry = requireEntry(entries, parsed.id);
       if (parsed.parts.length === 0) {
         return entry.set(value);
@@ -199,6 +203,7 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
 
     ref(id) {
       assertId(id);
+      materializeAsyncSignal(id);
       return createRef(registry, id);
     },
 
@@ -206,7 +211,7 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
       if (typeof fn !== "function") {
         throw new TypeError("subscribe(path, fn) requires a function.");
       }
-      const parsed = parsePath(path, entries);
+      const parsed = parseRegistryPath(path);
       const entry = requireEntry(entries, parsed.id);
       const subscriptionId = ++subscriptionCounter;
       return entry.subscribe(() => {
@@ -312,6 +317,7 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
     },
 
     _entry(id) {
+      materializeAsyncSignal(id);
       return requireEntry(entries, id);
     },
 
@@ -351,6 +357,42 @@ export function createSignalRegistry(initialMap = {}, options = {}) {
     }
   }
 
+  function parseRegistryPath(path) {
+    if (typeof path !== "string" || path.length === 0) {
+      throw new TypeError("Signal path must be a non-empty string.");
+    }
+    const segments = path.split(".");
+    for (let end = segments.length; end > 0; end -= 1) {
+      const id = segments.slice(0, end).join(".");
+      if (entries.has(id) || asyncDescriptors.has(id)) {
+        materializeAsyncSignal(id);
+        return { id, parts: segments.slice(end), path };
+      }
+    }
+    const [id, ...parts] = segments;
+    return { id, parts, path };
+  }
+
+  function materializeAsyncSignal(id) {
+    if (entries.has(id) || !asyncDescriptors.has(id)) {
+      return;
+    }
+    const descriptor = asyncDescriptors.get(id);
+    if (!isLazyDescriptor(descriptor) && typeof descriptor !== "function") {
+      throw new TypeError(`Async signal "${id}" must be a function or lazy descriptor.`);
+    }
+    const loader = async function runLazyAsyncSignal(...args) {
+      const resolved = await lazyRegistry.resolve("asyncSignal", id, descriptor);
+      if (typeof resolved !== "function") {
+        throw new TypeError(`Async signal "${id}" did not resolve to a function.`);
+      }
+      return resolved.apply(this, args);
+    };
+    const entry = createAsyncSignal(id, loader);
+    entries.set(id, entry);
+    bindEntry(id, entry);
+  }
+
   function scheduleCallback(fn, options = {}) {
     const scheduler = options.scheduler;
     if (!scheduler || options.phase === "sync") {