@async/framework 0.7.0 → 0.8.0

package/src/app.js

@@ -4,16 +4,18 @@ import { createHandlerRegistry } from "./handlers.js";
 import { Loader } from "./loader.js";
 import { createPartialRegistry } from "./partials.js";
 import { createRouteRegistry, createRouter } from "./router.js";
-import { createServerRegistry } from "./server.js";
+import { createScheduler } from "./scheduler.js";
+import { createServerNamespace } 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) {
+export function defineApp(initial, options = {}) {
   const registry = createRegistryStore(undefined, { target: "browser" });
   const runtimes = new Set();
+  const createRuntime = options.createRuntime ?? createApp;
 
   const app = {
     registry,
@@ -32,7 +34,7 @@ export function defineApp(initial) {
     },
 
     start(options = {}) {
-      const runtime = createApp(app, options).start();
+      const runtime = createRuntime(app, options).start();
       app.runtime = runtime;
       return runtime;
     },
@@ -57,13 +59,18 @@ export function defineApp(initial) {
 export function createApp(appOrDefinition = Async, options = {}) {
   const app = isAppHub(appOrDefinition) ? appOrDefinition : defineApp(appOrDefinition ?? {});
   const target = options.target ?? "browser";
+  const scheduler = options.scheduler ?? options.loader?.scheduler ?? createScheduler({
+    strategy: target === "server" ? "manual" : "microtask"
+  });
+  const ownsScheduler = !options.scheduler && !options.loader?.scheduler;
   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 serverFactory = options.serverFactory ?? createServerReferenceRegistry;
+  const server = options.server ?? serverFactory(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" });
@@ -91,6 +98,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
     },
     loader,
     router,
+    scheduler,
     attributes,
 
     start() {
@@ -107,12 +115,13 @@ export function createApp(appOrDefinition = Async, options = {}) {
           handlers,
           server,
           cache: browserCache,
+          scheduler,
           attributes
         });
         runtime.loader = loader;
 
         configureServerContext({ cache: browserCache });
-        signals._setContext?.({ server, loader, cache: browserCache });
+        signals._setContext?.({ server, loader, cache: browserCache, scheduler });
 
         loader.start();
 
@@ -128,6 +137,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
             server,
             cache: browserCache,
             partials,
+            scheduler,
             fetch: options.fetch,
             routeEndpoint: options.routeEndpoint,
             attributes
@@ -139,7 +149,7 @@ export function createApp(appOrDefinition = Async, options = {}) {
         }
       } else {
         configureServerContext({ cache: serverCache });
-        signals._setContext?.({ server, cache: serverCache });
+        signals._setContext?.({ server, cache: serverCache, scheduler });
       }
 
       return runtime;
@@ -153,9 +163,10 @@ export function createApp(appOrDefinition = Async, options = {}) {
     async render(url) {
       assertActive();
       configureServerContext({ cache: serverCache });
-      signals._setContext?.({ server, cache: serverCache });
+      signals._setContext?.({ server, cache: serverCache, scheduler });
       const matched = routes.match(url);
       if (!matched) {
+        await scheduler.flush();
         return {
           html: renderDocument("", { status: 404, signals, browserCache, boundary: options.boundary ?? "route", attributes }),
           status: 404,
@@ -175,8 +186,8 @@ export function createApp(appOrDefinition = Async, options = {}) {
             cache: serverCache,
             browserCache,
             partials,
-            request: options.request,
-            locals: options.locals
+            scheduler,
+            ...currentRequestContext()
           })
         : { html: "" };
 
@@ -189,6 +200,8 @@ export function createApp(appOrDefinition = Async, options = {}) {
         browserCache.restore(result.cache.browser);
       }
 
+      await scheduler.flush();
+
       const status = result.status ?? 200;
       return {
         html: renderDocument(result.html, { status, signals, browserCache, boundary: result.boundary ?? options.boundary ?? "route", attributes }),
@@ -207,6 +220,9 @@ export function createApp(appOrDefinition = Async, options = {}) {
       router?.destroy?.();
       loader?.destroy?.();
       signals.destroy?.();
+      if (ownsScheduler) {
+        scheduler.destroy();
+      }
     },
 
     _applyUse(normalized) {
@@ -227,11 +243,23 @@ export function createApp(appOrDefinition = Async, options = {}) {
       loader,
       router,
       cache,
-      request: options.request,
-      locals: options.locals
+      scheduler,
+      requestContext: options.requestContext,
+      ...currentRequestContext()
     });
   }
 
+  function currentRequestContext() {
+    const context = readRequestContextLike(options.requestContext);
+    return {
+      requestContext: context,
+      request: context.request ?? options.request,
+      headers: context.headers ?? options.headers,
+      cookies: context.cookies ?? options.cookies,
+      locals: context.locals ?? options.locals
+    };
+  }
+
   function assertActive() {
     if (destroyed) {
       throw new Error("Async app runtime has been destroyed.");
@@ -385,6 +413,77 @@ function attachServerCache(server, cache) {
   }
 }
 
+function createServerReferenceRegistry(initialMap = {}, options = {}) {
+  const registry = options.registry ?? createRegistryStore();
+  const type = options.type ?? "server";
+  const defaults = {};
+
+  const reference = {
+    registry,
+
+    register(id, value) {
+      registry.register(type, id, value);
+      return id;
+    },
+
+    registerMany(map) {
+      for (const [id, value] of Object.entries(map ?? {})) {
+        reference.register(id, value);
+      }
+      return reference;
+    },
+
+    unregister(id) {
+      return registry.unregister(type, id);
+    },
+
+    resolve() {
+      return undefined;
+    },
+
+    async run(id) {
+      throw new Error(`Server command "${id}" cannot run without a server proxy or server registry.`);
+    },
+
+    keys() {
+      return registry.keys(type);
+    },
+
+    entries() {
+      return registry.entries(type);
+    },
+
+    inspect() {
+      return registry.entries(type);
+    },
+
+    _setContext(context = {}) {
+      Object.assign(defaults, context);
+      return reference;
+    },
+
+    _adoptMany() {
+      return reference;
+    }
+  };
+
+  reference.registerMany(initialMap);
+  return createServerNamespace((id, args, context) => reference.run(id, args, context), reference, () => defaults);
+}
+
+function readRequestContextLike(store) {
+  if (!store) {
+    return {};
+  }
+  if (typeof store.get === "function") {
+    return store.get() ?? {};
+  }
+  if (typeof store.getStore === "function") {
+    return store.getStore() ?? {};
+  }
+  return {};
+}
+
 function normalizeEntries(type, entries = {}) {
   if (type !== "signal") {
     return { ...(entries ?? {}) };

package/src/async-signal.js

@@ -90,7 +90,8 @@ export function asyncSignal(id, fn) {
               router: context.router,
               loader: context.loader,
               cache: context.cache,
-              abort: activeAbort
+              abort: activeAbort,
+              scheduler: context.scheduler
             });
           }
           return server;
@@ -104,6 +105,9 @@ export function asyncSignal(id, fn) {
         get cache() {
           return registry._context?.().cache;
         },
+        get scheduler() {
+          return registry._context?.().scheduler;
+        },
         get version() {
           return runVersion;
         },
@@ -180,11 +184,20 @@ export function asyncSignal(id, fn) {
     _bindRegistry(nextRegistry, nextId) {
       registry = nextRegistry;
       registeredId = nextId;
-      queueMicrotask(() => {
+      const start = () => {
         if (registry === nextRegistry && status === "idle") {
           state.refresh();
         }
-      });
+      };
+      const scheduler = registry._context?.().scheduler;
+      if (scheduler) {
+        scheduler.enqueue("async", start, {
+          scope: registeredId,
+          key: `asyncSignal:${registeredId}:initial`
+        });
+      } else {
+        queueMicrotask(start);
+      }
     },
 
     _dispose() {
@@ -220,11 +233,26 @@ export function asyncSignal(id, fn) {
     for (const dependency of dependencies) {
       const dependencyId = String(dependency).split(".")[0];
       if (dependencyId && dependencyId !== registeredId) {
-        dependencyCleanups.add(registry.subscribe(dependency, () => state.refresh()));
+        dependencyCleanups.add(registry.subscribe(dependency, () => scheduleRefresh()));
       }
     }
   }
 
+  function scheduleRefresh() {
+    if (activeAbort && !activeAbort.aborted) {
+      activeAbort.cancel(new Error(`Async signal "${registeredId}" dependency changed.`));
+    }
+    const scheduler = registry?._context?.().scheduler;
+    if (!scheduler) {
+      state.refresh();
+      return;
+    }
+    scheduler.enqueue("async", () => state.refresh(), {
+      scope: registeredId,
+      key: `asyncSignal:${registeredId}:refresh`
+    });
+  }
+
   function notify() {
     for (const subscriber of [...subscribers]) {
       subscriber(state);

package/src/browser.js

@@ -0,0 +1,15 @@
+export { asyncSignal } from "./async-signal.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 { Loader, AsyncLoader } from "./loader.js";
+export { createPartialRegistry } from "./partials.js";
+export { createRegistryStore } from "./registry-store.js";
+export { createRouteRegistry, createRouter, defineRoute, route } from "./router.js";
+export { createScheduler } from "./scheduler.js";
+export { applyServerResult, createServerProxy, resolveServerCommandArguments, unwrapServerResult } from "./server.js";
+export { computed, createSignal, createSignalRegistry, effect, signal } from "./signals.js";

package/src/component.js

@@ -113,10 +113,15 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
     html,
     attach(target) {
       for (const hook of attachHooks) {
-        const cleanup = hook(target);
-        if (typeof cleanup === "function") {
-          cleanups.push(cleanup);
-        }
+        runtime.scheduler?.enqueue("lifecycle", () => {
+          const cleanup = hook(target);
+          if (typeof cleanup === "function") {
+            cleanups.push(cleanup);
+          }
+        }, {
+          scope,
+          key: `attach:${attachHooks.indexOf(hook)}`
+        }) ?? runAttachHook(hook, target);
       }
     },
     mount(target) {
@@ -124,7 +129,17 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
     },
     visible(target, observeVisible) {
       for (const hook of visibleHooks) {
-        const cleanup = observeVisible(target, hook);
+        const cleanup = observeVisible(target, () => {
+          runtime.scheduler?.enqueue("lifecycle", () => {
+            const hookCleanup = hook(target);
+            if (typeof hookCleanup === "function") {
+              cleanups.push(hookCleanup);
+            }
+          }, {
+            scope,
+            key: `visible:${visibleHooks.indexOf(hook)}`
+          }) ?? runVisibleHook(hook, target);
+        });
         if (typeof cleanup === "function") {
           cleanups.push(cleanup);
         }
@@ -134,6 +149,7 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
       while (destroyHooks.length > 0) {
         destroyHooks.pop()?.();
       }
+      runtime.scheduler?.markScopeDestroyed(scope);
       while (cleanups.length > 0) {
         cleanups.pop()?.();
       }
@@ -142,10 +158,24 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
       }
     }
   };
+
+  function runAttachHook(hook, target) {
+    const cleanup = hook(target);
+    if (typeof cleanup === "function") {
+      cleanups.push(cleanup);
+    }
+  }
+
+  function runVisibleHook(hook, target) {
+    const cleanup = hook(target);
+    if (typeof cleanup === "function") {
+      cleanups.push(cleanup);
+    }
+  }
 }
 
 function createComponentContext({ runtime, scope, cleanups, attachHooks, visibleHooks, destroyHooks, renderScopedTemplate }) {
-  const { signals, handlers, loader, server, router, cache } = runtime;
+  const { signals, handlers, loader, server, router, cache, scheduler } = runtime;
   const generatedHandlers = new WeakMap();
   let generatedHandlerCounter = 0;
   let generatedSignalCounter = 0;
@@ -157,6 +187,7 @@ function createComponentContext({ runtime, scope, cleanups, attachHooks, visible
     server,
     router,
     cache,
+    scheduler,
 
     signal(name, initial) {
       if (arguments.length === 1) {
@@ -201,7 +232,11 @@ function createComponentContext({ runtime, scope, cleanups, attachHooks, visible
     },
 
     effect(fn) {
-      const cleanup = signals.effect(() => fn.call(context));
+      const cleanup = signals.effect(() => fn.call(context), {
+        scheduler,
+        phase: "effect",
+        scope
+      });
       cleanups.push(cleanup);
       return cleanup;
     },

package/src/index.js

@@ -1,5 +1,5 @@
 export { asyncSignal } from "./async-signal.js";
-export { Async, createApp, defineApp, readSnapshot } from "./app.js";
+export { Async, createApp, defineApp, readSnapshot } from "./server-entry.js";
 export { attributeName, defineAttributeConfig } from "./attributes.js";
 export { createCacheRegistry, defineCache } from "./cache.js";
 export { component, createComponentRegistry, defineComponent } from "./component.js";
@@ -10,5 +10,8 @@ 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";
-export { createServerProxy, createServerRegistry } from "./server.js";
+export { createScheduler } from "./scheduler.js";
+export { createRequestContextStore } from "./request-context.js";
+export { applyServerResult, createServerProxy, resolveServerCommandArguments, unwrapServerResult } from "./server.js";
+export { createServerRegistry } from "./server-registry.js";
 export { computed, createSignal, createSignalRegistry, effect, signal } from "./signals.js";

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 {};
+}