@framers/sql-storage-adapter 0.4.2 → 0.5.1

package/dist/features/sync/crossPlatformSync.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Cross-Platform Sync Entry Point.
+ *
+ * Main API for synchronizing data across Electron, Capacitor,
+ * browser, and server platforms.
+ *
+ * @packageDocumentation
+ */
+import type { StorageAdapter } from '../../core/contracts';
+import type { VectorClockData } from './protocol/vectorClock';
+import type { ChangeRecord } from './protocol/messages';
+import type { TransportOptions } from './transport/transport';
+import type { SyncConflict, ConflictResolution, ConflictStrategy, ConflictUIHooks, FieldMerger } from './conflicts/conflictResolver';
+import type { DeviceInfo, DeviceType } from './devices/deviceManager';
+/**
+ * Table sync configuration.
+ */
+export interface TableSyncConfig {
+    /** Sync priority (higher = synced first) */
+    priority?: 'critical' | 'high' | 'normal' | 'low';
+    /** Conflict resolution strategy for this table */
+    conflictStrategy?: ConflictStrategy;
+    /** Maximum records to sync per batch */
+    maxRecords?: number;
+    /** Custom field mergers for merge strategy */
+    fieldMergers?: Record<string, FieldMerger>;
+    /** Whether to track deletes */
+    trackDeletes?: boolean;
+    /** Primary key column (default: 'id') */
+    primaryKey?: string;
+}
+/**
+ * Cross-platform sync options.
+ */
+export interface CrossPlatformSyncOptions {
+    /** Local storage adapter */
+    localAdapter: StorageAdapter;
+    /** Sync server endpoint */
+    endpoint: string;
+    /** Authentication token */
+    authToken?: string;
+    /** Device information */
+    device?: {
+        name?: string;
+        type?: DeviceType;
+    };
+    /** Tables to sync with their configuration */
+    tables: Record<string, TableSyncConfig>;
+    /** Transport type preference */
+    transport?: 'websocket' | 'http' | 'auto';
+    /** Transport options */
+    transportOptions?: Partial<TransportOptions>;
+    /** Default conflict strategy */
+    defaultConflictStrategy?: ConflictStrategy;
+    /** Conflict resolution UI hooks */
+    hooks?: CrossPlatformSyncHooks;
+    /** Sync interval in milliseconds (0 = manual only) */
+    syncInterval?: number;
+    /** Enable real-time sync (push changes immediately) */
+    realTime?: boolean;
+    /** Batch size for sync operations */
+    batchSize?: number;
+    /** Enable compression for sync payloads */
+    compression?: boolean;
+}
+/**
+ * Hooks for sync events and conflict resolution.
+ */
+export interface CrossPlatformSyncHooks extends ConflictUIHooks {
+    /** Called before sync starts */
+    onSyncStart?: () => void;
+    /** Called after sync completes */
+    onSyncComplete?: (result: SyncResult) => void;
+    /** Called when sync fails */
+    onSyncError?: (error: Error) => void;
+    /** Called when a change is pushed */
+    onChangePushed?: (change: ChangeRecord) => void;
+    /** Called when a change is pulled */
+    onChangePulled?: (change: ChangeRecord) => void;
+    /** Called when connection state changes */
+    onConnectionStateChange?: (connected: boolean) => void;
+    /** Called when a peer device is discovered */
+    onPeerDiscovered?: (peer: DeviceInfo) => void;
+}
+/**
+ * Sync operation result.
+ */
+export interface SyncResult {
+    /** Whether sync was successful */
+    success: boolean;
+    /** Number of records pushed */
+    pushed: number;
+    /** Number of records pulled */
+    pulled: number;
+    /** Number of conflicts detected */
+    conflicts: number;
+    /** Number of conflicts resolved */
+    conflictsResolved: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Errors encountered */
+    errors: Error[];
+    /** Resulting vector clock */
+    vectorClock: VectorClockData;
+}
+/**
+ * Sync status information.
+ */
+export interface SyncStatus {
+    /** Current sync state */
+    state: 'idle' | 'syncing' | 'error' | 'offline';
+    /** Whether connected to sync server */
+    connected: boolean;
+    /** Last successful sync time */
+    lastSyncAt?: number;
+    /** Last sync result */
+    lastResult?: SyncResult;
+    /** Pending changes count */
+    pendingChanges: number;
+    /** Pending conflicts count */
+    pendingConflicts: number;
+    /** Current device info */
+    device?: DeviceInfo;
+    /** Known peer devices */
+    peers: DeviceInfo[];
+}
+/**
+ * Cross-platform sync manager.
+ *
+ * Orchestrates synchronization between local database and remote
+ * sync server across all platforms.
+ *
+ * @example
+ * ```typescript
+ * const sync = await createCrossPlatformSync({
+ *   localAdapter: db,
+ *   endpoint: 'wss://sync.example.com',
+ *   authToken: 'token',
+ *   device: { name: 'MacBook Pro', type: 'electron' },
+ *   tables: {
+ *     notes: { priority: 'high', conflictStrategy: 'merge' },
+ *     settings: { priority: 'critical', conflictStrategy: 'local-wins' },
+ *   },
+ *   hooks: {
+ *     onConflictNeedsResolution: (conflict) => showConflictDialog(conflict),
+ *     onSyncComplete: (result) => console.log('Synced:', result),
+ *   },
+ * });
+ *
+ * await sync.sync();
+ * ```
+ */
+export declare class CrossPlatformSync {
+    private _adapter;
+    private _transport;
+    private _conflictResolver;
+    private _deviceManager;
+    private _syncLogManager;
+    private _options;
+    private _syncTimer;
+    private _status;
+    private _isSyncing;
+    private _disposed;
+    private _deviceId;
+    constructor(options: CrossPlatformSyncOptions);
+    /**
+     * Initialize the sync manager.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Perform a sync operation.
+     */
+    sync(): Promise<SyncResult>;
+    /**
+     * Push a single change immediately (for real-time sync).
+     */
+    pushChange(tableName: string, recordId: string, operation: 'INSERT' | 'UPDATE' | 'DELETE', data: Record<string, unknown>): Promise<void>;
+    /**
+     * Get current sync status.
+     */
+    getStatus(): SyncStatus;
+    /**
+     * Get pending conflicts.
+     */
+    getPendingConflicts(): SyncConflict[];
+    /**
+     * Resolve a conflict manually.
+     */
+    resolveConflict(conflictId: string, decision: 'use_local' | 'use_remote' | 'use_merged' | 'keep_both' | 'defer', mergedData?: Record<string, unknown>): Promise<ConflictResolution>;
+    /**
+     * Connect to sync server.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from sync server.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Dispose of the sync manager.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Initialize the transport layer.
+     */
+    private _initializeTransport;
+    /**
+     * Set up transport event listeners.
+     */
+    private _setupTransportListeners;
+    /**
+     * Set up device manager listeners.
+     */
+    private _setupDeviceManagerListeners;
+    /**
+     * Send handshake to server.
+     */
+    private _sendHandshake;
+    /**
+     * Handle incoming sync message.
+     */
+    private _handleIncomingMessage;
+    /**
+     * Push local changes to server.
+     */
+    private _pushChanges;
+    /**
+     * Pull remote changes from server.
+     */
+    private _pullChanges;
+    /**
+     * Apply remote changes to local database.
+     */
+    private _applyRemoteChanges;
+    /**
+     * Apply a single change to local database.
+     */
+    private _applyChange;
+    /**
+     * Get a local record by table and ID.
+     */
+    private _getLocalRecord;
+    /**
+     * Resolve pending conflicts.
+     */
+    private _resolveConflicts;
+    /**
+     * Get count of pending changes.
+     */
+    private _getPendingChangesCount;
+    /**
+     * Start sync timer.
+     */
+    private _startSyncTimer;
+    /**
+     * Build table strategies map.
+     */
+    private _buildTableStrategies;
+    /**
+     * Build field mergers map.
+     */
+    private _buildFieldMergers;
+}
+/**
+ * Create a cross-platform sync instance.
+ *
+ * @example
+ * ```typescript
+ * const sync = await createCrossPlatformSync({
+ *   localAdapter: db,
+ *   endpoint: 'wss://sync.example.com',
+ *   tables: {
+ *     notes: { priority: 'high', conflictStrategy: 'merge' },
+ *     settings: { priority: 'critical', conflictStrategy: 'local-wins' },
+ *   },
+ * });
+ *
+ * await sync.sync();
+ * ```
+ */
+export declare const createCrossPlatformSync: (options: CrossPlatformSyncOptions) => Promise<CrossPlatformSync>;
+//# sourceMappingURL=crossPlatformSync.d.ts.map

package/dist/features/sync/crossPlatformSync.d.ts.map

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