statewire 0.8.1 → 0.9.0

package/src/client/core.ts

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 import { createChanges } from "./changes";
-import { getCommandsHost, getEmitHost, getStateHost } from "../host/host";
+import { getCommandsHost, getStateHost } from "../host/host";
 import type { CommandsInvocation, CommandsListener } from "../host/host";
 import { recordMutations } from "../util/recordMutations";
 import { createMacrotaskPoster } from "../util/macrotask";
@@ -26,319 +26,328 @@ const failureOf = (error: unknown): StatewireClient.SendFailure =>
 
 type Overlay = { inv: CommandsInvocation; dropped: boolean };
 
-const createCore = (
-  getOptions: () => StatewireClient.Options<any, any, any>,
-) => {
-  let value: Statewire<unknown> | null = null;
-  let source: Statewire.StateSource | null = null;
-  let overlays: Overlay[] = [];
-  let updates: Statewire.CommandUpdate[] = [];
-  let events: unknown[] = [];
-  let pendingChanged: StatewirePath[] = [];
-  let canonical: unknown;
-  let published: unknown;
-  let overlayPaths: readonly StatewirePath[] = [];
-  let notifiedPublished: unknown;
-  let notifiedOverlayPaths: readonly StatewirePath[] = [];
-  let notifiedConnection: StatewireClient.Connection | null = null;
-  let stale = false;
-  let everAttached = false;
-  let overlaysDirty = false;
-  let flushing = false;
-  const listeners = new Set<() => void>();
+type Core = {
+  getOptions: () => StatewireClient.Options<any, any>;
+  value: Statewire<unknown> | null;
+  source: Statewire.StateSource | null;
+  overlays: Overlay[];
+  updates: Statewire.CommandUpdate[];
+  pendingChanged: StatewirePath[];
+  canonical: unknown;
+  published: unknown;
+  overlayPaths: readonly StatewirePath[];
+  notifiedPublished: unknown;
+  notifiedOverlayPaths: readonly StatewirePath[];
+  notifiedConnection: StatewireClient.Connection | null;
+  notifiedBusy: boolean;
+  stale: boolean;
+  everAttached: boolean;
+  overlaysDirty: boolean;
+  flushing: boolean;
+  scheduled: boolean;
+  listeners: Set<() => void>;
+  post: () => void;
+  commandsListener: CommandsListener;
+  getState: () => unknown;
+  getBusy: () => boolean;
+  commands: Statewire.CommandsProxy<any>;
+  subscribe: (listener: () => void) => () => void;
+};
 
-  const post = createMacrotaskPoster(() => {
-    scheduled = false;
-    flush();
-  });
-  let scheduled = false;
-  const schedule = () => {
-    if (scheduled) return;
-    scheduled = true;
-    post();
-  };
+const schedule = (c: Core) => {
+  if (c.scheduled) return;
+  c.scheduled = true;
+  c.post();
+};
 
-  const markStale = () => {
-    stale = true;
-    schedule();
-  };
+const markStale = (c: Core) => {
+  c.stale = true;
+  schedule(c);
+};
 
-  // initialState stands in for the canonical state only before the first
-  // attach snapshot; replay boundaries after that read as loading, not preload.
-  const drainCanonical = () => {
-    if (source) {
-      pendingChanged.push(...source.takeChanged());
-      const snapshot = source.snapshot();
-      if (snapshot !== undefined) {
-        everAttached = true;
-        canonical = snapshot;
-        return;
-      }
-      const next = everAttached ? undefined : getOptions().initialState;
-      if (next !== canonical) pendingChanged.push([]);
-      canonical = next;
-    } else if (value) {
-      if (value.state !== undefined) everAttached = true;
-      const next = everAttached ? value.state : getOptions().initialState;
-      if (next !== canonical) {
-        pendingChanged.push([]);
-        canonical = next;
-      }
+// initialState stands in for the canonical state only before the first
+// attach snapshot; replay boundaries after that read as loading, not preload.
+const drainCanonical = (c: Core) => {
+  if (c.source) {
+    c.pendingChanged.push(...c.source.takeChanged());
+    const snapshot = c.source.snapshot();
+    if (snapshot !== undefined) {
+      c.everAttached = true;
+      c.canonical = snapshot;
+      return;
     }
-  };
-
-  const recompute = () => {
-    if (!stale || !value) return;
-    stale = false;
-    const prevCanonical = canonical;
-    drainCanonical();
-    if (canonical === prevCanonical && !overlaysDirty) return;
-    overlaysDirty = false;
-    const { optimistic, materialize } = getOptions();
-    let next = canonical;
-    let paths: readonly StatewirePath[] = [];
-    if (optimistic && canonical !== undefined) {
-      for (const overlay of overlays) {
-        if (overlay.dropped) continue;
-        const { inv } = overlay;
-        const ctx: StatewireClient.OptimisticContext = {
-          ts: inv.ts,
-          seq: inv.seq,
-          ...(inv.clientId !== undefined && { clientId: inv.clientId }),
-        };
-        try {
-          const recorded = recordMutations(next, (draft) =>
-            optimistic(
-              draft as never,
-              { method: inv.method, params: inv.params } as Statewire.Command,
-              ctx,
-            ),
-          );
-          next = recorded.state;
-          paths = [...paths, ...recorded.changedPaths];
-        } catch (error) {
-          overlay.dropped = true;
-          console.error(
-            `statewire: optimistic reducer threw for "${inv.method}"; dropping its optimistic update`,
-            error,
-          );
-        }
-      }
+    const next = c.everAttached ? undefined : c.getOptions().initialState;
+    if (next !== c.canonical) c.pendingChanged.push([]);
+    c.canonical = next;
+  } else if (c.value) {
+    if (c.value.state !== undefined) c.everAttached = true;
+    const next = c.everAttached ? c.value.state : c.getOptions().initialState;
+    if (next !== c.canonical) {
+      c.pendingChanged.push([]);
+      c.canonical = next;
     }
-    if (materialize && next !== undefined) {
+  }
+};
+
+const recompute = (c: Core) => {
+  if (!c.stale || !c.value) return;
+  c.stale = false;
+  const prevCanonical = c.canonical;
+  drainCanonical(c);
+  if (c.canonical === prevCanonical && !c.overlaysDirty) return;
+  c.overlaysDirty = false;
+  const { optimistic, materialize } = c.getOptions();
+  let next = c.canonical;
+  let paths: readonly StatewirePath[] = [];
+  if (optimistic && c.canonical !== undefined) {
+    for (const overlay of c.overlays) {
+      if (overlay.dropped) continue;
+      const { inv } = overlay;
+      const ctx: StatewireClient.OptimisticContext = {
+        ts: inv.ts,
+        seq: inv.seq,
+        ...(inv.clientId !== undefined && { clientId: inv.clientId }),
+      };
       try {
         const recorded = recordMutations(next, (draft) =>
-          materialize(draft as never),
+          optimistic(
+            draft as never,
+            { method: inv.method, params: inv.params } as Statewire.Command,
+            ctx,
+          ),
         );
         next = recorded.state;
         paths = [...paths, ...recorded.changedPaths];
       } catch (error) {
+        overlay.dropped = true;
         console.error(
-          "statewire: materialize threw; publishing without its update",
+          `statewire: optimistic reducer threw for "${inv.method}"; dropping its optimistic update`,
           error,
         );
       }
     }
-    published = next;
-    overlayPaths = paths;
-  };
-
-  const getConnection = (): StatewireClient.Connection =>
-    value?.connection ?? LIVE_CONNECTION;
-
-  const flush = () => {
-    if (!value) return;
-    if (flushing) {
-      schedule();
-      return;
-    }
-    flushing = true;
+  }
+  if (materialize && next !== undefined) {
     try {
-      recompute();
-      const options = getOptions();
-      const stateChanged = published !== notifiedPublished;
-      if (stateChanged) {
-        const prev = notifiedPublished;
-        const changed = [
-          ...pendingChanged,
-          ...notifiedOverlayPaths,
-          ...overlayPaths,
-        ];
-        pendingChanged = [];
-        notifiedPublished = published;
-        notifiedOverlayPaths = overlayPaths;
-        options.onStateChange?.(published as never, {
-          changes: createChanges(prev, published, changed),
-        });
-      }
-      if (updates.length > 0 && published !== undefined) {
-        const batch = updates;
-        updates = [];
-        for (const update of batch) {
-          options.onCommandChange?.(update, { state: published as never });
-        }
-      }
-      if (events.length > 0 && published !== undefined) {
-        const batch = events;
-        events = [];
-        for (const event of batch) {
-          options.onEvent?.(event, { state: published as never });
-        }
-      }
-      const connection = getConnection();
-      const connectionChanged = connection !== notifiedConnection;
-      notifiedConnection = connection;
-      if (connectionChanged) options.onConnectionChange?.(connection);
-      if (stateChanged || connectionChanged) {
-        for (const listener of [...listeners]) listener();
-      }
-    } finally {
-      flushing = false;
-    }
-  };
-
-  const note = (
-    inv: CommandsInvocation,
-    status: Statewire.CommandUpdate["status"],
-    extra?: { result?: unknown; failure?: StatewireClient.SendFailure },
-  ) => {
-    if (!getOptions().onCommandChange) return;
-    updates.push({
-      method: inv.method,
-      params: inv.params as never[],
-      seq: inv.seq,
-      status,
-      ...extra,
-    });
-    schedule();
-  };
-
-  const commandsListener: CommandsListener = {
-    onStart: (inv) => {
-      overlays.push({ inv, dropped: false });
-      overlaysDirty = true;
-      markStale();
-      note(inv, "queued");
-    },
-    onPosted: (inv) => note(inv, "posted"),
-    onAck: (inv) => note(inv, "acked"),
-    onCovered: (inv) => {
-      if (!overlays.some((o) => o.inv === inv)) return;
-      overlays = overlays.filter((o) => o.inv !== inv);
-      overlaysDirty = true;
-      markStale();
-    },
-    onSettle: (inv, outcome) => {
-      note(
-        inv,
-        "settled",
-        outcome.type === "accepted"
-          ? { result: outcome.payload }
-          : { failure: failureOf(outcome.error) },
+      const recorded = recordMutations(next, (draft) =>
+        materialize(draft as never),
+      );
+      next = recorded.state;
+      paths = [...paths, ...recorded.changedPaths];
+    } catch (error) {
+      console.error(
+        "statewire: materialize threw; publishing without its update",
+        error,
       );
-      flush();
-    },
-  };
+    }
+  }
+  c.published = next;
+  c.overlayPaths = paths;
+};
 
-  const eventSink = (event: unknown) => {
-    if (!getOptions().onEvent) return;
-    events.push(event);
-    schedule();
-  };
+const getConnection = (c: Core): StatewireClient.Connection =>
+  c.value?.connection ?? LIVE_CONNECTION;
 
-  const attach = (next: Statewire<unknown>) => {
-    if (next === value) return;
-    const prev = value;
-    value = next;
-    const nextSource =
-      next.source ??
-      (typeof next.state === "object" && next.state !== null
-        ? getStateHost(next.state)
-        : undefined) ??
-      null;
-    if (nextSource !== source) {
-      source?.setOnChange(null);
-      source = nextSource;
-      source?.setOnChange(markStale);
-      // A new source is a new attach lifecycle: initialState preloads again.
-      everAttached = false;
-      markStale();
+const flush = (c: Core) => {
+  if (!c.value) return;
+  if (c.flushing) {
+    schedule(c);
+    return;
+  }
+  c.flushing = true;
+  try {
+    recompute(c);
+    const options = c.getOptions();
+    const stateChanged = c.published !== c.notifiedPublished;
+    if (stateChanged) {
+      const prev = c.notifiedPublished;
+      const changed = [
+        ...c.pendingChanged,
+        ...c.notifiedOverlayPaths,
+        ...c.overlayPaths,
+      ];
+      c.pendingChanged = [];
+      c.notifiedPublished = c.published;
+      c.notifiedOverlayPaths = c.overlayPaths;
+      options.onStateChange?.(c.published as never, {
+        changes: createChanges(prev, c.published, changed),
+      });
     }
-    if (next.commands !== prev?.commands) {
-      if (prev) getCommandsHost(prev.commands)?.setListener(null);
-      getCommandsHost(next.commands)?.setListener(commandsListener);
-      if (overlays.length > 0) {
-        overlays = [];
-        overlaysDirty = true;
+    if (c.updates.length > 0 && c.published !== undefined) {
+      const batch = c.updates;
+      c.updates = [];
+      for (const update of batch) {
+        options.onCommandChange?.(update, { state: c.published as never });
       }
-      markStale();
     }
-    if (next.emit !== prev?.emit) {
-      if (prev) getEmitHost(prev.emit)?.setSink(null);
-      getEmitHost(next.emit)?.setSink(eventSink);
+    const connection = getConnection(c);
+    const connectionChanged = connection !== c.notifiedConnection;
+    c.notifiedConnection = connection;
+    if (connectionChanged) options.onConnectionChange?.(connection);
+    const busy = c.getBusy();
+    const busyChanged = busy !== c.notifiedBusy;
+    c.notifiedBusy = busy;
+    if (stateChanged || connectionChanged || busyChanged) {
+      for (const listener of [...c.listeners]) listener();
     }
-    if (!source) markStale();
-    schedule();
-  };
+  } finally {
+    c.flushing = false;
+  }
+};
 
-  const detach = () => {
-    source?.setOnChange(null);
-    source = null;
-    if (value) {
-      getCommandsHost(value.commands)?.setListener(null);
-      getEmitHost(value.emit)?.setSink(null);
-      value = null;
-    }
-  };
+const note = (
+  c: Core,
+  inv: CommandsInvocation,
+  status: Statewire.CommandUpdate["status"],
+  extra?: { result?: unknown; failure?: StatewireClient.SendFailure },
+) => {
+  if (!c.getOptions().onCommandChange) return;
+  c.updates.push({
+    method: inv.method,
+    params: inv.params as never[],
+    seq: inv.seq,
+    status,
+    ...extra,
+  });
+  schedule(c);
+};
 
-  const commands = createMethodProxy<Statewire.CommandsProxy<any>>(
-    (method, params) => {
-      if (!value) {
-        return Promise.reject(
-          new StatewireSendError({ fate: "aborted", cause: "unmount" }),
-        );
-      }
-      const send = (
-        value.commands as Record<
-          string,
-          (...args: unknown[]) => Promise<unknown>
-        >
-      )[method]!;
-      const promise = send(...params);
-      flush();
-      return promise;
-    },
-  );
+const attach = (c: Core, next: Statewire<unknown>) => {
+  if (next === c.value) return;
+  const prev = c.value;
+  c.value = next;
+  const nextSource =
+    next.source ??
+    (typeof next.state === "object" && next.state !== null
+      ? getStateHost(next.state)
+      : undefined) ??
+    null;
+  if (nextSource !== c.source) {
+    c.source?.setOnChange(null);
+    c.source = nextSource;
+    c.source?.setOnChange(() => markStale(c));
+    // A new source is a new attach lifecycle: initialState preloads again.
+    c.everAttached = false;
+    markStale(c);
+  }
+  if (next.commands !== prev?.commands) {
+    if (prev) getCommandsHost(prev.commands)?.setListener(null);
+    getCommandsHost(next.commands)?.setListener(c.commandsListener);
+    if (c.overlays.length > 0) {
+      c.overlays = [];
+      c.overlaysDirty = true;
+    }
+    markStale(c);
+  }
+  if (!c.source) markStale(c);
+  schedule(c);
+};
 
-  return {
-    attach,
-    detach,
-    getState: () => {
-      recompute();
-      return published;
-    },
-    commands,
-    subscribe: (listener: () => void) => {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    },
-  };
+const detach = (c: Core) => {
+  c.source?.setOnChange(null);
+  c.source = null;
+  if (c.value) {
+    getCommandsHost(c.value.commands)?.setListener(null);
+    c.value = null;
+  }
 };
 
 export const useStatewireCore = (
-  getOptions: () => StatewireClient.Options<any, any, any>,
+  getOptions: () => StatewireClient.Options<any, any>,
   value: Statewire<unknown>,
 ) => {
-  const [core] = useState(() => createCore(getOptions));
+  const [core] = useState((): Core => {
+    const c: Core = {
+      getOptions,
+      value: null,
+      source: null,
+      overlays: [],
+      updates: [],
+      pendingChanged: [],
+      canonical: undefined,
+      published: undefined,
+      overlayPaths: [],
+      notifiedPublished: undefined,
+      notifiedOverlayPaths: [],
+      notifiedConnection: null,
+      notifiedBusy: true,
+      stale: false,
+      everAttached: false,
+      overlaysDirty: false,
+      flushing: false,
+      scheduled: false,
+      listeners: new Set(),
+      post: createMacrotaskPoster(() => {
+        c.scheduled = false;
+        flush(c);
+      }),
+      commandsListener: {
+        onStart: (inv) => {
+          c.overlays.push({ inv, dropped: false });
+          c.overlaysDirty = true;
+          markStale(c);
+          note(c, inv, "queued");
+        },
+        onPosted: (inv) => note(c, inv, "posted"),
+        onApplied: (inv) => note(c, inv, "applied"),
+        onCovered: (inv) => {
+          if (!c.overlays.some((o) => o.inv === inv)) return;
+          c.overlays = c.overlays.filter((o) => o.inv !== inv);
+          c.overlaysDirty = true;
+          markStale(c);
+        },
+        onSettle: (inv, outcome) => {
+          note(
+            c,
+            inv,
+            "settled",
+            outcome.type === "accepted"
+              ? { result: outcome.payload }
+              : { failure: failureOf(outcome.error) },
+          );
+          flush(c);
+        },
+      },
+      getState: () => {
+        recompute(c);
+        return c.published;
+      },
+      getBusy: () => c.value?.isBusy ?? true,
+      commands: createMethodProxy<Statewire.CommandsProxy<any>>(
+        (method, params) => {
+          if (!c.value) {
+            return Promise.reject(
+              new StatewireSendError({ fate: "aborted", cause: "unmount" }),
+            );
+          }
+          const send = (
+            c.value.commands as Record<
+              string,
+              (...args: unknown[]) => Promise<unknown>
+            >
+          )[method]!;
+          const promise = send(...params);
+          flush(c);
+          return promise;
+        },
+      ),
+      subscribe: (listener) => {
+        c.listeners.add(listener);
+        return () => {
+          c.listeners.delete(listener);
+        };
+      },
+    };
+    return c;
+  });
+  core.getOptions = getOptions;
   // Attach during render so the first snapshot reads the transport's state;
   // re-attaching the same transport is a no-op and the single-slot host
   // listeners make a swap land on the last writer.
-  core.attach(value);
+  attach(core, value);
   useEffect(() => {
-    core.attach(value);
+    attach(core, value);
   });
-  useEffect(() => () => core.detach(), [core]);
+  useEffect(() => () => detach(core), [core]);
   return core;
 };