@pol-studios/powersync 1.0.0

package/dist/provider/index.js

@@ -0,0 +1,63 @@
+import {
+  AttachmentQueueContext,
+  ConnectionHealthContext,
+  PowerSyncContext,
+  PowerSyncProvider,
+  SyncMetricsContext,
+  SyncStatusContext,
+  useAttachmentQueue,
+  useConnectionHealth,
+  useDatabase,
+  useDownloadProgress,
+  useEntitySyncStatus,
+  useIsSyncing,
+  useOnlineStatus,
+  usePendingMutations,
+  usePlatform,
+  usePowerSync,
+  useSyncActivity,
+  useSyncControl,
+  useSyncMetrics,
+  useSyncMode,
+  useSyncStatus,
+  useUploadStatus
+} from "../chunk-Q3LFFMRR.js";
+import "../chunk-GBGATW2S.js";
+import {
+  DEFAULT_CONNECTION_HEALTH,
+  DEFAULT_SYNC_CONFIG,
+  DEFAULT_SYNC_METRICS,
+  DEFAULT_SYNC_STATUS
+} from "../chunk-CFCK2LHI.js";
+import "../chunk-NPNBGCRC.js";
+import "../chunk-FLHDT4TS.js";
+import "../chunk-CHRTN5PF.js";
+export {
+  AttachmentQueueContext,
+  ConnectionHealthContext,
+  DEFAULT_CONNECTION_HEALTH,
+  DEFAULT_SYNC_CONFIG,
+  DEFAULT_SYNC_METRICS,
+  DEFAULT_SYNC_STATUS,
+  PowerSyncContext,
+  PowerSyncProvider,
+  SyncMetricsContext,
+  SyncStatusContext,
+  useAttachmentQueue,
+  useConnectionHealth,
+  useDatabase,
+  useDownloadProgress,
+  useEntitySyncStatus,
+  useIsSyncing,
+  useOnlineStatus,
+  usePendingMutations,
+  usePlatform,
+  usePowerSync,
+  useSyncActivity,
+  useSyncControl,
+  useSyncMetrics,
+  useSyncMode,
+  useSyncStatus,
+  useUploadStatus
+};
+//# sourceMappingURL=index.js.map

package/dist/provider/index.js.map

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

package/dist/supabase-connector-D14-kl5v.d.ts

@@ -0,0 +1,232 @@
+import { C as CrudEntry, i as ClassifiedError, P as PowerSyncBackendConnector, A as AbstractPowerSyncDatabase } from './types-afHtE1U_.js';
+import { SupabaseClient } from '@supabase/supabase-js';
+import { LoggerAdapter } from './platform/index.js';
+
+/**
+ * Connector Types for @pol-studios/powersync
+ *
+ * Defines interfaces for PowerSync backend connectors.
+ */
+
+/**
+ * Options for creating a SupabaseConnector
+ */
+interface SupabaseConnectorOptions {
+    /** Supabase client instance */
+    supabaseClient: SupabaseClient;
+    /** PowerSync service URL */
+    powerSyncUrl: string;
+    /**
+     * Optional: Custom schema routing function.
+     * Determines which Supabase schema a table belongs to.
+     * @default Returns 'public' for all tables
+     */
+    schemaRouter?: SchemaRouter;
+    /**
+     * Optional: Custom CRUD handler for complex mutations.
+     * Allows overriding default upsert/update/delete behavior.
+     */
+    crudHandler?: CrudHandler;
+    /** Logger for debugging */
+    logger?: LoggerAdapter;
+    /** Called when a transaction is successfully uploaded */
+    onTransactionSuccess?: (entries: CrudEntry[]) => void;
+    /** Called when a transaction fails to upload */
+    onTransactionFailure?: (entries: CrudEntry[], error: Error, classified: ClassifiedError) => void;
+    /** Called when a transaction is fully completed (after transaction.complete()) */
+    onTransactionComplete?: (entries: CrudEntry[]) => void;
+    /** Function to check if upload should proceed. Used for sync mode gating. */
+    shouldUpload?: () => boolean;
+}
+/**
+ * Configuration passed to PowerSyncProvider for connector setup
+ */
+interface ConnectorConfig {
+    /**
+     * Custom schema routing function.
+     * Determines which Supabase schema a table belongs to.
+     * @default Returns 'public' for all tables
+     *
+     * @example
+     * ```typescript
+     * schemaRouter: (table) => {
+     *   if (['Profile', 'Comment'].includes(table)) return 'core';
+     *   return 'public';
+     * }
+     * ```
+     */
+    schemaRouter?: SchemaRouter;
+    /**
+     * Custom CRUD handler for complex mutations.
+     * @default Uses standard upsert/update/delete operations
+     */
+    crudHandler?: CrudHandler;
+    /**
+     * Token refresh configuration.
+     */
+    tokenRefresh?: {
+        /** Refresh token when it expires within this many seconds (default: 60) */
+        refreshThresholdSeconds?: number;
+    };
+}
+/**
+ * Function that determines which Supabase schema a table belongs to.
+ *
+ * @param tableName - The name of the table
+ * @returns The schema name (e.g., 'public', 'core')
+ */
+type SchemaRouter = (tableName: string) => string;
+/**
+ * Default schema router that returns 'public' for all tables
+ */
+declare const defaultSchemaRouter: SchemaRouter;
+/**
+ * Custom handler for CRUD operations.
+ *
+ * Return `true` from a handler to indicate the operation was handled.
+ * Return `false` to fall back to default behavior.
+ */
+interface CrudHandler {
+    /**
+     * Handle a PUT operation (insert or replace).
+     * @param entry - The CRUD entry
+     * @param supabase - Supabase client
+     * @param schema - The resolved schema for this table
+     * @returns true if handled, false to use default behavior
+     */
+    handlePut?(entry: CrudEntry, supabase: SupabaseClient, schema: string): Promise<boolean>;
+    /**
+     * Handle a PATCH operation (update).
+     * @param entry - The CRUD entry
+     * @param supabase - Supabase client
+     * @param schema - The resolved schema for this table
+     * @returns true if handled, false to use default behavior
+     */
+    handlePatch?(entry: CrudEntry, supabase: SupabaseClient, schema: string): Promise<boolean>;
+    /**
+     * Handle a DELETE operation.
+     * @param entry - The CRUD entry
+     * @param supabase - Supabase client
+     * @param schema - The resolved schema for this table
+     * @returns true if handled, false to use default behavior
+     */
+    handleDelete?(entry: CrudEntry, supabase: SupabaseClient, schema: string): Promise<boolean>;
+}
+/**
+ * Credentials returned by fetchCredentials
+ */
+interface PowerSyncCredentials {
+    /** PowerSync service endpoint URL */
+    endpoint: string;
+    /** JWT token for authentication */
+    token: string;
+    /** When the token expires */
+    expiresAt?: Date;
+}
+
+/**
+ * Supabase Connector for PowerSync
+ *
+ * A generic, configurable connector that handles:
+ * - Authentication with Supabase JWT tokens
+ * - Uploading local changes back to Supabase
+ * - Schema routing for multi-schema databases
+ * - Custom CRUD handling for complex operations
+ */
+
+/**
+ * Generic Supabase connector for PowerSync.
+ *
+ * This connector handles authentication and CRUD uploads to Supabase.
+ * It supports configurable schema routing and custom CRUD handlers
+ * for complex use cases.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const connector = new SupabaseConnector({
+ *   supabaseClient: supabase,
+ *   powerSyncUrl: 'https://your-powersync-instance.com',
+ * });
+ * ```
+ *
+ * @example With schema routing
+ * ```typescript
+ * const connector = new SupabaseConnector({
+ *   supabaseClient: supabase,
+ *   powerSyncUrl: 'https://your-powersync-instance.com',
+ *   schemaRouter: (table) => {
+ *     if (['Profile', 'Comment', 'CommentSection'].includes(table)) {
+ *       return 'core';
+ *     }
+ *     return 'public';
+ *   },
+ * });
+ * ```
+ *
+ * @example With custom CRUD handler
+ * ```typescript
+ * const connector = new SupabaseConnector({
+ *   supabaseClient: supabase,
+ *   powerSyncUrl: 'https://your-powersync-instance.com',
+ *   crudHandler: {
+ *     async handlePut(entry, supabase, schema) {
+ *       // Custom handling for specific tables
+ *       if (entry.table === 'SpecialTable') {
+ *         await myCustomUpsert(entry);
+ *         return true; // Handled
+ *       }
+ *       return false; // Use default
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare class SupabaseConnector implements PowerSyncBackendConnector {
+    private readonly supabase;
+    private readonly powerSyncUrl;
+    private readonly schemaRouter;
+    private readonly crudHandler?;
+    private readonly logger?;
+    private readonly onTransactionSuccess?;
+    private readonly onTransactionFailure?;
+    private readonly onTransactionComplete?;
+    private readonly shouldUploadFn?;
+    private activeProjectIds;
+    constructor(options: SupabaseConnectorOptions);
+    /**
+     * Set the active project IDs for scoped sync.
+     * Call this when user selects/opens projects.
+     */
+    setActiveProjectIds(projectIds: string[]): void;
+    /**
+     * Get the current active project IDs.
+     */
+    getActiveProjectIds(): string[];
+    /**
+     * Get credentials for PowerSync connection.
+     * Uses Supabase session token.
+     *
+     * Note: Token refresh is handled by Supabase's startAutoRefresh() which must be
+     * called on app initialization. getSession() returns the auto-refreshed token.
+     */
+    fetchCredentials(): Promise<PowerSyncCredentials>;
+    /**
+     * Upload local changes to Supabase.
+     * Called automatically by PowerSync when there are pending uploads.
+     */
+    uploadData(database: AbstractPowerSyncDatabase): Promise<void>;
+    /**
+     * Process a single CRUD operation.
+     *
+     * UUID-native tables (public schema, post-migration) use `id` as the UUID column.
+     * Core schema tables (Profile, Comment, CommentSection) still use a separate `uuid` column.
+     */
+    /**
+     * Process a single CRUD operation.
+     *
+     * All synced tables use `id` as their UUID primary key column.
+     */
+    private processCrudEntry;
+}
+
+export { type ConnectorConfig as C, type PowerSyncCredentials as P, SupabaseConnector as S, type SupabaseConnectorOptions as a, type SchemaRouter as b, type CrudHandler as c, defaultSchemaRouter as d };

package/dist/sync/index.d.ts

@@ -0,0 +1,421 @@
+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 { AsyncStorageAdapter, LoggerAdapter } from '../platform/index.js';
+
+/**
+ * Sync Status Tracker for @pol-studios/powersync
+ *
+ * Tracks and normalizes PowerSync status changes, providing a consistent
+ * interface for status updates with throttling support.
+ */
+
+/**
+ * Tracks sync status from PowerSync and provides normalized updates.
+ *
+ * Features:
+ * - Normalizes raw PowerSync status to a consistent format
+ * - Throttles notifications to prevent UI thrashing
+ * - Tracks pending mutations count
+ * - Persists and restores paused state
+ *
+ * @example
+ * ```typescript
+ * const tracker = new SyncStatusTracker({
+ *   storage,
+ *   logger,
+ *   onStatusChange: (status) => console.log('Status:', status),
+ * });
+ *
+ * // Register with PowerSync
+ * db.registerListener({
+ *   statusChanged: (rawStatus) => tracker.handleStatusChange(rawStatus),
+ * });
+ *
+ * // Get current status
+ * const status = tracker.getStatus();
+ * ```
+ */
+declare class SyncStatusTracker {
+    private readonly storage;
+    private readonly logger;
+    private readonly notifyThrottleMs;
+    private readonly onStatusChange?;
+    private _state;
+    private _pendingMutations;
+    private _lastNotifyTime;
+    private _notifyTimer;
+    private _listeners;
+    private _syncModeListeners;
+    private _forceNextUpload;
+    private _lastProgress;
+    private _failedTransactions;
+    private readonly _maxStoredFailures;
+    private readonly _failureTTLMs;
+    private _failureListeners;
+    private _completedTransactions;
+    private readonly _maxCompletedHistory;
+    private _completedListeners;
+    constructor(storage: AsyncStorageAdapter, logger: LoggerAdapter, options?: SyncStatusTrackerOptions);
+    /**
+     * Initialize the tracker by loading persisted state.
+     * Includes migration from old isPaused boolean to new syncMode.
+     */
+    init(): Promise<void>;
+    /**
+     * Dispose the tracker and clear timers.
+     */
+    dispose(): void;
+    /**
+     * Get the current sync status.
+     */
+    getStatus(): SyncStatus;
+    /**
+     * Get the current sync mode.
+     */
+    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.
+     */
+    canUpload(): boolean;
+    /**
+     * Check if downloads are allowed based on current sync mode.
+     */
+    canDownload(): boolean;
+    /**
+     * Set the force next upload flag for "Sync Now" functionality.
+     */
+    setForceNextUpload(force: boolean): void;
+    /**
+     * Clear the force next upload flag.
+     * Should be called after all pending uploads have been processed.
+     */
+    clearForceNextUpload(): void;
+    /**
+     * Check if upload should proceed, considering force flag.
+     * 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;
+    /**
+     * Get pending mutations.
+     */
+    getPendingMutations(): CrudEntry[];
+    /**
+     * Get pending mutation count.
+     */
+    getPendingCount(): number;
+    /**
+     * Handle a raw status update from PowerSync.
+     */
+    handleStatusChange(rawStatus: PowerSyncRawStatus): void;
+    /**
+     * Update pending mutations from a CRUD transaction.
+     */
+    updatePendingMutations(mutations: CrudEntry[]): void;
+    /**
+     * Valid sync modes for runtime validation.
+     */
+    private static readonly VALID_SYNC_MODES;
+    /**
+     * Set the sync mode.
+     */
+    setSyncMode(mode: SyncMode): Promise<void>;
+    /**
+     * Set paused state.
+     * @deprecated Use setSyncMode() instead
+     */
+    setPaused(paused: boolean): Promise<void>;
+    /**
+     * Subscribe to status changes.
+     * @returns Unsubscribe function
+     */
+    onStatusUpdate(listener: (status: SyncStatus) => void): Unsubscribe;
+    /**
+     * Subscribe to sync mode changes.
+     * @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.
+     */
+    recordTransactionFailure(entries: CrudEntry[], error: SyncError, isPermanent: boolean, affectedEntityIds: string[], affectedTables: string[]): void;
+    /**
+     * Clear a specific failure by ID.
+     */
+    clearFailure(failureId: string): void;
+    /**
+     * Clear all failures.
+     */
+    clearAllFailures(): void;
+    /**
+     * Get failures affecting a specific entity.
+     */
+    getFailuresForEntity(entityId: string): FailedTransaction[];
+    /**
+     * Get all failed transactions.
+     */
+    getFailedTransactions(): FailedTransaction[];
+    /**
+     * Check if there are any upload errors.
+     */
+    hasUploadErrors(): boolean;
+    /**
+     * Get count of permanent errors.
+     */
+    getPermanentErrorCount(): number;
+    /**
+     * Subscribe to failure changes.
+     * @returns Unsubscribe function
+     */
+    onFailureChange(listener: (failures: FailedTransaction[]) => void): Unsubscribe;
+    /**
+     * Clean up stale failures (older than TTL).
+     */
+    cleanupStaleFailures(): void;
+    /**
+     * Record a successfully completed transaction.
+     * Creates a CompletedTransaction record and adds it to history.
+     */
+    recordTransactionComplete(entries: CrudEntry[]): void;
+    /**
+     * Get all completed transactions.
+     */
+    getCompletedTransactions(): CompletedTransaction[];
+    /**
+     * Clear completed transaction history.
+     */
+    clearCompletedHistory(): void;
+    /**
+     * Subscribe to completed transaction changes.
+     * @returns Unsubscribe function
+     */
+    onCompletedChange(listener: (completed: CompletedTransaction[]) => void): Unsubscribe;
+    private _hasStatusChanged;
+    private _notifyListeners;
+    private _notifyFailureListeners;
+    private _notifyCompletedListeners;
+}
+
+/**
+ * Sync Metrics Collector for @pol-studios/powersync
+ *
+ * Collects and persists sync operation metrics for monitoring and debugging.
+ */
+
+/**
+ * Collects sync metrics including operation counts, timing, and errors.
+ *
+ * Features:
+ * - Tracks sync operation success/failure rates
+ * - Calculates average sync duration
+ * - Monitors data transfer amounts
+ * - Persists metrics to storage for continuity across sessions
+ * - Records last error for debugging
+ *
+ * @example
+ * ```typescript
+ * const collector = new MetricsCollector({
+ *   storage,
+ *   logger,
+ *   onMetricsChange: (metrics) => updateUI(metrics),
+ * });
+ *
+ * // Start tracking a sync
+ * const startTime = Date.now();
+ *
+ * // On sync complete
+ * collector.recordSync({
+ *   durationMs: Date.now() - startTime,
+ *   success: true,
+ *   operationsDownloaded: 150,
+ * });
+ *
+ * // Get current metrics
+ * const metrics = collector.getMetrics();
+ * ```
+ */
+declare class MetricsCollector {
+    private readonly storage;
+    private readonly logger;
+    private readonly storageKey;
+    private readonly persistMetrics;
+    private readonly onMetricsChange?;
+    private _metrics;
+    private _listeners;
+    private _initialized;
+    private _syncStartTime;
+    private _wasSyncing;
+    constructor(storage: AsyncStorageAdapter, logger: LoggerAdapter, options?: MetricsCollectorOptions);
+    /**
+     * Initialize the collector by loading persisted metrics.
+     */
+    init(): Promise<void>;
+    /**
+     * Dispose the collector.
+     */
+    dispose(): void;
+    /**
+     * Get current sync metrics.
+     */
+    getMetrics(): SyncMetrics;
+    /**
+     * Record a completed sync operation.
+     */
+    recordSync(data: SyncOperationData): Promise<void>;
+    /**
+     * Record a sync error without a full sync operation.
+     */
+    recordError(error: Error): Promise<void>;
+    /**
+     * Record an upload operation.
+     */
+    recordUpload(operationCount: number): Promise<void>;
+    /**
+     * Clear all metrics and start fresh.
+     */
+    reset(): Promise<void>;
+    /**
+     * Called when sync starts (downloading becomes true).
+     */
+    markSyncStart(): void;
+    /**
+     * Called when sync ends (downloading becomes false).
+     * Returns the duration if a sync was in progress.
+     */
+    markSyncEnd(): number | null;
+    /**
+     * Check if sync is currently in progress.
+     */
+    isSyncInProgress(): boolean;
+    /**
+     * Subscribe to metrics changes.
+     * @returns Unsubscribe function
+     */
+    onMetricsUpdate(listener: (metrics: SyncMetrics) => void): Unsubscribe;
+    private _persist;
+    private _notifyListeners;
+}
+
+/**
+ * Connection Health Monitor for @pol-studios/powersync
+ *
+ * Monitors database connection health with periodic checks and latency tracking.
+ */
+
+/**
+ * Monitors connection health with periodic checks.
+ *
+ * Features:
+ * - Periodic health checks with configurable interval
+ * - Latency measurement and degraded state detection
+ * - Consecutive failure tracking
+ * - Auto-recovery detection
+ *
+ * @example
+ * ```typescript
+ * const monitor = new HealthMonitor(db, logger, {
+ *   checkIntervalMs: 30000,
+ *   onHealthChange: (health) => {
+ *     if (health.status === 'degraded') {
+ *       showWarning('Connection is slow');
+ *     }
+ *   },
+ * });
+ *
+ * // Start monitoring
+ * monitor.start();
+ *
+ * // Get current health
+ * const health = monitor.getHealth();
+ *
+ * // Stop when done
+ * monitor.stop();
+ * ```
+ */
+declare class HealthMonitor {
+    private readonly logger;
+    private readonly checkIntervalMs;
+    private readonly checkTimeoutMs;
+    private readonly degradedThresholdMs;
+    private readonly maxConsecutiveFailures;
+    private readonly onHealthChange?;
+    private _db;
+    private _health;
+    private _intervalId;
+    private _listeners;
+    private _running;
+    private _paused;
+    constructor(logger: LoggerAdapter, options?: HealthMonitorOptions);
+    /**
+     * Set the database instance to monitor.
+     */
+    setDatabase(db: AbstractPowerSyncDatabase | null): void;
+    /**
+     * Start the health monitor.
+     */
+    start(): void;
+    /**
+     * Stop the health monitor.
+     */
+    stop(): void;
+    /**
+     * Pause health checks temporarily.
+     */
+    pause(): void;
+    /**
+     * Resume health checks.
+     */
+    resume(): void;
+    /**
+     * Dispose the monitor and clear all resources.
+     */
+    dispose(): void;
+    /**
+     * Get current connection health.
+     */
+    getHealth(): ConnectionHealth;
+    /**
+     * Check if the monitor is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Perform an immediate health check.
+     * @returns The result of the health check
+     */
+    checkNow(): Promise<HealthCheckResult>;
+    /**
+     * Record a reconnection attempt.
+     */
+    recordReconnectAttempt(): void;
+    /**
+     * Reset reconnection attempts counter (call on successful connection).
+     */
+    resetReconnectAttempts(): void;
+    /**
+     * Subscribe to health changes.
+     * @returns Unsubscribe function
+     */
+    onHealthUpdate(listener: (health: ConnectionHealth) => void): Unsubscribe;
+    private _checkHealth;
+    private _updateHealth;
+    private _hasHealthChanged;
+    private _notifyListeners;
+    private _withTimeout;
+}
+
+export { HealthCheckResult, HealthMonitor, HealthMonitorOptions, MetricsCollector, MetricsCollectorOptions, PowerSyncRawStatus, SyncOperationData, SyncStatusTracker, SyncStatusTrackerOptions, Unsubscribe };