@pol-studios/powersync 1.0.0

package/dist/sync/index.js

@@ -0,0 +1,14 @@
+import "../chunk-7JQZBZ5N.js";
+import {
+  HealthMonitor,
+  MetricsCollector,
+  SyncStatusTracker
+} from "../chunk-CFCK2LHI.js";
+import "../chunk-NPNBGCRC.js";
+import "../chunk-CHRTN5PF.js";
+export {
+  HealthMonitor,
+  MetricsCollector,
+  SyncStatusTracker
+};
+//# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-Cd7RhNqf.d.ts

@@ -0,0 +1,224 @@
+import { a as SyncStatus, S as SyncMode, e as SyncMetrics, b as ConnectionHealth, f as SyncError } from './types-afHtE1U_.js';
+
+/**
+ * Sync Module Types for @pol-studios/powersync
+ *
+ * Defines interfaces for sync status tracking, metrics collection,
+ * and health monitoring.
+ */
+
+/**
+ * Defines a scope for selective sync.
+ * Used to limit which data is synced based on project or user context.
+ */
+interface SyncScope {
+    /**
+     * Scope type identifier.
+     * @example "project", "user", "organization"
+     */
+    type: string;
+    /**
+     * IDs to include in the scope.
+     * @example ["project-uuid-1", "project-uuid-2"]
+     */
+    ids: string[];
+    /**
+     * Optional metadata for the scope.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Internal state for the status tracker.
+ */
+interface SyncStatusState {
+    /** Current sync status */
+    status: SyncStatus;
+    /** Current sync mode */
+    syncMode: SyncMode;
+    /** Timestamp when status was last updated */
+    lastUpdated: Date;
+}
+/**
+ * Options for creating a SyncStatusTracker.
+ */
+interface SyncStatusTrackerOptions {
+    /**
+     * Throttle notifications to avoid excessive updates.
+     * @default 500 (ms)
+     */
+    notifyThrottleMs?: number;
+    /**
+     * Called when status changes.
+     */
+    onStatusChange?: (status: SyncStatus) => void;
+}
+/**
+ * Raw status from PowerSync database.
+ */
+interface PowerSyncRawStatus {
+    connected?: boolean;
+    connecting?: boolean;
+    hasSynced?: boolean;
+    lastSyncedAt?: Date | null;
+    dataFlowStatus?: {
+        uploading?: boolean;
+        downloading?: boolean;
+    };
+    downloadProgress?: {
+        downloadedFraction?: number;
+        downloadedOperations?: number;
+        totalOperations?: number;
+    };
+}
+/**
+ * Actions available for sync control.
+ */
+interface SyncControlActions {
+    /**
+     * Trigger a sync operation.
+     * Forces a fresh sync by disconnecting and reconnecting.
+     */
+    triggerSync: () => Promise<void>;
+    /**
+     * Sync Now - forces a full sync including uploads regardless of sync mode.
+     * Sets forceNextUpload flag and reconnects.
+     */
+    syncNow: () => Promise<void>;
+    /**
+     * Pause sync operations.
+     * Sets sync mode to 'offline' and disconnects.
+     */
+    pause: () => Promise<void>;
+    /**
+     * Resume sync operations.
+     * Sets sync mode to 'push-pull' and reconnects.
+     */
+    resume: () => Promise<void>;
+    /**
+     * Set the sync mode.
+     * @param mode - The sync mode to set ('push-pull', 'pull-only', or 'offline')
+     */
+    setSyncMode: (mode: SyncMode) => Promise<void>;
+    /**
+     * Disconnect from the PowerSync service.
+     */
+    disconnect: () => Promise<void>;
+    /**
+     * Set the sync scope for selective sync.
+     * @param scope - The scope to apply
+     */
+    setScope: (scope: SyncScope | null) => void;
+}
+/**
+ * Options for creating a MetricsCollector.
+ */
+interface MetricsCollectorOptions {
+    /**
+     * Storage key for persisting metrics.
+     * @default "@pol-studios/powersync-metrics"
+     */
+    storageKey?: string;
+    /**
+     * Whether to persist metrics to storage.
+     * @default true
+     */
+    persistMetrics?: boolean;
+    /**
+     * Called when metrics change.
+     */
+    onMetricsChange?: (metrics: SyncMetrics) => void;
+}
+/**
+ * Data to record for a sync operation.
+ */
+interface SyncOperationData {
+    /** Duration of the sync in milliseconds */
+    durationMs: number;
+    /** Whether the sync was successful */
+    success: boolean;
+    /** Number of operations downloaded (optional) */
+    operationsDownloaded?: number;
+    /** Number of operations uploaded (optional) */
+    operationsUploaded?: number;
+    /** Error that occurred, if any */
+    error?: Error;
+}
+/**
+ * Options for creating a HealthMonitor.
+ */
+interface HealthMonitorOptions {
+    /**
+     * Interval between health checks in milliseconds.
+     * @default 30000 (30 seconds)
+     */
+    checkIntervalMs?: number;
+    /**
+     * Timeout for health check queries in milliseconds.
+     * @default 5000 (5 seconds)
+     */
+    checkTimeoutMs?: number;
+    /**
+     * Latency threshold above which connection is considered degraded.
+     * @default 1000 (1 second)
+     */
+    degradedThresholdMs?: number;
+    /**
+     * Number of consecutive failures before marking as disconnected.
+     * @default 2
+     */
+    maxConsecutiveFailures?: number;
+    /**
+     * Called when health status changes.
+     */
+    onHealthChange?: (health: ConnectionHealth) => void;
+}
+/**
+ * Result of a health check.
+ */
+interface HealthCheckResult {
+    /** Whether the check succeeded */
+    success: boolean;
+    /** Latency in milliseconds (if successful) */
+    latencyMs?: number;
+    /** Error that occurred (if failed) */
+    error?: Error;
+    /** Timestamp of the check */
+    timestamp: Date;
+}
+/**
+ * Events emitted by sync components.
+ */
+type SyncEvent = {
+    type: 'status_changed';
+    status: SyncStatus;
+} | {
+    type: 'health_changed';
+    health: ConnectionHealth;
+} | {
+    type: 'metrics_updated';
+    metrics: SyncMetrics;
+} | {
+    type: 'sync_started';
+} | {
+    type: 'sync_completed';
+    durationMs: number;
+} | {
+    type: 'sync_failed';
+    error: SyncError;
+} | {
+    type: 'paused';
+} | {
+    type: 'resumed';
+} | {
+    type: 'disconnected';
+};
+/**
+ * Listener for sync events.
+ */
+type SyncEventListener = (event: SyncEvent) => void;
+/**
+ * Function to unsubscribe from a listener.
+ */
+type Unsubscribe = () => void;
+
+export type { HealthMonitorOptions as H, MetricsCollectorOptions as M, PowerSyncRawStatus as P, SyncScope as S, Unsubscribe as U, SyncStatusState as a, SyncStatusTrackerOptions as b, SyncControlActions as c, SyncOperationData as d, HealthCheckResult as e, SyncEvent as f, SyncEventListener as g };

package/dist/types-afHtE1U_.d.ts

@@ -0,0 +1,391 @@
+/**
+ * Core types for @pol-studios/powersync
+ *
+ * This module contains all the shared TypeScript interfaces for sync status,
+ * connection health, storage information, metrics, and cache statistics.
+ */
+/**
+ * Unified sync state for a specific entity.
+ * Used by useEntitySyncStatus hook to provide a simple status for UI rendering.
+ *
+ * State transitions:
+ * - 'idle' → No pending operations, no errors
+ * - 'saving' → Local changes detected but not yet syncing (reserved for future local-only tracking)
+ * - 'syncing' → Changes are being uploaded to the server
+ * - 'synced' → Recently synced successfully (within last few seconds)
+ * - 'error' → Permanent failure that needs user attention
+ */
+type EntitySyncState = 'idle' | 'saving' | 'syncing' | 'synced' | 'error';
+/**
+ * Sync mode controlling data flow behavior.
+ * - 'push-pull': Normal bidirectional sync (upload and download)
+ * - 'pull-only': Download updates but don't upload local changes
+ * - 'offline': No sync at all (fully disconnected)
+ */
+type SyncMode = 'push-pull' | 'pull-only' | 'offline';
+/**
+ * CrudEntry represents a pending CRUD operation in the sync queue
+ */
+interface CrudEntry {
+    /** Unique identifier for the record (typically UUID) */
+    id: string;
+    /** Client-side ID for tracking */
+    clientId: number;
+    /** The type of operation */
+    op: "PUT" | "PATCH" | "DELETE";
+    /** The table name */
+    table: string;
+    /** The data being modified (for PUT/PATCH operations) */
+    opData?: Record<string, unknown>;
+    /** Transaction ID for grouping operations */
+    transactionId?: number;
+}
+/**
+ * Download progress information during sync
+ */
+interface DownloadProgress {
+    /** Number of operations downloaded so far */
+    current: number;
+    /** Total number of operations to download */
+    target: number;
+    /** Percentage complete (0-100) */
+    percentage: number;
+}
+/**
+ * Current sync status from PowerSync
+ */
+interface SyncStatus {
+    /** Whether connected to the PowerSync service */
+    connected: boolean;
+    /** Whether currently attempting to connect */
+    connecting: boolean;
+    /** Whether initial sync has completed */
+    hasSynced: boolean;
+    /** Timestamp of last successful sync */
+    lastSyncedAt: Date | null;
+    /** Whether currently uploading local changes */
+    uploading: boolean;
+    /** Whether currently downloading remote changes */
+    downloading: boolean;
+    /** Download progress details */
+    downloadProgress: DownloadProgress | null;
+    /** Failed transactions that need attention */
+    failedTransactions: FailedTransaction[];
+    /** Whether there are any upload errors */
+    hasUploadErrors: boolean;
+    /** Count of permanent errors that need user action */
+    permanentErrorCount: number;
+}
+/**
+ * Connection health status for monitoring database connectivity
+ */
+interface ConnectionHealth {
+    /** Current connection status */
+    status: "healthy" | "degraded" | "disconnected";
+    /** Last measured query latency in milliseconds */
+    latency: number | null;
+    /** Timestamp of the last health check */
+    lastHealthCheck: Date | null;
+    /** Number of consecutive health check failures */
+    consecutiveFailures: number;
+    /** Total reconnection attempts since last successful connection */
+    reconnectAttempts: number;
+}
+/**
+ * Storage information with detailed breakdown
+ */
+interface StorageInfo {
+    /** Actual data bytes (excluding free pages) */
+    used: number;
+    /** Formatted used storage string (e.g., "1.5 GB") */
+    usedFormatted: string;
+    /** Total file size on disk */
+    total: number;
+    /** Formatted total storage string */
+    totalFormatted: string;
+    /** Free pages that can be reclaimed via VACUUM */
+    reclaimable: number;
+    /** Formatted reclaimable storage string */
+    reclaimableFormatted: string;
+}
+/**
+ * Device storage quota information
+ */
+interface StorageQuota {
+    /** Free space available on device in bytes */
+    deviceFreeSpace: number;
+    /** Current database file size in bytes */
+    databaseSize: number;
+    /** Warning threshold in bytes */
+    warningThreshold: number;
+    /** Critical threshold in bytes */
+    criticalThreshold: number;
+    /** Current storage status based on free space vs thresholds */
+    status: "ok" | "warning" | "critical";
+}
+/**
+ * Sync operation metrics for monitoring and debugging
+ */
+interface SyncMetrics {
+    /** Total number of sync operations attempted */
+    totalSyncs: number;
+    /** Number of successful sync operations */
+    successfulSyncs: number;
+    /** Number of failed sync operations */
+    failedSyncs: number;
+    /** Duration of the last sync in milliseconds */
+    lastSyncDuration: number | null;
+    /** Average sync duration in milliseconds */
+    averageSyncDuration: number | null;
+    /** Total bytes downloaded across all syncs */
+    totalDataDownloaded: number;
+    /** Total bytes uploaded across all syncs */
+    totalDataUploaded: number;
+    /** Last sync error details */
+    lastError: SyncError | null;
+}
+/**
+ * Details about a sync error
+ */
+interface SyncError {
+    /** Error type classification */
+    type: SyncErrorType;
+    /** Error message (original/technical) */
+    message: string;
+    /** User-friendly error message for display */
+    userMessage: string;
+    /** When the error occurred */
+    timestamp: Date;
+    /** PostgreSQL error code if available */
+    pgCode?: string;
+    /** Whether this is a permanent failure (requires user action) */
+    isPermanent: boolean;
+}
+/**
+ * Categorized error types for sync operations
+ */
+type SyncErrorType = "network" | "auth" | "server" | "conflict" | "validation" | "quota" | "unknown";
+/**
+ * Represents a successfully completed CRUD transaction.
+ * Used to track recent sync activity for UI feedback.
+ */
+interface CompletedTransaction {
+    /** Unique identifier for this completion record */
+    id: string;
+    /** All CRUD entries that were successfully synced */
+    entries: CrudEntry[];
+    /** When the transaction was completed */
+    completedAt: Date;
+    /** Table names involved in this transaction */
+    affectedTables: string[];
+    /** Entity IDs affected by this transaction */
+    affectedEntityIds: string[];
+}
+/**
+ * Represents a failed CRUD transaction that needs attention.
+ *
+ * PowerSync uses atomic transactions - when any operation fails,
+ * the entire transaction fails and will be retried. We track failures
+ * at the transaction level to avoid data integrity issues.
+ */
+interface FailedTransaction {
+    /** Unique ID for this failure record */
+    id: string;
+    /** All CRUD entries in the failed transaction */
+    entries: CrudEntry[];
+    /** The error that caused the failure */
+    error: SyncError;
+    /** Number of times PowerSync has retried this transaction */
+    retryCount: number;
+    /** When the failure first occurred */
+    firstFailedAt: Date;
+    /** When the last retry failed */
+    lastFailedAt: Date;
+    /** Whether this is a permanent failure that needs user action */
+    isPermanent: boolean;
+    /** Entity IDs affected (for UI filtering by entity) */
+    affectedEntityIds: string[];
+    /** Table names involved in this transaction */
+    affectedTables: string[];
+}
+/**
+ * Result of classifying a Supabase/PostgreSQL error
+ */
+interface ClassifiedError {
+    /** The error type category */
+    type: SyncErrorType;
+    /** Whether this error is permanent (won't be fixed by retrying) */
+    isPermanent: boolean;
+    /** Whether this is a conflict with existing data */
+    isConflict: boolean;
+    /** PostgreSQL error code if available */
+    pgCode?: string;
+    /** User-friendly error message */
+    userMessage: string;
+}
+/**
+ * Result of database compaction (VACUUM) operation
+ */
+interface CompactResult {
+    /** Whether the compaction was successful */
+    success: boolean;
+    /** Number of bytes reclaimed */
+    bytesReclaimed: number;
+    /** Error message if compaction failed */
+    error?: string;
+}
+/**
+ * Result of database integrity check
+ */
+interface IntegrityResult {
+    /** Whether the database is healthy */
+    isHealthy: boolean;
+    /** List of issues found (empty if healthy) */
+    issues: string[];
+}
+/**
+ * Statistics for a single cached table
+ */
+interface TableCacheStats {
+    /** User-friendly table name */
+    name: string;
+    /** Internal PowerSync table name (e.g., "ps_data__TableName") */
+    internalName: string;
+    /** Number of rows in the table */
+    rowCount: number;
+    /** Storage size in bytes for this table */
+    storageBytes: number;
+    /** Formatted storage size string */
+    storageFormatted: string;
+    /** Whether this is an internal PowerSync table */
+    isInternal: boolean;
+    /** Whether this is a local-only table (not synced) */
+    isLocalOnly: boolean;
+}
+/**
+ * Complete cache statistics for the PowerSync database
+ */
+interface CacheStats {
+    /** Statistics for each table */
+    tables: TableCacheStats[];
+    /** Total number of user tables (excluding internal) */
+    totalTables: number;
+    /** Total number of rows across all user tables */
+    totalRows: number;
+    /** Detailed storage information */
+    storage: StorageInfo;
+}
+/**
+ * Abstract interface for PowerSync database operations.
+ * This allows the package to work with different PowerSync implementations
+ * (react-native, web) without direct dependencies.
+ */
+interface AbstractPowerSyncDatabase {
+    /** Execute a query and return all results */
+    getAll<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Execute a query and return first result or null */
+    get<T>(sql: string, params?: unknown[]): Promise<T | null>;
+    /** Execute a SQL statement (INSERT, UPDATE, DELETE) */
+    execute(sql: string, params?: unknown[]): Promise<{
+        rowsAffected: number;
+    }>;
+    /** Whether the database is currently connected */
+    connected: boolean;
+    /** Current sync status */
+    currentStatus: {
+        connected: boolean;
+        connecting: boolean;
+        hasSynced: boolean;
+        lastSyncedAt: Date | null;
+        dataFlowStatus?: {
+            uploading: boolean;
+            downloading: boolean;
+        };
+        downloadProgress?: {
+            downloadedFraction: number;
+            downloadedOperations: number;
+            totalOperations: number;
+        };
+    };
+    /** Initialize the database */
+    init(): Promise<void>;
+    /** Close the database connection */
+    close(): Promise<void>;
+    /** Connect to the PowerSync service */
+    connect(connector: PowerSyncBackendConnector): Promise<void>;
+    /** Disconnect from the PowerSync service */
+    disconnect(): Promise<void>;
+    /** Register a listener for status changes */
+    registerListener(listener: {
+        statusChanged?: (status: unknown) => void;
+    }): () => void;
+    /** Get the next pending CRUD transaction */
+    getNextCrudTransaction(): Promise<CrudTransaction | null>;
+    /** Watch a query for changes with callback-based API */
+    watch(sql: string, params: unknown[], callbacks: {
+        onResult: (results: {
+            rows?: {
+                _array?: unknown[];
+            };
+        }) => void;
+        onError?: (error: Error) => void;
+    }, options?: {
+        signal?: AbortSignal;
+        tables?: string[];
+        throttleMs?: number;
+    }): void;
+}
+/**
+ * A transaction containing pending CRUD operations
+ */
+interface CrudTransaction {
+    /** The CRUD operations in this transaction */
+    crud: CrudEntry[];
+    /** Mark the transaction as complete */
+    complete(): Promise<void>;
+}
+/**
+ * Backend connector interface for PowerSync
+ */
+interface PowerSyncBackendConnector {
+    /** Fetch credentials for authentication */
+    fetchCredentials(): Promise<{
+        endpoint: string;
+        token: string;
+        expiresAt?: Date;
+    }>;
+    /** Upload local changes to the backend */
+    uploadData(database: AbstractPowerSyncDatabase): Promise<void>;
+}
+/** Row returned by: SELECT name FROM sqlite_master */
+interface SqliteTableRow {
+    name: string;
+}
+/** Row returned by: SELECT name, SUM(pgsize) as size FROM dbstat GROUP BY name */
+interface DbStatRow {
+    name: string;
+    size: number;
+}
+/** Row returned by: SELECT COUNT(*) as c FROM ... */
+interface CountRow {
+    c: number;
+}
+/** Row returned by: PRAGMA page_size */
+interface PageSizeRow {
+    page_size: number;
+}
+/** Row returned by: PRAGMA page_count */
+interface PageCountRow {
+    page_count: number;
+}
+/** Row returned by: PRAGMA freelist_count */
+interface FreelistCountRow {
+    freelist_count: number;
+}
+/** Row returned by: PRAGMA integrity_check */
+interface IntegrityCheckRow {
+    integrity_check: string;
+    [key: string]: unknown;
+}
+
+export type { AbstractPowerSyncDatabase as A, CrudEntry as C, DownloadProgress as D, EntitySyncState as E, FailedTransaction as F, IntegrityResult as I, PowerSyncBackendConnector as P, SyncMode as S, TableCacheStats as T, SyncStatus as a, ConnectionHealth as b, StorageInfo as c, StorageQuota as d, SyncMetrics as e, SyncError as f, SyncErrorType as g, CompletedTransaction as h, ClassifiedError as i, CompactResult as j, CacheStats as k, CrudTransaction as l, SqliteTableRow as m, DbStatRow as n, CountRow as o, PageSizeRow as p, PageCountRow as q, FreelistCountRow as r, IntegrityCheckRow as s };