@syncular/client 0.0.1-60

package/dist/engine/SyncEngine.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @syncular/client - Core sync engine
+ *
+ * Event-driven sync engine that manages push/pull cycles, connection state,
+ * and provides a clean API for framework bindings to consume.
+ */
+import type { SyncSubscriptionRequest } from '@syncular/core';
+import { type Kysely } from 'kysely';
+import type { SyncClientDb } from '../schema';
+import type { ConflictInfo, OutboxStats, PresenceEntry, SyncEngineConfig, SyncEngineState, SyncEventListener, SyncEventType, SyncResult } from './types';
+export declare class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
+    private config;
+    private state;
+    private listeners;
+    private pollerId;
+    private fallbackPollerId;
+    private realtimeDisconnect;
+    private realtimePresenceUnsub;
+    private isDestroyed;
+    private migrated;
+    private syncPromise;
+    private syncRequestedWhileRunning;
+    private retryTimeoutId;
+    private realtimeCatchupTimeoutId;
+    private hasRealtimeConnectedOnce;
+    /**
+     * In-memory map tracking local mutation timestamps by rowId.
+     * Used for efficient fingerprint-based rerender optimization.
+     * Key format: `${table}:${rowId}`, Value: timestamp (Date.now())
+     */
+    private mutationTimestamps;
+    /**
+     * In-memory map tracking table-level mutation timestamps.
+     * Used for coarse invalidation during large bootstrap snapshots to avoid
+     * storing timestamps for every row.
+     */
+    private tableMutationTimestamps;
+    /**
+     * In-memory presence state by scope key.
+     * Updated via realtime presence events.
+     */
+    private presenceByScopeKey;
+    constructor(config: SyncEngineConfig<DB>);
+    /**
+     * Get mutation timestamp for a row (used by query hooks for fingerprinting).
+     * Returns 0 if row has no recorded mutation timestamp.
+     */
+    getMutationTimestamp(table: string, rowId: string): number;
+    /**
+     * Get presence entries for a scope key.
+     * Returns empty array if no presence data for the scope.
+     */
+    getPresence<TMetadata = Record<string, unknown>>(scopeKey: string): PresenceEntry<TMetadata>[];
+    /**
+     * Update presence for a scope key (called by realtime transport).
+     * Emits presence:change event for listeners.
+     */
+    updatePresence(scopeKey: string, presence: PresenceEntry[]): void;
+    /**
+     * Join presence for a scope key.
+     * Sends via transport (if available) and updates local state optimistically.
+     */
+    joinPresence(scopeKey: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Leave presence for a scope key.
+     */
+    leavePresence(scopeKey: string): void;
+    /**
+     * Update presence metadata for a scope key.
+     */
+    updatePresenceMetadata(scopeKey: string, metadata: Record<string, unknown>): void;
+    /**
+     * Handle a single presence event (join/leave/update).
+     * Updates the in-memory presence state and emits change event.
+     */
+    handlePresenceEvent(event: {
+        action: 'join' | 'leave' | 'update';
+        scopeKey: string;
+        clientId: string;
+        actorId: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    private createInitialState;
+    private isEnabled;
+    private detectTransportMode;
+    /**
+     * Get current engine state.
+     * Returns the same object reference to avoid useSyncExternalStore infinite loops.
+     */
+    getState(): Readonly<SyncEngineState>;
+    /**
+     * Get database instance
+     */
+    getDb(): Kysely<DB>;
+    /**
+     * Get current actor id (sync scoping).
+     */
+    getActorId(): string | null | undefined;
+    /**
+     * Get current client id (device/app install id).
+     */
+    getClientId(): string | null | undefined;
+    /**
+     * Subscribe to sync events
+     */
+    on<T extends SyncEventType>(event: T, listener: SyncEventListener<T>): () => void;
+    /**
+     * Subscribe to any state change (for useSyncExternalStore)
+     */
+    subscribe(callback: () => void): () => void;
+    private emit;
+    private updateState;
+    private setConnectionState;
+    /**
+     * Start the sync engine
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the sync engine (cleanup without destroy)
+     */
+    stop(): void;
+    /**
+     * Destroy the engine (cannot be restarted)
+     */
+    destroy(): void;
+    /**
+     * Trigger a manual sync
+     */
+    sync(opts?: {
+        trigger?: 'ws' | 'local' | 'poll';
+    }): Promise<SyncResult>;
+    private performSyncLoop;
+    private performSyncOnce;
+    private extractChangedTables;
+    private applyWsDeliveredChanges;
+    private handleWsDelivery;
+    private timestampCounter;
+    private nextPreciseTimestamp;
+    private bumpMutationTimestamp;
+    private bumpTableMutationTimestamp;
+    /**
+     * Record local mutations that were already applied to the DB.
+     *
+     * This updates in-memory mutation timestamps (for fingerprint-based rerenders),
+     * and emits a single `data:change` event for the affected tables.
+     *
+     * This is intentionally separate from applyLocalMutation() so callers that
+     * perform their own DB transactions (e.g. `useMutations`) can still keep UI
+     * updates correct without double-writing.
+     */
+    recordLocalMutations(inputs: Array<{
+        table: string;
+        rowId: string;
+        op: 'upsert' | 'delete';
+    }>, now?: number): void;
+    private recordMutationTimestampsFromPullResponse;
+    private scheduleRetry;
+    private handleError;
+    private setupPolling;
+    private stopPolling;
+    private setupRealtime;
+    private stopRealtime;
+    private scheduleRealtimeReconnectCatchupSync;
+    private startFallbackPolling;
+    private stopFallbackPolling;
+    /**
+     * Clear all in-memory mutation state and emit data:change so UI re-renders.
+     * Call this after deleting local data (e.g. reset flow) so that React hooks
+     * recompute fingerprints from scratch instead of seeing stale timestamps.
+     */
+    resetLocalState(): void;
+    /**
+     * Reconnect
+     */
+    reconnect(): void;
+    /**
+     * Disconnect (pause syncing)
+     */
+    disconnect(): void;
+    /**
+     * Refresh outbox statistics
+     */
+    refreshOutboxStats(options?: {
+        emit?: boolean;
+    }): Promise<OutboxStats>;
+    /**
+     * Get pending conflicts with operation details from outbox
+     */
+    getConflicts(): Promise<ConflictInfo[]>;
+    /**
+     * Update subscriptions dynamically
+     */
+    updateSubscriptions(subscriptions: Array<Omit<SyncSubscriptionRequest, 'cursor'>>): void;
+    /**
+     * Apply local mutations immediately to the database and emit change events.
+     * Used for instant UI updates before the sync cycle completes.
+     */
+    applyLocalMutation(inputs: Array<{
+        table: string;
+        rowId: string;
+        op: 'upsert' | 'delete';
+        payload?: Record<string, unknown> | null;
+    }>): Promise<void>;
+    /**
+     * Clear failed commits from the outbox.
+     * Use this to discard commits that keep failing (e.g., version conflicts).
+     */
+    clearFailedCommits(): Promise<number>;
+    /**
+     * Clear all pending and failed commits from the outbox.
+     * Use this to reset the outbox completely (e.g., for testing).
+     */
+    clearAllCommits(): Promise<number>;
+}
+//# sourceMappingURL=SyncEngine.d.ts.map

package/dist/engine/SyncEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncEngine.d.ts","sourceRoot":"","sources":["../../src/engine/SyncEngine.ts"],"names":[],"mappings":"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"}