@async/framework 0.5.0 → 0.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@async/framework",
-  "version": "0.5.0",
-  "description": "No-build AsyncLoader app runtime with signals, command events, server calls, route partials, cache split, SSR activation, and streaming boundaries.",
+  "version": "0.7.0",
+  "description": "No-build Loader app runtime with signals, command events, server calls, route partials, cache split, SSR activation, and streaming boundaries.",
   "type": "module",
   "packageManager": "pnpm@11.1.0",
   "engines": {
@@ -28,21 +28,49 @@
     "web-framework"
   ],
   "license": "MIT",
-  "unpkg": "./framework.js",
+  "types": "./framework.d.ts",
+  "unpkg": "./framework.umd.min.js",
+  "jsdelivr": "./framework.umd.min.js",
   "exports": {
     ".": {
-      "unpkg": "./framework.js",
+      "types": "./framework.d.ts",
+      "unpkg": "./framework.umd.min.js",
       "browser": "./framework.js",
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
-    "./framework.js": "./framework.js",
+    "./framework.js": {
+      "types": "./framework.d.ts",
+      "default": "./framework.js"
+    },
+    "./framework.min.js": {
+      "types": "./framework.d.ts",
+      "default": "./framework.min.js"
+    },
+    "./framework.umd.js": {
+      "types": "./framework.d.ts",
+      "default": "./framework.umd.js"
+    },
+    "./framework.umd.min.js": {
+      "types": "./framework.d.ts",
+      "default": "./framework.umd.min.js"
+    },
+    "./framework.ts": {
+      "types": "./framework.d.ts",
+      "default": "./framework.ts"
+    },
+    "./framework.d.ts": "./framework.d.ts",
     "./package.json": "./package.json"
   },
   "files": [
     "CHANGELOG.md",
     "README.md",
+    "framework.d.ts",
     "framework.js",
+    "framework.min.js",
+    "framework.umd.js",
+    "framework.umd.min.js",
+    "framework.ts",
     "src",
     "examples",
     "LICENSE",
@@ -68,6 +96,7 @@
     "pipeline:sync:generate": "async-pipeline sync generate",
     "pipeline:task:docs.site": "async-pipeline run-task docs.site",
     "pipeline:verify": "async-pipeline run verify",
+    "registry:lint": "node scripts/registry-lint.js",
     "release:check": "pnpm run pipeline:verify -- --force && pnpm run pipeline:pages -- --force && pnpm run pipeline:sync:check && pnpm run pipeline:github:check",
     "test": "node --test tests/*.test.js"
   },

package/src/app.js

@@ -1,7 +1,7 @@
 import { createCacheRegistry } from "./cache.js";
 import { createComponentRegistry } from "./component.js";
 import { createHandlerRegistry } from "./handlers.js";
-import { AsyncLoader } from "./loader.js";
+import { Loader } from "./loader.js";
 import { createPartialRegistry } from "./partials.js";
 import { createRouteRegistry, createRouter } from "./router.js";
 import { createServerRegistry } from "./server.js";
@@ -73,7 +73,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
   let started = false;
   let destroyed = false;
 
-  applySnapshot(signals, browserCache, options.snapshot);
+  applySnapshot(signals, browserCache, options.snapshot ?? (target === "browser" ? readSnapshot(options.root, { attributes }) : undefined));
   attachServerCache(server, serverCache);
 
   const runtime = {
@@ -101,7 +101,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
       started = true;
 
       if (target !== "server") {
-        loader = loader ?? AsyncLoader({
+        loader = loader ?? Loader({
           root: options.root,
           signals,
           handlers,
@@ -241,6 +241,38 @@ export function createApp(appOrDefinition = Async, options = {}) {
 
 export const Async = defineApp();
 
+export function readSnapshot(root = globalThis.document, { attributes } = {}) {
+  const attributeConfig = normalizeAttributeConfig(attributes);
+  const snapshotAttr = attributeName(attributeConfig, "async", "snapshot");
+  const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
+  const rootNode = root ?? documentRef;
+  if (!rootNode?.querySelectorAll && !documentRef?.querySelectorAll) {
+    return {};
+  }
+
+  for (const searchRoot of new Set([rootNode, documentRef])) {
+    if (!searchRoot?.querySelectorAll) {
+      continue;
+    }
+    for (const script of searchRoot.querySelectorAll("script[type='application/json'], script")) {
+      if (!script.hasAttribute?.(snapshotAttr)) {
+        continue;
+      }
+      const source = script.textContent?.trim() ?? "";
+      if (!source) {
+        return {};
+      }
+      try {
+        return JSON.parse(source);
+      } catch (cause) {
+        throw new Error(`Could not parse Async snapshot: ${cause instanceof Error ? cause.message : String(cause)}`);
+      }
+    }
+  }
+
+  return {};
+}
+
 function applyUseToRuntime(runtime, normalized) {
   applyRegistryUse(runtime.signals, runtime.registry, normalized.signal);
   applyRegistryUse(runtime.handlers, runtime.registry, normalized.handler);

package/src/cache.js

@@ -15,6 +15,7 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now(), r
   const registryStore = registry ?? createRegistryStore();
   const definitions = registryStore._map(type);
   const entries = registryStore._map(`${type}.entries`);
+  const pending = new Map();
 
   const registryApi = attachRegistryInspection({
     register(id, definition = defineCache()) {
@@ -76,19 +77,37 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now(), r
       if (cached !== undefined) {
         return cached;
       }
-      const value = await fn();
-      registryApi.set(key, value, options);
-      return value;
+      if (pending.has(key)) {
+        return pending.get(key);
+      }
+      let promise;
+      promise = Promise.resolve()
+        .then(fn)
+        .then((value) => {
+          if (pending.get(key) === promise) {
+            registryApi.set(key, value, options);
+          }
+          return value;
+        })
+        .finally(() => {
+          if (pending.get(key) === promise) {
+            pending.delete(key);
+          }
+        });
+      pending.set(key, promise);
+      return promise;
     },
 
     delete(key) {
       assertKey(key);
+      pending.delete(key);
       return entries.delete(key);
     },
 
     clear(prefix) {
       if (prefix === undefined) {
         entries.clear();
+        pending.clear();
         return registryApi;
       }
       for (const key of [...entries.keys()]) {
@@ -96,6 +115,11 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now(), r
           entries.delete(key);
         }
       }
+      for (const key of [...pending.keys()]) {
+        if (key.startsWith(prefix)) {
+          pending.delete(key);
+        }
+      }
       return registryApi;
     },
 

package/src/component.js

@@ -89,7 +89,7 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
     bind(value) {
       const id = runtime.loader?._registerBinding?.(value);
       if (!id) {
-        throw new Error("Inline template bindings require an AsyncLoader.");
+        throw new Error("Inline template bindings require a Loader.");
       }
       bindingIds.push(id);
       return id;

package/src/index.js

@@ -1,12 +1,12 @@
 export { asyncSignal } from "./async-signal.js";
-export { Async, createApp, defineApp } from "./app.js";
+export { Async, createApp, defineApp, readSnapshot } 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";
 export { createHandlerRegistry } from "./handlers.js";
 export { html } from "./html.js";
-export { AsyncLoader } from "./loader.js";
+export { Loader, AsyncLoader } from "./loader.js";
 export { createPartialRegistry } from "./partials.js";
 export { createRegistryStore } from "./registry-store.js";
 export { createRouteRegistry, createRouter, defineRoute, route } from "./router.js";

package/src/loader.js

@@ -5,7 +5,7 @@ import { matchAttribute, normalizeAttributeConfig, readAttribute } from "./attri
 
 const inlineBindingPrefix = "__async:inline:";
 
-export function AsyncLoader({ root, signals, handlers, server, router, cache, attributes } = {}) {
+export function Loader({ root, signals, handlers, server, router, cache, attributes } = {}) {
   const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
   const rootNode = root ?? documentRef;
   const signalRegistry = signals ?? createSignalRegistry();
@@ -447,7 +447,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
 
   function assertActive() {
     if (destroyed) {
-      throw new Error("AsyncLoader has been destroyed.");
+      throw new Error("Loader has been destroyed.");
     }
   }
 
@@ -511,6 +511,8 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
   return api;
 }
 
+export const AsyncLoader = Loader;
+
 function normalizeClassTokens(value, tokens = new Set()) {
   if (value == null || value === false) {
     return tokens;

package/src/router.js

@@ -1,4 +1,4 @@
-import { AsyncLoader } from "./loader.js";
+import { Loader } from "./loader.js";
 import { createHandlerRegistry } from "./handlers.js";
 import { createSignalRegistry } from "./signals.js";
 import { applyServerResult } from "./server.js";
@@ -31,6 +31,7 @@ export function createRouteRegistry(initialMap = {}, options = {}) {
       const nextRoute = normalizeRoute(pattern, definition);
       entries.set(pattern, nextRoute.definition);
       routes.push(nextRoute);
+      sortRoutes(routes);
       return nextRoute;
     },
 
@@ -103,6 +104,7 @@ export function createRouteRegistry(initialMap = {}, options = {}) {
     const nextRoute = normalizeRoute(pattern, definition);
     entries.set(pattern, nextRoute.definition);
     routes.push(nextRoute);
+    sortRoutes(routes);
   }
 }
 
@@ -128,7 +130,7 @@ export function createRouter({
   const attributeConfig = normalizeAttributeConfig(attributes ?? loader?.attributes);
   const loaderInstance =
     loader ??
-    AsyncLoader({
+    Loader({
       root: rootNode,
       signals: signalRegistry,
       handlers: handlerRegistry,
@@ -139,6 +141,8 @@ export function createRouter({
   const ownsLoader = !loader;
   const cleanups = new Set();
   let destroyed = false;
+  let navigationVersion = 0;
+  let activeNavigation;
 
   const api = {
     mode,
@@ -178,7 +182,7 @@ export function createRouter({
     },
 
     match(url) {
-      return routes.match(url);
+      return routes.match(resolveUrl(url));
     },
 
     prefetch(url) {
@@ -203,7 +207,7 @@ export function createRouter({
         return null;
       }
 
-      const target = toUrl(url);
+      const target = resolveUrl(url);
       if (mode === "ssr-spa") {
         return fetchRoutePartial(target, options);
       }
@@ -215,6 +219,7 @@ export function createRouter({
         return;
       }
       destroyed = true;
+      activeNavigation?.controller.abort(new Error("Router has been destroyed."));
       for (const cleanup of cleanups) {
         cleanup();
       }
@@ -254,24 +259,37 @@ export function createRouter({
   async function renderLocalRoutePartial(target, options = {}) {
     const matched = api.match(target);
     if (!matched) {
+      beginNavigation(target, null);
       setNoRouteError(target);
       return null;
     }
 
+    const navigation = beginNavigation(target, matched);
     setMatchedRouterState(target, matched, { pending: true, error: null });
 
     try {
       if (!matched.route?.partial || !partials?.resolve?.(matched.route.partial)) {
         const error = new Error(`Route "${target.pathname}" does not have a registered partial.`);
-        setRouterState({ pending: false, error });
+        if (isActiveNavigation(navigation)) {
+          setRouterState({ pending: false, error });
+        }
         return null;
       }
 
-      const result = await partials.render(matched.route.partial, matched.params, contextFor(matched));
-      await applyNavigationResult(result, target, options);
+      const result = await partials.render(matched.route.partial, matched.params, contextFor(matched, navigation));
+      if (!isActiveNavigation(navigation)) {
+        return null;
+      }
+      await applyNavigationResult(result, target, options, navigation);
+      if (!isActiveNavigation(navigation)) {
+        return null;
+      }
       setRouterState({ pending: false, error: null });
       return result;
     } catch (error) {
+      if (!isActiveNavigation(navigation)) {
+        return null;
+      }
       setRouterState({ pending: false, error });
       throw error;
     }
@@ -279,26 +297,43 @@ export function createRouter({
 
   async function fetchRoutePartial(target, options = {}) {
     const matched = api.match(target);
+    const navigation = beginNavigation(target, matched);
     setMatchedRouterState(target, matched, { pending: true, error: null });
 
     try {
-      const result = await fetchRoute(target.href);
-      await applyNavigationResult(result, target, options);
+      const result = await fetchRoute(target.href, { signal: navigation.abort });
+      if (!isActiveNavigation(navigation)) {
+        return null;
+      }
+      await applyNavigationResult(result, target, options, navigation);
+      if (!isActiveNavigation(navigation)) {
+        return null;
+      }
       setRouterState({ pending: false, error: null });
       return result;
     } catch (error) {
+      if (!isActiveNavigation(navigation)) {
+        return null;
+      }
       setRouterState({ pending: false, error });
       throw error;
     }
   }
 
-  async function applyNavigationResult(result, target, options) {
+  async function applyNavigationResult(result, target, options, navigation) {
+    if (!isActiveNavigation(navigation)) {
+      return;
+    }
     await applyServerResult(result, {
       signals: signalRegistry,
       loader: loaderInstance,
       router: api,
-      cache
+      cache,
+      abort: navigation?.abort
     });
+    if (!isActiveNavigation(navigation)) {
+      return;
+    }
     if (result?.html != null && !result.boundary && !result.redirect) {
       loaderInstance.swap(boundary, result.html);
     }
@@ -312,14 +347,15 @@ export function createRouter({
     documentRef.defaultView?.history?.pushState?.({}, "", target.href);
   }
 
-  async function fetchRoute(url, { prefetch = false } = {}) {
+  async function fetchRoute(url, { prefetch = false, signal } = {}) {
     if (typeof fetchImpl !== "function") {
       throw new Error("Router navigation requires a partial registry or fetch.");
     }
     const response = await fetchImpl(`${routeEndpoint}?to=${encodeURIComponent(String(url))}`, {
       headers: {
         accept: "application/json, text/html"
-      }
+      },
+      signal
     });
     if (!response.ok) {
       throw new Error(`Route "${url}" failed with ${response.status}.`);
@@ -334,7 +370,7 @@ export function createRouter({
     return { boundary, html: await response.text() };
   }
 
-  function contextFor(matched) {
+  function contextFor(matched, navigation) {
     return {
       params: matched.params,
       route: matched.route,
@@ -344,10 +380,28 @@ export function createRouter({
       loader: loaderInstance,
       server,
       cache,
-      abort: undefined
+      abort: navigation?.abort
     };
   }
 
+  function beginNavigation(target, matched) {
+    activeNavigation?.controller.abort(new Error(`Router navigation superseded by ${target.pathname}${target.search}.`));
+    const controller = new AbortController();
+    const navigation = {
+      id: ++navigationVersion,
+      controller,
+      abort: controller.signal,
+      target,
+      matched
+    };
+    activeNavigation = navigation;
+    return navigation;
+  }
+
+  function isActiveNavigation(navigation) {
+    return !destroyed && navigation && activeNavigation?.id === navigation.id && !navigation.abort.aborted;
+  }
+
   function updateStateFromLocation() {
     const url = currentUrl();
     const matched = api.match(url);
@@ -382,7 +436,14 @@ export function createRouter({
   }
 
   function currentUrl() {
-    return toUrl(documentRef.defaultView?.location?.href ?? "http://localhost/");
+    return resolveUrl(documentRef.defaultView?.location?.href ?? "http://localhost/");
+  }
+
+  function resolveUrl(url) {
+    if (url instanceof URL) {
+      return url;
+    }
+    return new URL(String(url), documentRef.defaultView?.location?.href ?? "http://localhost/");
   }
 
   function assertActive() {
@@ -399,6 +460,7 @@ function normalizeRoute(pattern, definition) {
     pattern,
     regex,
     keys,
+    score: routeScore(pattern),
     definition: normalized
   };
 }
@@ -467,6 +529,28 @@ function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function sortRoutes(routes) {
+  routes.sort((left, right) => right.score - left.score || right.pattern.length - left.pattern.length);
+}
+
+function routeScore(pattern) {
+  if (pattern === "*") {
+    return -1;
+  }
+  return pattern
+    .split("/")
+    .filter(Boolean)
+    .reduce((score, segment) => {
+      if (segment === "*") {
+        return score;
+      }
+      if (segment.startsWith(":")) {
+        return score + 2;
+      }
+      return score + 4;
+    }, pattern === "/" ? 3 : 0);
+}
+
 function assertPattern(pattern) {
   if (typeof pattern !== "string" || (pattern !== "*" && !pattern.startsWith("/"))) {
     throw new TypeError("Route pattern must be a path string or \"*\".");

package/src/server.js

@@ -1,6 +1,8 @@
 import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 
 const serverEnvelopeKeys = new Set(["value", "signals", "boundary", "html", "redirect", "error"]);
+const appliedServerResult = Symbol.for("@async/framework.appliedServerResult");
+const appliedServerValues = new WeakSet();
 
 export function createServerRegistry(initialMap = {}, options = {}) {
   const registryStore = options.registry ?? createRegistryStore();
@@ -107,6 +109,7 @@ export function createServerProxy({
       input: context.input ?? defaultInput(runContext),
       signals: context.signalValues ?? snapshotSignalPaths(context.signalPaths, runContext.signals)
     };
+    assertJsonTransportable(body);
 
     const response = await fetchImpl(joinEndpoint(endpoint, id), {
       method: "POST",
@@ -124,7 +127,7 @@ export function createServerProxy({
 
     const result = await readServerResponse(response);
     await applyServerResult(result, runContext);
-    return unwrapServerResult(result);
+    return markAppliedServerValue(unwrapServerResult(result));
   }
 
   return createServerNamespace(run, {
@@ -159,6 +162,9 @@ export async function applyServerResult(result, context = {}) {
   if (!isServerEnvelope(result)) {
     return result;
   }
+  if (result[appliedServerResult] || appliedServerValues.has(result)) {
+    return result;
+  }
 
   if (result.signals && context.signals) {
     for (const [path, value] of Object.entries(result.signals)) {
@@ -182,6 +188,12 @@ export async function applyServerResult(result, context = {}) {
     throw toError(result.error);
   }
 
+  Object.defineProperty(result, appliedServerResult, {
+    configurable: true,
+    enumerable: false,
+    value: true
+  });
+
   return result;
 }
 
@@ -192,6 +204,13 @@ export function unwrapServerResult(result) {
   return result;
 }
 
+function markAppliedServerValue(value) {
+  if (value && typeof value === "object") {
+    appliedServerValues.add(value);
+  }
+  return value;
+}
+
 export function defaultInput(context = {}) {
   const form = findForm(context);
   if (form) {
@@ -369,6 +388,30 @@ function formDataToObject(formData) {
   return output;
 }
 
+function assertJsonTransportable(value, seen = new Set()) {
+  if (value == null || typeof value !== "object") {
+    return;
+  }
+  if (seen.has(value)) {
+    return;
+  }
+  seen.add(value);
+
+  const tag = Object.prototype.toString.call(value);
+  if (tag === "[object File]" || tag === "[object Blob]" || tag === "[object FormData]") {
+    throw new Error("Server proxy JSON transport does not support File, Blob, or FormData values yet.");
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      assertJsonTransportable(item, seen);
+    }
+    return;
+  }
+  for (const item of Object.values(value)) {
+    assertJsonTransportable(item, seen);
+  }
+}
+
 function joinEndpoint(endpoint, id) {
   return `${String(endpoint).replace(/\/$/, "")}/${encodeURIComponent(id)}`;
 }