@pol-studios/db 1.0.58 → 1.0.59

package/dist/DataLayerContext-V5FotiSk.d.ts

@@ -0,0 +1,563 @@
+import * as react from 'react';
+import { SupabaseClient } from '@supabase/supabase-js';
+import { QueryClient } from '@tanstack/react-query';
+import { P as PowerSyncDatabase } from './executor-Bu1OlqCl.js';
+import { QueryOptions, DatabaseSchema, TableStrategy, DataLayerConfig, SyncControl, SyncStatus } from './core/index.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 PowerSync database reference.
+     * Called when PowerSync becomes available after initial construction.
+     *
+     * @param db - PowerSync database instance or null
+     */
+    setPowerSyncDb(db: PowerSyncDatabase | null): void;
+    /**
+     * 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;
+    /**
+     * Detect backend availability WITHOUT notifying listeners.
+     *
+     * This method is safe to call during React's render phase because it does not
+     * trigger state updates in other components. Use this method when you need to
+     * check backend status synchronously during render (e.g., in getAdapter()).
+     *
+     * The regular detect() method with listener notifications should only be called
+     * from useEffect or event handlers to avoid the React warning:
+     * "Cannot update a component while rendering a different component"
+     *
+     * @returns Detection result with recommendation and reasoning
+     */
+    detectSilent(): AutoDetectionResult;
+    /**
+     * Internal detection logic shared by detect() and detectSilent().
+     * @private
+     */
+    private performDetection;
+    /**
+     * 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 false by default for non-browser environments (React Native, Node.js, etc.)
+     * to ensure offline-first behavior works correctly.
+     *
+     * @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;
+
+/**
+ * Status type for the data layer
+ */
+interface DataLayerStatus {
+    isInitialized: boolean;
+    currentBackend: "powersync" | "supabase" | null;
+    powerSyncStatus: BackendStatus;
+    isOnline: boolean;
+    lastDetection: AutoDetectionResult | null;
+    error: Error | null;
+    hasSynced: boolean;
+}
+/**
+ * Simplified adapter registry interface.
+ *
+ * This provides the same interface as the old AdapterRegistry class
+ * but is implemented inline in the provider.
+ */
+interface SimpleAdapterRegistry {
+    /** Get adapter for a specific table */
+    getAdapter: (table: string, operation?: 'read' | 'write') => TableDataAdapter;
+    /** Get strategy for a table */
+    getTableStrategy: (table: string) => TableStrategy | undefined;
+    /** Check if table uses PowerSync */
+    usesPowerSync: (table: string) => boolean;
+    /** Get all PowerSync table names */
+    getPowerSyncTables: () => string[];
+    /** Get PowerSync alias for a table */
+    getTableAlias: (table: string) => string;
+    /** Get debug info */
+    getDebugInfo: () => {
+        isInitialized: boolean;
+        hasPowerSync: boolean;
+        hasSupabase: boolean;
+        configuredTableCount: number;
+        powerSyncTables: string[];
+    };
+    /** Config reference */
+    config: DataLayerConfig;
+    /** Whether registry is initialized */
+    isInitialized: boolean;
+}
+/**
+ * Core context value - stable values that don't change after initialization.
+ *
+ * Supports lazy init: start with Supabase, automatically switch to PowerSync when available.
+ */
+interface DataLayerCoreContextValue {
+    /** Simplified registry for adapter access */
+    registry: SimpleAdapterRegistry;
+    /** Get adapter for a table - simple: PowerSync if offline table, else Supabase */
+    getAdapter: (table: string, operation?: 'read' | 'write') => TableDataAdapter;
+    /** PowerSync database instance (null if not using offline-first) */
+    powerSync: PowerSyncDatabase | null;
+    /** Supabase client (always available) */
+    supabase: SupabaseClient;
+    /** React Query client */
+    queryClient: QueryClient;
+    /** Database schema */
+    schema: DatabaseSchema;
+    /** Sync controls (no-op functions when PowerSync not available) */
+    syncControl: SyncControl;
+}
+/**
+ * Status context value - dynamic values that change during runtime.
+ */
+interface DataLayerStatusContextValue {
+    /** Current status */
+    status: DataLayerStatus;
+    /** Sync status (for PowerSync, default values for Supabase-only) */
+    syncStatus: SyncStatus;
+}
+/**
+ * Combined context value for backward compatibility.
+ * Combines core and status values.
+ *
+ * @deprecated Prefer using useDataLayerCore() for queries/mutations
+ * and useDataLayerStatus() for status display components.
+ */
+interface DataLayerContextValue extends DataLayerCoreContextValue, DataLayerStatusContextValue {
+}
+/**
+ * Main data layer context (combined).
+ * For backward compatibility - use DataLayerCoreContext for better performance.
+ */
+declare const DataLayerContext: react.Context<DataLayerContextValue>;
+/**
+ * Core context - stable values that don't change after initialization.
+ * Components using useDataLayerCore() will NOT re-render on status changes.
+ */
+declare const DataLayerCoreContext: react.Context<DataLayerCoreContextValue>;
+/**
+ * Status context - dynamic values that change during runtime.
+ * Components using useDataLayerStatus() WILL re-render on status changes.
+ */
+declare const DataLayerStatusContext: react.Context<DataLayerStatusContextValue>;
+/**
+ * Nesting detection context.
+ * Warns if DataLayerProvider is accidentally nested.
+ */
+declare const DataLayerNestingContext: react.Context<boolean>;
+
+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, AdapterAutoDetector as g, createAdapterAutoDetector as h, type AutoDetectionResult as i, type AutoDetectorOptions as j, type BackendChangeListener as k, DataLayerCoreContext as l, DataLayerStatusContext as m, DataLayerNestingContext as n, type DataLayerContextValue as o, type DataLayerCoreContextValue as p, type DataLayerStatusContextValue as q, type DataLayerStatus as r, type SimpleAdapterRegistry as s };

package/dist/auth/context.js

@@ -11,8 +11,8 @@ import {
   useUserMetadataState,
   useUserMetadataValue,
   userMetadataContext
-} from "../chunk-6SDH7M7J.js";
-import "../chunk-GWYTROSD.js";
+} from "../chunk-ARALLEDJ.js";
+import "../chunk-L4DFVMTS.js";
 import "../chunk-W7PERM66.js";
 import "../chunk-QYAFI34Q.js";
 import "../chunk-J4ZVCXZ4.js";

package/dist/auth/hooks.js

@@ -11,14 +11,14 @@ import {
   usePermissionLoading,
   usePermissionsBatch,
   useSetupAuth
-} from "../chunk-MEBT5YHA.js";
+} from "../chunk-SNPZMRBC.js";
 import {
   useSetUserMetadata,
   useUserMetadata,
   useUserMetadataState,
   useUserMetadataValue
-} from "../chunk-6SDH7M7J.js";
-import "../chunk-GWYTROSD.js";
+} from "../chunk-ARALLEDJ.js";
+import "../chunk-L4DFVMTS.js";
 import "../chunk-W7PERM66.js";
 import "../chunk-QYAFI34Q.js";
 import "../chunk-J4ZVCXZ4.js";

package/dist/auth/index.js

@@ -12,7 +12,7 @@ import {
   usePermissionLoading,
   usePermissionsBatch,
   useSetupAuth
-} from "../chunk-MEBT5YHA.js";
+} from "../chunk-SNPZMRBC.js";
 import {
   AuthProvider,
   PermissionProvider,
@@ -26,8 +26,8 @@ import {
   useUserMetadataState,
   useUserMetadataValue,
   userMetadataContext
-} from "../chunk-6SDH7M7J.js";
-import "../chunk-GWYTROSD.js";
+} from "../chunk-ARALLEDJ.js";
+import "../chunk-L4DFVMTS.js";
 import {
   hasAccess,
   hasAllAccess,