@pol-studios/db 1.0.19 → 1.0.21

package/dist/executor-CB4KHyYG.d.ts

@@ -0,0 +1,507 @@
+import { DatabaseSchema, ResolvedRelationship, TableSchema, SelectColumn, WhereClause, OrderBy, BuiltQuery, QueryOptions } from './core/index.js';
+
+/**
+ * Relationship Resolver
+ *
+ * Looks up relationships between tables from the database schema.
+ * Used to determine how to join related data in queries.
+ */
+
+/**
+ * Resolves relationships between tables using the database schema.
+ *
+ * Given a table and a relation name (which could be another table),
+ * this class determines:
+ * 1. Whether a relationship exists
+ * 2. The type of relationship (one-to-many or many-to-one)
+ * 3. Which columns are used for the join
+ */
+declare class RelationshipResolver {
+    private schema;
+    constructor(schema: DatabaseSchema);
+    /**
+     * Resolve a relationship from one table to another.
+     *
+     * This handles both:
+     * - Forward relationships: This table has a FK to the related table (many-to-one)
+     * - Reverse relationships: Related table has a FK to this table (one-to-many)
+     *
+     * @param fromTable - The table we're querying from
+     * @param relationName - The name of the related table
+     * @returns The resolved relationship or null if not found
+     *
+     * @example
+     * // Forward relationship (many-to-one)
+     * // EquipmentUnit.projectDatabaseId -> ProjectDatabase.id
+     * resolver.resolve("EquipmentUnit", "ProjectDatabase")
+     * // Returns: {
+     * //   type: "many-to-one",
+     * //   fromTable: "EquipmentUnit",
+     * //   toTable: "ProjectDatabase",
+     * //   foreignKey: "projectDatabaseId",
+     * //   referencedColumn: "id"
+     * // }
+     *
+     * @example
+     * // Reverse relationship (one-to-many)
+     * // EquipmentUnit <- EquipmentFixture.equipmentUnitId
+     * resolver.resolve("EquipmentUnit", "EquipmentFixture")
+     * // Returns: {
+     * //   type: "one-to-many",
+     * //   fromTable: "EquipmentUnit",
+     * //   toTable: "EquipmentFixture",
+     * //   foreignKey: "equipmentUnitId",
+     * //   referencedColumn: "id"
+     * // }
+     */
+    resolve(fromTable: string, relationName: string): ResolvedRelationship | null;
+    /**
+     * Get all forward relationships for a table (many-to-one).
+     * These are relationships where this table has a foreign key.
+     */
+    getForwardRelationships(tableName: string): ResolvedRelationship[];
+    /**
+     * Get all reverse relationships for a table (one-to-many).
+     * These are relationships where other tables have FKs pointing to this table.
+     */
+    getReverseRelationships(tableName: string): ResolvedRelationship[];
+    /**
+     * Get all relationships for a table (both directions).
+     */
+    getAllRelationships(tableName: string): ResolvedRelationship[];
+    /**
+     * Check if a relationship exists between two tables.
+     */
+    hasRelationship(fromTable: string, toTable: string): boolean;
+    /**
+     * Get the table schema from the database schema.
+     * Searches across all schema namespaces (public, core, etc.).
+     */
+    getTableSchema(tableName: string): TableSchema | null;
+    /**
+     * Get the primary key column for a table.
+     * Defaults to "id" if not explicitly found.
+     */
+    getPrimaryKey(tableName: string): string;
+    /**
+     * Get all column names for a table.
+     */
+    getColumnNames(tableName: string): string[];
+    /**
+     * Check if a table exists in the schema.
+     */
+    hasTable(tableName: string): boolean;
+    /**
+     * Get all table names in the schema.
+     */
+    getAllTableNames(): string[];
+}
+/**
+ * Create a relationship resolver instance.
+ * Convenience function for creating a resolver.
+ */
+declare function createRelationshipResolver(schema: DatabaseSchema): RelationshipResolver;
+
+/**
+ * SQL Builder
+ *
+ * Builds SQLite queries from parsed select statements and query options.
+ * Produces parameterized queries for safe execution against PowerSync's local SQLite.
+ *
+ * Note: SQLite uses double quotes for identifiers (table/column names).
+ * This builder only creates queries for single tables - relations are queried
+ * separately and joined in code.
+ */
+
+/**
+ * SQLite query builder.
+ * Creates parameterized SQL queries for local SQLite execution.
+ */
+declare class SQLBuilder {
+    /**
+     * Build a SELECT query for a single table.
+     *
+     * @param table - Table name
+     * @param columns - Columns to select ("*" or array of column definitions)
+     * @param options - Query options (where, orderBy, limit, offset)
+     * @returns Built query with SQL and parameters
+     *
+     * @example
+     * const builder = new SQLBuilder();
+     * const query = builder.build("EquipmentUnit", "*", {
+     *   where: { status: "active", projectDatabaseId: 123 },
+     *   orderBy: [{ field: "name", direction: "asc" }],
+     *   limit: 10
+     * });
+     * // query.sql: SELECT * FROM "EquipmentUnit" WHERE "status" = ? AND "projectDatabaseId" = ? ORDER BY "name" ASC LIMIT ?
+     * // query.params: ["active", 123, 10]
+     */
+    build(table: string, columns: "*" | SelectColumn[], options?: {
+        where?: WhereClause;
+        orderBy?: OrderBy[];
+        limit?: number;
+        offset?: number;
+    }): BuiltQuery;
+    /**
+     * Build WHERE clauses from operator objects.
+     */
+    private buildOperatorClauses;
+    /**
+     * Build a query to fetch related records by foreign key.
+     *
+     * @param table - The related table name
+     * @param foreignKey - The FK column to match against
+     * @param parentIds - Array of parent IDs to fetch related records for
+     * @param columns - Columns to select
+     * @returns Built query
+     *
+     * @example
+     * // Fetch all EquipmentFixtures for given EquipmentUnit IDs
+     * const query = builder.buildRelationQuery(
+     *   "EquipmentFixture",
+     *   "equipmentUnitId",
+     *   ["uuid-1", "uuid-2"],
+     *   "*"
+     * );
+     * // query.sql: SELECT * FROM "EquipmentFixture" WHERE "equipmentUnitId" IN (?, ?)
+     * // query.params: ["uuid-1", "uuid-2"]
+     */
+    buildRelationQuery(table: string, foreignKey: string, parentIds: (string | number)[], columns: "*" | SelectColumn[]): BuiltQuery;
+    /**
+     * Build column list ensuring the foreign key is included.
+     */
+    private buildColumnList;
+    /**
+     * Build a SELECT query for a single record by ID.
+     *
+     * @param table - Table name
+     * @param id - Record ID
+     * @param columns - Columns to select
+     * @param idColumn - Name of the ID column (defaults to "id")
+     * @returns Built query
+     */
+    buildByIdQuery(table: string, id: string | number, columns?: "*" | SelectColumn[], idColumn?: string): BuiltQuery;
+    /**
+     * Build an INSERT query.
+     *
+     * @param table - Table name
+     * @param data - Record data to insert
+     * @returns Built query
+     */
+    buildInsertQuery(table: string, data: Record<string, unknown>): BuiltQuery;
+    /**
+     * Build an UPDATE query.
+     *
+     * @param table - Table name
+     * @param id - Record ID
+     * @param data - Fields to update
+     * @param idColumn - Name of the ID column (defaults to "id")
+     * @returns Built query
+     */
+    buildUpdateQuery(table: string, id: string | number, data: Record<string, unknown>, idColumn?: string): BuiltQuery;
+    /**
+     * Build a DELETE query.
+     *
+     * @param table - Table name
+     * @param id - Record ID
+     * @param idColumn - Name of the ID column (defaults to "id")
+     * @returns Built query
+     */
+    buildDeleteQuery(table: string, id: string | number, idColumn?: string): BuiltQuery;
+    /**
+     * Build a COUNT query.
+     *
+     * @param table - Table name
+     * @param where - Optional where clause
+     * @returns Built query
+     */
+    buildCountQuery(table: string, where?: WhereClause): BuiltQuery;
+}
+/**
+ * Create a new SQL builder instance.
+ */
+declare function createSQLBuilder(): SQLBuilder;
+
+/**
+ * Result Joiner
+ *
+ * After querying the base table and related tables separately,
+ * this module joins them into a nested structure matching Supabase's format.
+ */
+
+/**
+ * Data about a relation to be joined onto base records.
+ */
+interface RelationJoinData {
+    records: Record<string, unknown>[];
+    relationship: ResolvedRelationship;
+    nestedRelations: Map<string, RelationJoinData>;
+}
+/**
+ * Result joiner for combining base records with related data.
+ *
+ * This class handles joining related data onto base records after
+ * separate queries have been executed. It supports:
+ * - One-to-many relationships (base gets array of related)
+ * - Many-to-one relationships (base gets single related object or null)
+ * - Nested relationships (recursive joining)
+ */
+declare class ResultJoiner {
+    /**
+     * Join related data onto base records.
+     *
+     * @param baseRecords - The base table records
+     * @param relatedRecords - Records from the related table
+     * @param relationship - The relationship definition
+     * @param relationName - The property name to use for the relation
+     * @returns Base records with related data attached
+     *
+     * @example
+     * // One-to-many: EquipmentUnit -> EquipmentFixture[]
+     * const joiner = new ResultJoiner();
+     * const result = joiner.join(
+     *   equipmentUnits,
+     *   equipmentFixtures,
+     *   { type: "one-to-many", foreignKey: "equipmentUnitId", referencedColumn: "id", ... },
+     *   "EquipmentFixture"
+     * );
+     * // Each equipmentUnit now has EquipmentFixture: [...]
+     *
+     * @example
+     * // Many-to-one: EquipmentUnit -> ProjectDatabase
+     * const result = joiner.join(
+     *   equipmentUnits,
+     *   projectDatabases,
+     *   { type: "many-to-one", foreignKey: "projectDatabaseId", referencedColumn: "id", ... },
+     *   "ProjectDatabase"
+     * );
+     * // Each equipmentUnit now has ProjectDatabase: {...} or null
+     */
+    join<T extends Record<string, unknown>>(baseRecords: T[], relatedRecords: Record<string, unknown>[], relationship: ResolvedRelationship, relationName: string): T[];
+    /**
+     * Recursively join nested relations onto records.
+     *
+     * @param baseRecords - The base records
+     * @param relationData - Map of relation names to join data
+     * @returns Base records with all nested relations attached
+     *
+     * @example
+     * // Join EquipmentFixture and ProjectDatabase onto EquipmentUnit
+     * // where EquipmentFixture has its own nested Organization relation
+     * const result = joiner.joinNested(equipmentUnits, new Map([
+     *   ["EquipmentFixture", {
+     *     records: fixtures,
+     *     relationship: { type: "one-to-many", ... },
+     *     nestedRelations: new Map()
+     *   }],
+     *   ["ProjectDatabase", {
+     *     records: projects,
+     *     relationship: { type: "many-to-one", ... },
+     *     nestedRelations: new Map([
+     *       ["Organization", { records: orgs, relationship: ..., nestedRelations: new Map() }]
+     *     ])
+     *   }]
+     * ]));
+     */
+    joinNested<T extends Record<string, unknown>>(baseRecords: T[], relationData: Map<string, RelationJoinData>): T[];
+    /**
+     * Group records by a key field.
+     * Useful for preparing data before joining.
+     *
+     * @param records - Records to group
+     * @param keyField - Field to group by
+     * @returns Map of key values to arrays of records
+     */
+    groupBy<T extends Record<string, unknown>>(records: T[], keyField: string): Map<unknown, T[]>;
+    /**
+     * Index records by a unique key field.
+     * Useful for many-to-one lookups.
+     *
+     * @param records - Records to index
+     * @param keyField - Field to index by (should be unique)
+     * @returns Map of key values to single records
+     */
+    indexBy<T extends Record<string, unknown>>(records: T[], keyField: string): Map<unknown, T>;
+    /**
+     * Extract unique values for a field from records.
+     * Useful for building IN clauses for related queries.
+     *
+     * @param records - Records to extract from
+     * @param field - Field to extract
+     * @returns Array of unique non-null values
+     */
+    extractUniqueValues<T extends Record<string, unknown>>(records: T[], field: string): (string | number)[];
+    /**
+     * Remove a relation property from records (for cleanup).
+     *
+     * @param records - Records to process
+     * @param relationName - Relation property to remove
+     * @returns Records without the specified property
+     */
+    removeRelation<T extends Record<string, unknown>>(records: T[], relationName: string): Omit<T, typeof relationName>[];
+    /**
+     * Flatten a nested relation into the parent record.
+     * Useful for flattening many-to-one relations.
+     *
+     * @param records - Records with nested relation
+     * @param relationName - Name of the relation to flatten
+     * @param prefix - Prefix for flattened field names
+     * @returns Records with flattened relation fields
+     */
+    flattenRelation<T extends Record<string, unknown>>(records: T[], relationName: string, prefix?: string): Record<string, unknown>[];
+}
+/**
+ * Create a new result joiner instance.
+ */
+declare function createResultJoiner(): ResultJoiner;
+
+/**
+ * Query Executor
+ *
+ * Orchestrates the full query execution pipeline:
+ * 1. Parse select string
+ * 2. Build SQL queries
+ * 3. Execute against PowerSync database
+ * 4. Join related data
+ *
+ * This provides a unified interface for executing Supabase-style queries
+ * against the local SQLite database via PowerSync.
+ */
+
+/**
+ * Interface for PowerSync database.
+ * This matches the getAll method signature from @powersync/react-native.
+ */
+interface PowerSyncDatabase {
+    getAll<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    get<T>(sql: string, params?: unknown[]): Promise<T | null>;
+    execute(sql: string, params?: unknown[]): Promise<{
+        rowsAffected: number;
+    }>;
+}
+/**
+ * Query executor that handles the full query lifecycle.
+ *
+ * @example
+ * const executor = new QueryExecutor(db, databaseSchema);
+ *
+ * // Simple query
+ * const units = await executor.execute<EquipmentUnit>("EquipmentUnit", {
+ *   where: { status: "active" },
+ *   orderBy: [{ field: "name", direction: "asc" }],
+ *   limit: 10
+ * });
+ *
+ * // Query with relations
+ * const unitsWithRelations = await executor.execute<EquipmentUnitWithRelations>(
+ *   "EquipmentUnit",
+ *   {
+ *     select: "*, EquipmentFixture(*), ProjectDatabase(name, Organization(*))",
+ *     where: { status: "active" }
+ *   }
+ * );
+ */
+declare class QueryExecutor {
+    private db;
+    private schema;
+    private resolver;
+    private builder;
+    private joiner;
+    constructor(db: PowerSyncDatabase, schema: DatabaseSchema);
+    /**
+     * Execute a query and return results.
+     *
+     * @param table - The table to query
+     * @param options - Query options including select, where, orderBy, limit, offset
+     * @returns Array of records with relations attached
+     */
+    execute<T>(table: string, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Execute a query for a single record by ID.
+     *
+     * @param table - The table to query
+     * @param id - The record ID
+     * @param options - Query options (only select is used)
+     * @returns Single record or null
+     */
+    executeById<T>(table: string, id: string | number, options?: Pick<QueryOptions, "select">): Promise<T | null>;
+    /**
+     * Execute a count query.
+     *
+     * @param table - The table to count
+     * @param options - Query options (only where is used)
+     * @returns Count of matching records
+     */
+    count(table: string, options?: Pick<QueryOptions, "where">): Promise<number>;
+    /**
+     * Insert a record.
+     *
+     * @param table - The table to insert into
+     * @param data - The record data
+     * @returns The inserted record (re-fetched to get defaults)
+     */
+    insert<T>(table: string, data: Record<string, unknown>): Promise<T>;
+    /**
+     * Update a record.
+     *
+     * @param table - The table to update
+     * @param id - The record ID
+     * @param data - The fields to update
+     * @returns The updated record
+     */
+    update<T>(table: string, id: string | number, data: Record<string, unknown>): Promise<T>;
+    /**
+     * Upsert a record (insert or update).
+     *
+     * @param table - The table to upsert into
+     * @param data - The record data (must include ID for update)
+     * @returns The upserted record
+     */
+    upsert<T>(table: string, data: Record<string, unknown>): Promise<T>;
+    /**
+     * Delete a record.
+     *
+     * @param table - The table to delete from
+     * @param id - The record ID
+     */
+    delete(table: string, id: string | number): Promise<void>;
+    /**
+     * Query and join relations onto parent records.
+     *
+     * @param parentTable - The parent table name
+     * @param parentRecords - Parent records to add relations to
+     * @param relations - Relations to query and join
+     * @returns Parent records with relations attached
+     */
+    private queryAndJoinRelations;
+    /**
+     * Get parent IDs needed for a relation query.
+     */
+    private getParentIdsForRelation;
+    /**
+     * Build a query for related records.
+     */
+    private buildRelatedQuery;
+    /**
+     * Get the relationship resolver (for advanced use).
+     */
+    getResolver(): RelationshipResolver;
+    /**
+     * Get the SQL builder (for advanced use).
+     */
+    getBuilder(): SQLBuilder;
+    /**
+     * Get the result joiner (for advanced use).
+     */
+    getJoiner(): ResultJoiner;
+}
+/**
+ * Create a query executor instance.
+ *
+ * @param db - PowerSync database instance
+ * @param schema - Database schema
+ * @returns QueryExecutor instance
+ */
+declare function createQueryExecutor(db: PowerSyncDatabase, schema: DatabaseSchema): QueryExecutor;
+
+export { type PowerSyncDatabase as P, QueryExecutor as Q, RelationshipResolver as R, SQLBuilder as S, createSQLBuilder as a, ResultJoiner as b, createRelationshipResolver as c, createResultJoiner as d, type RelationJoinData as e, createQueryExecutor as f };