@steve31415/baselib 2.0.0 → 2.2.0

package/dist/sync-browser/client.d.ts

@@ -0,0 +1,187 @@
+import type { Logger as BrowserLogger } from '../log-browser.js';
+import type { ClientEvent, EventBody, SyncEvent } from '../sync/index.js';
+import type { IndexedDbOutbox } from './outbox.js';
+export interface PendingEntry<C extends EventBody, Summary = unknown> {
+    event: ClientEvent<C>;
+    summary: Summary;
+    createdAt: number;
+    /** Durable submission order; assigned by the outbox. */
+    ordinal?: number;
+    /** Runtime-only fields; persistence excludes these fields. */
+    status: 'pending' | 'unconfirmed' | 'rejected';
+    error?: string;
+    recovered?: boolean;
+}
+export type PersistedPendingEntry<C extends EventBody, Summary = unknown> = Pick<PendingEntry<C, Summary>, 'event' | 'summary' | 'createdAt' | 'ordinal'>;
+export interface SyncStoreAdapter<B, C extends EventBody, S extends EventBody> {
+    installBootstrap(data: B): void;
+    currentSeq(): number;
+    setCurrentSeq(seq: number): void;
+    applyOptimistic(event: ClientEvent<C>): void;
+    restorePending(event: ClientEvent<C>): void;
+    applyServerEvent(event: SyncEvent<S>): void;
+    rejectPending(eventGuid: string, error: {
+        code: string;
+        message: string;
+    }): void;
+}
+export interface CatchupResult<S extends EventBody> {
+    reload?: boolean;
+    events: SyncEvent<S>[];
+    buildId?: string;
+}
+export interface SyncBrowserRuntime {
+    now(): number;
+    randomGuid(): string;
+    createSocket(url: string): WebSocket;
+    sendBeacon(url: string, body: Blob): boolean;
+    visibility(): DocumentVisibilityState;
+    onVisibilityChange(listener: () => void): () => void;
+    onOnline(listener: () => void): () => void;
+    onPageHide(listener: () => void): () => void;
+    setTimeout: typeof globalThis.setTimeout;
+    clearTimeout: typeof globalThis.clearTimeout;
+    setInterval: typeof globalThis.setInterval;
+    clearInterval: typeof globalThis.clearInterval;
+}
+export type SyncClientState = {
+    kind: 'starting';
+    pending: number;
+} | {
+    kind: 'connecting';
+    pending: number;
+} | {
+    kind: 'connected';
+    pending: 0;
+} | {
+    kind: 'syncing';
+    pending: number;
+} | {
+    kind: 'reconnecting';
+    pending: number;
+    inSeconds: number;
+} | {
+    kind: 'disconnected';
+    pending: number;
+} | {
+    kind: 'error';
+    pending: number;
+    message: string;
+} | {
+    kind: 'expired';
+    pending: number;
+};
+export interface SyncClientOptions<B, C extends EventBody, S extends EventBody, Summary = unknown> {
+    clientGuid: string;
+    outbox: Pick<IndexedDbOutbox<PersistedPendingEntry<C, Summary>>, 'init' | 'add' | 'remove'>;
+    store: SyncStoreAdapter<B, C, S>;
+    fetchBootstrap(signal: AbortSignal): Promise<B>;
+    fetchCatchup(afterSeq: number, signal: AbortSignal): Promise<CatchupResult<S>>;
+    beaconUrl: string;
+    socketUrl(): string;
+    runtime: SyncBrowserRuntime;
+    authState: {
+        isBlocked(): boolean;
+        markBlocked(): void;
+        onBlocked(listener: () => void): () => void;
+    };
+    logger: Pick<BrowserLogger, 'info' | 'warn' | 'error'>;
+    onState(state: SyncClientState): void;
+    onEventFailed(entry: PendingEntry<C, Summary>, error: string, rejected: boolean): void;
+    onEventRecovered?(eventGuid: string): void;
+    onSafetyChange?(): void;
+    onReloadRequired(reason: 'server' | 'sequence-gap'): void;
+    onBuildObserved?(buildId: string): void;
+    onBuildChanged?(): void;
+    markPerformance?(name: 'outbox-start' | 'outbox-ready' | 'bootstrap-start' | 'bootstrap-response' | 'store-ready'): void;
+    reconnectBeforeMs?: number;
+}
+export declare class SyncClient<B, C extends EventBody, S extends EventBody, Summary = unknown> {
+    private readonly options;
+    private socket;
+    private readonly pending;
+    private readonly unresolvedFailures;
+    private readonly rejected;
+    private readonly confirmedPending;
+    private readonly pendingRejections;
+    private readonly settlementInFlight;
+    private readonly settledPending;
+    private readonly failureTimers;
+    private readonly subscribers;
+    private readonly abortControllers;
+    private readonly removeListeners;
+    private currentState;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private countdownTimer;
+    private pingTimer;
+    private watchdogTimer;
+    private rolloverTimer;
+    private escalateTimer;
+    private escalateArmedAt;
+    private outageStartedAt;
+    private outageEscalated;
+    private halted;
+    private refetchInFlight;
+    private probeInFlight;
+    private resyncTimes;
+    private reconciliationTail;
+    private initialization;
+    private disposed;
+    constructor(options: SyncClientOptions<B, C, S, Summary>);
+    init(): Promise<void>;
+    private initialize;
+    dispose(): void;
+    submit(event: ClientEvent<C>, summary: Summary): Promise<void>;
+    /** Current-tab entries only; recovered work is retried silently. */
+    pendingEntries(): PendingEntry<C, Summary>[];
+    failedEntries(): Array<{
+        eventGuid: string;
+        entry: PendingEntry<C, Summary>;
+        error: string;
+    }>;
+    hasPendingWork(): boolean;
+    hasUnsafeWork(): boolean;
+    hasUnresolvedFailures(): boolean;
+    dismissFailure(eventGuid: string): void;
+    refreshConnectionForBuild(): void;
+    state(): SyncClientState;
+    subscribe(listener: (state: SyncClientState) => void): () => void;
+    private installRuntimeListeners;
+    private wakeConnection;
+    private connect;
+    private connectNow;
+    private scheduleReconnect;
+    private probeSession;
+    private startOutage;
+    private handleMessage;
+    private handleSocketCatchup;
+    /** Returns false when a forward gap prevented application. */
+    private handleServerEvent;
+    private handleRejection;
+    private confirmPending;
+    private clearFailureTimer;
+    private retrySettlement;
+    private finishConfirmation;
+    private finishRejection;
+    private reconcileStore;
+    private failUnconfirmed;
+    private onSyncEstablished;
+    private requestReload;
+    private resyncFromServer;
+    private sendConnect;
+    private sendRaw;
+    private trySend;
+    private flushViaBeacon;
+    private updateConnectedState;
+    private updatePendingState;
+    private publish;
+    private pendingCount;
+    private stopBeforeStoreMutation;
+    private halt;
+    private clearConnectionTimers;
+    private clearAllTimers;
+    private detachSocket;
+    private abortable;
+    private abortFetches;
+}