statewire 0.12.2 → 0.13.0

package/src/statewire.ts

@@ -59,10 +59,21 @@ export const useStatewire = <
     core.getState,
   ) as TState;
   const isBusy = useSyncExternalStore(subscribe, core.getBusy, core.getBusy);
+  const failed = useSyncExternalStore(
+    subscribe,
+    core.getFailed,
+    core.getFailed,
+  );
   const connection = value.connection ?? LIVE_CONNECTION;
 
-  return useMemo(
-    () => ({
+  return useMemo(() => {
+    const failures = (): NonNullable<typeof value.failures> => {
+      if (!value.failures) {
+        throw new Error("statewire: this transport has no failed-send lane");
+      }
+      return value.failures;
+    };
+    return {
       state,
       getState: core.getState as () => TState,
       connection,
@@ -76,9 +87,13 @@ export const useStatewire = <
         }
         value.setContext(contextValue);
       },
-    }),
-    [state, isBusy, connection, core, value],
-  );
+      failed,
+      retryFailed: (entry: StatewireClient.FailedCommand) =>
+        failures().retry(entry),
+      discardFailed: (entry: StatewireClient.FailedCommand) =>
+        failures().discard(entry),
+    };
+  }, [state, isBusy, failed, connection, core, value]);
 };
 
 export const StatewireResource = <
@@ -121,6 +136,18 @@ export class StatewireClient<
     this.root.getValue().setContext(value);
   }
 
+  get failed(): readonly StatewireClient.FailedCommand[] {
+    return this.root.getValue().failed;
+  }
+
+  retryFailed(entry: StatewireClient.FailedCommand): Promise<unknown> {
+    return this.root.getValue().retryFailed(entry);
+  }
+
+  discardFailed(entry: StatewireClient.FailedCommand): void {
+    this.root.getValue().discardFailed(entry);
+  }
+
   subscribe(listener: () => void): () => void {
     return this.root.subscribe(listener);
   }
@@ -155,6 +182,11 @@ export namespace StatewireClient {
       ctx: { state: NonNullable<TState> },
     ) => void;
     onConnectionChange?: (connection: Connection) => void;
+    /** Drops a retained failed entry once a canonical snapshot shows its effect landed; checked against each new snapshot. */
+    failureCovered?: (
+      state: NonNullable<TState>,
+      entry: FailedCommand,
+    ) => boolean;
   };
 
   export type Helpers<
@@ -171,6 +203,12 @@ export namespace StatewireClient {
     isBusy: boolean;
     /** Replace this client's ambient context on the server; throws on transports without a client context channel. */
     setContext: (value: Record<string, unknown>) => void;
+    /** Non-accepted sends retained in the session record; reload with it. */
+    failed: readonly FailedCommand[];
+    /** Re-enqueues the entry's command on fresh clocks and removes the entry. */
+    retryFailed: (entry: FailedCommand) => Promise<unknown>;
+    /** Removes the entry. */
+    discardFailed: (entry: FailedCommand) => void;
   };
 
   export type ConnectionState =
@@ -259,6 +297,16 @@ export namespace StatewireClient {
     }>,
   ) => "requeue" | "drop";
 
+  /** A non-accepted send retained for the user: the wire statement, its failure, and its original clocks. */
+  export type FailedCommand = {
+    readonly command: string;
+    readonly params: readonly unknown[];
+    readonly meta?: unknown;
+    readonly failure: SendFailure;
+    readonly ts: number;
+    readonly seq: number;
+  };
+
   /** A command as persisted while un-durable: its lane seq plus the wire statement. */
   export type SessionCommand = {
     seq: number;
@@ -275,6 +323,8 @@ export namespace StatewireClient {
     commands: readonly SessionCommand[];
     /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
     verdicts?: readonly SessionVerdict[];
+    /** Non-accepted sends retained for the user; survive record rebases and resets. */
+    failed?: readonly FailedCommand[];
   };
 
   /** A terminal verdict one sharer's connection carried, parked for the sharer awaiting the seq. */

package/src/transports/remote.ts

@@ -1,6 +1,9 @@
 import { useEffect } from "react";
 import type { Statewire } from "../types";
 import {
+  discardFailed,
+  failedCommands,
+  retryFailed,
   setContext,
   setTransport,
   useStatewireSession,
@@ -39,5 +42,10 @@ export const useStatewireRemote = <
       return !s.idle;
     },
     setContext: (value) => setContext(s, value),
+    failures: {
+      list: () => failedCommands(s),
+      retry: (entry) => retryFailed(s, entry),
+      discard: (entry) => discardFailed(s, entry),
+    },
   };
 };

package/src/types.ts

@@ -59,6 +59,12 @@ export interface Statewire<
   isBusy?: boolean;
   /** Replace this client's ambient context on the server; it rides the ctx lane (no verdict). */
   setContext?: (value: Record<string, unknown>) => void;
+  /** The retained failed-send lane; present on transports with a durable session. */
+  failures?: {
+    list: () => readonly StatewireClient.FailedCommand[];
+    retry: (entry: StatewireClient.FailedCommand) => Promise<unknown>;
+    discard: (entry: StatewireClient.FailedCommand) => void;
+  };
 }
 
 const describe = (failure: StatewireClient.SendFailure): string => {