@pol-studios/db 1.0.19 → 1.0.22

package/dist/powersync-bridge/index.d.ts

@@ -0,0 +1,284 @@
+import { SyncControl, SyncStatus } from '../core/index.js';
+export { P as PowerSyncDatabase } from '../executor-CB4KHyYG.js';
+
+/**
+ * PowerSync Bridge for @pol-studios/db
+ *
+ * This module provides integration utilities between @pol-studios/db and
+ * @pol-studios/powersync packages. It re-exports key types and provides
+ * helper functions for type-safe integration.
+ *
+ * The @pol-studios/powersync package is an optional peer dependency.
+ * This bridge allows the db package to work seamlessly with or without
+ * the powersync package installed.
+ *
+ * @example
+ * ```typescript
+ * import { isPowerSyncAvailable, usePowerSyncDatabase } from '@pol-studios/db/powersync-bridge';
+ *
+ * if (isPowerSyncAvailable()) {
+ *   // Use PowerSync features
+ * }
+ * ```
+ */
+/**
+ * Re-export core types from @pol-studios/powersync for convenience.
+ * These types are defined here to avoid runtime dependency on the package.
+ */
+/**
+ * Abstract interface for PowerSync database operations.
+ * This matches the interface from @pol-studios/powersync/core.
+ */
+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: unknown): 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<unknown>;
+}
+/**
+ * Sync status from @pol-studios/powersync.
+ */
+interface PowerSyncSyncStatus {
+    /** 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: {
+        current: number;
+        target: number;
+        percentage: number;
+    } | null;
+}
+/**
+ * Connection health status from @pol-studios/powersync.
+ */
+interface PowerSyncConnectionHealth {
+    /** 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;
+}
+/**
+ * Sync metrics from @pol-studios/powersync.
+ */
+interface PowerSyncMetrics {
+    /** 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: {
+        type: string;
+        message: string;
+        timestamp: Date;
+    } | null;
+}
+/**
+ * Sync control actions from @pol-studios/powersync.
+ */
+interface PowerSyncControlActions {
+    /** Trigger a sync operation */
+    triggerSync: () => Promise<void>;
+    /** Pause sync operations */
+    pause: () => Promise<void>;
+    /** Resume sync operations */
+    resume: () => Promise<void>;
+    /** Disconnect from the PowerSync service */
+    disconnect: () => Promise<void>;
+    /** Set the sync scope for selective sync */
+    setScope: (scope: {
+        type: string;
+        ids: string[];
+    } | null) => void;
+}
+/**
+ * Check if @pol-studios/powersync is available.
+ *
+ * This function performs a lazy check to see if the powersync package
+ * is installed and can be imported. The result is cached for subsequent calls.
+ *
+ * @returns true if @pol-studios/powersync is available, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isPowerSyncAvailable } from '@pol-studios/db/powersync-bridge';
+ *
+ * if (isPowerSyncAvailable()) {
+ *   // Safe to use PowerSync features
+ *   const { usePowerSync } = await import('@pol-studios/powersync');
+ * }
+ * ```
+ */
+declare function isPowerSyncAvailable(): boolean;
+/**
+ * Reset the availability check cache.
+ * Useful for testing or when package installation state might change.
+ */
+declare function resetPowerSyncAvailabilityCache(): void;
+/**
+ * Type guard to check if a value is an AbstractPowerSyncDatabase.
+ *
+ * @param value - The value to check
+ * @returns true if value implements AbstractPowerSyncDatabase interface
+ */
+declare function isAbstractPowerSyncDatabase(value: unknown): value is AbstractPowerSyncDatabase;
+/**
+ * Type guard to check if a value is a PowerSyncSyncStatus.
+ *
+ * @param value - The value to check
+ * @returns true if value matches PowerSyncSyncStatus interface
+ */
+declare function isPowerSyncSyncStatus(value: unknown): value is PowerSyncSyncStatus;
+/**
+ * Convert PowerSync sync status to the V3 DataLayer SyncStatus format.
+ *
+ * This utility helps bridge the sync status from @pol-studios/powersync
+ * to the format expected by @pol-studios/db's DataLayerProvider.
+ *
+ * @param powerSyncStatus - The sync status from @pol-studios/powersync
+ * @param pendingCount - Number of pending uploads (from pendingMutations)
+ * @returns SyncStatus in @pol-studios/db format
+ */
+declare function convertToDataLayerSyncStatus(powerSyncStatus: PowerSyncSyncStatus, pendingCount?: number): SyncStatus;
+/**
+ * Convert PowerSync sync control to the V3 DataLayer SyncControl format.
+ *
+ * @param powerSyncControl - The sync control actions from @pol-studios/powersync
+ * @returns SyncControl in @pol-studios/db format
+ */
+declare function convertToDataLayerSyncControl(powerSyncControl: PowerSyncControlActions): SyncControl;
+/**
+ * Create a database instance getter that works with PowerSync context.
+ *
+ * This is useful for integrating PowerSyncProvider with DataLayerProvider
+ * by providing a way to get the database instance from the PowerSync context.
+ *
+ * @param getPowerSyncDb - Function to get the PowerSync database from context
+ * @returns A function that returns the database or null
+ */
+declare function createDatabaseGetter(getPowerSyncDb: () => AbstractPowerSyncDatabase | null): () => AbstractPowerSyncDatabase | null;
+/**
+ * Options for setting up DataLayerProvider with PowerSync integration.
+ */
+interface PowerSyncIntegrationOptions {
+    /**
+     * The PowerSync database instance from PowerSyncProvider.
+     */
+    database: AbstractPowerSyncDatabase | null;
+    /**
+     * Whether the PowerSync database is ready.
+     */
+    isReady: boolean;
+    /**
+     * Current sync status from PowerSyncProvider.
+     */
+    syncStatus?: PowerSyncSyncStatus;
+    /**
+     * Sync control actions from PowerSyncProvider.
+     */
+    syncControl?: PowerSyncControlActions;
+    /**
+     * Number of pending mutations.
+     */
+    pendingCount?: number;
+}
+/**
+ * Get the powerSyncInstance prop for DataLayerProvider from PowerSync context values.
+ *
+ * This helper extracts the necessary values from @pol-studios/powersync hooks
+ * and returns them in a format suitable for DataLayerProvider.
+ *
+ * @param options - The PowerSync integration options
+ * @returns The powerSyncInstance to pass to DataLayerProvider, or null if not ready
+ *
+ * @example
+ * ```typescript
+ * // Inside a component wrapped with PowerSyncProvider
+ * const { db, isReady } = usePowerSync();
+ * const { status, pendingCount } = useSyncStatus();
+ * const syncControl = useSyncControl();
+ *
+ * const powerSyncInstance = getPowerSyncInstance({
+ *   database: db,
+ *   isReady,
+ *   syncStatus: status,
+ *   syncControl,
+ *   pendingCount,
+ * });
+ *
+ * return (
+ *   <DataLayerProvider
+ *     config={config}
+ *     powerSyncInstance={powerSyncInstance}
+ *     supabaseClient={supabase}
+ *     queryClient={queryClient}
+ *   >
+ *     {children}
+ *   </DataLayerProvider>
+ * );
+ * ```
+ */
+declare function getPowerSyncInstance(options: PowerSyncIntegrationOptions): AbstractPowerSyncDatabase | null;
+
+export { type AbstractPowerSyncDatabase, type PowerSyncConnectionHealth, type PowerSyncControlActions, type PowerSyncIntegrationOptions, type PowerSyncMetrics, type PowerSyncSyncStatus, convertToDataLayerSyncControl, convertToDataLayerSyncStatus, createDatabaseGetter, getPowerSyncInstance, isAbstractPowerSyncDatabase, isPowerSyncAvailable, isPowerSyncSyncStatus, resetPowerSyncAvailabilityCache };

package/dist/powersync-bridge/index.js

@@ -7,7 +7,7 @@ import {
   isPowerSyncAvailable,
   isPowerSyncSyncStatus,
   resetPowerSyncAvailabilityCache
-} from "../chunk-N26IEHZT.js";
+} from "../chunk-FZF26ZRB.js";
 import "../chunk-P4UZ7IXC.js";
 export {
   convertToDataLayerSyncControl,