stellar-drive 1.0.0

package/dist/diagnostics.js.map

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

package/dist/engine.d.ts

@@ -0,0 +1,230 @@
+/**
+ * @fileoverview Local-First Sync Engine - Core orchestrator for offline-first data synchronization.
+ *
+ * This is the heart of stellar-drive: a bidirectional sync engine that keeps local
+ * IndexedDB (via Dexie) in sync with a remote Supabase database. It implements the
+ * "local-first" pattern where all reads/writes happen against the local DB for instant
+ * responsiveness, and a background sync loop reconciles with the server.
+ *
+ * ## Architecture Overview
+ *
+ * ```
+ * ┌─────────────┐     ┌──────────────┐     ┌──────────────┐
+ * │   UI Layer   │────▶│  Local DB    │────▶│  Sync Engine │────▶ Supabase
+ * │  (instant)   │◀────│  (IndexedDB) │◀────│  (background)│◀──── (remote)
+ * └─────────────┘     └──────────────┘     └──────────────┘
+ * ```
+ *
+ * ## Core Rules
+ *
+ * 1. **All reads come from local DB** (IndexedDB via Dexie)
+ * 2. **All writes go to local DB first**, immediately (no waiting for network)
+ * 3. **Every write creates a pending operation** in the sync queue (outbox pattern)
+ * 4. **Sync loop ships outbox to server** in the background (push phase)
+ * 5. **On refresh, load local state instantly**, then run background sync (pull phase)
+ *
+ * ## Sync Cycle Flow
+ *
+ * 1. **Push**: Coalesce pending ops → send to Supabase → remove from queue
+ * 2. **Pull**: Fetch changes since last cursor → apply with conflict resolution → update cursor
+ * 3. **Notify**: Tell registered stores to refresh from local DB
+ *
+ * ## Key Subsystems
+ *
+ * - **Egress monitoring**: Tracks bytes/records transferred for debugging bandwidth usage
+ * - **Sync lock (mutex)**: Prevents concurrent sync cycles from corrupting state
+ * - **Watchdog**: Detects stuck syncs and auto-releases locks after timeout
+ * - **Tombstone cleanup**: Garbage-collects soft-deleted records after configured TTL
+ * - **Auth validation**: Ensures valid session before syncing (prevents silent RLS failures)
+ * - **Visibility sync**: Smart re-sync when user returns to tab after extended absence
+ * - **Realtime integration**: Skips polling pull when WebSocket subscription is healthy
+ *
+ * ## Egress Optimization Strategy
+ *
+ * The engine aggressively minimizes Supabase egress (bandwidth) through:
+ * - Operation coalescing (50 rapid updates → 1 request)
+ * - Push-only mode when realtime is healthy (skip pull after local writes)
+ * - Cached user validation (1 getUser() call per hour instead of per sync)
+ * - Visibility-aware sync (skip sync if tab was hidden briefly)
+ * - Reconnect cooldown (skip sync if we just synced before going offline)
+ * - Selective column fetching (only request configured columns, not `*`)
+ *
+ * @module engine
+ * @see {@link ./queue.ts} - Sync queue (outbox) management
+ * @see {@link ./conflicts.ts} - Field-level conflict resolution
+ * @see {@link ./realtime.ts} - Supabase Realtime WebSocket subscriptions
+ * @see {@link ./config.ts} - Engine configuration and table definitions
+ */
+/**
+ * Clear all pending sync operations from the outbox queue.
+ *
+ * **SECURITY**: Called when offline credentials are found to be invalid, to prevent
+ * unauthorized data from being synced to the server. Without this, a user who
+ * tampered with offline credentials could queue malicious writes that get pushed
+ * once the device reconnects.
+ *
+ * @returns The number of operations that were cleared
+ *
+ * @example
+ * ```ts
+ * // Called during auth validation failure
+ * const cleared = await clearPendingSyncQueue();
+ * console.log(`Prevented ${cleared} unauthorized sync operations`);
+ * ```
+ */
+export declare function clearPendingSyncQueue(): Promise<number>;
+/** Stats captured for each sync cycle (push + pull) */
+interface SyncCycleStats {
+    timestamp: string;
+    trigger: string;
+    pushedItems: number;
+    pulledTables: number;
+    pulledRecords: number;
+    egressBytes: number;
+    durationMs: number;
+}
+/**
+ * Mark an entity as recently modified to protect it from being overwritten by pull.
+ *
+ * Called by repository functions after every local write. The protection expires
+ * after `RECENTLY_MODIFIED_TTL_MS` (2 seconds).
+ *
+ * @param entityId - The UUID of the entity that was just modified locally
+ */
+export declare function markEntityModified(entityId: string): void;
+/**
+ * Return a snapshot of engine-internal state for diagnostics.
+ *
+ * This function is prefixed with `_` to signal that it exposes module-private
+ * state and should only be consumed by the diagnostics module.
+ *
+ * @returns A plain object containing current engine state values
+ */
+export declare function _getEngineDiagnostics(): {
+    syncStats: SyncCycleStats[];
+    totalSyncCycles: number;
+    egressStats: {
+        byTable: {
+            [x: string]: {
+                bytes: number;
+                records: number;
+            };
+        };
+        totalBytes: number;
+        totalRecords: number;
+        sessionStart: string;
+    };
+    hasHydrated: boolean;
+    schemaValidated: boolean;
+    isTabVisible: boolean;
+    tabHiddenAt: number | null;
+    lockHeld: boolean;
+    lockHeldForMs: number | null;
+    recentlyModifiedCount: number;
+    wasOffline: boolean;
+    authValidatedAfterReconnect: boolean;
+    lastSuccessfulSyncTimestamp: number;
+};
+/**
+ * Register a callback to be invoked when a sync cycle completes.
+ *
+ * Used by Svelte stores to refresh their data from the local DB after new
+ * remote data has been pulled. Returns an unsubscribe function for cleanup.
+ *
+ * @param callback - Function to call after each sync completion
+ * @returns Unsubscribe function that removes the callback
+ *
+ * @example
+ * ```ts
+ * // In a Svelte store
+ * const unsubscribe = onSyncComplete(() => {
+ *   refreshFromLocalDb();
+ * });
+ * // Later, during cleanup:
+ * unsubscribe();
+ * ```
+ */
+export declare function onSyncComplete(callback: () => void): () => void;
+/**
+ * Schedule a debounced sync push after a local write.
+ *
+ * Called by repository functions after every write to the local DB. The debounce
+ * prevents hammering the server during rapid edits (e.g., typing in a text field).
+ * When realtime is healthy, runs in push-only mode (skips the pull phase) since
+ * remote changes arrive via WebSocket.
+ *
+ * @example
+ * ```ts
+ * // After a local write in a repository
+ * await db.table('todos').put(newTodo);
+ * scheduleSyncPush(); // Sync will fire after debounce delay
+ * ```
+ */
+export declare function scheduleSyncPush(): void;
+/**
+ * Execute a full sync cycle: push local changes, then pull remote changes.
+ *
+ * This is the main entry point for sync. It orchestrates the complete cycle:
+ * 1. **Pre-flight checks**: Online status, auth validation, session validity
+ * 2. **Acquire lock**: Prevent concurrent syncs
+ * 3. **Push phase**: Send pending local changes to Supabase
+ * 4. **Pull phase**: Fetch remote changes since last cursor (with retry)
+ * 5. **Post-sync**: Update UI status, notify stores, log egress stats
+ *
+ * The `quiet` flag controls whether the UI sync indicator is shown. Background
+ * periodic syncs use `quiet=true` to avoid distracting the user. User-triggered
+ * syncs (after local writes) use `quiet=false` to show progress.
+ *
+ * The `skipPull` flag enables push-only mode when realtime subscriptions are
+ * healthy — since remote changes arrive via WebSocket, polling is redundant.
+ *
+ * @param quiet - If `true`, don't update the UI status indicator
+ * @param skipPull - If `true`, skip the pull phase (push-only mode)
+ */
+export declare function runFullSync(quiet?: boolean, skipPull?: boolean): Promise<void>;
+/**
+ * Start the sync engine: initialize all listeners, timers, and subscriptions.
+ *
+ * This is the main "boot" function for the sync engine. It:
+ * 1. Ensures the Dexie DB is open and upgraded
+ * 2. Cleans up any existing listeners (idempotent restart support)
+ * 3. Subscribes to Supabase auth state changes (handles sign-out/token-refresh)
+ * 4. Registers online/offline handlers with auth validation
+ * 5. Registers visibility change handler for smart tab-return syncing
+ * 6. Starts realtime WebSocket subscriptions
+ * 7. Starts periodic background sync interval
+ * 8. Validates Supabase schema (one-time)
+ * 9. Runs initial hydration (if local DB is empty) or full sync
+ * 10. Runs initial cleanup (tombstones, conflicts, failed items)
+ * 11. Starts the watchdog timer
+ * 12. Registers debug window utilities (Tombstones, Sync, Diagnostics)
+ *
+ * **Must be called after `initEngine()`** — requires configuration to be set.
+ * Safe to call multiple times (previous listeners are cleaned up first).
+ */
+export declare function startSyncEngine(): Promise<void>;
+/**
+ * Stop the sync engine: tear down all listeners, timers, and subscriptions.
+ *
+ * After calling this, no sync activity will occur. All event listeners are
+ * removed to prevent memory leaks. The sync lock is released in case a sync
+ * was in progress. Hydration and schema validation flags are reset so the
+ * engine can be cleanly restarted.
+ *
+ * Call this during app teardown, before reconfiguring the engine, or when
+ * the user navigates away from pages that need sync.
+ */
+export declare function stopSyncEngine(): Promise<void>;
+/**
+ * Clear all local data from IndexedDB (used during logout).
+ *
+ * Wipes all entity tables, the sync queue, and conflict history in a single
+ * transaction. Also removes the user's sync cursor from localStorage and
+ * resets the hydration flag so the next login triggers a fresh hydration.
+ *
+ * **IMPORTANT**: Call this BEFORE calling `stopSyncEngine()` to ensure the
+ * database is still open when clearing tables.
+ */
+export declare function clearLocalCache(): Promise<void>;
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAgLH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAW7D;AAuCD,uDAAuD;AACvD,UAAU,cAAc;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAgLD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB;;;;;;uBAxLF,MAAM;yBAAW,MAAM;;;oBAF5C,MAAM;sBACJ,MAAM;sBAEN,MAAM;;;;;;;;;;;;EAuMrB;AAgLD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAO/D;AAuCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAcvC;AAi8BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAC/B,KAAK,GAAE,OAAe,EACtB,QAAQ,GAAE,OAAe,GACxB,OAAO,CAAC,IAAI,CAAC,CA2Mf;AAolBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAwYrD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CA+DpD;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAgDrD"}