@plyaz/db 0.4.1 → 0.5.0

package/dist/builder/query/QueryBuilder.d.ts

@@ -0,0 +1,850 @@
+/**
+ * @fileoverview Fluent Query Builder for @plyaz/db
+ *
+ * Provides a type-safe, chainable API for building database queries.
+ * Works with BaseRepository and can generate both QueryOptions and Filter arrays.
+ *
+ * @example
+ * ```typescript
+ * // Integrated with repository (recommended)
+ * const result = await userRepository.query()
+ *   .where('status', 'eq', 'active')
+ *   .orderByDesc('createdAt')
+ *   .limit(20)
+ *   .execute();
+ *
+ * // Standalone usage
+ * const query = QueryBuilder.create<User>()
+ *   .where('status', 'eq', 'active')
+ *   .orderByDesc('createdAt')
+ *   .limit(20)
+ *   .build();
+ *
+ * const result = await userRepository.findMany(query);
+ *
+ * // Complex query with multiple conditions
+ * const result = await orderRepository.query()
+ *   .where('status', 'eq', 'pending')
+ *   .andWhere('totalAmount', 'gte', 100)
+ *   .orWhere('priority', 'eq', 'high')
+ *   .whereIn('region', ['US', 'EU', 'APAC'])
+ *   .orderBy('createdAt', 'desc')
+ *   .paginate(1, 25)
+ *   .execute();
+ * ```
+ */
+import type { Filter, QueryOptions, SortOptions, PaginationOptions, DatabaseResult, PaginatedResult, OperationConfig, FilterOperator, RawCondition, JoinClause, GroupByClause, SelectClause, QueryBuilderResult, QueryExecutor } from "@plyaz/types/db";
+export type { FilterOperator, RawCondition, JoinClause, GroupByClause, SelectClause, QueryBuilderResult, QueryExecutor, };
+/**
+ * Fluent Query Builder
+ *
+ * Provides a chainable API for constructing database queries with type safety.
+ *
+ * **Design Philosophy:**
+ * - Type-safe field names derived from entity type
+ * - Chainable methods for intuitive query construction
+ * - Dual output: QueryOptions for repository, Filter[] for SQL builder
+ * - Direct repository integration via execute()
+ *
+ * **Application Flow:**
+ * ```
+ * repository.query()           // or QueryBuilder.create<Entity>()
+ *     ↓
+ * .where() / .orderBy() / .limit() chains
+ *     ↓
+ * .execute()                   // or .build() → repository.findMany(options)
+ *     ↓
+ * DatabaseResult<PaginatedResult<Entity>>
+ * ```
+ *
+ * @template TRecord The entity type this query operates on
+ */
+export declare class QueryBuilder<TRecord extends object> {
+    private _filters;
+    private _rawConditions;
+    private _sort;
+    private _pagination;
+    private _schema?;
+    private _executor?;
+    private _operationConfig?;
+    private _countExecutor?;
+    private _joins;
+    private _groupByFields;
+    private _havingConditions;
+    private _selectFields;
+    private _selectRawExpressions;
+    private _distinct;
+    /**
+     * Create a new QueryBuilder instance (standalone)
+     *
+     * @returns New QueryBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const builder = QueryBuilder.create<User>();
+     * ```
+     */
+    static create<T extends object>(): QueryBuilder<T>;
+    /**
+     * Create a QueryBuilder bound to a repository for direct execution
+     *
+     * @param executor - Repository or object with findMany method
+     * @returns New QueryBuilder instance bound to executor
+     *
+     * @example
+     * ```typescript
+     * // Usually called via repository.query()
+     * const builder = QueryBuilder.forRepository(userRepository);
+     * const result = await builder.where('status', 'eq', 'active').execute();
+     * ```
+     */
+    static forRepository<T extends object>(executor: QueryExecutor<T>): QueryBuilder<T>;
+    /**
+     * Private constructor - use QueryBuilder.create() or forRepository() instead
+     */
+    private constructor();
+    /**
+     * Add a WHERE condition with AND logical operator
+     *
+     * @param field - Field name to filter on
+     * @param operator - Comparison operator
+     * @param value - Value to compare against
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.where('status', 'eq', 'active')
+     * ```
+     */
+    where<K extends keyof TRecord & string>(field: K, operator: FilterOperator, value: TRecord[K]): this;
+    /**
+     * Add a WHERE condition with explicit AND logical operator
+     *
+     * @param field - Field name to filter on
+     * @param operator - Comparison operator
+     * @param value - Value to compare against
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.where('status', 'eq', 'active')
+     *        .andWhere('role', 'eq', 'admin')
+     * ```
+     */
+    andWhere<K extends keyof TRecord & string>(field: K, operator: FilterOperator, value: TRecord[K]): this;
+    /**
+     * Add a WHERE condition with OR logical operator
+     *
+     * @param field - Field name to filter on
+     * @param operator - Comparison operator
+     * @param value - Value to compare against
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.where('status', 'eq', 'active')
+     *        .orWhere('status', 'eq', 'pending')
+     * ```
+     */
+    orWhere<K extends keyof TRecord & string>(field: K, operator: FilterOperator, value: TRecord[K]): this;
+    /**
+     * Add a WHERE IN condition
+     *
+     * @param field - Field name to filter on
+     * @param values - Array of values to match
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.whereIn('status', ['active', 'pending', 'review'])
+     * ```
+     */
+    whereIn<K extends keyof TRecord & string>(field: K, values: TRecord[K][]): this;
+    /**
+     * Add a WHERE NOT IN condition
+     *
+     * @param field - Field name to filter on
+     * @param values - Array of values to exclude
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.whereNotIn('status', ['deleted', 'archived'])
+     * ```
+     */
+    whereNotIn<K extends keyof TRecord & string>(field: K, values: TRecord[K][]): this;
+    /**
+     * Add a WHERE BETWEEN condition
+     *
+     * @param field - Field name to filter on
+     * @param min - Minimum value (inclusive)
+     * @param max - Maximum value (inclusive)
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.whereBetween('price', 10, 100)
+     * builder.whereBetween('createdAt', startDate, endDate)
+     * ```
+     */
+    whereBetween<K extends keyof TRecord & string>(field: K, min: TRecord[K], max: TRecord[K]): this;
+    /**
+     * Add a WHERE LIKE condition (pattern matching)
+     *
+     * @param field - Field name to filter on
+     * @param pattern - LIKE pattern (use % for wildcards)
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.whereLike('email', '%@example.com')
+     * builder.whereLike('name', 'John%')
+     * ```
+     */
+    whereLike<K extends keyof TRecord & string>(field: K, pattern: string): this;
+    /**
+     * Add a WHERE IS NULL condition
+     *
+     * @param field - Field name to check for NULL
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.whereNull('deletedAt')
+     * ```
+     */
+    whereNull<K extends keyof TRecord & string>(field: K): this;
+    /**
+     * Add a WHERE IS NOT NULL condition
+     *
+     * @param field - Field name to check for non-NULL
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.whereNotNull('verifiedAt')
+     * ```
+     */
+    whereNotNull<K extends keyof TRecord & string>(field: K): this;
+    /**
+     * Add a raw SQL WHERE condition for complex queries
+     *
+     * Use this for conditions that cannot be expressed with the standard operators,
+     * such as subqueries, JSON operations, full-text search, or database-specific functions.
+     *
+     * @param clause - Raw SQL clause (use $1, $2, etc. for parameter placeholders)
+     * @param params - Parameter values for the clause (prevents SQL injection)
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * // JSON field query (PostgreSQL)
+     * builder.whereRaw('"metadata"->\'tags\' @> $1', [JSON.stringify(['featured'])])
+     *
+     * // Full-text search
+     * builder.whereRaw('to_tsvector(name) @@ plainto_tsquery($1)', ['search term'])
+     *
+     * // Subquery
+     * builder.whereRaw('"id" IN (SELECT user_id FROM orders WHERE total > $1)', [1000])
+     *
+     * // Date functions
+     * builder.whereRaw('DATE_TRUNC(\'month\', "createdAt") = DATE_TRUNC(\'month\', $1)', [new Date()])
+     *
+     * // Complex conditions
+     * builder
+     *   .where('status', 'eq', 'active')
+     *   .whereRaw('("score" > $1 OR "isPremium" = $2)', [80, true])
+     * ```
+     */
+    whereRaw(clause: string, params?: unknown[]): this;
+    /**
+     * Add a raw SQL WHERE condition with OR logical operator
+     *
+     * @param clause - Raw SQL clause (use $1, $2, etc. for parameter placeholders)
+     * @param params - Parameter values for the clause
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder
+     *   .where('status', 'eq', 'active')
+     *   .orWhereRaw('"metadata"->\'priority\' = $1', ['"high"'])
+     * ```
+     */
+    orWhereRaw(clause: string, params?: unknown[]): this;
+    /**
+     * Select specific fields (columns) to return
+     *
+     * @param fields - Field names to select
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.select('id', 'name', 'email')
+     *
+     * // With table prefix for joins
+     * builder
+     *   .select('users.id', 'users.name', 'orders.total')
+     *   .leftJoin('orders', 'users.id = orders.user_id')
+     * ```
+     */
+    select<K extends keyof TRecord & string>(...fields: (K | string)[]): this;
+    /**
+     * Add raw SELECT expression
+     *
+     * @param expression - Raw SQL expression
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder
+     *   .select('id', 'name')
+     *   .selectRaw('COUNT(*) as order_count')
+     *   .selectRaw('SUM(orders.total) as total_spent')
+     * ```
+     */
+    selectRaw(expression: string): this;
+    /**
+     * Add DISTINCT to SELECT
+     *
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder
+     *   .distinct()
+     *   .select('category')
+     *   .orderBy('category', 'asc')
+     * ```
+     */
+    distinct(): this;
+    /**
+     * Add INNER JOIN clause
+     *
+     * @param table - Table to join
+     * @param condition - Join condition
+     * @param alias - Optional alias for the joined table
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder
+     *   .join('orders', 'users.id = orders.user_id')
+     *   .where('orders.status', 'eq', 'completed')
+     *
+     * // With alias
+     * builder.join('orders', 'u.id = o.user_id', 'o')
+     *
+     * // With schema
+     * builder.innerJoin('analytics.events', 'users.id = events.user_id')
+     * ```
+     */
+    join(table: string, condition: string, alias?: string): this;
+    /**
+     * Add INNER JOIN clause (explicit)
+     *
+     * @param table - Table to join (can include schema: 'schema.table')
+     * @param condition - Join condition
+     * @param alias - Optional alias for the joined table
+     * @returns This builder for chaining
+     */
+    innerJoin(table: string, condition: string, alias?: string): this;
+    /**
+     * Add LEFT JOIN clause
+     *
+     * @param table - Table to join (can include schema: 'schema.table')
+     * @param condition - Join condition
+     * @param alias - Optional alias for the joined table
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder
+     *   .leftJoin('orders', 'users.id = orders.user_id')
+     *   .select('users.*', 'orders.total')
+     * ```
+     */
+    leftJoin(table: string, condition: string, alias?: string): this;
+    /**
+     * Add RIGHT JOIN clause
+     *
+     * @param table - Table to join (can include schema: 'schema.table')
+     * @param condition - Join condition
+     * @param alias - Optional alias for the joined table
+     * @returns This builder for chaining
+     */
+    rightJoin(table: string, condition: string, alias?: string): this;
+    /**
+     * Add FULL OUTER JOIN clause
+     *
+     * @param table - Table to join (can include schema: 'schema.table')
+     * @param condition - Join condition
+     * @param alias - Optional alias for the joined table
+     * @returns This builder for chaining
+     */
+    fullJoin(table: string, condition: string, alias?: string): this;
+    /**
+     * Parse table name that may include schema (schema.table)
+     */
+    private parseTableName;
+    /**
+     * Add GROUP BY clause
+     *
+     * @param fields - Fields to group by
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder
+     *   .select('status')
+     *   .selectRaw('COUNT(*) as count')
+     *   .groupBy('status')
+     *
+     * // Multiple fields
+     * builder
+     *   .select('region', 'status')
+     *   .selectRaw('SUM(amount) as total')
+     *   .groupBy('region', 'status')
+     * ```
+     */
+    groupBy<K extends keyof TRecord & string>(...fields: (K | string)[]): this;
+    /**
+     * Add HAVING condition (for use with GROUP BY)
+     *
+     * @param clause - Raw SQL HAVING condition (use $1, $2 for params)
+     * @param params - Parameter values
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder
+     *   .select('status')
+     *   .selectRaw('COUNT(*) as count')
+     *   .groupBy('status')
+     *   .having('COUNT(*) > $1', [10])
+     *
+     * // Multiple having conditions
+     * builder
+     *   .groupBy('category')
+     *   .selectRaw('AVG(price) as avg_price')
+     *   .having('AVG(price) > $1', [100])
+     *   .having('COUNT(*) >= $1', [5])
+     * ```
+     */
+    having(clause: string, params?: unknown[]): this;
+    /**
+     * Add HAVING condition with OR
+     *
+     * @param clause - Raw SQL HAVING condition
+     * @param params - Parameter values
+     * @returns This builder for chaining
+     */
+    orHaving(clause: string, params?: unknown[]): this;
+    /**
+     * Add ORDER BY clause
+     *
+     * @param field - Field name to sort by
+     * @param direction - Sort direction ('asc' or 'desc')
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.orderBy('createdAt', 'desc')
+     * ```
+     */
+    orderBy<K extends keyof TRecord & string>(field: K, direction?: "asc" | "desc"): this;
+    /**
+     * Add ORDER BY ASC clause (convenience method)
+     *
+     * @param field - Field name to sort by ascending
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.orderByAsc('name')
+     * ```
+     */
+    orderByAsc<K extends keyof TRecord & string>(field: K): this;
+    /**
+     * Add ORDER BY DESC clause (convenience method)
+     *
+     * @param field - Field name to sort by descending
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.orderByDesc('createdAt')
+     * ```
+     */
+    orderByDesc<K extends keyof TRecord & string>(field: K): this;
+    /**
+     * Set LIMIT for results
+     *
+     * @param limit - Maximum number of results to return
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.limit(20)
+     * ```
+     */
+    limit(limit: number): this;
+    /**
+     * Set OFFSET for results
+     *
+     * @param offset - Number of results to skip
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.offset(40)
+     * ```
+     */
+    offset(offset: number): this;
+    /**
+     * Set pagination by page number
+     *
+     * @param page - Page number (1-indexed)
+     * @param pageSize - Number of items per page
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.paginate(2, 25) // Page 2, 25 items per page
+     * ```
+     */
+    paginate(page: number, pageSize: number): this;
+    /**
+     * Set cursor for cursor-based pagination
+     *
+     * @param cursor - Cursor string from previous query
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.afterCursor('eyJpZCI6MTIzfQ==')
+     * ```
+     */
+    afterCursor(cursor: string): this;
+    /**
+     * Set database schema
+     *
+     * @param schema - Schema name to query from
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.schema('analytics')
+     * ```
+     */
+    schema(schema: string): this;
+    /**
+     * Set operation config for execute()
+     *
+     * @param config - Operation configuration (adapter, schema override, etc.)
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * const result = await userRepository.query()
+     *   .where('status', 'eq', 'active')
+     *   .withConfig({ adapter: 'analytics' })
+     *   .execute();
+     * ```
+     */
+    withConfig(config: OperationConfig): this;
+    /**
+     * Execute the query using the bound repository
+     *
+     * Requires QueryBuilder to be created via repository.query() or forRepository()
+     *
+     * @returns Promise resolving to paginated results
+     * @throws Error if no executor is bound
+     *
+     * @example
+     * ```typescript
+     * const result = await userRepository.query()
+     *   .where('status', 'eq', 'active')
+     *   .orderByDesc('createdAt')
+     *   .limit(20)
+     *   .execute();
+     *
+     * if (result.success) {
+     *   console.log('Found users:', result.value.data);
+     * }
+     * ```
+     */
+    execute(): Promise<DatabaseResult<PaginatedResult<TRecord>>>;
+    /**
+     * Execute and return just the data array (convenience method)
+     *
+     * @returns Promise resolving to array of records
+     * @throws Error if query fails or no executor
+     *
+     * @example
+     * ```typescript
+     * const users = await userRepository.query()
+     *   .where('status', 'eq', 'active')
+     *   .getMany();
+     * ```
+     */
+    getMany(): Promise<TRecord[]>;
+    /**
+     * Execute and return the first result (convenience method)
+     *
+     * @returns Promise resolving to first record or null
+     * @throws Error if query fails or no executor
+     *
+     * @example
+     * ```typescript
+     * const user = await userRepository.query()
+     *   .where('email', 'eq', 'john@example.com')
+     *   .getOne();
+     * ```
+     */
+    getOne(): Promise<TRecord | null>;
+    /**
+     * Execute a count query
+     *
+     * Returns the count of records matching the filter conditions.
+     * Requires QueryBuilder to be created via repository.query() or forRepository()
+     *
+     * @returns Promise resolving to the count
+     * @throws Error if no executor or count not supported
+     *
+     * @example
+     * ```typescript
+     * const count = await userRepository.query()
+     *   .where('status', 'eq', 'active')
+     *   .count();
+     *
+     * // Complex count
+     * const premiumCount = await userRepository.query()
+     *   .where('role', 'eq', 'premium')
+     *   .andWhere('verified', 'eq', true)
+     *   .count();
+     * ```
+     */
+    count(): Promise<number>;
+    /**
+     * Check if any records exist matching the conditions
+     *
+     * @returns Promise resolving to true if at least one record exists
+     * @throws Error if query fails or no executor
+     *
+     * @example
+     * ```typescript
+     * const hasActiveUsers = await userRepository.query()
+     *   .where('status', 'eq', 'active')
+     *   .exists();
+     * ```
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Build QueryOptions for BaseRepository.findMany()
+     *
+     * For single filter queries, returns standard QueryOptions.
+     * For multi-filter queries, returns the first filter (use toFilters() for full array).
+     *
+     * @returns QueryOptions compatible with BaseRepository
+     *
+     * @example
+     * ```typescript
+     * const options = builder.build();
+     * const result = await repository.findMany(options);
+     * ```
+     */
+    build(): QueryOptions<TRecord>;
+    /**
+     * Build and return full result including filters array and raw conditions
+     *
+     * Use this when you need access to all filters for direct SQL building
+     * or when using multi-condition queries with raw SQL.
+     *
+     * @returns QueryBuilderResult with options, filters, and raw conditions
+     *
+     * @example
+     * ```typescript
+     * const { options, filters, rawConditions } = builder.buildFull();
+     *
+     * // Use options for repository
+     * const result = await repository.findMany(options);
+     *
+     * // Use filters for custom SQL building
+     * const whereClause = buildWhereClause(filters);
+     *
+     * // Append raw conditions manually
+     * rawConditions.forEach(raw => {
+     *   whereClause += ` ${raw.logical?.toUpperCase() ?? ''} ${raw.clause}`;
+     * });
+     * ```
+     */
+    buildFull(): QueryBuilderResult<TRecord>;
+    /**
+     * Get array of all filters
+     *
+     * Use for direct SQL building with buildWhereClause()
+     *
+     * @returns Array of Filter objects
+     *
+     * @example
+     * ```typescript
+     * const filters = builder.toFilters();
+     * const whereClause = buildWhereClause(filters);
+     * ```
+     */
+    toFilters(): Filter<TRecord>[];
+    /**
+     * Get array of raw SQL conditions
+     *
+     * Use for manual SQL building with complex conditions
+     *
+     * @returns Array of RawCondition objects
+     *
+     * @example
+     * ```typescript
+     * const rawConditions = builder.toRawConditions();
+     * // Manually append to WHERE clause
+     * ```
+     */
+    toRawConditions(): RawCondition[];
+    /**
+     * Get array of sort options
+     *
+     * @returns Array of SortOptions
+     */
+    toSortOptions(): SortOptions<TRecord>[];
+    /**
+     * Get pagination options
+     *
+     * @returns PaginationOptions
+     */
+    toPaginationOptions(): PaginationOptions;
+    /**
+     * Check if any filters are defined (standard or raw)
+     *
+     * @returns True if filters exist
+     */
+    hasFilters(): boolean;
+    /**
+     * Check if raw SQL conditions are defined
+     *
+     * @returns True if raw conditions exist
+     */
+    hasRawConditions(): boolean;
+    /**
+     * Check if sorting is defined
+     *
+     * @returns True if sort options exist
+     */
+    hasSort(): boolean;
+    /**
+     * Check if pagination is defined
+     *
+     * @returns True if pagination options exist
+     */
+    hasPagination(): boolean;
+    /**
+     * Reset all query parameters
+     *
+     * @returns This builder for chaining
+     */
+    reset(): this;
+    /**
+     * Clone this query builder
+     *
+     * @returns New QueryBuilder with same parameters
+     *
+     * @example
+     * ```typescript
+     * const baseQuery = QueryBuilder.create<User>()
+     *   .where('status', 'eq', 'active');
+     *
+     * const adminQuery = baseQuery.clone()
+     *   .andWhere('role', 'eq', 'admin');
+     *
+     * const userQuery = baseQuery.clone()
+     *   .andWhere('role', 'eq', 'user');
+     * ```
+     */
+    clone(): QueryBuilder<TRecord>;
+    /**
+     * Check if JOINs are defined
+     *
+     * @returns True if joins exist
+     */
+    hasJoins(): boolean;
+    /**
+     * Check if GROUP BY is defined
+     *
+     * @returns True if group by fields exist
+     */
+    hasGroupBy(): boolean;
+    /**
+     * Check if custom SELECT is defined
+     *
+     * @returns True if select fields or expressions exist
+     */
+    hasSelect(): boolean;
+    /**
+     * Get JOIN clauses
+     *
+     * @returns Array of JoinClause objects
+     */
+    toJoins(): JoinClause[];
+    /**
+     * Get GROUP BY fields
+     *
+     * @returns Array of field names
+     */
+    toGroupByFields(): string[];
+    /**
+     * Get HAVING conditions
+     *
+     * @returns Array of RawCondition objects
+     */
+    toHavingConditions(): RawCondition[];
+    /**
+     * Get SELECT fields
+     *
+     * @returns Array of field names
+     */
+    toSelectFields(): string[];
+    /**
+     * Get SELECT raw expressions
+     *
+     * @returns Array of raw SQL expressions
+     */
+    toSelectRawExpressions(): string[];
+    /**
+     * Check if DISTINCT is enabled
+     *
+     * @returns True if distinct is enabled
+     */
+    isDistinct(): boolean;
+    /**
+     * Generate SQL query string (for debugging/logging)
+     *
+     * Note: This is a simplified SQL representation. The actual query
+     * execution uses the adapter's SQL generation.
+     *
+     * @param tableName - Base table name
+     * @returns SQL query string
+     *
+     * @example
+     * ```typescript
+     * const sql = builder
+     *   .select('id', 'name')
+     *   .leftJoin('orders', 'users.id = orders.user_id')
+     *   .where('status', 'eq', 'active')
+     *   .toSQL('users');
+     *
+     * console.log(sql);
+     * // SELECT "id", "name" FROM "users"
+     * // LEFT JOIN "orders" ON users.id = orders.user_id
+     * // WHERE "status" = $1
+     * ```
+     */
+    toSQL(tableName: string): string;
+}
+//# sourceMappingURL=QueryBuilder.d.ts.map