@async/framework 0.7.0 → 0.9.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/boundary-receiver.js

@@ -0,0 +1,302 @@
+const defaultRecentLimit = 50;
+
+export function createBoundaryReceiver(options = {}) {
+  const loader = options.loader;
+  const signals = options.signals ?? loader?.signals;
+  const cache = options.cache ?? loader?.cache;
+  const scheduler = options.scheduler ?? loader?.scheduler;
+  const router = options.router ?? loader?.router;
+  const recentLimit = options.recentLimit ?? defaultRecentLimit;
+  const throwOnError = options.throwOnError === true;
+  const onApply = typeof options.onApply === "function" ? options.onApply : undefined;
+  const onIgnore = typeof options.onIgnore === "function" ? options.onIgnore : undefined;
+  const onError = typeof options.onError === "function" ? options.onError : undefined;
+  const isScopeDestroyed = typeof options.isScopeDestroyed === "function"
+    ? options.isScopeDestroyed
+    : (scope) => scheduler?.isScopeDestroyed?.(scope) ?? scheduler?.inspectDestroyed?.(scope) ?? false;
+
+  if (!loader || typeof loader.swap !== "function") {
+    throw new TypeError("createBoundaryReceiver(...) requires a loader with swap(boundary, html).");
+  }
+  if (!Number.isInteger(recentLimit) || recentLimit < 0) {
+    throw new TypeError("createBoundaryReceiver(...) recentLimit must be a non-negative integer.");
+  }
+
+  const boundaries = new Map();
+  const recent = [];
+  let destroyed = false;
+
+  const receiver = {
+    async apply(patch) {
+      if (destroyed) {
+        throw new Error("Boundary receiver has been destroyed.");
+      }
+
+      const normalized = validatePatch(patch);
+      const record = boundaryRecord(normalized.boundary);
+      if (normalized.seq <= record.lastSeq) {
+        const result = {
+          status: "ignored-stale",
+          boundary: normalized.boundary,
+          seq: normalized.seq,
+          lastSeq: record.lastSeq
+        };
+        record.ignored += 1;
+        record.lastStatus = result.status;
+        remember(result);
+        onIgnore?.(result, patch);
+        return result;
+      }
+
+      if (normalized.parentScope !== undefined && isScopeDestroyed(normalized.parentScope)) {
+        const result = {
+          status: "ignored-destroyed",
+          boundary: normalized.boundary,
+          seq: normalized.seq,
+          parentScope: normalized.parentScope
+        };
+        record.ignored += 1;
+        record.lastStatus = result.status;
+        remember(result);
+        onIgnore?.(result, patch);
+        return result;
+      }
+
+      record.lastSeq = normalized.seq;
+
+      if (Object.hasOwn(normalized, "error")) {
+        const error = toStableError(normalized.error);
+        const result = {
+          status: "errored",
+          boundary: normalized.boundary,
+          seq: normalized.seq,
+          error
+        };
+        record.errored += 1;
+        record.lastStatus = result.status;
+        remember(result);
+        onError?.(error, result, patch);
+        if (throwOnError) {
+          throw error;
+        }
+        return result;
+      }
+
+      if (normalized.signals) {
+        if (!signals || typeof signals.set !== "function") {
+          throw new Error("Boundary patch includes signals, but no signal registry is available.");
+        }
+        for (const [path, value] of Object.entries(normalized.signals)) {
+          signals.set(path, value);
+        }
+      }
+
+      if (normalized.cache?.browser) {
+        if (!cache || typeof cache.restore !== "function") {
+          throw new Error("Boundary patch includes browser cache, but no cache registry is available.");
+        }
+        cache.restore(normalized.cache.browser);
+      }
+
+      if (normalized.html != null) {
+        loader.swap(normalized.boundary, normalized.html);
+      }
+
+      await flushScheduler(scheduler, normalized.scope);
+
+      if (normalized.redirect) {
+        await followRedirect(normalized.redirect, router, loader);
+        const result = {
+          status: "redirected",
+          boundary: normalized.boundary,
+          seq: normalized.seq,
+          redirect: normalized.redirect
+        };
+        record.applied += 1;
+        record.lastStatus = result.status;
+        remember(result);
+        onApply?.(result, patch);
+        return result;
+      }
+
+      const result = {
+        status: "applied",
+        boundary: normalized.boundary,
+        seq: normalized.seq
+      };
+      record.applied += 1;
+      record.lastStatus = result.status;
+      remember(result);
+      onApply?.(result, patch);
+      return result;
+    },
+
+    inspect() {
+      const snapshot = {};
+      for (const [boundary, record] of boundaries) {
+        snapshot[boundary] = {
+          lastSeq: record.lastSeq,
+          applied: record.applied,
+          ignored: record.ignored,
+          lastStatus: record.lastStatus
+        };
+        if (record.errored > 0) {
+          snapshot[boundary].errored = record.errored;
+        }
+      }
+      return {
+        destroyed,
+        boundaries: snapshot,
+        recent: recent.map((entry) => ({ ...entry }))
+      };
+    },
+
+    reset(boundary) {
+      if (boundary === undefined) {
+        boundaries.clear();
+        recent.length = 0;
+        return receiver;
+      }
+      assertBoundary(boundary);
+      boundaries.delete(boundary);
+      for (let index = recent.length - 1; index >= 0; index -= 1) {
+        if (recent[index].boundary === boundary) {
+          recent.splice(index, 1);
+        }
+      }
+      return receiver;
+    },
+
+    destroy() {
+      destroyed = true;
+      boundaries.clear();
+      recent.length = 0;
+    }
+  };
+
+  return receiver;
+
+  function boundaryRecord(boundary) {
+    if (!boundaries.has(boundary)) {
+      boundaries.set(boundary, {
+        lastSeq: -Infinity,
+        applied: 0,
+        ignored: 0,
+        errored: 0,
+        lastStatus: undefined
+      });
+    }
+    return boundaries.get(boundary);
+  }
+
+  function remember(result) {
+    if (recentLimit === 0) {
+      return;
+    }
+    recent.push(toRecentEntry(result));
+    while (recent.length > recentLimit) {
+      recent.shift();
+    }
+  }
+}
+
+function validatePatch(patch) {
+  if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+    throw new TypeError("receiver.apply(patch) requires a boundary patch object.");
+  }
+
+  assertBoundary(patch.boundary);
+  if (typeof patch.seq !== "number" || !Number.isFinite(patch.seq)) {
+    throw new TypeError("Boundary patch seq must be a finite number.");
+  }
+
+  if (patch.signals !== undefined && !isPlainObject(patch.signals)) {
+    throw new TypeError("Boundary patch signals must be an object.");
+  }
+  if (patch.cache !== undefined && !isPlainObject(patch.cache)) {
+    throw new TypeError("Boundary patch cache must be an object.");
+  }
+  if (patch.cache?.browser !== undefined && !isPlainObject(patch.cache.browser)) {
+    throw new TypeError("Boundary patch cache.browser must be an object.");
+  }
+  if (patch.redirect !== undefined && (typeof patch.redirect !== "string" || patch.redirect.length === 0)) {
+    throw new TypeError("Boundary patch redirect must be a non-empty string.");
+  }
+  if (patch.parentScope !== undefined && typeof patch.parentScope !== "string") {
+    throw new TypeError("Boundary patch parentScope must be a string.");
+  }
+  if (patch.scope !== undefined && typeof patch.scope !== "string") {
+    throw new TypeError("Boundary patch scope must be a string.");
+  }
+
+  const hasHtml = Object.hasOwn(patch, "html") && patch.html != null;
+  const hasSignals = patch.signals && Object.keys(patch.signals).length > 0;
+  const hasBrowserCache = patch.cache?.browser && Object.keys(patch.cache.browser).length > 0;
+  const hasRedirect = Boolean(patch.redirect);
+  const hasError = Object.hasOwn(patch, "error");
+  if (!hasHtml && !hasSignals && !hasBrowserCache && !hasRedirect && !hasError) {
+    throw new TypeError("Boundary patch must include html, signals, cache.browser, redirect, or error.");
+  }
+
+  return patch;
+}
+
+function assertBoundary(boundary) {
+  if (typeof boundary !== "string" || boundary.length === 0) {
+    throw new TypeError("Boundary patch boundary must be a non-empty string.");
+  }
+}
+
+async function flushScheduler(scheduler, scope) {
+  if (!scheduler) {
+    return;
+  }
+  if (scope !== undefined && typeof scheduler.flushScope === "function") {
+    await scheduler.flushScope(scope);
+    return;
+  }
+  if (typeof scheduler.flush === "function") {
+    await scheduler.flush();
+  }
+}
+
+async function followRedirect(redirect, router, loader) {
+  if (router && typeof router.navigate === "function") {
+    await router.navigate(redirect);
+    return;
+  }
+  const location = loader?.root?.ownerDocument?.defaultView?.location ?? globalThis.location;
+  location?.assign?.(redirect);
+}
+
+function toStableError(value) {
+  if (value instanceof Error) {
+    return value;
+  }
+  if (value && typeof value === "object" && typeof value.message === "string") {
+    return Object.assign(new Error(value.message), value);
+  }
+  return new Error(String(value));
+}
+
+function toRecentEntry(result) {
+  const entry = {
+    boundary: result.boundary,
+    seq: result.seq,
+    status: result.status
+  };
+  if (result.status === "ignored-stale") {
+    entry.lastSeq = result.lastSeq;
+  }
+  if (result.status === "ignored-destroyed" && result.parentScope !== undefined) {
+    entry.parentScope = result.parentScope;
+  }
+  if (result.status === "redirected") {
+    entry.redirect = result.redirect;
+  }
+  return entry;
+}
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/src/browser.js

@@ -0,0 +1,16 @@
+export { asyncSignal } from "./async-signal.js";
+export { Async, createApp, defineApp, readSnapshot } from "./app.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";
+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";