statewire 0.0.1 → 0.0.2

package/src/statewire.ts

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from "react";
+import { useMemo, useRef, useState, useSyncExternalStore } from "react";
 import {
   createTapRoot,
   flushTapSync,
@@ -6,102 +6,195 @@ import {
   useResource,
 } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
-import { createStatewireCore, LIVE_CONNECTION } from "./client/core";
-import type { StatewireTransport } from "./types";
-import type {
-  StatewireCommands,
-  StatewireCommandsProxy,
-  StatewireHelpers,
-  StatewireOptions,
-} from "./types";
-import type { StatewireConnection } from "./transports/sse";
+import { LIVE_CONNECTION, useStatewireCore } from "./client/core";
+import type { Statewire } from "./types";
+import type { ConnectionState } from "./transports/sse";
+import type { StatewireSessionStoreOptions } from "./client/sessionStore";
 
 export const useStatewire = <
   TState,
-  TCommands extends StatewireCommands = StatewireCommands,
+  TCommands extends Statewire.Commands = Statewire.Commands,
   TEvent = any,
 >(
-  options: StatewireOptions<TState, TCommands, TEvent>,
-): StatewireHelpers<TState, TCommands> => {
+  options: StatewireClient.Options<TState, TCommands, TEvent>,
+): StatewireClient.Helpers<TState, TCommands> => {
   const latest = useRef(options);
   latest.current = options;
-  const [, setVersion] = useState(0);
-  const [core] = useState(() => createStatewireCore(() => latest.current));
-
-  const value = useResource(options.transport) as StatewireTransport<unknown>;
-  core.attach(value);
-
-  useEffect(() => {
-    core.attach(value);
-  });
-  useEffect(() => {
-    const unsubscribe = core.subscribe(() =>
-      flushTapSync(() => setVersion((v) => v + 1)),
-    );
-    return () => {
-      unsubscribe();
-      core.detach();
-    };
-  }, [core]);
-
-  return {
-    state: core.getState() as TState,
-    connection: value.connection ?? LIVE_CONNECTION,
-    commands: core.commands as StatewireCommandsProxy<TCommands>,
-  };
+
+  const value = useResource(options.transport) as Statewire<unknown>;
+  const core = useStatewireCore(() => latest.current, value);
+  const [subscribe] = useState(
+    () => (listener: () => void) =>
+      core.subscribe(() => flushTapSync(listener)),
+  );
+
+  const state = useSyncExternalStore(
+    subscribe,
+    core.getState,
+    core.getState,
+  ) as TState;
+  const connection = value.connection ?? LIVE_CONNECTION;
+
+  return useMemo(
+    () => ({
+      state,
+      getState: core.getState as () => TState,
+      connection,
+      commands: core.commands as Statewire.CommandsProxy<TCommands>,
+    }),
+    [state, connection, core],
+  );
 };
 
 export const StatewireResource = <
   TState,
-  TCommands extends StatewireCommands = StatewireCommands,
+  TCommands extends Statewire.Commands = Statewire.Commands,
   TEvent = any,
 >(
-  options: StatewireOptions<TState, TCommands, TEvent>,
-): ResourceElement<StatewireHelpers<TState, TCommands>> =>
+  options: StatewireClient.Options<TState, TCommands, TEvent>,
+): ResourceElement<StatewireClient.Helpers<TState, TCommands>> =>
   resource(useStatewire<TState, TCommands, TEvent>)(options);
 
-export class Statewire<
+export class StatewireClient<
   TState,
-  TCommands extends StatewireCommands = StatewireCommands,
+  TCommands extends Statewire.Commands = Statewire.Commands,
   TEvent = any,
 > {
-  private readonly core;
   private readonly root;
   private disposed = false;
 
-  constructor(options: StatewireOptions<TState, TCommands, TEvent>) {
-    this.core = createStatewireCore(() => options);
-    const core = this.core;
-    this.root = createTapRoot(() => {
-      const value = useResource(
-        options.transport,
-      ) as StatewireTransport<unknown>;
-      core.attach(value);
-      return value;
-    });
-    flushTapSync(() => {});
+  constructor(options: StatewireClient.Options<TState, TCommands, TEvent>) {
+    const ClientRoot = () => useStatewire<TState, TCommands, TEvent>(options);
+    this.root = createTapRoot(ClientRoot);
   }
 
   get state(): TState {
-    return this.core.getState() as TState;
+    return this.root.getValue().getState();
   }
 
-  get connection(): StatewireConnection {
-    return this.root.getValue().connection ?? LIVE_CONNECTION;
+  get connection(): StatewireClient.Connection {
+    return this.root.getValue().connection;
   }
 
-  get commands(): StatewireCommandsProxy<TCommands> {
-    return this.core.commands as StatewireCommandsProxy<TCommands>;
+  get commands(): Statewire.CommandsProxy<TCommands> {
+    return this.root.getValue().commands;
   }
 
   subscribe(listener: () => void): () => void {
-    return this.core.subscribe(listener);
+    return this.root.subscribe(listener);
   }
 
   dispose(): void {
     if (this.disposed) return;
     this.disposed = true;
     this.root.unmount();
-    this.core.dispose();
   }
 }
+
+export namespace StatewireClient {
+  export type Options<
+    TState,
+    TCommands extends Statewire.Commands = Statewire.Commands,
+    TEvent = any,
+  > = {
+    transport: ResourceElement<Statewire<TState, TCommands, TEvent>>;
+    optimistic?: Optimistic<NonNullable<TState>, TCommands>;
+    onEvent?: (event: TEvent, ctx: { state: NonNullable<TState> }) => void;
+    onStateChange?: (
+      state: NonNullable<TState>,
+      ctx: { changes: Statewire.Changes },
+    ) => void;
+    onCommandChange?: (
+      update: Statewire.CommandUpdate<TCommands>,
+      ctx: { state: NonNullable<TState> },
+    ) => void;
+  };
+
+  export type Helpers<
+    TState,
+    TCommands extends Statewire.Commands = Statewire.Commands,
+  > = {
+    /** The statewire's state type — remote statewires include `undefined` until the first attach snapshot applies. */
+    state: TState;
+    /** Identity-stable across renders; reads the current canonical state without subscribing the caller. */
+    getState: () => TState;
+    connection: Connection;
+    commands: Statewire.CommandsProxy<TCommands>;
+  };
+
+  export type Connection = ConnectionState & { reconnect: () => void };
+  export type ConnectionStatus = Connection["status"];
+
+  /**
+   * Mutate the draft in place; the client records the next state plus the exact
+   * changed paths. Re-run against the new base on every rebase.
+   */
+  export type Optimistic<
+    TState,
+    TCommands extends Statewire.Commands = Statewire.Commands,
+  > = (
+    draft: TState,
+    command: Statewire.Command<TCommands>,
+    ctx: OptimisticContext,
+  ) => void;
+
+  export type OptimisticContext = {
+    ts: number;
+    seq: number;
+    clientId?: string;
+  };
+
+  /**
+   * fate: "aborted" = never sent, "rejected" = the handler refused,
+   * "unknown-command" = no such command, "invalid-params" = the args did not
+   * match the command's schema, "lost" = sent but never covered by an ack,
+   * "crashed" = acked but the processing died, "result-unavailable" = acked
+   * but the result is gone.
+   * cause is which channel settled it: "server" = the server's answer;
+   * the rest are channel deaths the client settled locally.
+   */
+  export type SendFailure =
+    | { fate: "rejected"; cause: "server"; message: string; payload?: unknown }
+    | { fate: "unknown-command"; cause: "server" }
+    | { fate: "invalid-params"; cause: "server"; message: string }
+    | { fate: "crashed"; cause: "server" }
+    | {
+        fate: "result-unavailable";
+        cause:
+          | "server"
+          | "unmount"
+          | "stream-gone"
+          | "session-lost"
+          | "superseded";
+      }
+    | {
+        fate: "aborted";
+        cause:
+          | "cascade"
+          | "unmount"
+          | "stream-gone"
+          | "session-lost"
+          | "superseded";
+      }
+    | {
+        fate: "lost";
+        cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
+      };
+
+  export type SSEOptions = StatewireSessionStoreOptions & {
+    url: string;
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    fetch?: typeof globalThis.fetch;
+    onChange?: (connection: Connection) => void;
+  };
+
+  export type WSOptions = StatewireSessionStoreOptions & {
+    url: string;
+    protocols?: string | string[];
+    query?:
+      | Record<string, string>
+      | (() => Record<string, string> | Promise<Record<string, string>>);
+    webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
+    onChange?: (connection: Connection) => void;
+  };
+}

package/src/transports/fake-sse.ts

@@ -0,0 +1,51 @@
+import type { StatewireEnvelope } from "../client/connection";
+
+export type FakeStreamHandle = {
+  clientId: string;
+  send: (text: string) => void;
+  close: () => void;
+};
+
+export const sseFrame = (envelope: StatewireEnvelope) =>
+  `data: ${JSON.stringify(envelope)}\n\n`;
+
+export const openSSEStream = (
+  streams: Set<FakeStreamHandle>,
+  clientId: string,
+  onOpen: (handle: FakeStreamHandle) => void,
+  signal?: AbortSignal,
+): Response => {
+  const encoder = new TextEncoder();
+  let handle: FakeStreamHandle;
+  const body = new ReadableStream<Uint8Array>({
+    start: (controller) => {
+      let open = true;
+      handle = {
+        clientId,
+        send: (text) => {
+          if (open) controller.enqueue(encoder.encode(text));
+        },
+        close: () => {
+          if (!open) return;
+          open = false;
+          streams.delete(handle);
+          controller.close();
+        },
+      };
+      streams.add(handle);
+      onOpen(handle);
+    },
+    cancel: () => {
+      streams.delete(handle);
+    },
+  });
+  signal?.addEventListener("abort", () => {
+    for (const stream of [...streams]) {
+      if (stream.clientId === clientId) stream.close();
+    }
+  });
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": "text/event-stream" },
+  });
+};

package/src/transports/fixtures.ts

@@ -0,0 +1,60 @@
+import { resource } from "@assistant-ui/tap";
+import {
+  useStatewireCommands,
+  useStatewireEmit,
+  useStatewireState,
+} from "../host";
+import { tick } from "./testing";
+
+/** Let several rounds of queued microtasks and op batches drain. */
+export const settle = async () => {
+  for (let i = 0; i < 3; i++) await tick();
+};
+
+/** A minimal statewire host element: `{ count }` state with an `increment` command. */
+export const createCounterElement = () =>
+  resource(() => {
+    const [state] = useStatewireState(() => ({ count: 0 }));
+    const emit = useStatewireEmit();
+    const commands = useStatewireCommands({
+      increment: () => {
+        state.count += 1;
+      },
+    });
+    return { state, commands, emit };
+  })();
+
+/** Serialize a command frame as a client would send it over a socket. */
+export const commandFrame = (
+  method: string,
+  seq: number,
+  params: unknown[] = [],
+) => JSON.stringify({ method, params, seq });
+
+export type SocketRecorder = {
+  sent: string[];
+  closes: { code?: number; reason?: string }[];
+  last: () => any;
+  send: (data: string) => void;
+  close: (code?: number, reason?: string) => void;
+};
+
+/** Record sent frames and close calls; `last()` parses the latest frame. */
+export const createSocketRecorder = (): SocketRecorder => {
+  const sent: string[] = [];
+  const closes: { code?: number; reason?: string }[] = [];
+  return {
+    sent,
+    closes,
+    last: () => JSON.parse(sent.at(-1)!),
+    send: (data) => {
+      sent.push(data);
+    },
+    close: (code, reason) => {
+      closes.push({
+        ...(code !== undefined && { code }),
+        ...(reason !== undefined && { reason }),
+      });
+    },
+  };
+};

package/src/transports/remote.ts

@@ -1,65 +1,23 @@
-import { useEffect, useState } from "react";
-import { useStatewireConn } from "../client/connection";
-import type { ConnBase } from "../client/connection";
+import { useEffect } from "react";
 import { useStatewireEmit } from "../host/host";
-import type { StatewireTransport } from "../types";
-import {
-  createSession,
-  handleFinish,
-  handleOps,
-  handleSnapshot,
-  setTransport,
-  start,
-  stop,
-} from "../client/session";
-import type { SessionOptions } from "../client/session";
-import type {
-  RemoteLink,
-  StatewireConnection,
-  StatewireTransportProps,
-} from "./sse";
+import type { Statewire } from "../types";
+import { setTransport, useStatewireSession } from "../client/session";
+import type { StatewireSessionStoreOptions } from "../client/sessionStore";
+import type { StatewireClient } from "../statewire";
+import type { RemoteLink, StatewireRemoteProps } from "./sse";
 
 export const useStatewireRemote = <
   TOptions extends {
     url: string;
-    onChange?: (connection: StatewireConnection) => void;
-  } & SessionOptions,
+    onChange?: (connection: StatewireClient.Connection) => void;
+  } & StatewireSessionStoreOptions,
 >(
   options: TOptions,
-  create: (
-    latest: {
-      readonly current: { options: TOptions; ctx: StatewireTransportProps };
-    },
-    notify: (connection: StatewireConnection) => void,
-  ) => ConnBase & { send: RemoteLink["send"] },
-): StatewireTransport<any, any, any> => {
+  useLink: (options: TOptions, ctx: StatewireRemoteProps) => RemoteLink,
+): Statewire<any, any, any> => {
   const emit = useStatewireEmit<any>();
-  const [s] = useState(() =>
-    createSession({ sessionStore: options.sessionStore }),
-  );
-
-  useEffect(() => {
-    s.emitEvent = emit;
-    return () => {
-      s.emitEvent = () => {};
-    };
-  }, [s, emit]);
-  useEffect(() => {
-    start(s);
-    return () => stop(s);
-  }, [s]);
-
-  const [ctx] = useState(
-    (): StatewireTransportProps => ({
-      get clientId() {
-        return s.record.clientId;
-      },
-      onSnapshot: (args) => handleSnapshot(s, args),
-      onOps: (args) => handleOps(s, args),
-      onFinish: (args) => handleFinish(s, args),
-    }),
-  );
-  const conn = useStatewireConn(options, ctx, create);
+  const s = useStatewireSession({ sessionStore: options.sessionStore }, emit);
+  const conn = useLink(options, s.ctx);
   useEffect(() => setTransport(s, conn), [s, conn]);
 
   return {