@async/framework 0.6.0 → 0.8.0

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,88 +1,6 @@
-import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
-
 const serverEnvelopeKeys = new Set(["value", "signals", "boundary", "html", "redirect", "error"]);
-
-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);
-}
+const appliedServerResult = Symbol.for("@async/framework.appliedServerResult");
+const appliedServerValues = new WeakSet();
 
 export function createServerProxy({
   endpoint = "/__async/server",
@@ -91,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);
@@ -107,6 +26,7 @@ export function createServerProxy({
       input: context.input ?? defaultInput(runContext),
       signals: context.signalValues ?? snapshotSignalPaths(context.signalPaths, runContext.signals)
     };
+    assertJsonTransportable(body);
 
     const response = await fetchImpl(joinEndpoint(endpoint, id), {
       method: "POST",
@@ -124,7 +44,7 @@ export function createServerProxy({
 
     const result = await readServerResponse(response);
     await applyServerResult(result, runContext);
-    return unwrapServerResult(result);
+    return markAppliedServerValue(unwrapServerResult(result));
   }
 
   return createServerNamespace(run, {
@@ -159,6 +79,9 @@ export async function applyServerResult(result, context = {}) {
   if (!isServerEnvelope(result)) {
     return result;
   }
+  if (result[appliedServerResult] || appliedServerValues.has(result)) {
+    return result;
+  }
 
   if (result.signals && context.signals) {
     for (const [path, value] of Object.entries(result.signals)) {
@@ -182,6 +105,12 @@ export async function applyServerResult(result, context = {}) {
     throw toError(result.error);
   }
 
+  Object.defineProperty(result, appliedServerResult, {
+    configurable: true,
+    enumerable: false,
+    value: true
+  });
+
   return result;
 }
 
@@ -192,6 +121,13 @@ export function unwrapServerResult(result) {
   return result;
 }
 
+function markAppliedServerValue(value) {
+  if (value && typeof value === "object") {
+    appliedServerValues.add(value);
+  }
+  return value;
+}
+
 export function defaultInput(context = {}) {
   const form = findForm(context);
   if (form) {
@@ -210,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) {
@@ -292,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;
   }
@@ -369,6 +305,30 @@ function formDataToObject(formData) {
   return output;
 }
 
+function assertJsonTransportable(value, seen = new Set()) {
+  if (value == null || typeof value !== "object") {
+    return;
+  }
+  if (seen.has(value)) {
+    return;
+  }
+  seen.add(value);
+
+  const tag = Object.prototype.toString.call(value);
+  if (tag === "[object File]" || tag === "[object Blob]" || tag === "[object FormData]") {
+    throw new Error("Server proxy JSON transport does not support File, Blob, or FormData values yet.");
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      assertJsonTransportable(item, seen);
+    }
+    return;
+  }
+  for (const item of Object.values(value)) {
+    assertJsonTransportable(item, seen);
+  }
+}
+
 function joinEndpoint(endpoint, id) {
   return `${String(endpoint).replace(/\/$/, "")}/${encodeURIComponent(id)}`;
 }
@@ -390,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.");
   }