@pol-studios/db 1.0.9 → 1.0.11

package/dist/DataLayerContext-CL6alnkb.d.ts

@@ -0,0 +1,755 @@
+import * as react from 'react';
+import { SupabaseClient } from '@supabase/supabase-js';
+import { QueryClient } from '@tanstack/react-query';
+import { DatabaseSchema, QueryOptions, DataLayerConfig, TableStrategy, SyncStatus, SyncControl } from './core/index.js';
+import { P as PowerSyncDatabase } from './executor-CB4KHyYG.js';
+
+/**
+ * V3 Data Layer Adapter Types
+ *
+ * Extended types for the adapter layer that complement the core DataAdapter interface.
+ * These types support the Strategy pattern for routing queries to different backends.
+ */
+
+/**
+ * Result from adapter query operations.
+ * Extends the basic array with optional count for pagination.
+ */
+interface AdapterQueryResult<T> {
+    /** The queried data */
+    data: T[];
+    /** Total count of matching records (for pagination) */
+    count?: number;
+}
+/**
+ * Extended adapter interface that accepts table name for multi-table routing.
+ *
+ * This interface is used by the AdapterRegistry to provide table-aware adapters
+ * that can handle multiple tables with a single adapter instance.
+ *
+ * Differences from core DataAdapter:
+ * - Includes table name parameter in all methods
+ * - Returns AdapterQueryResult with optional count
+ * - Supports optional subscribe method for reactivity
+ */
+interface TableDataAdapter {
+    /**
+     * Unique identifier for the adapter type
+     */
+    readonly name: string;
+    /**
+     * Execute a query and return results
+     *
+     * @param table - The table name to query
+     * @param options - Query options (select, where, orderBy, limit, offset)
+     * @returns Promise resolving to query results with optional count
+     */
+    query<T>(table: string, options: QueryOptions): Promise<AdapterQueryResult<T>>;
+    /**
+     * Query a single record by ID
+     *
+     * @param table - The table name to query
+     * @param id - The record ID
+     * @param options - Optional query options (mainly for select)
+     * @returns Promise resolving to the record or null if not found
+     */
+    queryById?<T>(table: string, id: string, options?: Pick<QueryOptions, "select">): Promise<T | null>;
+    /**
+     * Subscribe to real-time changes on a query.
+     * Not all adapters support this - it's optional.
+     *
+     * @param table - The table name to watch
+     * @param options - Query options to filter what to watch
+     * @param callback - Function called with updated data
+     * @returns Unsubscribe function
+     */
+    subscribe?<T>(table: string, options: QueryOptions, callback: (data: T[]) => void): () => void;
+    /**
+     * Insert a new record
+     *
+     * @param table - The table name
+     * @param data - The data to insert
+     * @returns Promise resolving to the inserted record
+     */
+    insert<T>(table: string, data: Partial<T>): Promise<T>;
+    /**
+     * Update an existing record by ID
+     *
+     * @param table - The table name
+     * @param id - The record ID to update
+     * @param data - The data to update
+     * @returns Promise resolving to the updated record
+     */
+    update<T>(table: string, id: string, data: Partial<T>): Promise<T>;
+    /**
+     * Upsert (insert or update) a record
+     * If the record has an ID and exists, it will be updated.
+     * Otherwise, a new record will be inserted.
+     *
+     * @param table - The table name
+     * @param data - The data to upsert
+     * @returns Promise resolving to the upserted record
+     */
+    upsert<T>(table: string, data: Partial<T>): Promise<T>;
+    /**
+     * Delete a record by ID
+     *
+     * @param table - The table name
+     * @param id - The record ID to delete
+     * @returns Promise that resolves when deletion is complete
+     */
+    delete(table: string, id: string): Promise<void>;
+}
+/**
+ * Configuration for creating an adapter
+ */
+interface AdapterConfig {
+    /**
+     * The strategy type to create
+     */
+    strategy: "powersync" | "supabase" | "cached" | "hybrid";
+    /**
+     * Additional strategy-specific configuration
+     */
+    [key: string]: unknown;
+}
+/**
+ * Factory interface for creating adapters
+ */
+interface AdapterFactory {
+    /**
+     * Create a new adapter instance based on configuration
+     *
+     * @param config - Adapter configuration
+     * @returns The created adapter instance
+     */
+    create(config: AdapterConfig): TableDataAdapter;
+}
+/**
+ * Describes the capabilities of an adapter
+ */
+interface AdapterCapabilities {
+    /**
+     * Whether the adapter supports real-time subscriptions
+     */
+    supportsSubscribe: boolean;
+    /**
+     * Whether the adapter works offline
+     */
+    supportsOffline: boolean;
+    /**
+     * Whether the adapter caches data locally
+     */
+    supportsCache: boolean;
+    /**
+     * Whether the adapter syncs data bidirectionally
+     */
+    supportsSync: boolean;
+}
+/**
+ * Extended adapter interface with capability reporting
+ */
+interface CapableDataAdapter extends TableDataAdapter {
+    /**
+     * Get the capabilities of this adapter
+     */
+    readonly capabilities: AdapterCapabilities;
+}
+/**
+ * Dependencies required to initialize adapters.
+ * Uses 'unknown' type for external dependencies to allow proper typing
+ * when concrete implementations are provided.
+ */
+interface AdapterDependencies {
+    /**
+     * PowerSync database instance
+     * Will be typed as PowerSyncDatabase when PowerSync is integrated
+     */
+    powerSync: unknown;
+    /**
+     * Supabase client instance
+     * Will be typed as SupabaseClient when imported
+     */
+    supabase: unknown;
+    /**
+     * TanStack Query client for caching
+     * Will be typed as QueryClient when imported
+     */
+    queryClient: unknown;
+    /**
+     * Database schema for relationship resolution
+     */
+    schema: DatabaseSchema;
+}
+/**
+ * String literals for adapter strategy types
+ */
+declare const ADAPTER_STRATEGIES: {
+    readonly POWERSYNC: "powersync";
+    readonly SUPABASE: "supabase";
+    readonly CACHED: "cached";
+    readonly HYBRID: "hybrid";
+    readonly AUTO: "auto";
+};
+
+/**
+ * Type for adapter strategy values
+ */
+type AdapterStrategyType = (typeof ADAPTER_STRATEGIES)[keyof typeof ADAPTER_STRATEGIES];
+
+/**
+ * Adapter Auto-Detector
+ *
+ * Detects available backends (PowerSync, Supabase) at runtime and recommends
+ * the best one to use based on availability and configuration preferences.
+ *
+ * This enables the V3 data layer to automatically select the optimal backend
+ * for offline-first or online-first experiences.
+ */
+
+/**
+ * Status of a backend adapter
+ */
+declare enum BackendStatus {
+    /** Backend is available and ready to use */
+    AVAILABLE = "available",
+    /** Backend is initializing (e.g., PowerSync syncing) */
+    INITIALIZING = "initializing",
+    /** Backend is not available */
+    UNAVAILABLE = "unavailable"
+}
+/**
+ * Result of auto-detection
+ */
+interface AutoDetectionResult {
+    /** PowerSync availability status */
+    powerSyncStatus: BackendStatus;
+    /** Supabase availability status */
+    supabaseStatus: BackendStatus;
+    /** Recommended backend to use */
+    recommendedBackend: "powersync" | "supabase";
+    /** Whether device is online */
+    isOnline: boolean;
+    /** Reason for recommendation */
+    reason: string;
+}
+/**
+ * Sync status information from PowerSync
+ */
+interface SyncStatusInfo {
+    /** Whether PowerSync has completed at least one full sync */
+    hasSynced: boolean;
+    /** Whether connected to PowerSync service */
+    connected: boolean;
+    /** Whether currently connecting */
+    connecting: boolean;
+    /** Network connectivity status from platform adapter (NetInfo on React Native) */
+    isOnline?: boolean;
+}
+/**
+ * Options for auto-detection
+ */
+interface AutoDetectorOptions {
+    /** Prefer PowerSync when available (default: true) */
+    preferPowerSync?: boolean;
+    /** Timeout for status checks in ms (default: 1000) */
+    statusCheckTimeout?: number;
+    /**
+     * Use Supabase for queries until PowerSync completes initial sync.
+     * When true, queries return online data while syncing.
+     * @default true
+     */
+    useOnlineUntilSynced?: boolean;
+}
+/**
+ * Listener for backend change events
+ */
+type BackendChangeListener = (result: AutoDetectionResult) => void;
+/**
+ * Detects available backends and recommends the best one to use.
+ *
+ * The auto-detector checks for PowerSync and Supabase availability and
+ * makes intelligent recommendations based on:
+ * - Backend availability
+ * - Network connectivity
+ * - User preferences (preferPowerSync option)
+ *
+ * @example
+ * ```typescript
+ * const detector = new AdapterAutoDetector(powerSyncDb, supabaseClient, {
+ *   preferPowerSync: true,
+ * });
+ *
+ * const result = detector.detect();
+ * console.log(`Using ${result.recommendedBackend}: ${result.reason}`);
+ * ```
+ */
+declare class AdapterAutoDetector {
+    private powerSyncDb;
+    private supabase;
+    private options;
+    private listeners;
+    private lastResult;
+    private syncStatus;
+    constructor(powerSyncDb: PowerSyncDatabase | null, supabase: SupabaseClient | null, options?: AutoDetectorOptions);
+    /**
+     * Update the sync status from PowerSync.
+     * Called when sync status changes to re-evaluate backend recommendation.
+     *
+     * @param status - Current sync status or null if not available
+     */
+    updateSyncStatus(status: SyncStatusInfo | null): void;
+    /**
+     * Get current sync status.
+     * @returns Current sync status or null
+     */
+    getSyncStatus(): SyncStatusInfo | null;
+    /**
+     * Detect backend availability and recommend best option.
+     *
+     * The detection logic follows this priority:
+     * 1. If preferPowerSync is true and PowerSync is available, use PowerSync
+     * 2. If PowerSync is initializing and online with Supabase available, use Supabase temporarily
+     * 3. If online with Supabase available, use Supabase
+     * 4. If offline but PowerSync available, use PowerSync (offline mode)
+     * 5. If offline and PowerSync exists (even if initializing), use PowerSync local data
+     * 6. Default to Supabase as fallback
+     *
+     * @returns Detection result with recommendation and reasoning
+     */
+    detect(): AutoDetectionResult;
+    /**
+     * Check if PowerSync is available.
+     *
+     * PowerSync status depends on:
+     * 1. Database instance exists
+     * 2. If useOnlineUntilSynced is true, also checks if initial sync completed
+     *
+     * @returns PowerSync backend status
+     */
+    detectPowerSyncStatus(): BackendStatus;
+    /**
+     * Check if Supabase is available.
+     *
+     * Supabase is considered available if we have a client instance.
+     * The actual network connectivity is checked separately via checkOnlineStatus().
+     *
+     * @returns Supabase backend status
+     */
+    detectSupabaseStatus(): BackendStatus;
+    /**
+     * Check if device is online.
+     *
+     * Prefers the sync status's isOnline property if available (from React Native NetInfo).
+     * Falls back to navigator.onLine in browser environments.
+     * Returns true by default for other environments.
+     *
+     * @returns Whether the device has network connectivity
+     */
+    checkOnlineStatus(): boolean;
+    /**
+     * Update PowerSync instance (e.g., when it becomes available).
+     *
+     * @param db - New PowerSync database instance or null
+     */
+    setPowerSync(db: PowerSyncDatabase | null): void;
+    /**
+     * Update Supabase instance.
+     *
+     * @param supabase - New Supabase client instance or null
+     */
+    setSupabase(supabase: SupabaseClient | null): void;
+    /**
+     * Get current PowerSync instance.
+     *
+     * @returns Current PowerSync database instance or null
+     */
+    getPowerSync(): PowerSyncDatabase | null;
+    /**
+     * Get current Supabase instance.
+     *
+     * @returns Current Supabase client instance or null
+     */
+    getSupabase(): SupabaseClient | null;
+    /**
+     * Update detector options.
+     *
+     * @param options - New options to merge with existing
+     */
+    setOptions(options: Partial<AutoDetectorOptions>): void;
+    /**
+     * Get current detector options.
+     *
+     * @returns Current detector options
+     */
+    getOptions(): Required<AutoDetectorOptions>;
+    /**
+     * Add a listener for backend change events.
+     *
+     * @param listener - Callback to invoke when detection result changes
+     * @returns Function to remove the listener
+     */
+    addListener(listener: BackendChangeListener): () => void;
+    /**
+     * Remove a listener for backend change events.
+     *
+     * @param listener - Listener to remove
+     */
+    removeListener(listener: BackendChangeListener): void;
+    /**
+     * Get the last detection result.
+     *
+     * @returns Last detection result or null if never detected
+     */
+    getLastResult(): AutoDetectionResult | null;
+    /**
+     * Check if the detection result has changed from the last result.
+     */
+    private hasResultChanged;
+    /**
+     * Notify all listeners of a detection result change.
+     */
+    private notifyListeners;
+}
+/**
+ * Create an AdapterAutoDetector instance.
+ *
+ * @param powerSyncDb - PowerSync database instance or null
+ * @param supabase - Supabase client instance or null
+ * @param options - Detection options
+ * @returns New AdapterAutoDetector instance
+ *
+ * @example
+ * ```typescript
+ * const detector = createAdapterAutoDetector(powerSyncDb, supabaseClient, {
+ *   preferPowerSync: true,
+ *   statusCheckTimeout: 2000,
+ * });
+ *
+ * const { recommendedBackend, reason } = detector.detect();
+ * ```
+ */
+declare function createAdapterAutoDetector(powerSyncDb: PowerSyncDatabase | null, supabase: SupabaseClient | null, options?: AutoDetectorOptions): AdapterAutoDetector;
+
+/**
+ * V3 Data Layer Adapter Registry
+ *
+ * Factory that creates and manages adapter instances based on table configuration.
+ * Uses lazy initialization to create adapters on first access.
+ */
+
+/**
+ * Registry that manages and provides adapters based on table configuration.
+ *
+ * The registry:
+ * - Stores configuration for table strategies
+ * - Lazily creates adapters when first accessed
+ * - Caches created adapters for reuse
+ * - Provides default fallback for unconfigured tables
+ *
+ * Usage:
+ * ```typescript
+ * const registry = createAdapterRegistry(config);
+ *
+ * // Later, when providers initialize:
+ * registry.setPowerSyncAdapter(powerSyncAdapter);
+ * registry.setSupabaseAdapter(supabaseAdapter);
+ *
+ * // Get adapter for a table:
+ * const adapter = registry.getAdapter("Project");
+ * ```
+ */
+declare class AdapterRegistry {
+    private config;
+    /**
+     * Cache of created adapters by table name
+     */
+    private adapters;
+    /**
+     * PowerSync adapter instance (set during initialization)
+     */
+    private powerSyncAdapter;
+    /**
+     * Supabase adapter instance (set during initialization)
+     */
+    private supabaseAdapter;
+    /**
+     * Cached adapter instance (wraps Supabase with TanStack Query)
+     */
+    private cachedAdapter;
+    /**
+     * Dependencies for creating adapters
+     */
+    private deps;
+    /**
+     * Whether the registry has been initialized with adapters
+     */
+    private _isInitialized;
+    /**
+     * Auto-detector instance for automatic backend selection
+     */
+    private autoDetector;
+    /**
+     * Listeners for backend change events
+     */
+    private backendChangeListeners;
+    /**
+     * Last auto-detection result for debugging and status
+     */
+    private lastDetectionResult;
+    /**
+     * Create a new adapter registry
+     *
+     * @param config - Data layer configuration with table strategies
+     */
+    constructor(config: DataLayerConfig);
+    /**
+     * Check if the registry has been initialized
+     */
+    get isInitialized(): boolean;
+    /**
+     * Initialize the registry with dependencies.
+     * Called by DataLayerProvider when PowerSync and Supabase are ready.
+     *
+     * @param deps - Dependencies needed to create adapters
+     */
+    initialize(deps: AdapterDependencies): void;
+    /**
+     * Set the PowerSync adapter instance
+     *
+     * @param adapter - PowerSync adapter implementation
+     */
+    setPowerSyncAdapter(adapter: TableDataAdapter): void;
+    /**
+     * Set the Supabase adapter instance
+     *
+     * @param adapter - Supabase adapter implementation
+     */
+    setSupabaseAdapter(adapter: TableDataAdapter): void;
+    /**
+     * Set the Cached adapter instance
+     *
+     * @param adapter - Cached adapter implementation
+     */
+    setCachedAdapter(adapter: TableDataAdapter): void;
+    /**
+     * Initialize auto-detection with a detector instance
+     *
+     * @param detector - The auto-detector to use
+     */
+    initializeAutoDetection(detector: AdapterAutoDetector): void;
+    /**
+     * Get the appropriate adapter for a table based on configuration.
+     *
+     * The adapter is selected based on the table's strategy in config.tables:
+     * - "powersync": Returns PowerSyncAdapter
+     * - "supabase": Returns SupabaseAdapter
+     * - "cached": Returns CachedAdapter (wrapping Supabase)
+     * - "hybrid": Returns HybridAdapter (combining PowerSync + Cached)
+     * - "auto": Uses auto-detection to select the best backend
+     *
+     * For tables not in config, defaults to auto-detection if available,
+     * otherwise falls back to SupabaseAdapter.
+     *
+     * @param table - The table name
+     * @returns The appropriate adapter for the table
+     * @throws Error if adapters are not initialized
+     */
+    getAdapter(table: string): TableDataAdapter;
+    /**
+     * Get the PowerSync adapter directly
+     *
+     * @returns PowerSync adapter or null if not initialized
+     */
+    getPowerSyncAdapter(): TableDataAdapter | null;
+    /**
+     * Get the Supabase adapter directly
+     *
+     * @returns Supabase adapter or null if not initialized
+     */
+    getSupabaseAdapter(): TableDataAdapter | null;
+    /**
+     * Get the Cached adapter directly
+     *
+     * @returns Cached adapter or null if not initialized
+     */
+    getCachedAdapter(): TableDataAdapter | null;
+    /**
+     * Get all configured table names
+     *
+     * @returns Array of table names with explicit strategy configuration
+     */
+    getConfiguredTables(): string[];
+    /**
+     * Get the strategy for a specific table
+     *
+     * @param table - The table name
+     * @returns The table strategy or undefined if not configured
+     */
+    getTableStrategy(table: string): TableStrategy | undefined;
+    /**
+     * Check if a table uses PowerSync strategy
+     *
+     * @param table - The table name
+     * @returns True if table uses PowerSync or Hybrid strategy
+     */
+    usesPowerSync(table: string): boolean;
+    /**
+     * Get all tables that use PowerSync
+     *
+     * @returns Array of table names using PowerSync or Hybrid strategy
+     */
+    getPowerSyncTables(): string[];
+    /**
+     * Get adapter using auto-detection
+     *
+     * @param strategy - Optional auto strategy configuration
+     * @returns The automatically selected adapter
+     */
+    private getAutoAdapter;
+    /**
+     * Subscribe to backend changes
+     *
+     * @param callback - Function called when recommended backend changes
+     * @returns Unsubscribe function
+     */
+    onBackendChange(callback: (backend: "powersync" | "supabase") => void): () => void;
+    /**
+     * Notify listeners of backend change
+     *
+     * @param backend - The new recommended backend
+     */
+    private notifyBackendChange;
+    /**
+     * Get the last auto-detection result
+     *
+     * @returns Last detection result or null if never detected
+     */
+    getLastDetectionResult(): AutoDetectionResult | null;
+    /**
+     * Get the auto-detector instance
+     *
+     * @returns Auto-detector instance or null if not initialized
+     */
+    getAutoDetector(): AdapterAutoDetector | null;
+    /**
+     * Create an adapter based on the strategy type
+     *
+     * @param strategy - The table strategy configuration
+     * @returns The created adapter
+     * @throws Error if the required base adapter is not initialized
+     */
+    private createAdapter;
+    /**
+     * Clear all cached adapters.
+     * Useful when configuration changes and adapters need to be recreated.
+     */
+    clearCache(): void;
+    /**
+     * Reset the registry to uninitialized state.
+     * Used during cleanup or testing.
+     */
+    reset(): void;
+    /**
+     * Dispose all adapters and clean up resources.
+     * Called when the DataLayerProvider unmounts.
+     */
+    dispose(): void;
+    /**
+     * Get debug information about the registry state
+     */
+    getDebugInfo(): {
+        isInitialized: boolean;
+        hasPowerSync: boolean;
+        hasSupabase: boolean;
+        hasCached: boolean;
+        cachedAdapterCount: number;
+        configuredTableCount: number;
+        powerSyncTables: string[];
+        hasAutoDetector: boolean;
+        lastDetectionResult: AutoDetectionResult | null;
+    };
+}
+/**
+ * Create a new adapter registry
+ *
+ * @param config - Data layer configuration
+ * @returns A new AdapterRegistry instance
+ *
+ * @example
+ * ```typescript
+ * const config: DataLayerConfig = {
+ *   schema: databaseSchema,
+ *   connections: { ... },
+ *   tables: {
+ *     Project: { strategy: "powersync", syncScope: "activeProject" },
+ *     AuditLog: { strategy: "supabase" },
+ *     Report: { strategy: "cached", cacheTime: 60000 },
+ *   },
+ *   scopes: { ... },
+ *   defaults: { syncMode: "live" },
+ * };
+ *
+ * const registry = createAdapterRegistry(config);
+ *
+ * // In provider:
+ * registry.setPowerSyncAdapter(new PowerSyncAdapter(db, schema));
+ * registry.setSupabaseAdapter(new SupabaseAdapter(supabase));
+ *
+ * // In hooks:
+ * const adapter = registry.getAdapter("Project"); // Returns PowerSyncAdapter
+ * ```
+ */
+declare function createAdapterRegistry(config: DataLayerConfig): AdapterRegistry;
+
+/**
+ * Status of the data layer initialization
+ */
+interface DataLayerStatus {
+    /** Whether the data layer is fully initialized */
+    isInitialized: boolean;
+    /** Current active backend */
+    currentBackend: "powersync" | "supabase" | null;
+    /** PowerSync connection status */
+    powerSyncStatus: BackendStatus;
+    /** Whether device is online */
+    isOnline: boolean;
+    /** Last auto-detection result */
+    lastDetection: AutoDetectionResult | null;
+    /** Initialization error if any */
+    error: Error | null;
+    /** Whether initial sync has completed (from PowerSync) */
+    hasSynced: boolean;
+}
+/**
+ * Context value for the data layer
+ */
+interface DataLayerContextValue {
+    /** Adapter registry for getting table adapters */
+    registry: AdapterRegistry;
+    /** Get adapter for a specific table */
+    getAdapter: (table: string) => TableDataAdapter;
+    /** PowerSync database instance (null when not available) */
+    powerSync: PowerSyncDatabase | null;
+    /** Supabase client (always available) */
+    supabase: SupabaseClient;
+    /** React Query client */
+    queryClient: QueryClient;
+    /** Database schema */
+    schema: DatabaseSchema;
+    /** Current status */
+    status: DataLayerStatus;
+    /** Sync status (for PowerSync, no-op for Supabase-only) */
+    syncStatus: SyncStatus;
+    /** Sync controls (for PowerSync, no-op for Supabase-only) */
+    syncControl: SyncControl;
+}
+/**
+ * Data layer context
+ *
+ * Provides access to the V3 data layer throughout the React component tree.
+ * Must be accessed via the useDataLayer hook or similar consumer.
+ */
+declare const DataLayerContext: react.Context<DataLayerContextValue>;
+
+export { type AdapterQueryResult as A, BackendStatus as B, type CapableDataAdapter as C, DataLayerContext as D, type SyncStatusInfo as S, type TableDataAdapter as T, type AdapterConfig as a, type AdapterFactory as b, type AdapterCapabilities as c, type AdapterDependencies as d, type AdapterStrategyType as e, ADAPTER_STRATEGIES as f, AdapterRegistry as g, createAdapterRegistry as h, AdapterAutoDetector as i, createAdapterAutoDetector as j, type AutoDetectionResult as k, type AutoDetectorOptions as l, type BackendChangeListener as m, type DataLayerContextValue as n, type DataLayerStatus as o };