@async/framework 0.2.2 → 0.3.0

package/src/app.js

@@ -6,17 +6,21 @@ import { createPartialRegistry } from "./partials.js";
 import { createRouteRegistry, createRouter } from "./router.js";
 import { createServerRegistry } from "./server.js";
 import { createSignal, createSignalRegistry } from "./signals.js";
+import { createRegistryStore } from "./registry-store.js";
+import { attributeName, normalizeAttributeConfig } from "./attributes.js";
 
 const registryTypes = new Set(["signal", "handler", "server", "partial", "route", "component"]);
 
 export function defineApp(initial) {
-  const declarations = emptyDeclarations();
+  const registry = createRegistryStore(undefined, { target: "browser" });
   const runtimes = new Set();
 
   const app = {
+    registry,
+
     use(typeOrModule, entries) {
       const normalized = normalizeUse(typeOrModule, entries);
-      appendDeclarations(declarations, normalized);
+      appendDeclarations(registry, normalized);
       for (const runtime of runtimes) {
         runtime._applyUse(normalized);
       }
@@ -24,7 +28,7 @@ export function defineApp(initial) {
     },
 
     snapshot() {
-      return cloneDeclarations(declarations);
+      return registry.rawSnapshot();
     },
 
     start(options = {}) {
@@ -53,15 +57,16 @@ export function defineApp(initial) {
 export function createApp(appOrDefinition = Async, options = {}) {
   const app = isAppHub(appOrDefinition) ? appOrDefinition : defineApp(appOrDefinition ?? {});
   const target = options.target ?? "browser";
-  const snapshot = app.snapshot();
-  const signals = options.signals ?? createSignalRegistry(snapshot.signal);
-  const handlers = options.handlers ?? createHandlerRegistry(snapshot.handler);
-  const serverCache = createCacheRegistry(snapshot.cache.server);
-  const browserCache = createCacheRegistry(snapshot.cache.browser);
-  const server = options.server ?? createServerRegistry(snapshot.server);
-  const partials = options.partials ?? createPartialRegistry(snapshot.partial);
-  const routes = options.routes ?? createRouteRegistry(snapshot.route);
-  const components = options.components ?? createComponentRegistry(snapshot.component);
+  const attributes = normalizeAttributeConfig(options.attributes);
+  const registry = options.registry ?? app.registry.view({ target });
+  const signals = options.signals ?? createSignalRegistry(undefined, { registry, type: "signal" });
+  const handlers = options.handlers ?? createHandlerRegistry(undefined, { registry, type: "handler" });
+  const serverCache = createCacheRegistry(undefined, { registry, type: "cache.server" });
+  const browserCache = createCacheRegistry(undefined, { registry, type: "cache.browser" });
+  const server = options.server ?? createServerRegistry(undefined, { registry, type: "server" });
+  const partials = options.partials ?? createPartialRegistry(undefined, { registry, type: "partial" });
+  const routes = options.routes ?? createRouteRegistry(undefined, { registry, type: "route" });
+  const components = options.components ?? createComponentRegistry(undefined, { registry, type: "component" });
   let loader = options.loader;
   let router = options.router;
   let detach = () => {};
@@ -73,6 +78,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
 
   const runtime = {
     app,
+    registry,
     target,
     signals,
     handlers,
@@ -85,6 +91,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
     },
     loader,
     router,
+    attributes,
 
     start() {
       assertActive();
@@ -99,7 +106,8 @@ export function createApp(appOrDefinition = Async, options = {}) {
           signals,
           handlers,
           server,
-          cache: browserCache
+          cache: browserCache,
+          attributes
         });
         runtime.loader = loader;
 
@@ -121,7 +129,8 @@ export function createApp(appOrDefinition = Async, options = {}) {
             cache: browserCache,
             partials,
             fetch: options.fetch,
-            routeEndpoint: options.routeEndpoint
+            routeEndpoint: options.routeEndpoint,
+            attributes
           });
           runtime.router = router;
           loader.router = router;
@@ -148,7 +157,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
       const matched = routes.match(url);
       if (!matched) {
         return {
-          html: renderDocument("", { status: 404, signals, browserCache, boundary: options.boundary ?? "route" }),
+          html: renderDocument("", { status: 404, signals, browserCache, boundary: options.boundary ?? "route", attributes }),
           status: 404,
           signals: signals.snapshot(),
           cache: { browser: browserCache.snapshot() }
@@ -182,7 +191,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
 
       const status = result.status ?? 200;
       return {
-        html: renderDocument(result.html, { status, signals, browserCache, boundary: result.boundary ?? options.boundary ?? "route" }),
+        html: renderDocument(result.html, { status, signals, browserCache, boundary: result.boundary ?? options.boundary ?? "route", attributes }),
         status,
         signals: signals.snapshot(),
         cache: { browser: browserCache.snapshot() }
@@ -233,16 +242,25 @@ export function createApp(appOrDefinition = Async, options = {}) {
 export const Async = defineApp();
 
 function applyUseToRuntime(runtime, normalized) {
-  runtime.signals.registerMany(normalized.signal);
-  runtime.handlers.registerMany(normalized.handler);
-  if (typeof runtime.server.registerMany === "function") {
-    runtime.server.registerMany(normalized.server);
+  applyRegistryUse(runtime.signals, runtime.registry, normalized.signal);
+  applyRegistryUse(runtime.handlers, runtime.registry, normalized.handler);
+  applyRegistryUse(runtime.server, runtime.registry, normalized.server);
+  applyRegistryUse(runtime.partials, runtime.registry, normalized.partial);
+  applyRegistryUse(runtime.routes, runtime.registry, normalized.route);
+  applyRegistryUse(runtime.components, runtime.registry, normalized.component);
+  applyRegistryUse(runtime.browser.cache, runtime.registry, normalized.cache.browser);
+  applyRegistryUse(runtime.server.cache, runtime.registry, normalized.cache.server);
+}
+
+function applyRegistryUse(registry, runtimeRegistry, entries) {
+  if (!entries || Object.keys(entries).length === 0) {
+    return;
+  }
+  if (registry?.registry === runtimeRegistry) {
+    registry._adoptMany?.(entries);
+    return;
   }
-  runtime.partials.registerMany(normalized.partial);
-  runtime.routes.registerMany(normalized.route);
-  runtime.components.registerMany(normalized.component);
-  runtime.browser.cache.registerMany(normalized.cache.browser);
-  runtime.server.cache.registerMany(normalized.cache.server);
+  registry?.registerMany?.(entries);
 }
 
 function emptyDeclarations() {
@@ -267,7 +285,7 @@ function normalizeUse(typeOrModule, entries) {
     if (!registryTypes.has(typeOrModule)) {
       throw new Error(`Unknown Async registry type "${typeOrModule}".`);
     }
-    normalized[typeOrModule] = { ...(entries ?? {}) };
+    normalized[typeOrModule] = normalizeEntries(typeOrModule, entries);
     return normalized;
   }
 
@@ -284,7 +302,7 @@ function normalizeUse(typeOrModule, entries) {
     if (!registryTypes.has(type)) {
       throw new Error(`Unknown Async registry type "${type}".`);
     }
-    normalized[type] = { ...(value ?? {}) };
+    normalized[type] = normalizeEntries(type, value);
   }
 
   return normalized;
@@ -292,38 +310,20 @@ function normalizeUse(typeOrModule, entries) {
 
 function appendDeclarations(target, source) {
   for (const type of registryTypes) {
-    addEntries(target[type], source[type], type);
+    addEntries(target, type, source[type]);
   }
-  addEntries(target.cache.browser, source.cache.browser, "cache.browser");
-  addEntries(target.cache.server, source.cache.server, "cache.server");
+  addEntries(target, "cache.browser", source.cache.browser);
+  addEntries(target, "cache.server", source.cache.server);
 }
 
-function addEntries(target, source, label) {
+function addEntries(registry, type, source) {
   for (const [id, value] of Object.entries(source ?? {})) {
-    if (Object.hasOwn(target, id)) {
-      throw new Error(`${label} "${id}" is already registered.`);
-    }
-    target[id] = value;
+    registry.register(type, id, value);
   }
 }
 
-function cloneDeclarations(source) {
-  return {
-    signal: { ...source.signal },
-    handler: { ...source.handler },
-    server: { ...source.server },
-    partial: { ...source.partial },
-    route: { ...source.route },
-    component: { ...source.component },
-    cache: {
-      browser: { ...source.cache.browser },
-      server: { ...source.cache.server }
-    }
-  };
-}
-
 function isAppHub(value) {
-  return Boolean(value && typeof value.use === "function" && typeof value.snapshot === "function");
+  return Boolean(value && typeof value.use === "function" && typeof value.snapshot === "function" && value.registry);
 }
 
 function applySnapshot(signals, browserCache, snapshot = {}) {
@@ -353,6 +353,24 @@ function attachServerCache(server, cache) {
   }
 }
 
+function normalizeEntries(type, entries = {}) {
+  if (type !== "signal") {
+    return { ...(entries ?? {}) };
+  }
+  const normalized = {};
+  for (const [id, value] of Object.entries(entries ?? {})) {
+    normalized[id] = normalizeSignalDeclaration(value);
+  }
+  return normalized;
+}
+
+function normalizeSignalDeclaration(value) {
+  if (value && typeof value === "object" && typeof value.subscribe === "function") {
+    return value;
+  }
+  return createSignal(value);
+}
+
 function isLocalServerRegistry(server) {
   return typeof server?.registerMany === "function";
 }
@@ -361,14 +379,16 @@ function shouldStartRouter(routes, options) {
   return Boolean(options.routerOptions || options.mode || routes.entries().length > 0);
 }
 
-function renderDocument(routeHtml, { signals, browserCache, boundary }) {
+function renderDocument(routeHtml, { signals, browserCache, boundary, attributes }) {
   const snapshot = {
     signals: signals.snapshot(),
     cache: {
       browser: browserCache.snapshot()
     }
   };
-  return `<section data-async-boundary="${escapeAttribute(boundary)}">${routeHtml ?? ""}</section><script type="application/json" data-async-snapshot>${escapeScriptJson(snapshot)}</script>`;
+  const boundaryAttr = attributeName(attributes, "async", "boundary");
+  const snapshotAttr = attributeName(attributes, "async", "snapshot");
+  return `<section ${boundaryAttr}="${escapeAttribute(boundary)}">${routeHtml ?? ""}</section><script type="application/json" ${snapshotAttr}>${escapeScriptJson(snapshot)}</script>`;
 }
 
 function escapeAttribute(value) {

package/src/attributes.js

@@ -0,0 +1,50 @@
+const defaultPrefixes = Object.freeze({
+  async: ["async:"],
+  signal: ["signal:"],
+  on: ["on:"]
+});
+
+export function defineAttributeConfig(config = {}) {
+  return normalizeAttributeConfig(config);
+}
+
+export function normalizeAttributeConfig(config = {}) {
+  return {
+    async: normalizePrefixes(config.async, defaultPrefixes.async),
+    signal: normalizePrefixes(config.signal, defaultPrefixes.signal),
+    on: normalizePrefixes(config.on, defaultPrefixes.on)
+  };
+}
+
+export function attributeName(attributes, type, name) {
+  return normalizeAttributeConfig(attributes)[type][0] + name;
+}
+
+export function readAttribute(element, attributes, type, name) {
+  for (const prefix of normalizeAttributeConfig(attributes)[type]) {
+    const attr = `${prefix}${name}`;
+    if (element.hasAttribute?.(attr)) {
+      return element.getAttribute(attr);
+    }
+  }
+  return null;
+}
+
+export function matchAttribute(name, attributes, type) {
+  for (const prefix of normalizeAttributeConfig(attributes)[type]) {
+    if (name.startsWith(prefix)) {
+      return name.slice(prefix.length);
+    }
+  }
+  return null;
+}
+
+function normalizePrefixes(value, fallback) {
+  const prefixes = value == null ? fallback : Array.isArray(value) ? value : [value];
+  return prefixes.map((prefix) => {
+    if (typeof prefix !== "string" || prefix.length === 0) {
+      throw new TypeError("Attribute prefixes must be non-empty strings.");
+    }
+    return prefix;
+  });
+}

package/src/cache.js

@@ -1,3 +1,5 @@
+import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
+
 const cacheDefinitionKind = Symbol.for("@async/framework.cacheDefinition");
 
 export function defineCache(options = {}) {
@@ -9,11 +11,12 @@ export function defineCache(options = {}) {
   };
 }
 
-export function createCacheRegistry(initialMap = {}, { now = () => Date.now() } = {}) {
-  const definitions = new Map();
-  const entries = new Map();
+export function createCacheRegistry(initialMap = {}, { now = () => Date.now(), registry, type = "cache.browser" } = {}) {
+  const registryStore = registry ?? createRegistryStore();
+  const definitions = registryStore._map(type);
+  const entries = registryStore._map(`${type}.entries`);
 
-  const registry = {
+  const registryApi = attachRegistryInspection({
     register(id, definition = defineCache()) {
       assertId(id);
       const normalized = normalizeDefinition(definition);
@@ -26,9 +29,9 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now() }
 
     registerMany(map) {
       for (const [id, definition] of Object.entries(map ?? {})) {
-        registry.register(id, definition);
+        registryApi.register(id, definition);
       }
-      return registry;
+      return registryApi;
     },
 
     resolve(id) {
@@ -64,12 +67,12 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now() }
       if (typeof fn !== "function") {
         throw new TypeError("cache.getOrSet(key, fn) requires a function.");
       }
-      const cached = registry.get(key);
+      const cached = registryApi.get(key);
       if (cached !== undefined) {
         return cached;
       }
       const value = await fn();
-      registry.set(key, value, options);
+      registryApi.set(key, value, options);
       return value;
     },
 
@@ -81,20 +84,20 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now() }
     clear(prefix) {
       if (prefix === undefined) {
         entries.clear();
-        return registry;
+        return registryApi;
       }
       for (const key of [...entries.keys()]) {
         if (key.startsWith(prefix)) {
           entries.delete(key);
         }
       }
-      return registry;
+      return registryApi;
     },
 
     snapshot() {
       const snapshot = {};
       for (const [key] of entries) {
-        const value = registry.get(key);
+        const value = registryApi.get(key);
         if (value !== undefined) {
           snapshot[key] = value;
         }
@@ -104,14 +107,26 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now() }
 
     restore(snapshot = {}) {
       for (const [key, value] of Object.entries(snapshot ?? {})) {
-        registry.set(key, value);
+        registryApi.set(key, value);
       }
-      return registry;
+      return registryApi;
+    },
+
+    entryKeys() {
+      return [...entries.keys()];
+    },
+
+    entryEntries() {
+      return registryStore.entries(`${type}.entries`);
+    },
+
+    _adoptMany() {
+      return registryApi;
     }
-  };
+  }, registryStore, type);
 
-  registry.registerMany(initialMap);
-  return registry;
+  registryApi.registerMany(initialMap);
+  return registryApi;
 
   function resolvePolicy(key, explicitId) {
     if (explicitId !== undefined) {

package/src/component.js

@@ -1,4 +1,5 @@
 import { rawHtml, renderTemplate } from "./html.js";
+import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 
 const componentKind = Symbol.for("@async/framework.component");
 let componentCounter = 0;
@@ -16,10 +17,12 @@ export function defineComponent(fn) {
 
 export const component = defineComponent;
 
-export function createComponentRegistry(initialMap = {}) {
-  const entries = new Map();
+export function createComponentRegistry(initialMap = {}, options = {}) {
+  const registryStore = options.registry ?? createRegistryStore();
+  const type = options.type ?? "component";
+  const entries = registryStore._map(type);
 
-  const registry = {
+  const registry = attachRegistryInspection({
     register(id, Component) {
       if (typeof id !== "string" || id.length === 0) {
         throw new TypeError("Component id must be a non-empty string.");
@@ -46,8 +49,12 @@ export function createComponentRegistry(initialMap = {}) {
         throw new TypeError("Component id must be a non-empty string.");
       }
       return entries.get(id);
+    },
+
+    _adoptMany() {
+      return registry;
     }
-  };
+  }, registryStore, type);
 
   registry.registerMany(initialMap);
   return registry;

package/src/handlers.js

@@ -4,6 +4,7 @@ import {
   resolveServerCommandArguments,
   unwrapServerResult
 } from "./server.js";
+import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 
 const builtInTokens = new Set(["preventDefault", "stopPropagation", "stopImmediatePropagation"]);
 const builtInHandlers = {
@@ -18,10 +19,12 @@ const builtInHandlers = {
   }
 };
 
-export function createHandlerRegistry(initialMap = {}) {
-  const handlers = new Map();
+export function createHandlerRegistry(initialMap = {}, options = {}) {
+  const registryStore = options.registry ?? createRegistryStore();
+  const type = options.type ?? "handler";
+  const handlers = registryStore._map(type);
 
-  const registry = {
+  const registry = attachRegistryInspection({
     register(id, fn) {
       assertId(id);
       if (typeof fn !== "function") {
@@ -90,14 +93,30 @@ export function createHandlerRegistry(initialMap = {}) {
       }
 
       return results;
+    },
+
+    _adoptMany() {
+      return registry;
     }
-  };
+  }, registryStore, type);
 
-  registry.registerMany(builtInHandlers);
+  registerBuiltIns(registry, handlers);
   registry.registerMany(initialMap);
   return registry;
 }
 
+function registerBuiltIns(registry, handlers) {
+  for (const [id, fn] of Object.entries(builtInHandlers)) {
+    if (!handlers.has(id)) {
+      registry.register(id, fn);
+      continue;
+    }
+    if (handlers.get(id) !== fn) {
+      throw new Error(`Handler "${id}" is already registered.`);
+    }
+  }
+}
+
 export function parseHandlerRef(ref) {
   if (typeof ref !== "string" || ref.trim().length === 0) {
     throw new TypeError("Handler ref must be a non-empty string.");

package/src/index.js

@@ -1,5 +1,6 @@
 export { asyncSignal } from "./async-signal.js";
 export { Async, createApp, defineApp } from "./app.js";
+export { attributeName, defineAttributeConfig } from "./attributes.js";
 export { createCacheRegistry, defineCache } from "./cache.js";
 export { component, createComponentRegistry, defineComponent } from "./component.js";
 export { delay } from "./delay.js";
@@ -7,6 +8,7 @@ export { createHandlerRegistry } from "./handlers.js";
 export { html } from "./html.js";
 export { AsyncLoader } from "./loader.js";
 export { createPartialRegistry } from "./partials.js";
+export { createRegistryStore } from "./registry-store.js";
 export { createRouteRegistry, createRouter, defineRoute, route } from "./router.js";
 export { createServerProxy, createServerRegistry } from "./server.js";
 export { computed, createSignal, createSignalRegistry, effect, signal } from "./signals.js";