@pol-studios/db 1.0.19 → 1.0.21

package/dist/core/index.d.ts

@@ -0,0 +1,539 @@
+/**
+ * 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;
+    /**
+     * Alias used in PowerSync schema for this table.
+     * Required when multiple schemas have tables with the same name.
+     * If not provided, auto-generated from schema.Table → SchemaTable (PascalCase).
+     * Example: "core.Profile" → "CoreProfile"
+     */
+    alias?: string;
+}
+/**
+ * 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;
+    /**
+     * Alias used in PowerSync schema for this table.
+     * See PowerSyncStrategy.alias for details.
+     */
+    alias?: string;
+}
+/**
+ * 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 };