@async/framework 0.8.0 → 0.9.0

package/server.d.ts

@@ -75,6 +75,7 @@ export interface Scheduler {
   afterFlush(job: () => MaybePromise<unknown>, options?: { scope?: unknown; boundary?: string; key?: string }): Cleanup;
   cancelScope(scope: unknown): this;
   markScopeDestroyed(scope: unknown): this;
+  isScopeDestroyed(scope: unknown): boolean;
   destroy(): void;
   inspect(): SchedulerInspection;
 }
@@ -458,6 +459,53 @@ export interface LoaderInstance {
 export type AsyncLoaderOptions = LoaderOptions;
 export type AsyncLoaderInstance = LoaderInstance;
 
+export interface BoundaryPatch {
+  boundary: string;
+  seq: number;
+  html?: TemplateLike;
+  signals?: Record<string, unknown>;
+  cache?: { browser?: Record<string, unknown> };
+  redirect?: string;
+  error?: unknown;
+  parentScope?: string;
+  scope?: string;
+  meta?: Record<string, unknown>;
+}
+
+export type BoundaryApplyResult =
+  | { status: "applied"; boundary: string; seq: number }
+  | { status: "ignored-stale"; boundary: string; seq: number; lastSeq: number }
+  | { status: "ignored-destroyed"; boundary: string; seq: number; parentScope?: string }
+  | { status: "redirected"; boundary: string; seq: number; redirect: string }
+  | { status: "errored"; boundary: string; seq: number; error: Error };
+
+export interface BoundaryReceiverInspection {
+  destroyed: boolean;
+  boundaries: Record<string, { lastSeq: number; applied: number; ignored: number; errored?: number; lastStatus?: BoundaryApplyResult["status"] }>;
+  recent: Array<{ boundary: string; seq: number; status: BoundaryApplyResult["status"]; lastSeq?: number; parentScope?: string; redirect?: string }>;
+}
+
+export interface BoundaryReceiverOptions {
+  loader: LoaderInstance;
+  signals?: SignalRegistry;
+  cache?: CacheRegistry;
+  scheduler?: Scheduler;
+  router?: Router;
+  onApply?(result: BoundaryApplyResult, patch: BoundaryPatch): void;
+  onIgnore?(result: BoundaryApplyResult, patch: BoundaryPatch): void;
+  onError?(error: Error, result: BoundaryApplyResult, patch: BoundaryPatch): void;
+  throwOnError?: boolean;
+  recentLimit?: number;
+  isScopeDestroyed?(scope: string): boolean;
+}
+
+export interface BoundaryReceiver {
+  apply(patch: BoundaryPatch): Promise<BoundaryApplyResult>;
+  inspect(): BoundaryReceiverInspection;
+  reset(boundary?: string): this;
+  destroy(): void;
+}
+
 export interface RegistryStore {
   target: RuntimeTarget;
   register(type: RegistryType, id: string, value: unknown): string;
@@ -568,6 +616,7 @@ export interface AsyncNamespace extends AppHub {
   readSnapshot: typeof readSnapshot;
   attributeName: typeof attributeName;
   defineAttributeConfig: typeof defineAttributeConfig;
+  createBoundaryReceiver: typeof createBoundaryReceiver;
   createCacheRegistry: typeof createCacheRegistry;
   defineCache: typeof defineCache;
   component: typeof component;
@@ -605,6 +654,7 @@ export declare function defineApp(initial?: AppDefinition): AppHub;
 export declare function readSnapshot(root?: Document | Element, options?: { attributes?: AttributeConfig }): { signals?: Record<string, unknown>; cache?: { browser?: Record<string, unknown> } };
 export declare function attributeName(attributes: AttributeConfig | undefined, type: keyof NormalizedAttributeConfig, name: string): string;
 export declare function defineAttributeConfig(config?: AttributeConfig): NormalizedAttributeConfig;
+export declare function createBoundaryReceiver(options: BoundaryReceiverOptions): BoundaryReceiver;
 export declare function createCacheRegistry(initialMap?: Record<string, CacheDefinition | CacheDefinitionOptions>, options?: { now?: () => number; registry?: RegistryStore; type?: "cache.browser" | "cache.server" }): CacheRegistry;
 export declare function defineCache(options?: CacheDefinitionOptions): CacheDefinition;
 export declare function component<TProps extends Record<string, unknown> = Record<string, unknown>>(fn: ComponentFunction<TProps>): ComponentFunction<TProps>;

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

@@ -1,6 +1,7 @@
 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";

package/src/index.js

@@ -1,6 +1,7 @@
 export { asyncSignal } from "./async-signal.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";

package/src/scheduler.js

@@ -162,6 +162,10 @@ export function createScheduler(options = {}) {
       return api;
     },
 
+    isScopeDestroyed(scope) {
+      return scope !== undefined && destroyedScopes.has(scope);
+    },
+
     inspect() {
       const counts = {};
       for (const [phase, queue] of queues) {