Connection Sync Guard

Utility that wraps a collaboration container so work only runs when connectivity is established and recent operations are synchronized.

Capabilities

Synchronize before running work

• When the container is connected, the guard waits for synchronization via the provided catch-up helper before running a submitted operation and returns that operation's result. @test
• If the catch-up helper indicates failure, runWhenSynchronized rejects without invoking the operation. @test

Queue while disconnected

• Operations submitted while disconnected are queued; after the next connection and successful synchronization they run in the original order. @test

State reporting and cleanup

• state reflects whether the container is currently connected, lastSyncSuccessful updates after each catch-up attempt, and calling dispose stops listening to container events and rejects new work. @test

Implementation

@generates

API

export type ConnectionStatus = "connected" | "disconnected";

export interface SyncableContainer {
  connected: boolean;
  on(event: "connected" | "disconnected" | "closed", listener: () => void): void;
  off?(event: "connected" | "disconnected" | "closed", listener: () => void): void;
}

export type CatchUp = () => Promise<boolean>;

export class ConnectionSyncGuard {
  constructor(container: SyncableContainer, waitForCatchUp: CatchUp, options?: {
    reconnectTimeoutMs?: number;
  });

  /** Current connection status derived from the container */
  readonly state: ConnectionStatus;

  /** Last outcome from a synchronization attempt, undefined before any attempt */
  readonly lastSyncSuccessful: boolean | undefined;

  /** Enqueue work to run after the container is connected and synchronized */
  runWhenSynchronized<T>(work: () => Promise<T>): Promise<T>;

  /** Stop listening to container events and reject new work */
  dispose(): void;
}

Dependencies { .dependencies }

@fluidframework/container-loader { .dependency }

Provides the collaboration container primitives, connection events, and synchronization helper needed by the guard.