@async/framework 0.7.0 → 0.9.0

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,6 +1,7 @@
 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 { createBoundaryReceiver } from "./boundary-receiver.js";
 export { createCacheRegistry, defineCache } from "./cache.js";
 export { component, createComponentRegistry, defineComponent } from "./component.js";
 export { delay } from "./delay.js";
@@ -10,5 +11,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 {};
+}

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";
@@ -121,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 ??
@@ -136,6 +140,7 @@ export function createRouter({
       handlers: handlerRegistry,
       server,
       cache,
+      scheduler: schedulerInstance,
       attributes: attributeConfig
     });
   const ownsLoader = !loader;
@@ -155,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();
       }
@@ -224,6 +230,9 @@ export function createRouter({
         cleanup();
       }
       cleanups.clear();
+      if (ownsScheduler) {
+        schedulerInstance.destroy();
+      }
     }
   };
 
@@ -329,13 +338,16 @@ export function createRouter({
       loader: loaderInstance,
       router: api,
       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;
@@ -380,6 +392,7 @@ export function createRouter({
       loader: loaderInstance,
       server,
       cache,
+      scheduler: schedulerInstance,
       abort: navigation?.abort
     };
   }

package/src/scheduler.js

@@ -0,0 +1,300 @@
+const defaultPhases = ["binding", "lifecycle", "effect", "async", "post"];
+
+export function createScheduler(options = {}) {
+  const phases = [...(options.phases ?? defaultPhases)];
+  const queues = new Map(phases.map((phase) => [phase, []]));
+  const keyedJobs = new Map();
+  const destroyedScopes = new Set();
+  const objectScopeIds = new WeakMap();
+  const onError = typeof options.onError === "function" ? options.onError : undefined;
+  const maxDepth = options.maxDepth ?? 100;
+  const strategy = options.strategy ?? "microtask";
+  let destroyed = false;
+  let flushing = false;
+  let scheduled = false;
+  let batchDepth = 0;
+  let jobCounter = 0;
+  let scopeCounter = 0;
+
+  const api = {
+    strategy,
+    phases,
+
+    batch(fn) {
+      if (typeof fn !== "function") {
+        throw new TypeError("scheduler.batch(fn) requires a function.");
+      }
+      assertActive();
+      batchDepth += 1;
+      let asyncBatch = false;
+      try {
+        const value = fn();
+        if (value && typeof value.then === "function") {
+          asyncBatch = true;
+          return value.finally(() => {
+            batchDepth -= 1;
+            requestFlush();
+          });
+        }
+        return value;
+      } finally {
+        if (!asyncBatch && batchDepth > 0) {
+          batchDepth -= 1;
+          requestFlush();
+        }
+      }
+    },
+
+    enqueue(phase, fn, options = {}) {
+      assertActive();
+      assertPhase(phase);
+      if (typeof fn !== "function") {
+        throw new TypeError("scheduler.enqueue(phase, fn) requires a function.");
+      }
+      const scope = options.scope;
+      if (scope !== undefined && destroyedScopes.has(scope)) {
+        return noop;
+      }
+
+      const dedupeKey = options.key === undefined ? undefined : `${phase}:${scopeKey(scope)}:${String(options.key)}`;
+      if (dedupeKey && keyedJobs.has(dedupeKey)) {
+        return keyedJobs.get(dedupeKey).cancel;
+      }
+
+      const job = {
+        id: ++jobCounter,
+        phase,
+        fn,
+        scope,
+        boundary: options.boundary,
+        key: dedupeKey,
+        canceled: false,
+        cancel() {
+          job.canceled = true;
+          if (job.key) {
+            keyedJobs.delete(job.key);
+          }
+        }
+      };
+      queues.get(phase).push(job);
+      if (job.key) {
+        keyedJobs.set(job.key, job);
+      }
+      requestFlush();
+      return job.cancel;
+    },
+
+    afterFlush(fn, options = {}) {
+      return api.enqueue("post", fn, options);
+    },
+
+    async flush() {
+      assertActive();
+      if (flushing) {
+        return;
+      }
+      scheduled = false;
+      flushing = true;
+      let depth = 0;
+      try {
+        while (hasJobs()) {
+          depth += 1;
+          if (depth > maxDepth) {
+            throw new Error(`Scheduler exceeded maxDepth ${maxDepth}.`);
+          }
+          for (const phase of phases) {
+            await flushPhase(phase);
+          }
+        }
+      } finally {
+        flushing = false;
+        if (hasJobs()) {
+          requestFlush();
+        }
+      }
+    },
+
+    async flushScope(scope) {
+      assertActive();
+      if (flushing) {
+        return;
+      }
+      scheduled = false;
+      flushing = true;
+      let depth = 0;
+      try {
+        while (hasJobsForScope(scope)) {
+          depth += 1;
+          if (depth > maxDepth) {
+            throw new Error(`Scheduler exceeded maxDepth ${maxDepth}.`);
+          }
+          for (const phase of phases) {
+            await flushPhase(phase, scope);
+          }
+        }
+      } finally {
+        flushing = false;
+        if (hasJobs()) {
+          requestFlush();
+        }
+      }
+    },
+
+    cancelScope(scope) {
+      if (scope === undefined) {
+        return api;
+      }
+      for (const queue of queues.values()) {
+        for (const job of queue) {
+          if (job.scope === scope) {
+            job.cancel();
+          }
+        }
+      }
+      return api;
+    },
+
+    markScopeDestroyed(scope) {
+      if (scope !== undefined) {
+        destroyedScopes.add(scope);
+        api.cancelScope(scope);
+      }
+      return api;
+    },
+
+    isScopeDestroyed(scope) {
+      return scope !== undefined && destroyedScopes.has(scope);
+    },
+
+    inspect() {
+      const counts = {};
+      for (const [phase, queue] of queues) {
+        counts[phase] = queue.filter((job) => !job.canceled).length;
+      }
+      return {
+        strategy,
+        phases: [...phases],
+        pending: counts,
+        scopesDestroyed: destroyedScopes.size,
+        flushing,
+        scheduled
+      };
+    },
+
+    destroy() {
+      destroyed = true;
+      for (const queue of queues.values()) {
+        for (const job of queue) {
+          job.cancel();
+        }
+        queue.length = 0;
+      }
+      keyedJobs.clear();
+      destroyedScopes.clear();
+    }
+  };
+
+  return api;
+
+  function requestFlush() {
+    if (strategy === "manual" || destroyed || flushing || batchDepth > 0 || scheduled) {
+      return;
+    }
+    scheduled = true;
+    scheduleMicrotask(() => {
+      if (!destroyed) {
+        void api.flush();
+      }
+    });
+  }
+
+  async function flushPhase(phase, scope) {
+    const queue = queues.get(phase);
+    const remaining = [];
+    const runnable = [];
+
+    for (const job of queue.splice(0)) {
+      if (job.canceled) {
+        continue;
+      }
+      if (scope !== undefined && job.scope !== scope) {
+        remaining.push(job);
+        continue;
+      }
+      runnable.push(job);
+    }
+
+    queue.push(...remaining);
+
+    for (const job of runnable) {
+      if (job.key) {
+        keyedJobs.delete(job.key);
+      }
+      if (job.canceled || (job.scope !== undefined && destroyedScopes.has(job.scope))) {
+        continue;
+      }
+      try {
+        await job.fn();
+      } catch (error) {
+        if (onError) {
+          onError(error, job);
+        } else {
+          throw error;
+        }
+      }
+    }
+  }
+
+  function hasJobs() {
+    for (const queue of queues.values()) {
+      if (queue.some((job) => !job.canceled)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  function hasJobsForScope(scope) {
+    for (const queue of queues.values()) {
+      if (queue.some((job) => !job.canceled && job.scope === scope)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  function assertActive() {
+    if (destroyed) {
+      throw new Error("Scheduler has been destroyed.");
+    }
+  }
+
+  function assertPhase(phase) {
+    if (!queues.has(phase)) {
+      throw new Error(`Unknown scheduler phase "${phase}".`);
+    }
+  }
+
+  function scopeKey(scope) {
+    if (scope === undefined) {
+      return "global";
+    }
+    if ((typeof scope === "object" && scope !== null) || typeof scope === "function") {
+      if (!objectScopeIds.has(scope)) {
+        objectScopeIds.set(scope, `scope:${++scopeCounter}`);
+      }
+      return objectScopeIds.get(scope);
+    }
+    return String(scope);
+  }
+}
+
+function scheduleMicrotask(fn) {
+  if (typeof queueMicrotask === "function") {
+    queueMicrotask(fn);
+    return;
+  }
+  Promise.resolve().then(fn);
+}
+
+function noop() {}