@async/framework 0.2.2 → 0.3.0

package/src/loader.js

@@ -1,12 +1,14 @@
 import { renderComponent } from "./component.js";
 import { createHandlerRegistry } from "./handlers.js";
 import { createSignalRegistry } from "./signals.js";
+import { matchAttribute, normalizeAttributeConfig, readAttribute } from "./attributes.js";
 
-export function AsyncLoader({ root, signals, handlers, server, router, cache } = {}) {
+export function AsyncLoader({ root, signals, handlers, server, router, cache, attributes } = {}) {
   const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
   const rootNode = root ?? documentRef;
   const signalRegistry = signals ?? createSignalRegistry();
   const handlerRegistry = handlers ?? createHandlerRegistry();
+  const attributeConfig = normalizeAttributeConfig(attributes);
   const cleanups = new Set();
   const eventBindings = new WeakMap();
   const signalBindings = new WeakMap();
@@ -23,6 +25,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache } =
     server,
     router,
     cache,
+    attributes: attributeConfig,
 
     start() {
       assertActive();
@@ -41,7 +44,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache } =
 
     swap(boundaryId, fragmentOrTemplate) {
       assertActive();
-      const boundary = findBoundary(rootNode, boundaryId);
+      const boundary = findBoundary(rootNode, boundaryId, attributeConfig);
       if (!boundary) {
         throw new Error(`Boundary "${boundaryId}" was not found.`);
       }
@@ -58,7 +61,8 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache } =
         loader: api,
         server: api.server,
         router: api.router,
-        cache: api.cache
+        cache: api.cache,
+        attributes: attributeConfig
       });
       target.replaceChildren(toFragment(rendered.html, target.ownerDocument));
       api.scan(target);
@@ -87,15 +91,15 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache } =
   signalRegistry._setContext?.({ server: api.server, router: api.router, loader: api, cache: api.cache });
 
   function bindEventAttributes(scope) {
-    for (const element of selectAll(scope, "[data-async-container], *")) {
+    for (const element of elementsIn(scope)) {
       if (typeof element.getAttributeNames !== "function") {
         continue;
       }
       for (const name of element.getAttributeNames()) {
-        if (!name.startsWith("on:")) {
+        const eventName = matchAttribute(name, attributeConfig, "on");
+        if (!eventName) {
           continue;
         }
-        const eventName = name.slice(3);
         if (eventName === "mount" || eventName === "visible") {
           continue;
         }
@@ -137,33 +141,39 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache } =
   }
 
   function bindSignalAttributes(scope) {
-    for (const element of selectAll(scope, "[data-async-text]")) {
-      bindSignal(element, `text:${element.getAttribute("data-async-text")}`, element.getAttribute("data-async-text"), (value) => {
-        element.textContent = value ?? "";
-      });
-    }
-
-    for (const element of selectAll(scope, "[data-async-value]")) {
-      const path = element.getAttribute("data-async-value");
-      bindSignal(element, `value:${path}`, path, (value) => {
-        if ("value" in element && element.value !== String(value ?? "")) {
-          element.value = value ?? "";
-        } else if (!("value" in element)) {
-          element.setAttribute("value", value ?? "");
-        }
-      });
-      bindValueWriter(element, path);
-    }
-
-    for (const element of selectAll(scope, "*")) {
+    for (const element of elementsIn(scope)) {
       for (const name of element.getAttributeNames?.() ?? []) {
-        if (name.startsWith("data-async-attr:")) {
-          const attr = name.slice("data-async-attr:".length);
+        const signalName = matchAttribute(name, attributeConfig, "signal");
+        if (!signalName) {
+          continue;
+        }
+        if (signalName === "text") {
+          const path = element.getAttribute(name);
+          bindSignal(element, `text:${path}`, path, (value) => {
+            element.textContent = value ?? "";
+          });
+          continue;
+        }
+        if (signalName === "value") {
+          const path = element.getAttribute(name);
+          bindSignal(element, `value:${path}`, path, (value) => {
+            if ("value" in element && element.value !== String(value ?? "")) {
+              element.value = value ?? "";
+            } else if (!("value" in element)) {
+              element.setAttribute("value", value ?? "");
+            }
+          });
+          bindValueWriter(element, path);
+          continue;
+        }
+        if (signalName.startsWith("attr:")) {
+          const attr = signalName.slice("attr:".length);
           const path = element.getAttribute(name);
           bindSignal(element, `attr:${attr}:${path}`, path, (value) => updateAttribute(element, attr, value));
+          continue;
         }
-        if (name.startsWith("data-async-class:")) {
-          const className = name.slice("data-async-class:".length);
+        if (signalName.startsWith("class:")) {
+          const className = signalName.slice("class:".length);
           const path = element.getAttribute(name);
           bindSignal(element, `class:${className}:${path}`, path, (value) => {
             element.classList.toggle(className, Boolean(value));
@@ -196,13 +206,16 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache } =
   }
 
   function bindBoundaries(scope) {
-    for (const boundary of selectAll(scope, "[data-async-boundary]")) {
+    for (const boundary of elementsIn(scope)) {
       if (renderingBoundaries.has(boundary)) {
         continue;
       }
-      const id = boundary.getAttribute("data-async-boundary");
+      const id = readAttribute(boundary, attributeConfig, "async", "boundary");
+      if (id == null) {
+        continue;
+      }
       if (!boundaryState.has(boundary)) {
-        const templates = collectBoundaryTemplates(boundary, id);
+        const templates = collectBoundaryTemplates(boundary, id, attributeConfig);
         if (Object.keys(templates).length === 0 || !signalRegistry.has(id)) {
           continue;
         }
@@ -238,20 +251,28 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache } =
   }
 
   function runPseudoEvents(scope) {
-    for (const element of selectAll(scope, "[on\\:mount]")) {
+    for (const element of elementsIn(scope)) {
+      const ref = readAttribute(element, attributeConfig, "on", "mount");
+      if (ref == null) {
+        continue;
+      }
       if (mountedElements.has(element)) {
         continue;
       }
       mountedElements.add(element);
-      runPseudo(element, element.getAttribute("on:mount"));
+      runPseudo(element, ref);
     }
 
-    for (const element of selectAll(scope, "[on\\:visible]")) {
+    for (const element of elementsIn(scope)) {
+      const ref = readAttribute(element, attributeConfig, "on", "visible");
+      if (ref == null) {
+        continue;
+      }
       if (visibleElements.has(element)) {
         continue;
       }
       visibleElements.add(element);
-      cleanups.add(observeVisible(element, () => runPseudo(element, element.getAttribute("on:visible"))));
+      cleanups.add(observeVisible(element, () => runPseudo(element, ref)));
     }
   }
 
@@ -309,16 +330,16 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache } =
   return api;
 }
 
-function collectBoundaryTemplates(boundary, id) {
+function collectBoundaryTemplates(boundary, id, attributeConfig) {
   const templates = {};
   for (const template of [...boundary.children].filter((child) => child.tagName === "TEMPLATE")) {
-    if (template.getAttribute("data-async-loading") === id) {
+    if (readAttribute(template, attributeConfig, "async", "loading") === id) {
       templates.loading = template;
     }
-    if (template.getAttribute("data-async-ready") === id) {
+    if (readAttribute(template, attributeConfig, "async", "ready") === id) {
       templates.ready = template;
     }
-    if (template.getAttribute("data-async-error") === id) {
+    if (readAttribute(template, attributeConfig, "async", "error") === id) {
       templates.error = template;
     }
   }
@@ -358,12 +379,17 @@ function selectAll(scope, selector) {
   return elements;
 }
 
-function findBoundary(root, boundaryId) {
-  const selector = `[data-async-boundary="${String(boundaryId).replaceAll('"', '\\"')}"]`;
-  if (root?.nodeType === 1 && root.matches?.(selector)) {
-    return root;
+function elementsIn(scope) {
+  return selectAll(scope, "*");
+}
+
+function findBoundary(root, boundaryId, attributeConfig) {
+  for (const element of elementsIn(root)) {
+    if (readAttribute(element, attributeConfig, "async", "boundary") === String(boundaryId)) {
+      return element;
+    }
   }
-  return root?.querySelector?.(selector);
+  return null;
 }
 
 function toFragment(value, documentRef) {

package/src/partials.js

@@ -1,9 +1,12 @@
 import { isTemplateResult, renderTemplate } from "./html.js";
+import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 
-export function createPartialRegistry(initialMap = {}) {
-  const entries = new Map();
+export function createPartialRegistry(initialMap = {}, options = {}) {
+  const registryStore = options.registry ?? createRegistryStore();
+  const type = options.type ?? "partial";
+  const entries = registryStore._map(type);
 
-  const registry = {
+  const registry = attachRegistryInspection({
     register(id, fn) {
       assertId(id);
       if (typeof fn !== "function") {
@@ -44,8 +47,12 @@ export function createPartialRegistry(initialMap = {}) {
       };
       const result = await fn.call(partialContext, props);
       return normalizePartialResult(result);
+    },
+
+    _adoptMany() {
+      return registry;
     }
-  };
+  }, registryStore, type);
 
   registry.registerMany(initialMap);
   return registry;

package/src/registry-store.js

@@ -0,0 +1,257 @@
+const declarationTypes = new Set(["signal", "handler", "server", "partial", "route", "component"]);
+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]);
+
+export function createRegistryStore(initial = {}, options = {}) {
+  const backing = options.backing ?? createBacking();
+  const target = options.target ?? "server";
+
+  const registry = {
+    target,
+
+    register(type, id, value) {
+      const map = registry._map(type);
+      assertId(type, id);
+      if (map.has(id)) {
+        throw new Error(`${type} "${id}" is already registered.`);
+      }
+      map.set(id, value);
+      return id;
+    },
+
+    registerMany(type, map = {}) {
+      for (const [id, value] of Object.entries(map ?? {})) {
+        registry.register(type, id, value);
+      }
+      return registry;
+    },
+
+    set(type, id, value) {
+      const map = registry._map(type);
+      assertId(type, id);
+      map.set(id, value);
+      return value;
+    },
+
+    delete(type, id) {
+      return registry._map(type).delete(id);
+    },
+
+    keys(type) {
+      if (isHiddenInBrowser(type, target)) {
+        return [];
+      }
+      return [...registry._map(type).keys()];
+    },
+
+    entries(type, entryOptions = {}) {
+      const normalized = normalizeType(type);
+      if (isHiddenInBrowser(normalized, entryOptions.target ?? target)) {
+        return [];
+      }
+      return [...registry._map(normalized)].map(([id, value]) => [
+        id,
+        publicValue(normalized, id, value, { target, ...entryOptions })
+      ]);
+    },
+
+    has(type, id) {
+      assertId(type, id);
+      if (isHiddenInBrowser(type, target)) {
+        return false;
+      }
+      return registry._map(type).has(id);
+    },
+
+    get(type, id, getOptions = {}) {
+      assertId(type, id);
+      const normalized = normalizeType(type);
+      if (isHiddenInBrowser(normalized, getOptions.target ?? target)) {
+        return undefined;
+      }
+      const value = registry._map(normalized).get(id);
+      if (value === undefined) {
+        return undefined;
+      }
+      return publicValue(normalized, id, value, { target, ...getOptions });
+    },
+
+    snapshot(snapshotOptions = {}) {
+      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"),
+        route: snapshotPlain(backing.route),
+        component: snapshotDescriptors(backing.component, "component"),
+        cache: {
+          browser: snapshotPlain(backing.cache.browser),
+          server: snapshotPlain(backing.cache.server)
+        },
+        entries: {
+          browser: snapshotCacheEntries(backing.cacheEntries.browser),
+          server: snapshotTarget === "browser" ? {} : snapshotCacheEntries(backing.cacheEntries.server)
+        }
+      };
+    },
+
+    rawSnapshot() {
+      return {
+        signal: Object.fromEntries(backing.signal),
+        handler: Object.fromEntries(backing.handler),
+        server: Object.fromEntries(backing.server),
+        partial: Object.fromEntries(backing.partial),
+        route: Object.fromEntries(backing.route),
+        component: Object.fromEntries(backing.component),
+        cache: {
+          browser: Object.fromEntries(backing.cache.browser),
+          server: Object.fromEntries(backing.cache.server)
+        }
+      };
+    },
+
+    view(viewOptions = {}) {
+      return createRegistryStore(undefined, {
+        backing,
+        target: viewOptions.target ?? target
+      });
+    },
+
+    _map(type) {
+      const normalized = normalizeType(type);
+      if (declarationTypes.has(normalized)) {
+        return backing[normalized];
+      }
+      if (normalized === "cache.browser") {
+        return backing.cache.browser;
+      }
+      if (normalized === "cache.server") {
+        return backing.cache.server;
+      }
+      if (normalized === "cache.browser.entries") {
+        return backing.cacheEntries.browser;
+      }
+      if (normalized === "cache.server.entries") {
+        return backing.cacheEntries.server;
+      }
+      throw new Error(`Unknown Async registry type "${type}".`);
+    }
+  };
+
+  applyInitial(registry, initial);
+  return registry;
+}
+
+export function attachRegistryInspection(target, registry, type) {
+  Object.defineProperty(target, "registry", {
+    configurable: true,
+    enumerable: true,
+    value: registry
+  });
+  target.keys = () => registry.keys(type);
+  target.entries = () => registry.entries(type);
+  target.inspect = () => registry.entries(type);
+  return target;
+}
+
+function createBacking() {
+  return {
+    signal: new Map(),
+    handler: new Map(),
+    server: new Map(),
+    partial: new Map(),
+    route: new Map(),
+    component: new Map(),
+    cache: {
+      browser: new Map(),
+      server: new Map()
+    },
+    cacheEntries: {
+      browser: new Map(),
+      server: new Map()
+    }
+  };
+}
+
+function applyInitial(registry, initial = {}) {
+  registry.registerMany("signal", initial.signal);
+  registry.registerMany("handler", initial.handler);
+  registry.registerMany("server", initial.server);
+  registry.registerMany("partial", initial.partial);
+  registry.registerMany("route", initial.route);
+  registry.registerMany("component", initial.component);
+  registry.registerMany("cache.browser", initial.cache?.browser);
+  registry.registerMany("cache.server", initial.cache?.server);
+
+  const entries = initial.entries ?? {};
+  for (const [key, value] of Object.entries(entries.browser ?? {})) {
+    registry.set("cache.browser.entries", key, cacheEntry(value));
+  }
+  for (const [key, value] of Object.entries(entries.server ?? {})) {
+    registry.set("cache.server.entries", key, cacheEntry(value));
+  }
+}
+
+function normalizeType(type) {
+  if (!allTypes.has(type)) {
+    throw new Error(`Unknown Async registry type "${type}".`);
+  }
+  return type;
+}
+
+function assertId(type, id) {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new TypeError(`${type} id must be a non-empty string.`);
+  }
+}
+
+function publicValue(type, id, value, options) {
+  if (type === "server" && options.target === "browser") {
+    return { id, kind: "server" };
+  }
+  if (cacheEntryTypes.has(type)) {
+    return value?.value;
+  }
+  return value;
+}
+
+function isHiddenInBrowser(type, target) {
+  return type === "cache.server.entries" && target === "browser";
+}
+
+function snapshotSignals(map) {
+  const snapshot = {};
+  for (const [id, entry] of map) {
+    snapshot[id] = typeof entry?.snapshot === "function" ? entry.snapshot() : entry?.value ?? entry;
+  }
+  return snapshot;
+}
+
+function snapshotDescriptors(map, kind) {
+  const snapshot = {};
+  for (const id of map.keys()) {
+    snapshot[id] = { id, kind };
+  }
+  return snapshot;
+}
+
+function snapshotPlain(map) {
+  return Object.fromEntries(map);
+}
+
+function snapshotCacheEntries(map) {
+  const snapshot = {};
+  for (const [id, entry] of map) {
+    snapshot[id] = entry?.value;
+  }
+  return snapshot;
+}
+
+function cacheEntry(value) {
+  if (value && typeof value === "object" && Object.hasOwn(value, "value")) {
+    return value;
+  }
+  return { value };
+}

package/src/router.js

@@ -2,6 +2,8 @@ import { AsyncLoader } from "./loader.js";
 import { createHandlerRegistry } from "./handlers.js";
 import { createSignalRegistry } from "./signals.js";
 import { applyServerResult } from "./server.js";
+import { createRegistryStore } from "./registry-store.js";
+import { normalizeAttributeConfig } from "./attributes.js";
 
 export function defineRoute(partial, options = {}) {
   return {
@@ -12,16 +14,22 @@ export function defineRoute(partial, options = {}) {
 
 export const route = defineRoute;
 
-export function createRouteRegistry(initialMap = {}) {
+export function createRouteRegistry(initialMap = {}, options = {}) {
+  const registryStore = options.registry ?? createRegistryStore();
+  const type = options.type ?? "route";
+  const entries = registryStore._map(type);
   const routes = [];
 
   const registry = {
+    registry: registryStore,
+
     register(pattern, definition) {
       assertPattern(pattern);
       if (routes.some((candidate) => candidate.pattern === pattern)) {
         throw new Error(`Route "${pattern}" is already registered.`);
       }
       const nextRoute = normalizeRoute(pattern, definition);
+      entries.set(pattern, nextRoute.definition);
       routes.push(nextRoute);
       return nextRoute;
     },
@@ -55,11 +63,38 @@ export function createRouteRegistry(initialMap = {}) {
 
     entries() {
       return routes.map(({ pattern, definition }) => ({ pattern, route: definition }));
+    },
+
+    keys() {
+      return [...entries.keys()];
+    },
+
+    inspect() {
+      return registryStore.entries(type);
+    },
+
+    _adoptMany(map = {}) {
+      for (const pattern of Object.keys(map ?? {})) {
+        adoptRoute(pattern, entries.get(pattern));
+      }
+      return registry;
     }
   };
 
+  for (const [pattern, definition] of entries) {
+    adoptRoute(pattern, definition);
+  }
   registry.registerMany(initialMap);
   return registry;
+
+  function adoptRoute(pattern, definition) {
+    if (routes.some((candidate) => candidate.pattern === pattern)) {
+      return;
+    }
+    const nextRoute = normalizeRoute(pattern, definition);
+    entries.set(pattern, nextRoute.definition);
+    routes.push(nextRoute);
+  }
 }
 
 export function createRouter({
@@ -74,12 +109,14 @@ export function createRouter({
   cache,
   partials,
   fetch: fetchImpl = globalThis.fetch?.bind(globalThis),
-  routeEndpoint = "/__async/route"
+  routeEndpoint = "/__async/route",
+  attributes
 } = {}) {
   const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
   const rootNode = root ?? documentRef;
   const signalRegistry = signals ?? loader?.signals ?? createSignalRegistry();
   const handlerRegistry = handlers ?? loader?.handlers ?? createHandlerRegistry();
+  const attributeConfig = normalizeAttributeConfig(attributes ?? loader?.attributes);
   const loaderInstance =
     loader ??
     AsyncLoader({
@@ -87,7 +124,8 @@ export function createRouter({
       signals: signalRegistry,
       handlers: handlerRegistry,
       server,
-      cache
+      cache,
+      attributes: attributeConfig
     });
   const ownsLoader = !loader;
   const cleanups = new Set();
@@ -104,6 +142,7 @@ export function createRouter({
     server,
     cache,
     partials,
+    attributes: attributeConfig,
 
     start() {
       assertActive();

package/src/server.js

@@ -1,10 +1,14 @@
+import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
+
 const serverEnvelopeKeys = new Set(["value", "signals", "boundary", "html", "redirect", "error"]);
 
-export function createServerRegistry(initialMap = {}) {
-  const entries = new Map();
+export function createServerRegistry(initialMap = {}, options = {}) {
+  const registryStore = options.registry ?? createRegistryStore();
+  const type = options.type ?? "server";
+  const entries = registryStore._map(type);
   const defaults = {};
 
-  const registry = {
+  const registry = attachRegistryInspection({
     register(id, fn) {
       assertServerId(id);
       if (typeof fn !== "function") {
@@ -64,8 +68,12 @@ export function createServerRegistry(initialMap = {}) {
     _setContext(context = {}) {
       Object.assign(defaults, context);
       return registry;
+    },
+
+    _adoptMany() {
+      return registry;
     }
-  };
+  }, registryStore, type);
 
   registry.registerMany(initialMap);
   return createServerNamespace((id, args, context) => registry.run(id, args, context), registry);