statewire 0.0.0-0 → 0.0.1

package/src/client/core.ts

@@ -0,0 +1,346 @@
+import { createChanges } from "./changes";
+import { getCommandsHost, getEmitHost, getStateHost } from "../host/host";
+import type { CommandsInvocation, CommandsListener } from "../host/host";
+import { recordMutations } from "./optimistic";
+import type { StatewirePath } from "../wire/ops";
+import { StatewireSendError } from "../types";
+import type {
+  SendFailure as StatewireSendFailure,
+  StatewireStateSource,
+  StatewireTransport,
+  StatewireCommand,
+  StatewireCommandsProxy,
+  StatewireCommandUpdate,
+  StatewireOptimisticContext,
+  StatewireOptions,
+} from "../types";
+import type { StatewireConnection } from "../transports/sse";
+
+export const LIVE_CONNECTION: StatewireConnection = {
+  status: "live",
+  reconnect: () => {},
+};
+
+const failureOf = (error: unknown): StatewireSendFailure =>
+  error instanceof StatewireSendError
+    ? error.failure
+    : {
+        fate: "rejected",
+        cause: "server",
+        message: error instanceof Error ? error.message : String(error),
+      };
+
+// MessageChannel schedules the flush as a macrotask (tap's pattern): it runs
+// after the whole microtask drain, so every producer in the current turn
+// coalesces. The port is ref'd only while a flush is pending — an active
+// MessagePort holds the Node event loop open. ref/unref are Node-only.
+const createMacrotaskPoster = (callback: () => void): (() => void) => {
+  if (typeof MessageChannel !== "undefined") {
+    let port1: (MessagePort & { ref?: () => void; unref?: () => void }) | null =
+      null;
+    let port2: MessagePort;
+    return () => {
+      if (!port1) {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => {
+          port1?.unref?.();
+          callback();
+        };
+        port1 = channel.port1;
+        port2 = channel.port2;
+      }
+      port1.ref?.();
+      port2!.postMessage(null);
+    };
+  }
+  return () => setTimeout(callback, 0);
+};
+
+type Overlay = { inv: CommandsInvocation; dropped: boolean };
+
+export type StatewireCore = ReturnType<typeof createStatewireCore>;
+
+export const createStatewireCore = (
+  getOptions: () => StatewireOptions<any, any, any>,
+) => {
+  let value: StatewireTransport<unknown> | null = null;
+  let source: StatewireStateSource | null = null;
+  let overlays: Overlay[] = [];
+  let updates: StatewireCommandUpdate[] = [];
+  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: StatewireConnection | null = null;
+  let stale = false;
+  let overlaysDirty = false;
+  let flushing = false;
+  let disposed = false;
+  const listeners = new Set<() => void>();
+
+  const post = createMacrotaskPoster(() => {
+    scheduled = false;
+    flush();
+  });
+  let scheduled = false;
+  const schedule = () => {
+    if (scheduled || disposed) return;
+    scheduled = true;
+    post();
+  };
+
+  const markStale = () => {
+    stale = true;
+    schedule();
+  };
+
+  const drainCanonical = () => {
+    if (source) {
+      pendingChanged.push(...source.takeChanged());
+      canonical = source.root();
+    } else if (value && value.state !== canonical) {
+      pendingChanged.push([]);
+      canonical = value.state;
+    }
+  };
+
+  const recompute = () => {
+    if (!stale || !value) return;
+    stale = false;
+    const prevCanonical = canonical;
+    drainCanonical();
+    if (canonical === prevCanonical && !overlaysDirty) return;
+    overlaysDirty = false;
+    const { optimistic } = 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: StatewireOptimisticContext = {
+          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 StatewireCommand,
+              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,
+          );
+        }
+      }
+    }
+    published = next;
+    overlayPaths = paths;
+  };
+
+  const getConnection = (): StatewireConnection =>
+    value?.connection ?? LIVE_CONNECTION;
+
+  const flush = () => {
+    if (disposed || !value) return;
+    if (flushing) {
+      schedule();
+      return;
+    }
+    flushing = true;
+    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) {
+        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 (stateChanged || connectionChanged) {
+        for (const listener of [...listeners]) listener();
+      }
+    } finally {
+      flushing = false;
+    }
+  };
+
+  const note = (
+    inv: CommandsInvocation,
+    status: StatewireCommandUpdate["status"],
+    extra?: { result?: unknown; failure?: StatewireSendFailure },
+  ) => {
+    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) },
+      );
+      flush();
+    },
+  };
+
+  const eventSink = (event: unknown) => {
+    if (!getOptions().onEvent) return;
+    events.push(event);
+    schedule();
+  };
+
+  const attach = (next: StatewireTransport<unknown>) => {
+    if (disposed || 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);
+      markStale();
+    }
+    if (next.commands !== prev?.commands) {
+      if (prev) getCommandsHost(prev.commands)?.setListener(null);
+      getCommandsHost(next.commands)?.setListener(commandsListener);
+      if (overlays.length > 0) {
+        overlays = [];
+        overlaysDirty = true;
+      }
+      markStale();
+    }
+    if (next.emit !== prev?.emit) {
+      if (prev) getEmitHost(prev.emit)?.setSink(null);
+      getEmitHost(next.emit)?.setSink(eventSink);
+    }
+    if (!source) markStale();
+    schedule();
+  };
+
+  const detach = () => {
+    source?.setOnChange(null);
+    source = null;
+    if (value) {
+      getCommandsHost(value.commands)?.setListener(null);
+      getEmitHost(value.emit)?.setSink(null);
+      value = null;
+    }
+  };
+
+  const memo = new Map<string, (...params: unknown[]) => Promise<unknown>>();
+  const commands = new Proxy({} as StatewireCommandsProxy<any>, {
+    get: (_target, method) => {
+      if (typeof method !== "string") return undefined;
+      let fn = memo.get(method);
+      if (fn === undefined) {
+        fn = (...params: unknown[]) => {
+          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;
+        };
+        memo.set(method, fn);
+      }
+      return fn;
+    },
+  });
+
+  return {
+    attach,
+    detach,
+    dispose: () => {
+      detach();
+      disposed = true;
+    },
+    getState: () => {
+      recompute();
+      return published;
+    },
+    getConnection,
+    commands,
+    flush,
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+};