statewire 0.8.0 → 0.9.0

package/src/host-internal.ts

@@ -22,6 +22,10 @@ export namespace StatewireHostInternal {
 
   export type SocketHostOptions = {
     heartbeatIntervalMs?: number;
+    /** LRU cap on stored client records; live or in-flight records are exempt. */
+    clientRecordLimit?: number;
+    /** Hang every attach up with `fin: idle` at the idle flag's rising edge. */
+    finOnIdle?: boolean;
   };
 
   export type Fin = StatewireHost.Fin;

package/src/host.ts

@@ -1,5 +1,4 @@
 import type { Statewire } from "./types";
-import type { ServerOp } from "./host/draft";
 
 export { StatewireReject } from "./host/engine";
 export { append } from "./host/draft";
@@ -7,7 +6,6 @@ export {
   getStateHost,
   useStatewireState,
   useStatewireCommands,
-  useStatewireEmit,
 } from "./host/host";
 
 export namespace StatewireHost {
@@ -20,20 +18,19 @@ export namespace StatewireHost {
 
   export type StateHost = Statewire.StateSource & {
     /** Synchronous, per locally-recorded op; the host owns batching. */
-    setOnOp: (listener: ((op: ServerOp) => void) | null) => void;
+    setOnOp: (listener: ((op: Statewire.Op) => void) | null) => void;
   };
 
-  export type StateSource = Statewire.StateSource;
-
   /**
    * Per-invocation handle bound as `this` of a command handler: `caller` is
-   * the submitting client, `ack()` releases the client's optimistic overlay /
-   * ack watermark before the handler settles (idempotent, a no-op after
-   * settle). The command settles when the handler's returned promise does.
+   * the submitting client, `applied()` states the broadcast state now contains
+   * the command's effects — the client drops its optimistic overlay — before
+   * the handler settles (idempotent, a no-op after settle). The command
+   * settles when the handler's returned promise does.
    */
   export type Ctx = {
     readonly caller: Caller;
-    readonly ack: () => void;
+    readonly applied: () => void;
   };
 
   /**
@@ -56,7 +53,13 @@ export namespace StatewireHost {
   };
 
   export type Fin = {
-    reason: "evicted" | "error" | "gone" | "superseded" | (string & {});
+    reason:
+      | "evicted"
+      | "error"
+      | "gone"
+      | "superseded"
+      | "idle"
+      | (string & {});
     message?: string;
     payload?: unknown;
     meta?: unknown;

package/src/index.ts

@@ -3,4 +3,3 @@ export { StatewireClient, useStatewire, StatewireResource } from "./statewire";
 export { StatewireSSE } from "./transports/sse";
 export { StatewireWS } from "./transports/ws";
 export { StatewireSendError } from "./types";
-export { applyOptimistic } from "./util/recordMutations";

package/src/statewire.ts

@@ -13,9 +13,8 @@ import type { StatewireSessionStoreOptions } from "./client/sessionStore";
 export const useStatewire = <
   TState,
   TCommands extends Statewire.Commands = Statewire.Commands,
-  TEvent = any,
 >(
-  options: StatewireClient.Options<TState, TCommands, TEvent>,
+  options: StatewireClient.Options<TState, TCommands>,
 ): StatewireClient.Helpers<TState, TCommands> => {
   const latest = useRef(options);
   latest.current = options;
@@ -32,6 +31,7 @@ export const useStatewire = <
     core.getState,
     core.getState,
   ) as TState;
+  const isBusy = useSyncExternalStore(subscribe, core.getBusy, core.getBusy);
   const connection = value.connection ?? LIVE_CONNECTION;
 
   return useMemo(
@@ -40,38 +40,37 @@ export const useStatewire = <
       getState: core.getState as () => TState,
       connection,
       commands: core.commands as Statewire.CommandsProxy<TCommands>,
+      isBusy,
       setContext: (contextValue: Record<string, unknown>) => {
         if (!value.setContext) {
           throw new Error(
             "statewire: this transport has no client context channel",
           );
         }
-        return value.setContext(contextValue);
+        value.setContext(contextValue);
       },
     }),
-    [state, connection, core, value],
+    [state, isBusy, connection, core, value],
   );
 };
 
 export const StatewireResource = <
   TState,
   TCommands extends Statewire.Commands = Statewire.Commands,
-  TEvent = any,
 >(
-  options: StatewireClient.Options<TState, TCommands, TEvent>,
+  options: StatewireClient.Options<TState, TCommands>,
 ): ResourceElement<StatewireClient.Helpers<TState, TCommands>> =>
-  resource(useStatewire<TState, TCommands, TEvent>)(options);
+  resource(useStatewire<TState, TCommands>)(options);
 
 export class StatewireClient<
   TState,
   TCommands extends Statewire.Commands = Statewire.Commands,
-  TEvent = any,
 > {
   private readonly root;
   private disposed = false;
 
-  constructor(options: StatewireClient.Options<TState, TCommands, TEvent>) {
-    const ClientRoot = () => useStatewire<TState, TCommands, TEvent>(options);
+  constructor(options: StatewireClient.Options<TState, TCommands>) {
+    const ClientRoot = () => useStatewire<TState, TCommands>(options);
     this.root = createTapRoot(ClientRoot);
   }
 
@@ -87,8 +86,12 @@ export class StatewireClient<
     return this.root.getValue().commands;
   }
 
-  setContext(value: Record<string, unknown>): Promise<unknown> {
-    return this.root.getValue().setContext(value);
+  get isBusy(): boolean {
+    return this.root.getValue().isBusy;
+  }
+
+  setContext(value: Record<string, unknown>): void {
+    this.root.getValue().setContext(value);
   }
 
   subscribe(listener: () => void): () => void {
@@ -106,14 +109,12 @@ export namespace StatewireClient {
   export type Options<
     TState,
     TCommands extends Statewire.Commands = Statewire.Commands,
-    TEvent = any,
   > = {
-    transport: ResourceElement<Statewire<TState, TCommands, TEvent>>;
+    transport: ResourceElement<Statewire<TState, TCommands>>;
     /** Served as the canonical state until the attach snapshot; own commands fold over it. */
     initialState?: TState;
     optimistic?: Optimistic<NonNullable<TState>, TCommands>;
     materialize?: Materialize<NonNullable<TState>>;
-    onEvent?: (event: TEvent, ctx: { state: NonNullable<TState> }) => void;
     onStateChange?: (
       state: NonNullable<TState>,
       ctx: { changes: Statewire.Changes },
@@ -135,13 +136,16 @@ export namespace StatewireClient {
     getState: () => TState;
     connection: Connection;
     commands: Statewire.CommandsProxy<TCommands>;
+    /** Negation of the server's broadcast idle level (a transport without idle is always busy). */
+    isBusy: boolean;
     /** Replace this client's ambient context on the server; throws on transports without a client context channel. */
-    setContext: (value: Record<string, unknown>) => Promise<unknown>;
+    setContext: (value: Record<string, unknown>) => void;
   };
 
   export type ConnectionState =
     | { status: "connecting" }
     | { status: "live" }
+    | { status: "idle" }
     | {
         status: "reconnecting";
         cause: "dropped" | "evicted" | "error" | "unauthorized";
@@ -181,28 +185,26 @@ export namespace StatewireClient {
   export type Materialize<TState> = (draft: TState) => void;
 
   /**
-   * 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.
+   * fate: "aborted" = never sent, "rejected" = the server refused it
+   * (`code` "unknown-command" | "invalid-params" for the static rejects,
+   * code-less for handler rejects), "lost" = sent but never covered by an
+   * applied, "failed" = the handler ran and threw, "crashed" = the handler
+   * died involuntarily, "expired" = concluded but the outcome is
+   * unavailable.
    * 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: "rejected";
+        cause: "server";
+        code?: "unknown-command" | "invalid-params";
+        message?: string;
+        payload?: unknown;
       }
+    | { fate: "failed"; cause: "server"; message?: string }
+    | { fate: "crashed"; cause: "server" }
+    | { fate: "expired"; cause: "server" }
     | {
         fate: "aborted";
         cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
@@ -223,6 +225,8 @@ export namespace StatewireClient {
     headers?: HeadersOption;
     fetch?: typeof globalThis.fetch;
     onChange?: (connection: Connection) => void;
+    /** The broadcast idle flag's rising edge: the instance went quiet. */
+    onDone?: () => void;
   };
 
   export type WSOptions = StatewireSessionStoreOptions & {
@@ -234,5 +238,7 @@ export namespace StatewireClient {
       | (() => Record<string, string> | Promise<Record<string, string>>);
     webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
     onChange?: (connection: Connection) => void;
+    /** The broadcast idle flag's rising edge: the instance went quiet. */
+    onDone?: () => void;
   };
 }

package/src/transports/fake-sse.ts

@@ -14,6 +14,7 @@ export const openSSEStream = (
   clientId: string,
   onOpen: (handle: FakeStreamHandle) => void,
   signal?: AbortSignal,
+  headers?: Record<string, string>,
 ): Response => {
   const encoder = new TextEncoder();
   let handle: FakeStreamHandle;
@@ -46,6 +47,6 @@ export const openSSEStream = (
   });
   return new Response(body, {
     status: 200,
-    headers: { "content-type": "text/event-stream" },
+    headers: { "content-type": "text/event-stream", ...headers },
   });
 };

package/src/transports/fixtures.ts

@@ -1,9 +1,5 @@
 import { resource } from "@assistant-ui/tap";
-import {
-  useStatewireCommands,
-  useStatewireEmit,
-  useStatewireState,
-} from "../host";
+import { useStatewireCommands, useStatewireState } from "../host";
 import { tick } from "./testing";
 
 /** Let several rounds of queued microtasks and op batches drain. */
@@ -15,21 +11,20 @@ export const settle = async () => {
 export const createCounterElement = () =>
   resource(() => {
     const [state] = useStatewireState(() => ({ count: 0 }));
-    const emit = useStatewireEmit();
     const commands = useStatewireCommands({
       increment: () => {
         state.count += 1;
       },
     });
-    return { state, commands, emit };
+    return { state, commands };
   })();
 
-/** Serialize a command frame as a client would send it over a socket. */
+/** Serialize a one-statement cmd-lane frame as a client would send it. */
 export const commandFrame = (
   method: string,
   seq: number,
   params: unknown[] = [],
-) => JSON.stringify({ method, params, seq });
+) => JSON.stringify({ cmd: [{ method, params, seq }] });
 
 export type SocketRecorder = {
   sent: string[];

package/src/transports/remote.ts

@@ -1,5 +1,4 @@
 import { useEffect } from "react";
-import { useStatewireEmit } from "../host/host";
 import type { Statewire } from "../types";
 import {
   setContext,
@@ -14,22 +13,30 @@ export const useStatewireRemote = <
   TOptions extends {
     url: string;
     onChange?: (connection: StatewireClient.Connection) => void;
+    onDone?: () => void;
   } & StatewireSessionOptions,
 >(
   options: TOptions,
   useLink: (options: TOptions, ctx: StatewireRemoteProps) => RemoteLink,
-): Statewire<any, any, any> => {
-  const emit = useStatewireEmit<any>();
-  const s = useStatewireSession({ sessionStore: options.sessionStore }, emit);
+): Statewire<any, any> => {
+  const s = useStatewireSession({
+    sessionStore: options.sessionStore,
+    onDone: options.onDone,
+  });
   const conn = useLink(options, s.ctx);
   useEffect(() => setTransport(s, conn), [s, conn]);
 
   return {
     state: s.canonical,
     commands: s.commands,
-    emit,
     connection: conn.connection,
     source: s.source,
+    get durableSeq() {
+      return s.durableSeq;
+    },
+    get isBusy() {
+      return !s.idle;
+    },
     setContext: (value) => setContext(s, value),
   };
 };