@async/framework 0.2.2 → 0.4.0

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") {
@@ -43,26 +46,30 @@ export function createPartialRegistry(initialMap = {}) {
         partials: registry
       };
       const result = await fn.call(partialContext, props);
-      return normalizePartialResult(result);
+      return normalizePartialResult(result, partialContext);
+    },
+
+    _adoptMany() {
+      return registry;
     }
-  };
+  }, registryStore, type);
 
   registry.registerMany(initialMap);
   return registry;
 }
 
-export function normalizePartialResult(result) {
+export function normalizePartialResult(result, context = {}) {
   if (isPartialEnvelope(result)) {
     return {
       ...result,
-      html: Object.hasOwn(result, "html") ? renderPartialValue(result.html) : result.html
+      html: Object.hasOwn(result, "html") ? renderPartialValue(result.html, context) : result.html
     };
   }
 
-  return { html: renderPartialValue(result) };
+  return { html: renderPartialValue(result, context) };
 }
 
-function renderPartialValue(value) {
+function renderPartialValue(value, context) {
   if (value?.nodeType) {
     return value;
   }
@@ -70,9 +77,17 @@ function renderPartialValue(value) {
     return value;
   }
   if (isTemplateResult(value)) {
-    return renderTemplate(value);
+    return renderTemplate(value, templateRenderOptions(context));
   }
-  return renderTemplate(value);
+  return renderTemplate(value, templateRenderOptions(context));
+}
+
+function templateRenderOptions(context) {
+  return {
+    attributes: context.loader?.attributes,
+    signals: context.signals,
+    bind: context.loader?._registerBinding?.bind(context.loader)
+  };
 }
 
 function isPartialEnvelope(value) {

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

package/src/signals.js

@@ -1,4 +1,5 @@
 import { asyncSignal as createAsyncSignal, isAsyncSignal } from "./async-signal.js";
+import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 
 const signalKind = Symbol.for("@async/framework.signal");
 const computedKind = Symbol.for("@async/framework.computed");
@@ -116,12 +117,15 @@ export function effect(fn) {
   };
 }
 
-export function createSignalRegistry(initialMap = {}) {
-  const entries = new Map();
+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 runtimeContext = {};
+  const boundEntries = new Set();
 
-  const registry = {
+  const registry = attachRegistryInspection({
     register(id, signalLike) {
       assertId(id);
       if (entries.has(id)) {
@@ -129,12 +133,7 @@ export function createSignalRegistry(initialMap = {}) {
       }
       const entry = normalizeSignal(signalLike);
       entries.set(id, entry);
-      if (typeof entry._bindRegistry === "function") {
-        const cleanup = entry._bindRegistry(registry, id);
-        if (typeof cleanup === "function") {
-          registryCleanups.add(cleanup);
-        }
-      }
+      bindEntry(id, entry);
       return registry.ref(id);
     },
 
@@ -289,11 +288,34 @@ export function createSignalRegistry(initialMap = {}) {
 
     _context() {
       return runtimeContext;
+    },
+
+    _adoptMany(map = {}) {
+      for (const id of Object.keys(map ?? {})) {
+        if (entries.has(id)) {
+          bindEntry(id, entries.get(id));
+        }
+      }
+      return registry;
     }
-  };
+  }, registryStore, type);
 
+  for (const [id, entry] of entries) {
+    bindEntry(id, entry);
+  }
   registry.registerMany(initialMap);
   return registry;
+
+  function bindEntry(id, entry) {
+    if (boundEntries.has(id) || typeof entry?._bindRegistry !== "function") {
+      return;
+    }
+    boundEntries.add(id);
+    const cleanup = entry._bindRegistry(registry, id);
+    if (typeof cleanup === "function") {
+      registryCleanups.add(cleanup);
+    }
+  }
 }
 
 function normalizeSignal(signalLike) {