@async/framework 0.7.0 → 0.8.0

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,296 @@
+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;
+    },
+
+    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() {}

package/src/server-entry.js

@@ -0,0 +1,20 @@
+import {
+  createApp as createBaseApp,
+  defineApp as defineBaseApp,
+  readSnapshot
+} from "./app.js";
+import { createServerRegistry } from "./server-registry.js";
+
+export function createApp(appOrDefinition = Async, options = {}) {
+  return createBaseApp(appOrDefinition, {
+    serverFactory: createServerRegistry,
+    ...options
+  });
+}
+
+export function defineApp(initial) {
+  return defineBaseApp(initial, { createRuntime: createApp });
+}
+
+export const Async = defineApp();
+export { readSnapshot };

package/src/server-registry.js

@@ -0,0 +1,97 @@
+import { readRequestContext } from "./request-context.js";
+import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
+import { assertServerId, createServerNamespace, createSignalReader } from "./server.js";
+
+export function createServerRegistry(initialMap = {}, options = {}) {
+  const registryStore = options.registry ?? createRegistryStore();
+  const type = options.type ?? "server";
+  const entries = registryStore._map(type);
+  const defaults = {};
+
+  const registry = attachRegistryInspection({
+    register(id, fn) {
+      assertServerId(id);
+      if (typeof fn !== "function") {
+        throw new TypeError(`Server function "${id}" must be a function.`);
+      }
+      if (entries.has(id)) {
+        throw new Error(`Server function "${id}" is already registered.`);
+      }
+      entries.set(id, fn);
+      return id;
+    },
+
+    registerMany(map) {
+      for (const [id, fn] of Object.entries(map ?? {})) {
+        registry.register(id, fn);
+      }
+      return registry;
+    },
+
+    unregister(id) {
+      assertServerId(id);
+      return entries.delete(id);
+    },
+
+    resolve(id) {
+      assertServerId(id);
+      return entries.get(id);
+    },
+
+    async run(id, args = [], context = {}) {
+      assertServerId(id);
+      const fn = registry.resolve(id);
+      if (!fn) {
+        throw new Error(`Server function "${id}" is not registered.`);
+      }
+
+      let runContext;
+      const server = createServerNamespace((childId, childArgs, childContext = {}) => {
+        return registry.run(childId, childArgs, { ...runContext, ...childContext });
+      }, {}, () => runContext);
+
+      const mergedContext = mergeRequestContext({
+        ...defaults,
+        ...context,
+        cache: defaults.cache ?? context.cache
+      });
+
+      runContext = {
+        ...mergedContext,
+        id,
+        args,
+        input: mergedContext.input,
+        signals: createSignalReader(mergedContext.signals),
+        abort: mergedContext.abort,
+        cache: mergedContext.cache,
+        server
+      };
+
+      return fn.call(runContext, ...args);
+    },
+
+    _setContext(context = {}) {
+      Object.assign(defaults, context);
+      return registry;
+    },
+
+    _adoptMany() {
+      return registry;
+    }
+  }, registryStore, type);
+
+  registry.registerMany(initialMap);
+  return createServerNamespace((id, args, context) => registry.run(id, args, context), registry, () => defaults);
+}
+
+function mergeRequestContext(context) {
+  const requestContext = readRequestContext(context.requestContext);
+  return {
+    ...context,
+    requestContext,
+    request: requestContext.request ?? context.request,
+    headers: requestContext.headers ?? context.headers,
+    cookies: requestContext.cookies ?? context.cookies,
+    locals: requestContext.locals ?? context.locals
+  };
+}

package/src/server.js

@@ -1,91 +1,7 @@
-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();
-  const type = options.type ?? "server";
-  const entries = registryStore._map(type);
-  const defaults = {};
-
-  const registry = attachRegistryInspection({
-    register(id, fn) {
-      assertServerId(id);
-      if (typeof fn !== "function") {
-        throw new TypeError(`Server function "${id}" must be a function.`);
-      }
-      if (entries.has(id)) {
-        throw new Error(`Server function "${id}" is already registered.`);
-      }
-      entries.set(id, fn);
-      return id;
-    },
-
-    registerMany(map) {
-      for (const [id, fn] of Object.entries(map ?? {})) {
-        registry.register(id, fn);
-      }
-      return registry;
-    },
-
-    unregister(id) {
-      assertServerId(id);
-      return entries.delete(id);
-    },
-
-    resolve(id) {
-      assertServerId(id);
-      return entries.get(id);
-    },
-
-    async run(id, args = [], context = {}) {
-      assertServerId(id);
-      const fn = registry.resolve(id);
-      if (!fn) {
-        throw new Error(`Server function "${id}" is not registered.`);
-      }
-
-      let runContext;
-      const server = createServerNamespace((childId, childArgs, childContext = {}) => {
-        return registry.run(childId, childArgs, { ...runContext, ...childContext });
-      }, {}, () => runContext);
-
-      const mergedContext = {
-        ...defaults,
-        ...context,
-        cache: defaults.cache ?? context.cache
-      };
-
-      runContext = {
-        ...mergedContext,
-        id,
-        args,
-        input: mergedContext.input,
-        signals: createSignalReader(mergedContext.signals),
-        abort: mergedContext.abort,
-        cache: mergedContext.cache,
-        server
-      };
-
-      return fn.call(runContext, ...args);
-    },
-
-    _setContext(context = {}) {
-      Object.assign(defaults, context);
-      return registry;
-    },
-
-    _adoptMany() {
-      return registry;
-    }
-  }, registryStore, type);
-
-  registry.registerMany(initialMap);
-  return createServerNamespace((id, args, context) => registry.run(id, args, context), registry, () => defaults);
-}
-
 export function createServerProxy({
   endpoint = "/__async/server",
   fetch: fetchImpl = globalThis.fetch?.bind(globalThis),
@@ -93,13 +9,14 @@ export function createServerProxy({
   loader,
   router,
   cache,
+  scheduler,
   headers = {}
 } = {}) {
   if (typeof fetchImpl !== "function") {
     throw new TypeError("createServerProxy(...) requires fetch to be available.");
   }
 
-  const defaults = { signals, loader, router, cache };
+  const defaults = { signals, loader, router, cache, scheduler };
 
   async function run(id, args = [], context = {}) {
     assertServerId(id);
@@ -229,7 +146,7 @@ export function defaultInput(context = {}) {
   };
 }
 
-function createServerNamespace(run, root = {}, contextProvider = () => ({})) {
+export function createServerNamespace(run, root = {}, contextProvider = () => ({})) {
   const cache = new Map();
 
   function namespace(parts) {
@@ -311,7 +228,7 @@ function readSignal(signals, path) {
   return signals.get(path);
 }
 
-function createSignalReader(signals) {
+export function createSignalReader(signals) {
   if (!signals || typeof signals.get === "function") {
     return signals;
   }
@@ -433,7 +350,7 @@ function toError(value) {
   return new Error(String(value));
 }
 
-function assertServerId(id) {
+export function assertServerId(id) {
   if (typeof id !== "string" || id.length === 0) {
     throw new TypeError("Server function id must be a non-empty string.");
   }