@async/framework 0.6.0 → 0.8.0

package/src/loader.js

@@ -1,15 +1,18 @@
 import { renderComponent } from "./component.js";
 import { createHandlerRegistry } from "./handlers.js";
+import { createScheduler } from "./scheduler.js";
 import { createSignalRegistry, isSignalRef } from "./signals.js";
 import { matchAttribute, normalizeAttributeConfig, readAttribute } from "./attributes.js";
 
 const inlineBindingPrefix = "__async:inline:";
 
-export function Loader({ root, signals, handlers, server, router, cache, attributes } = {}) {
+export function Loader({ root, signals, handlers, server, router, cache, attributes, scheduler } = {}) {
   const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
   const rootNode = root ?? documentRef;
   const signalRegistry = signals ?? createSignalRegistry();
   const handlerRegistry = handlers ?? createHandlerRegistry();
+  const schedulerInstance = scheduler ?? createScheduler();
+  const ownsScheduler = !scheduler;
   const attributeConfig = normalizeAttributeConfig(attributes);
   const cleanups = new Set();
   const eventBindings = new WeakMap();
@@ -30,6 +33,7 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
     server,
     router,
     cache,
+    scheduler: schedulerInstance,
     attributes: attributeConfig,
 
     start() {
@@ -69,6 +73,7 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
         server: api.server,
         router: api.router,
         cache: api.cache,
+        scheduler: schedulerInstance,
         attributes: attributeConfig
       });
       cleanupChildren(target);
@@ -89,6 +94,9 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
         runCleanup(cleanup);
       }
       cleanups.clear();
+      if (ownsScheduler) {
+        schedulerInstance.destroy();
+      }
     },
 
     _observeVisible(target, fn) {
@@ -106,13 +114,14 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
     }
   };
 
-  signalRegistry._setContext?.({ server: api.server, router: api.router, loader: api, cache: api.cache });
+  signalRegistry._setContext?.({ server: api.server, router: api.router, loader: api, cache: api.cache, scheduler: schedulerInstance });
   api.server?._setContext?.({
     signals: signalRegistry,
     handlers: handlerRegistry,
     loader: api,
     router: api.router,
-    cache: api.cache
+    cache: api.cache,
+    scheduler: schedulerInstance
   });
 
   function bindEventAttributes(scope) {
@@ -144,18 +153,19 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
 
     const listener = async (event) => {
       try {
-        await handlerRegistry.run(ref, {
+        await schedulerInstance.batch(() => handlerRegistry.run(ref, {
           signals: signalRegistry,
           handlers: handlerRegistry,
           loader: api,
           server: api.server,
           router: api.router,
           cache: api.cache,
+          scheduler: schedulerInstance,
           event,
           element,
           el: element,
           root: rootNode
-        });
+        }));
       } catch (error) {
         dispatchAsyncError(element, error);
       }
@@ -271,7 +281,12 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
 
     const read = () => readBinding(path, options);
     apply(read());
-    addCleanup(subscribeBinding(path, () => apply(read())), element);
+    addCleanup(subscribeBinding(path, () => {
+      schedulerInstance.enqueue("binding", () => apply(read()), {
+        scope: element,
+        key
+      });
+    }), element);
   }
 
   function bindValueWriter(element, path) {
@@ -332,7 +347,12 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
         const state = {
           id,
           templates,
-          cleanup: signalRegistry.subscribe(`${id}.$status`, () => renderBoundary(boundary))
+          cleanup: signalRegistry.subscribe(`${id}.$status`, () => {
+            schedulerInstance.enqueue("binding", () => renderBoundary(boundary), {
+              scope: boundary,
+              key: `boundary:${id}`
+            });
+          })
         };
         boundaryState.set(boundary, state);
         addCleanup(state.cleanup, boundary);
@@ -372,7 +392,7 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
       }
       mountedElements.add(element);
       for (const ref of refs) {
-        runPseudo(element, ref);
+        scheduleLifecycle(element, () => runPseudo(element, ref), `attach:${ref}`);
       }
     }
 
@@ -385,7 +405,7 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
         continue;
       }
       visibleElements.add(element);
-      addCleanup(observeVisible(element, () => runPseudo(element, ref)), element);
+      addCleanup(observeVisible(element, () => scheduleLifecycle(element, () => runPseudo(element, ref), `visible:${ref}`)), element);
     }
   }
 
@@ -409,6 +429,7 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
         server: api.server,
         router: api.router,
         cache: api.cache,
+        scheduler: schedulerInstance,
         element,
         el: element,
         root: rootNode
@@ -427,10 +448,13 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
     const ownerWindow = target.ownerDocument?.defaultView ?? globalThis;
     const Observer = ownerWindow.IntersectionObserver ?? globalThis.IntersectionObserver;
     if (!Observer) {
-      queueMicrotask(() => {
+      schedulerInstance.enqueue("lifecycle", () => {
         if (!destroyed) {
           fn(target);
         }
+      }, {
+        scope: target,
+        key: "visible:fallback"
       });
       return () => {};
     }
@@ -485,6 +509,7 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
     }
     for (const element of elementsIn(node)) {
       runScopedCleanups(element);
+      schedulerInstance.markScopeDestroyed(element);
     }
   }
 
@@ -508,6 +533,13 @@ export function Loader({ root, signals, handlers, server, router, cache, attribu
     }
   }
 
+  function scheduleLifecycle(element, fn, key) {
+    schedulerInstance.enqueue("lifecycle", fn, {
+      scope: element,
+      key
+    });
+  }
+
   return api;
 }
 

package/src/request-context.js

@@ -0,0 +1,40 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export function createRequestContextStore() {
+  const storage = new AsyncLocalStorage();
+
+  return {
+    storage,
+
+    run(context, fn, ...args) {
+      if (typeof fn !== "function") {
+        throw new TypeError("requestContext.run(context, fn) requires a function.");
+      }
+      return storage.run(context ?? {}, fn, ...args);
+    },
+
+    get() {
+      return storage.getStore();
+    },
+
+    snapshot() {
+      return { ...(storage.getStore() ?? {}) };
+    }
+  };
+}
+
+export function readRequestContext(store) {
+  if (!store) {
+    return {};
+  }
+  if (typeof store.get === "function") {
+    return store.get() ?? {};
+  }
+  if (typeof store.getStore === "function") {
+    return store.getStore() ?? {};
+  }
+  if (typeof store === "object") {
+    return store;
+  }
+  return {};
+}

package/src/router.js

@@ -1,5 +1,6 @@
 import { Loader } from "./loader.js";
 import { createHandlerRegistry } from "./handlers.js";
+import { createScheduler } from "./scheduler.js";
 import { createSignalRegistry } from "./signals.js";
 import { applyServerResult } from "./server.js";
 import { createRegistryStore } from "./registry-store.js";
@@ -31,6 +32,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 +105,7 @@ export function createRouteRegistry(initialMap = {}, options = {}) {
     const nextRoute = normalizeRoute(pattern, definition);
     entries.set(pattern, nextRoute.definition);
     routes.push(nextRoute);
+    sortRoutes(routes);
   }
 }
 
@@ -119,12 +122,15 @@ export function createRouter({
   partials,
   fetch: fetchImpl = globalThis.fetch?.bind(globalThis),
   routeEndpoint = "/__async/route",
-  attributes
+  attributes,
+  scheduler
 } = {}) {
   const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
   const rootNode = root ?? documentRef;
   const signalRegistry = signals ?? loader?.signals ?? createSignalRegistry();
   const handlerRegistry = handlers ?? loader?.handlers ?? createHandlerRegistry();
+  const schedulerInstance = scheduler ?? loader?.scheduler ?? createScheduler();
+  const ownsScheduler = !scheduler && !loader?.scheduler;
   const attributeConfig = normalizeAttributeConfig(attributes ?? loader?.attributes);
   const loaderInstance =
     loader ??
@@ -134,11 +140,14 @@ export function createRouter({
       handlers: handlerRegistry,
       server,
       cache,
+      scheduler: schedulerInstance,
       attributes: attributeConfig
     });
   const ownsLoader = !loader;
   const cleanups = new Set();
   let destroyed = false;
+  let navigationVersion = 0;
+  let activeNavigation;
 
   const api = {
     mode,
@@ -151,12 +160,13 @@ export function createRouter({
     server,
     cache,
     partials,
+    scheduler: schedulerInstance,
     attributes: attributeConfig,
 
     start() {
       assertActive();
       loaderInstance.router = api;
-      signalRegistry._setContext?.({ router: api, loader: loaderInstance, server, cache });
+      signalRegistry._setContext?.({ router: api, loader: loaderInstance, server, cache, scheduler: schedulerInstance });
       if (ownsLoader) {
         loaderInstance.start();
       }
@@ -178,7 +188,7 @@ export function createRouter({
     },
 
     match(url) {
-      return routes.match(url);
+      return routes.match(resolveUrl(url));
     },
 
     prefetch(url) {
@@ -203,7 +213,7 @@ export function createRouter({
         return null;
       }
 
-      const target = toUrl(url);
+      const target = resolveUrl(url);
       if (mode === "ssr-spa") {
         return fetchRoutePartial(target, options);
       }
@@ -215,10 +225,14 @@ export function createRouter({
         return;
       }
       destroyed = true;
+      activeNavigation?.controller.abort(new Error("Router has been destroyed."));
       for (const cleanup of cleanups) {
         cleanup();
       }
       cleanups.clear();
+      if (ownsScheduler) {
+        schedulerInstance.destroy();
+      }
     }
   };
 
@@ -254,24 +268,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,28 +306,48 @@ 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,
+      scheduler: schedulerInstance,
+      abort: navigation?.abort
     });
+    await schedulerInstance.flush();
+    if (!isActiveNavigation(navigation)) {
+      return;
+    }
     if (result?.html != null && !result.boundary && !result.redirect) {
       loaderInstance.swap(boundary, result.html);
+      await schedulerInstance.flush();
     }
     if (result?.redirect || options.history === false) {
       return;
@@ -312,14 +359,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 +382,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 +392,29 @@ export function createRouter({
       loader: loaderInstance,
       server,
       cache,
-      abort: undefined
+      scheduler: schedulerInstance,
+      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 +449,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 +473,7 @@ function normalizeRoute(pattern, definition) {
     pattern,
     regex,
     keys,
+    score: routeScore(pattern),
     definition: normalized
   };
 }
@@ -467,6 +542,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 \"*\".");