@pol-studios/powersync 1.0.6 → 1.0.10

package/dist/sync/index.d.ts

@@ -1,8 +1,7 @@
-import { b as SyncStatusTrackerOptions, P as PowerSyncRawStatus, U as Unsubscribe, M as MetricsCollectorOptions, d as SyncOperationData, H as HealthMonitorOptions, e as HealthCheckResult } from '../types-Cd7RhNqf.js';
-export { c as SyncControlActions, f as SyncEvent, g as SyncEventListener, S as SyncScope, a as SyncStatusState } from '../types-Cd7RhNqf.js';
-import { a as SyncStatus, S as SyncMode, C as CrudEntry, f as SyncError, F as FailedTransaction, h as CompletedTransaction, e as SyncMetrics, A as AbstractPowerSyncDatabase, b as ConnectionHealth } from '../types-afHtE1U_.js';
+import { b as SyncStatusTrackerOptions, P as PowerSyncRawStatus, U as Unsubscribe, M as MetricsCollectorOptions, d as SyncOperationData, H as HealthMonitorOptions, e as HealthCheckResult } from '../background-sync-ChCXW-EV.js';
+export { B as BackgroundSyncOptions, h as BackgroundSyncSystem, c as SyncControlActions, f as SyncEvent, g as SyncEventListener, S as SyncScope, a as SyncStatusState, i as defineBackgroundSyncTask, j as initializeBackgroundSync, k as isBackgroundSyncRegistered, r as registerBackgroundSync, u as unregisterBackgroundSync } from '../background-sync-ChCXW-EV.js';
+import { a as SyncStatus, S as SyncMode, C as CrudEntry, f as SyncError, F as FailedTransaction, h as CompletedTransaction, e as SyncMetrics, A as AbstractPowerSyncDatabase, b as ConnectionHealth } from '../types-CDqWh56B.js';
 import { AsyncStorageAdapter, LoggerAdapter } from '../platform/index.js';
-export { F as FailedUpload, a as FailedUploadStore, f as failedUploadStore } from '../failed-upload-store-C0cLxxPz.js';
 
 /**
  * Sync Status Tracker for @pol-studios/powersync
@@ -49,14 +48,19 @@ declare class SyncStatusTracker {
     private _listeners;
     private _syncModeListeners;
     private _forceNextUpload;
+    private _networkReachable;
+    private _networkRestoreTimer;
+    private readonly _networkRestoreDelayMs;
+    private _persistDebounceTimer;
     private _lastProgress;
     private _failedTransactions;
     private readonly _maxStoredFailures;
     private readonly _failureTTLMs;
     private _failureListeners;
     private _completedTransactions;
-    private readonly _maxCompletedHistory;
     private _completedListeners;
+    private _lastNotificationTime;
+    private _isAutoOffline;
     constructor(storage: AsyncStorageAdapter, logger: LoggerAdapter, options?: SyncStatusTrackerOptions);
     /**
      * Initialize the tracker by loading persisted state.
@@ -76,12 +80,7 @@ declare class SyncStatusTracker {
      */
     getSyncMode(): SyncMode;
     /**
-     * Get whether sync is paused (offline mode).
-     * @deprecated Use getSyncMode() instead
-     */
-    isPaused(): boolean;
-    /**
-     * Check if uploads are allowed based on current sync mode.
+     * Check if uploads are allowed based on current sync mode and network reachability.
      */
     canUpload(): boolean;
     /**
@@ -98,12 +97,22 @@ declare class SyncStatusTracker {
      */
     clearForceNextUpload(): void;
     /**
-     * Check if upload should proceed, considering force flag.
+     * Check if upload should proceed, considering force flag and network reachability.
      * NOTE: Does NOT auto-reset the flag - caller must use clearForceNextUpload()
      * after all uploads are complete. This prevents race conditions when
      * PowerSync calls uploadData() multiple times for multiple transactions.
      */
     shouldUpload(): boolean;
+    /**
+     * Set network reachability state.
+     * - When unreachable: Instantly blocks uploads (0ms)
+     * - When reachable: Delayed restore (1-2 seconds) to avoid flickering on brief disconnects
+     */
+    setNetworkReachable(reachable: boolean): void;
+    /**
+     * Get current network reachability state.
+     */
+    isNetworkReachable(): boolean;
     /**
      * Get pending mutations.
      */
@@ -129,10 +138,15 @@ declare class SyncStatusTracker {
      */
     setSyncMode(mode: SyncMode): Promise<void>;
     /**
-     * Set paused state.
-     * @deprecated Use setSyncMode() instead
+     * Get whether offline mode was set automatically (network loss) vs manually.
+     * Used to determine if sync should auto-resume when network returns.
      */
-    setPaused(paused: boolean): Promise<void>;
+    getIsAutoOffline(): boolean;
+    /**
+     * Set the auto-offline flag and persist it.
+     * @param isAuto - true if offline was set automatically, false if user chose offline
+     */
+    setIsAutoOffline(isAuto: boolean): Promise<void>;
     /**
      * Subscribe to status changes.
      * @returns Unsubscribe function
@@ -143,18 +157,17 @@ declare class SyncStatusTracker {
      * @returns Unsubscribe function
      */
     onSyncModeChange(listener: (mode: SyncMode) => void): Unsubscribe;
-    /**
-     * Subscribe to paused state changes.
-     * @deprecated Use onSyncModeChange() instead
-     * @returns Unsubscribe function
-     */
-    onPausedChange(listener: (isPaused: boolean) => void): Unsubscribe;
     /**
      * Record a transaction failure.
      * If a failure for the same entries already exists, updates the retry count.
      * Otherwise, creates a new failure record.
+     *
+     * @param preserveMetadata - Optional. If provided, preserves retryCount and firstFailedAt from a previous failure.
      */
-    recordTransactionFailure(entries: CrudEntry[], error: SyncError, isPermanent: boolean, affectedEntityIds: string[], affectedTables: string[]): void;
+    recordTransactionFailure(entries: CrudEntry[], error: SyncError, isPermanent: boolean, affectedEntityIds: string[], affectedTables: string[], preserveMetadata?: {
+        retryCount: number;
+        firstFailedAt: Date;
+    }): void;
     /**
      * Clear a specific failure by ID.
      */
@@ -163,6 +176,17 @@ declare class SyncStatusTracker {
      * Clear all failures.
      */
     clearAllFailures(): void;
+    /**
+     * Remove a failed transaction from tracking and return its entries.
+     * This is a "pop" operation - the failure is removed from the list.
+     *
+     * Note: The actual CRUD entries remain in PowerSync's ps_crud table
+     * until successfully uploaded. This just removes from our tracking.
+     *
+     * @param failureId - The failure ID to remove
+     * @returns The CrudEntry[] that were in the failure, or null if not found
+     */
+    takeFailureForRetry(failureId: string): CrudEntry[] | null;
     /**
      * Get failures affecting a specific entity.
      */
@@ -201,15 +225,63 @@ declare class SyncStatusTracker {
      * Clear completed transaction history.
      */
     clearCompletedHistory(): void;
+    /**
+     * Clear a specific completed transaction by ID.
+     */
+    clearCompletedItem(completedId: string): void;
     /**
      * Subscribe to completed transaction changes.
      * @returns Unsubscribe function
      */
     onCompletedChange(listener: (completed: CompletedTransaction[]) => void): Unsubscribe;
+    /**
+     * Get completed transactions that occurred AFTER the last notification time.
+     * This is used for displaying "X changes synced" notifications to avoid
+     * showing stale counts from historical completed transactions.
+     */
+    getNewCompletedTransactions(): CompletedTransaction[];
+    /**
+     * Mark notifications as seen by updating the last notification time.
+     * Call this when the notification is displayed or dismissed.
+     */
+    markNotificationsAsSeen(): void;
+    /**
+     * Get the timestamp of when notifications were last displayed/dismissed.
+     */
+    getLastNotificationTime(): number;
+    /**
+     * Schedule a debounced persist operation.
+     * This prevents race conditions from multiple rapid persist calls.
+     */
+    private _schedulePersist;
+    /**
+     * Persist completed and failed transactions to storage.
+     */
+    private _persistTransactions;
     private _hasStatusChanged;
+    /**
+     * Notify all listeners of status changes with throttling.
+     *
+     * Uses a "dirty" flag pattern: when throttled, we schedule a timer
+     * but get the CURRENT state when the timer fires, not the stale state
+     * from when the timer was scheduled. This ensures rapid state changes
+     * during the throttle window aren't lost.
+     */
     private _notifyListeners;
     private _notifyFailureListeners;
     private _notifyCompletedListeners;
+    /**
+     * Remap a CrudEntry from persisted JSON (handles toJSON() property remapping).
+     * PowerSync's CrudEntry.toJSON() remaps: opData→data, table→type, clientId→op_id, transactionId→tx_id
+     *
+     * @returns The remapped CrudEntry, or null if critical fields (table, id) are missing
+     */
+    private remapEntry;
+    /**
+     * Normalize CrudEntry array to plain objects to avoid CrudEntry.toJSON() remapping issues.
+     * PowerSync's CrudEntry.toJSON() remaps property names which breaks deserialization.
+     */
+    private normalizeEntries;
 }
 
 /**
@@ -361,6 +433,7 @@ declare class HealthMonitor {
     private _listeners;
     private _running;
     private _paused;
+    private _pendingTimers;
     constructor(logger: LoggerAdapter, options?: HealthMonitorOptions);
     /**
      * Set the database instance to monitor.
@@ -419,4 +492,196 @@ declare class HealthMonitor {
     private _withTimeout;
 }
 
-export { HealthCheckResult, HealthMonitor, HealthMonitorOptions, MetricsCollector, MetricsCollectorOptions, PowerSyncRawStatus, SyncOperationData, SyncStatusTracker, SyncStatusTrackerOptions, Unsubscribe };
+/**
+ * Dead Letter Queue (DLQ) for PowerSync
+ *
+ * Handles mutations that have permanently failed and cannot be automatically retried.
+ * These are operations that need manual intervention (data fix, user action, etc.).
+ *
+ * Use cases:
+ * - RLS policy violations (user doesn't have permission)
+ * - Foreign key constraint violations (referenced record doesn't exist)
+ * - Validation errors (data doesn't match schema)
+ * - Max retry exceeded for transient errors
+ *
+ * The DLQ gives users a way to:
+ * 1. See mutations that will never succeed automatically
+ * 2. Understand why they failed
+ * 3. Manually fix the underlying data issue
+ * 4. Retry after fixing
+ * 5. Permanently discard if no longer needed
+ */
+
+/**
+ * Reason why a mutation was moved to the dead letter queue
+ */
+type DeadLetterReason = 'permanent_error' | 'max_retries_exceeded' | 'manual_move' | 'conflict_unresolved' | 'data_corruption';
+/**
+ * A single entry in the dead letter queue
+ */
+interface DeadLetterEntry {
+    /** Unique identifier for this DLQ entry */
+    id: string;
+    /** The CRUD entries that failed */
+    entries: CrudEntry[];
+    /** The error that caused the failure */
+    error: SyncError;
+    /** Why this was moved to the DLQ */
+    reason: DeadLetterReason;
+    /** When this was moved to the DLQ */
+    movedAt: Date;
+    /** Table names affected */
+    affectedTables: string[];
+    /** Entity IDs affected */
+    affectedEntityIds: string[];
+    /** Number of retry attempts before being moved to DLQ */
+    retryAttempts: number;
+    /** Optional user note (e.g., why they're keeping it) */
+    userNote?: string;
+}
+/**
+ * Options for creating a DeadLetterQueue
+ */
+interface DeadLetterQueueOptions {
+    /** Async storage adapter for persistence */
+    storage: AsyncStorageAdapter;
+    /** Logger for debugging */
+    logger: LoggerAdapter;
+    /** Maximum entries to keep in DLQ */
+    maxEntries?: number;
+    /** Time-to-live for entries in ms (0 = never expire) */
+    entryTTLMs?: number;
+    /** Storage key for persistence */
+    storageKey?: string;
+}
+/**
+ * Listener for DLQ changes
+ */
+type DeadLetterQueueListener = (entries: DeadLetterEntry[]) => void;
+/**
+ * Dead Letter Queue for permanently failed mutations
+ *
+ * @example
+ * ```typescript
+ * const dlq = new DeadLetterQueue({
+ *   storage: asyncStorage,
+ *   logger: console,
+ * });
+ *
+ * await dlq.init();
+ *
+ * // Add a failed mutation
+ * await dlq.add({
+ *   id: 'dlq_123',
+ *   entries: failedCrudEntries,
+ *   error: { type: 'validation', message: 'RLS policy violation', ... },
+ *   reason: 'permanent_error',
+ *   movedAt: new Date(),
+ *   affectedTables: ['projects'],
+ *   affectedEntityIds: ['project-456'],
+ *   retryAttempts: 3,
+ * });
+ *
+ * // Subscribe to changes
+ * const unsubscribe = dlq.onQueueChange((entries) => {
+ *   console.log('DLQ has', entries.length, 'entries');
+ * });
+ *
+ * // Retry an entry (removes from DLQ)
+ * const entry = await dlq.retry('dlq_123');
+ * // Now re-submit entry.entries to PowerSync
+ * ```
+ */
+declare class DeadLetterQueue {
+    private readonly storage;
+    private readonly logger;
+    private readonly maxEntries;
+    private readonly entryTTLMs;
+    private readonly storageKey;
+    private entries;
+    private listeners;
+    private initialized;
+    constructor(options: DeadLetterQueueOptions);
+    /**
+     * Initialize the DLQ by loading persisted entries
+     */
+    init(): Promise<void>;
+    /**
+     * Dispose the DLQ (cleanup)
+     */
+    dispose(): void;
+    /**
+     * Add an entry to the dead letter queue
+     */
+    add(entry: DeadLetterEntry): Promise<void>;
+    /**
+     * Get all entries in the DLQ
+     */
+    getAll(): DeadLetterEntry[];
+    /**
+     * Get an entry by ID
+     */
+    get(id: string): DeadLetterEntry | null;
+    /**
+     * Get entries affecting a specific entity
+     */
+    getByEntityId(entityId: string): DeadLetterEntry[];
+    /**
+     * Get entries for a specific table
+     */
+    getByTable(tableName: string): DeadLetterEntry[];
+    /**
+     * Get entry count
+     */
+    get count(): number;
+    /**
+     * Check if DLQ has any entries
+     */
+    get hasEntries(): boolean;
+    /**
+     * Remove an entry from the DLQ (e.g., user discards it)
+     */
+    remove(id: string): Promise<DeadLetterEntry | null>;
+    /**
+     * Retry an entry - removes it from DLQ and returns it for resubmission
+     *
+     * @returns The entry that was removed (caller should resubmit to PowerSync)
+     */
+    retry(id: string): Promise<DeadLetterEntry | null>;
+    /**
+     * Clear all entries from the DLQ
+     */
+    clear(): Promise<void>;
+    /**
+     * Update user note on an entry
+     */
+    updateNote(id: string, note: string | undefined): Promise<void>;
+    /**
+     * Subscribe to DLQ changes
+     * @returns Unsubscribe function
+     */
+    onQueueChange(listener: DeadLetterQueueListener): () => void;
+    /**
+     * Get statistics about the DLQ
+     */
+    getStats(): {
+        totalEntries: number;
+        byReason: Record<DeadLetterReason, number>;
+        byTable: Record<string, number>;
+        oldestEntry: Date | null;
+        newestEntry: Date | null;
+    };
+    private persist;
+    private notifyListeners;
+    private cleanupExpired;
+}
+/**
+ * Generate a unique ID for a DLQ entry based on CRUD entries
+ */
+declare function generateDLQEntryId(entries: CrudEntry[]): string;
+/**
+ * Create a DeadLetterEntry from a failed transaction
+ */
+declare function createDeadLetterEntry(entries: CrudEntry[], error: SyncError, reason: DeadLetterReason, retryAttempts?: number): DeadLetterEntry;
+
+export { type DeadLetterEntry, DeadLetterQueue, type DeadLetterQueueListener, type DeadLetterQueueOptions, type DeadLetterReason, HealthCheckResult, HealthMonitor, HealthMonitorOptions, MetricsCollector, MetricsCollectorOptions, PowerSyncRawStatus, SyncOperationData, SyncStatusTracker, SyncStatusTrackerOptions, Unsubscribe, createDeadLetterEntry, generateDLQEntryId };

package/dist/sync/index.js

@@ -1,20 +1,32 @@
-import "../chunk-5FIMA26D.js";
+import {
+  DeadLetterQueue,
+  createDeadLetterEntry,
+  defineBackgroundSyncTask,
+  generateDLQEntryId,
+  initializeBackgroundSync,
+  isBackgroundSyncRegistered,
+  registerBackgroundSync,
+  unregisterBackgroundSync
+} from "../chunk-A4IBBWGO.js";
 import {
   HealthMonitor,
   MetricsCollector,
   SyncStatusTracker
-} from "../chunk-R4YFWQ3Q.js";
-import "../chunk-EJ23MXPQ.js";
-import {
-  FailedUploadStore,
-  failedUploadStore
-} from "../chunk-PAFBKNL3.js";
-import "../chunk-FPTDATY5.js";
+} from "../chunk-CUCAYK7Z.js";
+import "../chunk-24RDMMCL.js";
+import "../chunk-CGL33PL4.js";
+import "../chunk-VACPAAQZ.js";
 export {
-  FailedUploadStore,
+  DeadLetterQueue,
   HealthMonitor,
   MetricsCollector,
   SyncStatusTracker,
-  failedUploadStore
+  createDeadLetterEntry,
+  defineBackgroundSyncTask,
+  generateDLQEntryId,
+  initializeBackgroundSync,
+  isBackgroundSyncRegistered,
+  registerBackgroundSync,
+  unregisterBackgroundSync
 };
 //# sourceMappingURL=index.js.map