@pol-studios/db 1.0.17 → 1.0.19

package/dist/core/index.d.ts

@@ -1,527 +0,0 @@
-/**
- * V3 Data Layer Core Types
- *
- * This module defines all type definitions for the V3 PowerSync-based data layer.
- * These types support offline-first sync with Supabase through PowerSync.
- */
-/**
- * Column type mappings for schema definitions
- */
-type ColumnType = "string" | "number" | "boolean" | "date" | "enum";
-/**
- * Information about a database column
- */
-interface ColumnInfo {
-    /** Column name */
-    name: string;
-    /** Column data type */
-    type: ColumnType;
-    /** Whether the column allows null values */
-    isOptional: boolean;
-    /** Whether this column is an enum type */
-    isEnum?: boolean;
-    /** Possible values if this is an enum column */
-    enumValues?: string[];
-}
-/**
- * Information about a table relationship (foreign key)
- */
-interface RelationshipInfo {
-    /** The foreign key column name in this table */
-    foreignKey: string;
-    /** The table being referenced */
-    referencedTable: string;
-    /** The column in the referenced table (typically 'id') */
-    referencedColumn: string;
-}
-/**
- * Schema definition for a single table
- */
-interface TableSchema {
-    /** Table name */
-    name: string;
-    /** Column definitions */
-    columns: ColumnInfo[];
-    /** Foreign key relationships */
-    relationships: RelationshipInfo[];
-}
-/**
- * Complete database schema definition
- */
-interface DatabaseSchema {
-    schemas: {
-        [schemaName: string]: {
-            tables: Record<string, TableSchema>;
-            views: Record<string, TableSchema>;
-        };
-    };
-}
-/**
- * Sync scope determines which data is synced locally.
- * "global" means all data accessible to the user.
- * Custom strings reference scope definitions (e.g., "activeProject").
- */
-type SyncScope = "global" | string;
-/**
- * PowerSync strategy - data is synced to local SQLite via PowerSync
- */
-interface PowerSyncStrategy {
-    strategy: "powersync";
-    /** Which scope controls what data to sync */
-    syncScope: SyncScope;
-}
-/**
- * Supabase strategy - always query directly from Supabase (online only)
- */
-interface SupabaseStrategy {
-    strategy: "supabase";
-}
-/**
- * Cached strategy - query Supabase and cache in memory
- */
-interface CachedStrategy {
-    strategy: "cached";
-    /** How long to cache data in milliseconds */
-    cacheTime: number;
-}
-/**
- * Hybrid strategy - use PowerSync for recent data, fallback to cached for older
- */
-interface HybridStrategy {
-    strategy: "hybrid";
-    /** PowerSync configuration for frequently accessed data */
-    powersync: {
-        scope: SyncScope;
-        /** Optional limit on how many records to sync locally */
-        limit?: number;
-    };
-    /** Fallback for data not synced locally */
-    fallback: CachedStrategy;
-}
-/**
- * Auto strategy - automatically selects best backend at runtime
- */
-interface AutoStrategy {
-    strategy: "auto";
-    /** Prefer PowerSync when available (default: true) */
-    preferPowerSync?: boolean;
-}
-/**
- * Union type for all table strategies
- */
-type TableStrategy = PowerSyncStrategy | SupabaseStrategy | CachedStrategy | HybridStrategy | AutoStrategy;
-/**
- * Connection configuration for Supabase and PowerSync
- */
-interface ConnectionConfig {
-    supabase: {
-        /** Supabase project URL */
-        url: string;
-        /** Supabase anonymous key */
-        anonKey: string;
-    };
-    powerSync: {
-        /** PowerSync service URL */
-        url: string;
-    };
-}
-/**
- * Definition for a sync scope
- */
-interface ScopeDefinition {
-    /**
-     * Parameter key used to pass scope values to PowerSync sync rules.
-     * For example, "activeProjectIds" would pass selected project IDs to filter sync.
-     */
-    parameterKey?: string;
-}
-/**
- * Sync mode determines when and how syncing occurs
- */
-type SyncMode = 
-/** Manual - only sync when explicitly requested */
-"manual"
-/** On foreground - sync when app comes to foreground */
- | "onForeground"
-/** Periodic - sync at regular intervals */
- | "periodic"
-/** Live - maintain continuous sync connection */
- | "live";
-/**
- * Main configuration for the data layer
- * @template DB - The database types (from generated types)
- */
-interface DataLayerConfig<DB = unknown> {
-    /** Database schema definition */
-    schema: DatabaseSchema;
-    /** Connection configuration */
-    connections: ConnectionConfig;
-    /** Per-table strategy configuration */
-    tables: {
-        [tableName: string]: TableStrategy;
-    };
-    /** Scope definitions */
-    scopes: {
-        [scopeName: string]: ScopeDefinition;
-    };
-    /** Default settings */
-    defaults: {
-        /** Default sync mode */
-        syncMode: SyncMode;
-        /** Interval for periodic sync in milliseconds (default: 300000 = 5 min) */
-        periodicIntervalMs?: number;
-    };
-    /**
-     * Options for initial sync behavior when using PowerSync.
-     */
-    initialSync?: {
-        /**
-         * Use Supabase for queries until PowerSync completes initial sync.
-         *
-         * When true (default): Queries return online data from Supabase while
-         * PowerSync is downloading initial data, ensuring users see content
-         * immediately. Once sync completes, queries automatically switch to
-         * the local PowerSync database for offline-first operation.
-         *
-         * When false: Queries always use PowerSync (which may be empty during
-         * initial sync), showing loading states until data is available locally.
-         *
-         * @default true
-         */
-        useOnlineUntilSynced?: boolean;
-    };
-}
-/**
- * Comparison operators for where clauses
- */
-interface WhereOperators {
-    /** In array of values */
-    in?: (string | number)[];
-    /** Greater than */
-    gt?: number;
-    /** Greater than or equal */
-    gte?: number;
-    /** Less than */
-    lt?: number;
-    /** Less than or equal */
-    lte?: number;
-    /** LIKE pattern matching */
-    like?: string;
-    /** IS NULL check */
-    is?: null;
-    /** NOT equal */
-    neq?: string | number | boolean | null;
-    /** NOT in array */
-    notIn?: (string | number)[];
-}
-/**
- * Where clause for filtering queries
- */
-interface WhereClause {
-    [field: string]: string | number | boolean | null | WhereOperators;
-}
-/**
- * Order by clause for sorting results
- */
-interface OrderBy {
-    /** Field to sort by */
-    field: string;
-    /** Sort direction */
-    direction: "asc" | "desc";
-}
-/**
- * Options for query hooks
- */
-interface QueryOptions {
-    /**
-     * Select clause - supports relation syntax like "*, Relation(*)"
-     * Similar to Supabase select syntax
-     */
-    select?: string;
-    /** Where clause for filtering */
-    where?: WhereClause;
-    /** Order by clauses */
-    orderBy?: OrderBy[];
-    /** Maximum number of records to return */
-    limit?: number;
-    /** Number of records to skip */
-    offset?: number;
-    /**
-     * Whether the query is enabled.
-     * Set to false to disable the query (useful for conditional fetching)
-     */
-    enabled?: boolean;
-}
-/**
- * Result returned from query hooks
- * @template T - The type of data being queried
- */
-interface QueryResult<T> {
-    /** The queried data (undefined while loading) */
-    data: T[] | undefined;
-    /** True during initial load with no data */
-    isLoading: boolean;
-    /** True when no data has been fetched yet */
-    isPending: boolean;
-    /** True when fetching (including background refetch) */
-    isFetching: boolean;
-    /** Error if the query failed */
-    error: Error | null;
-    /** Function to manually refetch data */
-    refetch: () => Promise<void>;
-}
-/**
- * Result for a single-item query
- * @template T - The type of data being queried
- */
-interface QuerySingleResult<T> {
-    /** The queried data (undefined while loading, null if not found) */
-    data: T | null | undefined;
-    /** True during initial load with no data */
-    isLoading: boolean;
-    /** True when no data has been fetched yet */
-    isPending: boolean;
-    /** True when fetching (including background refetch) */
-    isFetching: boolean;
-    /** Error if the query failed */
-    error: Error | null;
-    /** Function to manually refetch data */
-    refetch: () => Promise<void>;
-}
-/**
- * Result from a single mutation operation
- * @template T - The type of data being mutated
- */
-interface MutationResult<T> {
-    /** Fire-and-forget mutation */
-    mutate: (data: Partial<T>) => void;
-    /** Async mutation that returns the result */
-    mutateAsync: (data: Partial<T>) => Promise<T>;
-    /** Whether the mutation is in progress */
-    isPending: boolean;
-    /** Error if the mutation failed */
-    error: Error | null;
-}
-/**
- * Result from a delete mutation
- */
-interface DeleteMutationResult {
-    /** Fire-and-forget delete */
-    mutate: (id: string) => void;
-    /** Async delete */
-    mutateAsync: (id: string) => Promise<void>;
-    /** Whether the delete is in progress */
-    isPending: boolean;
-    /** Error if the delete failed */
-    error: Error | null;
-}
-/**
- * Complete mutation hook result with all CRUD operations
- * @template T - The type of data being mutated
- */
-interface MutationHookResult<T> {
-    /** Upsert operation (insert or update based on primary key) */
-    upsert: MutationResult<T>;
-    /** Insert operation */
-    insert: MutationResult<T>;
-    /** Update operation */
-    update: MutationResult<T>;
-    /** Remove/delete operation */
-    remove: DeleteMutationResult;
-    /** Whether any mutation is in progress */
-    isPending: boolean;
-}
-/**
- * Current sync status
- */
-interface SyncStatus {
-    /** Whether connected to PowerSync service */
-    isConnected: boolean;
-    /** Whether currently syncing data */
-    isSyncing: boolean;
-    /** When the last successful sync completed */
-    lastSyncedAt: Date | null;
-    /** Number of local changes pending upload */
-    pendingUploads: number;
-    /** Any sync error */
-    error: Error | null;
-}
-/**
- * Controls for managing sync behavior
- */
-interface SyncControl {
-    /** Manually trigger a sync */
-    triggerSync: () => Promise<void>;
-    /** Start continuous live sync */
-    startLiveSync: () => Promise<void>;
-    /** Stop continuous sync */
-    stopLiveSync: () => void;
-    /**
-     * Set scope values to control what data is synced
-     * @param scopeName - Name of the scope (e.g., "activeProject")
-     * @param values - Array of values (e.g., project IDs)
-     */
-    setScope: (scopeName: string, values: string[]) => Promise<void>;
-}
-/**
- * Interface that all data adapters must implement
- * @template T - The row type
- */
-interface DataAdapter<T = unknown> {
-    /** Query multiple records */
-    query(options: QueryOptions): Promise<T[]>;
-    /** Query a single record by ID */
-    queryById(id: string, options?: Pick<QueryOptions, "select">): Promise<T | null>;
-    /** Insert a new record */
-    insert(data: Partial<T>): Promise<T>;
-    /** Update an existing record */
-    update(id: string, data: Partial<T>): Promise<T>;
-    /** Upsert (insert or update) a record */
-    upsert(data: Partial<T>): Promise<T>;
-    /** Delete a record */
-    delete(id: string): Promise<void>;
-}
-/**
- * Registry of adapters by table name
- */
-interface AdapterRegistry {
-    /** Get an adapter for a specific table */
-    getAdapter<T>(tableName: string): DataAdapter<T>;
-    /** Initialize all adapters (called by Provider) */
-    initialize(): Promise<void>;
-    /** Clean up adapters */
-    dispose(): void;
-}
-/**
- * Type for the useDbQuery hook
- */
-type UseDbQueryHook<DB> = <TableName extends string, T = unknown>(tableName: TableName, options?: QueryOptions) => QueryResult<T>;
-/**
- * Type for the useDbQueryById hook
- */
-type UseDbQueryByIdHook<DB> = <TableName extends string, T = unknown>(tableName: TableName, id: string | null | undefined, options?: Pick<QueryOptions, "select" | "enabled">) => QuerySingleResult<T>;
-/**
- * Type for the useDbMutation hook
- */
-type UseDbMutationHook<DB> = <TableName extends string, T = unknown>(tableName: TableName) => MutationHookResult<T>;
-/**
- * Collection of all V3 hooks
- */
-interface DataLayerHooks<DB> {
-    useDbQuery: UseDbQueryHook<DB>;
-    useDbQueryById: UseDbQueryByIdHook<DB>;
-    useDbMutation: UseDbMutationHook<DB>;
-    useSyncStatus: () => SyncStatus;
-    useSyncControl: () => SyncControl;
-    useOnlineStatus: () => {
-        isOnline: boolean;
-        isConnected: boolean;
-    };
-}
-/**
- * Extract row type from database for a given table
- */
-type ExtractRow<DB, SchemaName extends string = "public", TableName extends string = string> = DB extends {
-    [K in SchemaName]: {
-        Tables: {
-            [T in TableName]: {
-                Row: infer R;
-            };
-        };
-    };
-} ? R : unknown;
-/**
- * Extract insert type from database for a given table
- */
-type ExtractInsert<DB, SchemaName extends string = "public", TableName extends string = string> = DB extends {
-    [K in SchemaName]: {
-        Tables: {
-            [T in TableName]: {
-                Insert: infer I;
-            };
-        };
-    };
-} ? I : unknown;
-/**
- * Extract update type from database for a given table
- */
-type ExtractUpdate<DB, SchemaName extends string = "public", TableName extends string = string> = DB extends {
-    [K in SchemaName]: {
-        Tables: {
-            [T in TableName]: {
-                Update: infer U;
-            };
-        };
-    };
-} ? U : unknown;
-/**
- * Get all table names from a database schema
- */
-type TableNames<DB, SchemaName extends string = "public"> = DB extends {
-    [K in SchemaName]: {
-        Tables: infer T;
-    };
-} ? keyof T & string : string;
-/**
- * A single column in a parsed select statement
- */
-interface SelectColumn {
-    /** Column name */
-    name: string;
-    /** Optional alias for the column */
-    alias?: string;
-}
-/**
- * A relation in a parsed select statement (e.g., RelatedTable(*))
- */
-interface SelectRelation {
-    /** Relation/table name */
-    name: string;
-    /** Optional alias for the relation */
-    alias?: string;
-    /** Columns to select from the relation ("*" or specific columns) */
-    columns: "*" | SelectColumn[];
-    /** Nested relations within this relation */
-    relations: SelectRelation[];
-}
-/**
- * Complete parsed select statement AST
- */
-interface ParsedSelect {
-    /** Columns to select ("*" or specific columns) */
-    columns: "*" | SelectColumn[];
-    /** Relations to include */
-    relations: SelectRelation[];
-}
-/**
- * Type of relationship between tables
- * - one-to-many: Parent has many children (e.g., Project -> Tasks)
- * - many-to-one: Child belongs to parent (e.g., Task -> Project)
- */
-type RelationshipType = "one-to-many" | "many-to-one";
-/**
- * A resolved relationship with full context for joining
- */
-interface ResolvedRelationship {
-    /** The type of relationship */
-    type: RelationshipType;
-    /** The table we're querying from */
-    fromTable: string;
-    /** The related table */
-    toTable: string;
-    /** The foreign key column name */
-    foreignKey: string;
-    /** The referenced column (usually "id") */
-    referencedColumn: string;
-}
-/**
- * A built SQL query with parameterized values
- */
-interface BuiltQuery {
-    /** The SQL query string with ? placeholders */
-    sql: string;
-    /** Parameters to substitute for ? placeholders */
-    params: (string | number | boolean | null)[];
-}
-
-export type { AdapterRegistry, AutoStrategy, BuiltQuery, CachedStrategy, ColumnInfo, ColumnType, ConnectionConfig, DataAdapter, DataLayerConfig, DataLayerHooks, DatabaseSchema, DeleteMutationResult, ExtractInsert, ExtractRow, ExtractUpdate, HybridStrategy, MutationHookResult, MutationResult, OrderBy, ParsedSelect, PowerSyncStrategy, QueryOptions, QueryResult, QuerySingleResult, RelationshipInfo, RelationshipType, ResolvedRelationship, ScopeDefinition, SelectColumn, SelectRelation, SupabaseStrategy, SyncControl, SyncMode, SyncScope, SyncStatus, TableNames, TableSchema, TableStrategy, UseDbMutationHook, UseDbQueryByIdHook, UseDbQueryHook, WhereClause, WhereOperators };