@framers/sql-storage-adapter 0.1.0

package/dist/utils/syncManager.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Sync Manager for hybrid local/cloud database synchronization.
+ *
+ * Supports both online-first and offline-first patterns with automatic
+ * conflict resolution and intelligent sync strategies.
+ *
+ * @example Online-first with fallback
+ * ```typescript
+ * const manager = await createSyncManager({
+ *   primary: { url: process.env.DATABASE_URL, fallback: './local.db' },
+ *   sync: { mode: 'auto', interval: 30000 }
+ * });
+ * ```
+ *
+ * @example Offline-first with cloud sync
+ * ```typescript
+ * const manager = await createSyncManager({
+ *   primary: { file: './local.db' },
+ *   remote: { url: process.env.DATABASE_URL },
+ *   sync: { mode: 'periodic', interval: 60000 }
+ * });
+ * ```
+ *
+ * @example Manual sync control
+ * ```typescript
+ * const manager = await createSyncManager({
+ *   primary: './local.db',
+ *   remote: process.env.DATABASE_URL,
+ *   sync: { mode: 'manual' }
+ * });
+ *
+ * // Trigger sync when you want
+ * await manager.sync();
+ * ```
+ */
+import type { StorageAdapter } from '../types';
+/**
+ * Sync mode determines when synchronization occurs.
+ */
+export type SyncMode = 'manual' | 'auto' | 'periodic' | 'realtime' | 'on-reconnect';
+/**
+ * Conflict resolution strategy when same record modified offline and online.
+ */
+export type ConflictStrategy = 'last-write-wins' | 'local-wins' | 'remote-wins' | 'merge' | 'keep-both';
+/**
+ * Sync direction - which way data flows.
+ */
+export type SyncDirection = 'bidirectional' | 'push-only' | 'pull-only';
+/**
+ * Storage limit action for mobile devices.
+ */
+export type StorageLimitAction = 'warn' | 'error' | 'prune';
+/**
+ * Table sync priority.
+ */
+export type SyncPriority = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * Per-table sync configuration.
+ */
+export interface TableSyncConfig {
+    /** Priority level (critical syncs first) */
+    priority?: SyncPriority;
+    /** Sync in realtime regardless of global mode */
+    realtime?: boolean;
+    /** Skip this table in sync */
+    skip?: boolean;
+    /** Custom conflict resolution for this table */
+    conflictStrategy?: ConflictStrategy;
+    /** Max records to keep locally (mobile optimization) */
+    maxRecords?: number;
+    /** Custom merge function for 'merge' conflict strategy */
+    mergeFn?: (local: any, remote: any) => any;
+}
+/**
+ * Sync configuration options.
+ */
+export interface SyncConfig {
+    /** Sync mode - when synchronization occurs */
+    mode?: SyncMode;
+    /** Sync direction - which way data flows */
+    direction?: SyncDirection;
+    /** Conflict resolution strategy */
+    conflictStrategy?: ConflictStrategy;
+    /** Interval in ms for periodic sync (default: 30000 = 30s) */
+    interval?: number;
+    /** Debounce delay in ms for auto sync (default: 500ms) */
+    debounce?: number;
+    /** Batch size - sync N records at a time (default: 100) */
+    batchSize?: number;
+    /** Retry failed syncs automatically */
+    retryOnError?: boolean;
+    /** Max retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Retry delay in ms (default: 1000) */
+    retryDelay?: number;
+    /** Per-table sync configuration */
+    tables?: Record<string, TableSyncConfig>;
+    /** Mobile storage limit in MB (default: 50MB) */
+    mobileStorageLimit?: number;
+    /** Action when storage limit reached */
+    storageLimitAction?: StorageLimitAction;
+    /** Only sync specific tables (undefined = all) */
+    includeTables?: string[];
+    /** Exclude specific tables from sync */
+    excludeTables?: string[];
+}
+/**
+ * Database connection configuration.
+ */
+export interface DatabaseConfig {
+    /** Database URL (PostgreSQL) */
+    url?: string;
+    /** File path (SQLite) */
+    file?: string;
+    /** Fallback database path if primary fails */
+    fallback?: string;
+    /** PostgreSQL-specific options */
+    postgres?: {
+        max?: number;
+        min?: number;
+        ssl?: boolean | object;
+        statement_timeout?: number;
+    };
+}
+/**
+ * Sync manager configuration.
+ */
+export interface SyncManagerConfig {
+    /** Primary database (writes go here) */
+    primary: DatabaseConfig | string;
+    /** Remote database for sync (optional for offline-only) */
+    remote?: DatabaseConfig | string;
+    /** Sync configuration */
+    sync?: SyncConfig;
+    /** Called after successful sync */
+    onSync?: (result: SyncResult) => void;
+    /** Called when conflict detected */
+    onConflict?: (conflict: SyncConflict) => void;
+    /** Called when going offline */
+    onOffline?: () => void;
+    /** Called when coming online */
+    onOnline?: () => void;
+    /** Called on sync error */
+    onError?: (error: Error) => void;
+    /** Called on sync progress */
+    onProgress?: (progress: SyncProgress) => void;
+}
+/**
+ * Sync result after synchronization completes.
+ */
+export interface SyncResult {
+    /** Sync completed successfully */
+    success: boolean;
+    /** Direction of sync */
+    direction: SyncDirection;
+    /** Number of records synced */
+    recordsSynced: number;
+    /** Number of conflicts encountered */
+    conflicts: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Timestamp of sync */
+    timestamp: string;
+    /** Tables synced */
+    tables: string[];
+    /** Errors encountered */
+    errors?: Error[];
+    /** Detailed per-table results */
+    details?: Record<string, {
+        pushed: number;
+        pulled: number;
+        conflicts: number;
+    }>;
+}
+/**
+ * Conflict information.
+ */
+export interface SyncConflict {
+    /** Table name */
+    table: string;
+    /** Record identifier */
+    id: any;
+    /** Local version */
+    local: any;
+    /** Remote version */
+    remote: any;
+    /** Local last modified timestamp */
+    localTimestamp?: string;
+    /** Remote last modified timestamp */
+    remoteTimestamp?: string;
+}
+/**
+ * Sync progress information.
+ */
+export interface SyncProgress {
+    /** Current phase */
+    phase: 'connecting' | 'pulling' | 'pushing' | 'resolving' | 'complete';
+    /** Progress percentage (0-100) */
+    percent: number;
+    /** Current table being synced */
+    currentTable?: string;
+    /** Records processed */
+    recordsProcessed: number;
+    /** Total records to process */
+    totalRecords: number;
+}
+/**
+ * Internal resolved sync config with all required fields.
+ */
+type ResolvedSyncConfig = Required<Omit<SyncConfig, 'includeTables' | 'excludeTables'>> & {
+    includeTables?: string[];
+    excludeTables?: string[];
+};
+/**
+ * Sync manager for hybrid local/cloud databases.
+ * Handles automatic synchronization, conflict resolution, and offline support.
+ */
+export declare class SyncManager {
+    private readonly callbacks;
+    private primaryDb;
+    private remoteDb;
+    readonly config: ResolvedSyncConfig;
+    private syncTimer;
+    private debounceTimer;
+    private syncQueue;
+    private isSyncing;
+    private isOnline;
+    private lastSyncTime;
+    private pendingWrites;
+    private constructor();
+    /**
+     * Get the primary database adapter.
+     * Use this for all database operations.
+     */
+    get db(): StorageAdapter;
+    /**
+     * Check if manager is currently syncing.
+     */
+    get syncing(): boolean;
+    /**
+     * Check if currently online.
+     */
+    get online(): boolean;
+    /**
+     * Get last successful sync time.
+     */
+    get lastSync(): Date | null;
+    /**
+     * Trigger manual sync.
+     * Safe to call multiple times - queues if already syncing.
+     */
+    sync(): Promise<SyncResult>;
+    /**
+     * Perform the actual sync operation.
+     */
+    private performSync;
+    /**
+     * Sync a single table.
+     */
+    private syncTable;
+    /**
+     * Pull table data from remote to local.
+     */
+    private pullTable;
+    /**
+     * Push table data from local to remote.
+     */
+    private pushTable;
+    /**
+     * Resolve conflicts between local and remote data.
+     */
+    private resolveConflicts;
+    /**
+     * Get list of tables to sync.
+     */
+    private getTablesToSync;
+    /**
+     * Sort tables by priority.
+     */
+    private sortTablesByPriority;
+    /**
+     * Check network connection.
+     */
+    private checkConnection;
+    /**
+     * Start automatic sync based on mode.
+     */
+    private startAutoSync;
+    /**
+     * Stop automatic sync.
+     */
+    stop(): void;
+    /**
+     * Close all database connections.
+     */
+    close(): Promise<void>;
+    /**
+     * Create a sync manager instance.
+     */
+    static create(config: SyncManagerConfig): Promise<SyncManager>;
+}
+/**
+ * Create a sync manager for hybrid local/cloud databases.
+ *
+ * @example Online-first with automatic fallback
+ * ```typescript
+ * const manager = await createSyncManager({
+ *   primary: {
+ *     url: process.env.DATABASE_URL,
+ *     fallback: './offline.db'
+ *   },
+ *   sync: {
+ *     mode: 'periodic',
+ *     interval: 30000
+ *   }
+ * });
+ *
+ * // Use like normal database
+ * await manager.db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
+ * // Syncs automatically every 30s
+ * ```
+ *
+ * @example Offline-first with cloud sync
+ * ```typescript
+ * const manager = await createSyncManager({
+ *   primary: './local.db',
+ *   remote: process.env.DATABASE_URL,
+ *   sync: {
+ *     mode: 'manual'  // Sync only when you call manager.sync()
+ *   }
+ * });
+ *
+ * // Work offline
+ * await manager.db.run('INSERT INTO ...');
+ *
+ * // Sync when ready
+ * await manager.sync();
+ * ```
+ */
+export declare function createSyncManager(config: SyncManagerConfig): Promise<SyncManager>;
+export {};
+//# sourceMappingURL=syncManager.d.ts.map

package/dist/utils/syncManager.d.ts.map

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