@framers/sql-storage-adapter 0.4.2 → 0.5.1

package/README.md

@@ -19,7 +19,7 @@
 
 The SQL Storage Adapter provides a single, ergonomic interface over SQLite (native and WASM), PostgreSQL, Capacitor, IndexedDB, and in-memory stores. It handles adapter discovery, capability detection, and advanced features like cloud backups so you can focus on your application logic.
 
-**🆕 NEW:** Full IndexedDB support for browser-native, offline-first web apps!
+**🆕 NEW in v0.5.1:** Electron adapter with IPC bridge + Cross-platform real-time sync!
 
 ---
 
@@ -27,6 +27,8 @@ The SQL Storage Adapter provides a single, ergonomic interface over SQLite (nati
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Adapter Matrix](#adapter-matrix)
+- [Electron Adapter](#electron-adapter)
+- [Cross-Platform Sync](#cross-platform-sync)
 - [Configuration & Resolution](#configuration--resolution)
 - [Platform Strategy](#platform-strategy)
 - [CI, Releases, and Badges](#ci-releases-and-badges)
@@ -38,6 +40,8 @@ The SQL Storage Adapter provides a single, ergonomic interface over SQLite (nati
 - **Auto-detected adapters** – `createDatabase()` inspects environment signals and picks the best backend (native SQLite, PostgreSQL, Capacitor, sql.js, **IndexedDB**, memory, etc.).
 - **Capability-aware API** – consistent CRUD, transactions, batching, and event hooks across adapters with runtime capability introspection.
 - **🆕 IndexedDB** – sql.js + IndexedDB persistence wrapper for browser-native, offline-first web apps (uses sql.js for SQL execution, IndexedDB for storage).
+- **🆕 Electron Adapter** – Full IPC bridge with main/renderer process split, WAL management, auto-migrations, multi-window support.
+- **🆕 Cross-Platform Sync** – Real-time delta sync with vector clocks, WebSocket/HTTP transports, conflict resolution UI hooks, and device registry.
 - **🆕 Performance Tiers** – Configurable `fast`, `balanced`, `accurate`, `efficient` presets for cost/accuracy tradeoffs. See [Optimization Guide](./guides/OPTIMIZATION_GUIDE.md).
 - **🆕 Lifecycle Hooks** – Extensible hooks (`onBeforeQuery`, `onAfterQuery`, `onBeforeWrite`, `onAfterWrite`) for logging, analytics, caching, and custom extensions.
 - **Cloud backups & migrations** – built-in backup manager with compression, retention policies, and restore helpers plus migration utilities.
@@ -120,6 +124,7 @@ See [Platform Strategy Guide](./PLATFORM_STRATEGY.md) for detailed pros/cons and
 
 | Adapter | Package | Ideal for | Pros | Considerations |
 | --- | --- | --- | --- | --- |
+| **🆕 `electron`** | bundled | **Electron desktop apps** | IPC bridge, multi-window, WAL, auto-migrations, crash recovery | Requires Electron runtime |
 | **🆕 `indexeddb`** | bundled (sql.js) | **Browsers, PWAs** | sql.js + IndexedDB persistence wrapper, browser-native storage, 50MB-1GB+ quota, offline-first | IndexedDB quotas vary, WASM overhead (sql.js), not a separate SQL engine |
 | `better-sqlite3` | `better-sqlite3` | Node/Electron, CLI, CI | Native performance, transactional semantics, WAL support | Needs native toolchain; version must match Node ABI |
 | `postgres` | `pg` | Hosted or on-prem PostgreSQL | Connection pooling, rich SQL features, cloud friendly | Requires `DATABASE_URL`/credentials |
@@ -132,11 +137,98 @@ See [Platform Strategy Guide](./PLATFORM_STRATEGY.md) for detailed pros/cons and
 | Platform | Primary Adapter | Fallback | Use Case |
 |----------|----------------|----------|----------|
 | **Web (Browser)** | IndexedDB | sql.js | PWAs, offline-first web apps |
-| **Electron (Desktop)** | better-sqlite3 | sql.js | Desktop apps, dev tools |
+| **Electron (Desktop)** | electron | better-sqlite3 | Desktop apps, dev tools |
 | **Capacitor (Mobile)** | capacitor | IndexedDB | iOS/Android native apps |
 | **Node.js** | better-sqlite3 | Postgres, sql.js | CLI tools, local servers |
 | **Cloud (Serverless)** | Postgres | better-sqlite3 | Multi-tenant SaaS, APIs |
 
+## Electron Adapter
+
+The Electron adapter provides a complete IPC bridge architecture for Electron apps with main/renderer process split.
+
+```typescript
+// Main process (main.ts)
+import { createElectronMainAdapter } from '@framers/sql-storage-adapter/electron';
+
+const db = await createElectronMainAdapter({
+  filePath: path.join(app.getPath('userData'), 'app.db'),
+  wal: { enabled: true, checkpointInterval: 30000 },
+  autoMigration: { enabled: true, migrationsPath: './migrations' },
+  multiWindow: { enabled: true, broadcastChanges: true },
+});
+
+await db.open();
+```
+
+```typescript
+// Renderer process
+import { createElectronRendererAdapter } from '@framers/sql-storage-adapter/electron';
+
+const db = createElectronRendererAdapter();
+await db.open();
+
+const users = await db.all('SELECT * FROM users');
+```
+
+**Features:**
+- ✅ Type-safe IPC protocol with request/response correlation
+- ✅ WAL checkpoint management and corruption detection
+- ✅ Auto-migration on app version change
+- ✅ Multi-window database change broadcasting
+- ✅ Preload script with secure `contextBridge` API
+
+## Cross-Platform Sync
+
+Real-time delta synchronization across Electron, Capacitor, browser, and server platforms.
+
+```typescript
+import { createCrossPlatformSync } from '@framers/sql-storage-adapter/sync';
+
+const sync = await createCrossPlatformSync({
+  localAdapter: db,
+  endpoint: 'wss://sync.example.com',
+  authToken: 'bearer-token',
+  device: { name: 'MacBook Pro', type: 'electron' },
+  tables: {
+    notes: { priority: 'high', conflictStrategy: 'merge' },
+    settings: { priority: 'critical', conflictStrategy: 'local-wins' },
+  },
+  hooks: {
+    onConflictNeedsResolution: async (conflict) => {
+      // Show UI for manual conflict resolution
+      return showConflictDialog(conflict);
+    },
+    onSyncComplete: (result) => {
+      console.log(`Synced: ${result.changesPushed} pushed, ${result.changesPulled} pulled`);
+    },
+  },
+});
+
+// Manual sync
+await sync.sync();
+
+// Or enable real-time sync
+await sync.connect();
+```
+
+**Features:**
+- ✅ **Vector Clocks** – Distributed causality tracking for accurate conflict detection
+- ✅ **WebSocket Transport** – Real-time bidirectional sync with auto-reconnection
+- ✅ **HTTP Fallback** – Polling transport for firewalls that block WebSocket
+- ✅ **Conflict Resolution** – Strategies: `last-write-wins`, `local-wins`, `remote-wins`, `merge`, `manual`
+- ✅ **Device Registry** – Track syncing devices with presence status (online/offline/syncing)
+- ✅ **UI Hooks** – Custom conflict resolution dialogs
+
+**Conflict Strategies:**
+
+| Strategy | Description |
+|----------|-------------|
+| `last-write-wins` | Most recent change wins (by timestamp) |
+| `local-wins` | Local changes always take priority |
+| `remote-wins` | Remote changes always take priority |
+| `merge` | Field-level merge with custom mergers |
+| `manual` | Defer to UI hook for user decision |
+
 ## Configuration & Resolution
 
 - `resolveStorageAdapter` inspects:

package/dist/adapters/electron/electronMainAdapter.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Electron Main Process Storage Adapter.
+ *
+ * Wraps BetterSqliteAdapter for use in Electron's main process.
+ * Handles IPC communication, WAL management, crash recovery,
+ * and multi-window coordination.
+ *
+ * ## Architecture
+ * This adapter runs in the main process and owns the actual database connection.
+ * Renderer processes communicate with it via IPC using ElectronRendererAdapter.
+ *
+ * ## Features
+ * - WAL mode with configurable checkpointing
+ * - Integrity checking and auto-repair
+ * - Multi-window change broadcasting
+ * - Cloud backup scheduling
+ * - Auto-migration on app updates
+ *
+ * @example
+ * ```typescript
+ * import { createElectronMainAdapter } from '@framers/sql-storage-adapter/electron';
+ * import { app } from 'electron';
+ * import path from 'path';
+ *
+ * const db = await createElectronMainAdapter({
+ *   filePath: path.join(app.getPath('userData'), 'app.db'),
+ *   wal: { enabled: true, checkpointInterval: 300000 },
+ *   recovery: { enabled: true, checkOnOpen: true },
+ * });
+ *
+ * await db.open();
+ * ```
+ */
+import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult, BatchOperation, BatchResult, PreparedStatement } from '../../core/contracts';
+/**
+ * WAL (Write-Ahead Logging) configuration.
+ */
+export interface WalConfig {
+    /** Enable WAL mode (default: true) */
+    enabled?: boolean;
+    /** Checkpoint interval in milliseconds (default: 300000 = 5 minutes) */
+    checkpointInterval?: number;
+    /** Auto-checkpoint threshold in pages (default: 1000) */
+    autoCheckpointPages?: number;
+    /** Synchronous mode: OFF, NORMAL, FULL, EXTRA (default: NORMAL) */
+    synchronous?: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA';
+}
+/**
+ * Recovery and integrity check configuration.
+ */
+export interface RecoveryConfig {
+    /** Enable recovery features (default: true) */
+    enabled?: boolean;
+    /** Run integrity check on open (default: true) */
+    checkOnOpen?: boolean;
+    /** Attempt auto-repair on corruption (default: true) */
+    autoRepair?: boolean;
+    /** Maximum time for integrity check in ms (default: 30000) */
+    integrityCheckTimeout?: number;
+}
+/**
+ * Auto-migration configuration.
+ */
+export interface MigrationConfig {
+    /** Enable auto-migration (default: false) */
+    enabled?: boolean;
+    /** Path to migrations directory */
+    migrationsPath?: string;
+    /** Run migrations on app version change (default: true) */
+    runOnVersionChange?: boolean;
+}
+/**
+ * Cloud backup configuration.
+ */
+export interface BackupConfig {
+    /** Enable cloud backups (default: false) */
+    enabled?: boolean;
+    /** Backup interval in milliseconds (default: 3600000 = 1 hour) */
+    interval?: number;
+    /** Maximum backups to keep (default: 7) */
+    maxBackups?: number;
+    /** Backup provider (implement your own) */
+    provider?: CloudBackupProvider;
+}
+/**
+ * Cloud backup provider interface.
+ */
+export interface CloudBackupProvider {
+    upload(localPath: string, remotePath: string): Promise<void>;
+    download(remotePath: string, localPath: string): Promise<void>;
+    list(): Promise<{
+        path: string;
+        createdAt: Date;
+        size: number;
+    }[]>;
+    delete(remotePath: string): Promise<void>;
+}
+/**
+ * Multi-window coordination configuration.
+ */
+export interface MultiWindowConfig {
+    /** Enable multi-window support (default: true) */
+    enabled?: boolean;
+    /** Broadcast changes to other windows (default: true) */
+    broadcastChanges?: boolean;
+}
+/**
+ * Full configuration for ElectronMainAdapter.
+ */
+export interface ElectronMainAdapterOptions {
+    /** Path to SQLite database file */
+    filePath: string;
+    /** WAL configuration */
+    wal?: WalConfig;
+    /** Recovery configuration */
+    recovery?: RecoveryConfig;
+    /** Migration configuration */
+    migration?: MigrationConfig;
+    /** Backup configuration */
+    backup?: BackupConfig;
+    /** Multi-window configuration */
+    multiWindow?: MultiWindowConfig;
+    /** Enable verbose logging (default: false) */
+    verbose?: boolean;
+}
+/**
+ * Electron Main Process Storage Adapter.
+ *
+ * This adapter is designed to run exclusively in Electron's main process.
+ * It wraps BetterSqliteAdapter and adds Electron-specific features like
+ * IPC handling, multi-window coordination, and crash recovery.
+ */
+export declare class ElectronMainAdapter implements StorageAdapter {
+    readonly kind = "electron-main";
+    readonly capabilities: ReadonlySet<StorageCapability>;
+    private innerAdapter;
+    private isInitialized;
+    private walCheckpointTimer;
+    private backupTimer;
+    private readonly options;
+    private readonly walConfig;
+    private readonly recoveryConfig;
+    private readonly multiWindowConfig;
+    constructor(options: ElectronMainAdapterOptions);
+    /**
+     * Open the database and initialize all subsystems.
+     */
+    open(openOptions?: StorageOpenOptions): Promise<void>;
+    /**
+     * Close the database and cleanup all subsystems.
+     */
+    close(): Promise<void>;
+    run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
+    get<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T | null>;
+    all<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    exec(script: string): Promise<void>;
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
+    batch(operations: BatchOperation[]): Promise<BatchResult>;
+    prepare?<T = unknown>(statement: string): PreparedStatement<T>;
+    /**
+     * Configure WAL mode on the database.
+     */
+    private configureWalMode;
+    /**
+     * Start the WAL checkpoint timer.
+     */
+    private startWalCheckpointTimer;
+    /**
+     * Run a WAL checkpoint.
+     */
+    runWalCheckpoint(): Promise<{
+        framesCheckpointed: number;
+        totalFrames: number;
+    }>;
+    /**
+     * Run an integrity check on the database.
+     */
+    runIntegrityCheck(): Promise<{
+        ok: boolean;
+        issues: string[];
+    }>;
+    /**
+     * Attempt to repair the database.
+     */
+    private attemptRepair;
+    /**
+     * Start the backup scheduler.
+     */
+    private startBackupScheduler;
+    /**
+     * Run a backup.
+     */
+    runBackup(): Promise<void>;
+    /**
+     * Cleanup old backups beyond the retention limit.
+     */
+    private cleanupOldBackups;
+    /**
+     * Broadcast a database change to all windows.
+     */
+    private broadcastChange;
+    /**
+     * Detect mutation type from SQL statement.
+     */
+    private detectMutationType;
+    /**
+     * Extract table names from SQL statement.
+     */
+    private extractTables;
+    /**
+     * Log a message if verbose mode is enabled.
+     */
+    private log;
+    /**
+     * Check if the adapter is initialized.
+     */
+    isOpen(): boolean;
+    /**
+     * Get the database file path.
+     */
+    getFilePath(): string;
+}
+/**
+ * Create an Electron Main Process Storage Adapter.
+ *
+ * @param options - Adapter configuration
+ * @returns ElectronMainAdapter instance
+ *
+ * @example
+ * ```typescript
+ * const db = createElectronMainAdapter({
+ *   filePath: path.join(app.getPath('userData'), 'app.db'),
+ *   wal: { enabled: true },
+ *   recovery: { checkOnOpen: true },
+ * });
+ *
+ * await db.open();
+ * ```
+ */
+export declare function createElectronMainAdapter(options: ElectronMainAdapterOptions): ElectronMainAdapter;
+//# sourceMappingURL=electronMainAdapter.d.ts.map

package/dist/adapters/electron/electronMainAdapter.d.ts.map

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