@plyaz/db 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -7204,6 +7204,1201 @@ async function createDatabaseService(config) {
 }
 __name(createDatabaseService, "createDatabaseService");
 
+// src/builder/query/QueryBuilder.ts
+var QueryBuilder = class _QueryBuilder {
+  static {
+    __name(this, "QueryBuilder");
+  }
+  _filters = [];
+  _rawConditions = [];
+  _sort = [];
+  _pagination = {};
+  _schema;
+  _executor;
+  _operationConfig;
+  _countExecutor;
+  // Advanced query features
+  _joins = [];
+  _groupByFields = [];
+  _havingConditions = [];
+  _selectFields = [];
+  _selectRawExpressions = [];
+  _distinct = false;
+  /**
+   * Create a new QueryBuilder instance (standalone)
+   *
+   * @returns New QueryBuilder instance
+   *
+   * @example
+   * ```typescript
+   * const builder = QueryBuilder.create<User>();
+   * ```
+   */
+  static create() {
+    return new _QueryBuilder();
+  }
+  /**
+   * 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(executor) {
+    const builder = new _QueryBuilder();
+    builder._executor = executor;
+    return builder;
+  }
+  /**
+   * Private constructor - use QueryBuilder.create() or forRepository() instead
+   */
+  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(field, operator, value) {
+    this._filters.push({
+      field,
+      operator,
+      value,
+      logical: this._filters.length === 0 ? void 0 : "and"
+    });
+    return 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(field, operator, value) {
+    this._filters.push({
+      field,
+      operator,
+      value,
+      logical: "and"
+    });
+    return 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(field, operator, value) {
+    this._filters.push({
+      field,
+      operator,
+      value,
+      logical: "or"
+    });
+    return 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(field, values) {
+    this._filters.push({
+      field,
+      operator: "in",
+      value: values,
+      logical: this._filters.length === 0 ? void 0 : "and"
+    });
+    return 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(field, values) {
+    this._filters.push({
+      field,
+      operator: "notIn",
+      value: values,
+      logical: this._filters.length === 0 ? void 0 : "and"
+    });
+    return 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(field, min, max) {
+    this._filters.push({
+      field,
+      operator: "between",
+      value: [min, max],
+      logical: this._filters.length === 0 ? void 0 : "and"
+    });
+    return 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(field, pattern) {
+    this._filters.push({
+      field,
+      operator: "like",
+      value: pattern,
+      logical: this._filters.length === 0 ? void 0 : "and"
+    });
+    return 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(field) {
+    this._filters.push({
+      field,
+      operator: "isNull",
+      value: null,
+      logical: this._filters.length === 0 ? void 0 : "and"
+    });
+    return 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(field) {
+    this._filters.push({
+      field,
+      operator: "isNotNull",
+      value: null,
+      logical: this._filters.length === 0 ? void 0 : "and"
+    });
+    return 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, params = []) {
+    const hasConditions = this._filters.length > 0 || this._rawConditions.length > 0;
+    this._rawConditions.push({
+      clause,
+      params,
+      logical: hasConditions ? "and" : void 0
+    });
+    return 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, params = []) {
+    this._rawConditions.push({
+      clause,
+      params,
+      logical: "or"
+    });
+    return this;
+  }
+  // ============================================================
+  // SELECT Methods
+  // ============================================================
+  /**
+   * 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(...fields) {
+    this._selectFields.push(...fields);
+    return 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) {
+    this._selectRawExpressions.push(expression);
+    return this;
+  }
+  /**
+   * Add DISTINCT to SELECT
+   *
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * builder
+   *   .distinct()
+   *   .select('category')
+   *   .orderBy('category', 'asc')
+   * ```
+   */
+  distinct() {
+    this._distinct = true;
+    return this;
+  }
+  // ============================================================
+  // JOIN Methods
+  // ============================================================
+  /**
+   * 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, condition, alias) {
+    return this.innerJoin(table, condition, alias);
+  }
+  /**
+   * 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, condition, alias) {
+    const [schema, tableName] = this.parseTableName(table);
+    this._joins.push({
+      type: "inner",
+      table: tableName,
+      condition,
+      alias,
+      schema
+    });
+    return 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, condition, alias) {
+    const [schema, tableName] = this.parseTableName(table);
+    this._joins.push({
+      type: "left",
+      table: tableName,
+      condition,
+      alias,
+      schema
+    });
+    return 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, condition, alias) {
+    const [schema, tableName] = this.parseTableName(table);
+    this._joins.push({
+      type: "right",
+      table: tableName,
+      condition,
+      alias,
+      schema
+    });
+    return 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, condition, alias) {
+    const [schema, tableName] = this.parseTableName(table);
+    this._joins.push({
+      type: "full",
+      table: tableName,
+      condition,
+      alias,
+      schema
+    });
+    return this;
+  }
+  /**
+   * Parse table name that may include schema (schema.table)
+   */
+  parseTableName(table) {
+    const SCHEMA_TABLE_PARTS = 2;
+    const parts = table.split(".");
+    if (parts.length === SCHEMA_TABLE_PARTS) {
+      return [parts[0], parts[1]];
+    }
+    return [void 0, table];
+  }
+  // ============================================================
+  // GROUP BY / HAVING Methods
+  // ============================================================
+  /**
+   * 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(...fields) {
+    this._groupByFields.push(...fields);
+    return 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, params = []) {
+    this._havingConditions.push({
+      clause,
+      params,
+      logical: this._havingConditions.length === 0 ? void 0 : "and"
+    });
+    return this;
+  }
+  /**
+   * Add HAVING condition with OR
+   *
+   * @param clause - Raw SQL HAVING condition
+   * @param params - Parameter values
+   * @returns This builder for chaining
+   */
+  orHaving(clause, params = []) {
+    this._havingConditions.push({
+      clause,
+      params,
+      logical: "or"
+    });
+    return 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(field, direction = "asc") {
+    this._sort.push({ field, direction });
+    return 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(field) {
+    return this.orderBy(field, "asc");
+  }
+  /**
+   * 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(field) {
+    return this.orderBy(field, "desc");
+  }
+  /**
+   * Set LIMIT for results
+   *
+   * @param limit - Maximum number of results to return
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.limit(20)
+   * ```
+   */
+  limit(limit) {
+    this._pagination.limit = limit;
+    return this;
+  }
+  /**
+   * Set OFFSET for results
+   *
+   * @param offset - Number of results to skip
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.offset(40)
+   * ```
+   */
+  offset(offset) {
+    this._pagination.offset = offset;
+    return 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, pageSize) {
+    this._pagination.limit = pageSize;
+    this._pagination.offset = (page - 1) * pageSize;
+    return 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) {
+    this._pagination.cursor = cursor;
+    return this;
+  }
+  /**
+   * Set database schema
+   *
+   * @param schema - Schema name to query from
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.schema('analytics')
+   * ```
+   */
+  schema(schema) {
+    this._schema = schema;
+    return 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) {
+    this._operationConfig = config;
+    return 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);
+   * }
+   * ```
+   */
+  async execute() {
+    if (!this._executor) {
+      throw new Error(
+        "QueryBuilder has no executor. Use repository.query() or QueryBuilder.forRepository() to enable execute()."
+      );
+    }
+    return this._executor.findMany(this.build(), this._operationConfig);
+  }
+  /**
+   * 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();
+   * ```
+   */
+  async getMany() {
+    const result = await this.execute();
+    if (!result.success || !result.value) {
+      throw result.error ?? new Error("Query failed");
+    }
+    return result.value.data;
+  }
+  /**
+   * 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();
+   * ```
+   */
+  async getOne() {
+    const originalLimit = this._pagination.limit;
+    this._pagination.limit = 1;
+    const result = await this.execute();
+    this._pagination.limit = originalLimit;
+    if (!result.success || !result.value) {
+      throw result.error ?? new Error("Query failed");
+    }
+    return result.value.data[0] ?? 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();
+   * ```
+   */
+  async count() {
+    if (!this._executor) {
+      throw new Error(
+        "QueryBuilder has no executor. Use repository.query() to enable count()."
+      );
+    }
+    if (!this._executor.count) {
+      throw new Error("Executor does not support count().");
+    }
+    const filter = this._filters.length > 0 ? this._filters[0] : void 0;
+    const result = await this._executor.count(filter, this._operationConfig);
+    if (!result.success) {
+      throw result.error ?? new Error("Count query failed");
+    }
+    return result.value ?? 0;
+  }
+  /**
+   * 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();
+   * ```
+   */
+  async exists() {
+    const count = await this.count();
+    return count > 0;
+  }
+  /**
+   * 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() {
+    const options = {};
+    if (this._filters.length > 0) {
+      options.filter = this._filters[0];
+    }
+    if (this._sort.length > 0) {
+      options.sort = this._sort;
+    }
+    if (this._pagination.limit !== void 0 || this._pagination.offset !== void 0 || this._pagination.cursor !== void 0) {
+      options.pagination = this._pagination;
+    }
+    if (this._schema) {
+      options.schema = this._schema;
+    }
+    return options;
+  }
+  /**
+   * 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() {
+    const result = {
+      options: this.build(),
+      filters: [...this._filters],
+      rawConditions: [...this._rawConditions],
+      joins: [...this._joins]
+    };
+    if (this._groupByFields.length > 0) {
+      result.groupBy = {
+        fields: [...this._groupByFields],
+        having: this._havingConditions.length > 0 ? this._havingConditions.map((h) => ({ ...h })) : void 0
+      };
+    }
+    if (this._selectFields.length > 0 || this._selectRawExpressions.length > 0 || this._distinct) {
+      result.select = {
+        fields: [...this._selectFields],
+        rawExpressions: [...this._selectRawExpressions],
+        distinct: this._distinct
+      };
+    }
+    return result;
+  }
+  /**
+   * 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() {
+    return [...this._filters];
+  }
+  /**
+   * 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() {
+    return [...this._rawConditions];
+  }
+  /**
+   * Get array of sort options
+   *
+   * @returns Array of SortOptions
+   */
+  toSortOptions() {
+    return [...this._sort];
+  }
+  /**
+   * Get pagination options
+   *
+   * @returns PaginationOptions
+   */
+  toPaginationOptions() {
+    return { ...this._pagination };
+  }
+  /**
+   * Check if any filters are defined (standard or raw)
+   *
+   * @returns True if filters exist
+   */
+  hasFilters() {
+    return this._filters.length > 0 || this._rawConditions.length > 0;
+  }
+  /**
+   * Check if raw SQL conditions are defined
+   *
+   * @returns True if raw conditions exist
+   */
+  hasRawConditions() {
+    return this._rawConditions.length > 0;
+  }
+  /**
+   * Check if sorting is defined
+   *
+   * @returns True if sort options exist
+   */
+  hasSort() {
+    return this._sort.length > 0;
+  }
+  /**
+   * Check if pagination is defined
+   *
+   * @returns True if pagination options exist
+   */
+  hasPagination() {
+    return this._pagination.limit !== void 0 || this._pagination.offset !== void 0 || this._pagination.cursor !== void 0;
+  }
+  /**
+   * Reset all query parameters
+   *
+   * @returns This builder for chaining
+   */
+  reset() {
+    this._filters = [];
+    this._rawConditions = [];
+    this._sort = [];
+    this._pagination = {};
+    this._schema = void 0;
+    this._operationConfig = void 0;
+    this._joins = [];
+    this._groupByFields = [];
+    this._havingConditions = [];
+    this._selectFields = [];
+    this._selectRawExpressions = [];
+    this._distinct = false;
+    return 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() {
+    const cloned = new _QueryBuilder();
+    cloned._filters = [...this._filters];
+    cloned._rawConditions = this._rawConditions.map((rc) => ({ ...rc }));
+    cloned._sort = [...this._sort];
+    cloned._pagination = { ...this._pagination };
+    cloned._schema = this._schema;
+    cloned._executor = this._executor;
+    cloned._operationConfig = this._operationConfig ? { ...this._operationConfig } : void 0;
+    cloned._joins = this._joins.map((j) => ({ ...j }));
+    cloned._groupByFields = [...this._groupByFields];
+    cloned._havingConditions = this._havingConditions.map((h) => ({ ...h }));
+    cloned._selectFields = [...this._selectFields];
+    cloned._selectRawExpressions = [...this._selectRawExpressions];
+    cloned._distinct = this._distinct;
+    return cloned;
+  }
+  // ============================================================
+  // Additional Helper Methods
+  // ============================================================
+  /**
+   * Check if JOINs are defined
+   *
+   * @returns True if joins exist
+   */
+  hasJoins() {
+    return this._joins.length > 0;
+  }
+  /**
+   * Check if GROUP BY is defined
+   *
+   * @returns True if group by fields exist
+   */
+  hasGroupBy() {
+    return this._groupByFields.length > 0;
+  }
+  /**
+   * Check if custom SELECT is defined
+   *
+   * @returns True if select fields or expressions exist
+   */
+  hasSelect() {
+    return this._selectFields.length > 0 || this._selectRawExpressions.length > 0 || this._distinct;
+  }
+  /**
+   * Get JOIN clauses
+   *
+   * @returns Array of JoinClause objects
+   */
+  toJoins() {
+    return [...this._joins];
+  }
+  /**
+   * Get GROUP BY fields
+   *
+   * @returns Array of field names
+   */
+  toGroupByFields() {
+    return [...this._groupByFields];
+  }
+  /**
+   * Get HAVING conditions
+   *
+   * @returns Array of RawCondition objects
+   */
+  toHavingConditions() {
+    return [...this._havingConditions];
+  }
+  /**
+   * Get SELECT fields
+   *
+   * @returns Array of field names
+   */
+  toSelectFields() {
+    return [...this._selectFields];
+  }
+  /**
+   * Get SELECT raw expressions
+   *
+   * @returns Array of raw SQL expressions
+   */
+  toSelectRawExpressions() {
+    return [...this._selectRawExpressions];
+  }
+  /**
+   * Check if DISTINCT is enabled
+   *
+   * @returns True if distinct is enabled
+   */
+  isDistinct() {
+    return this._distinct;
+  }
+  /**
+   * 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
+   * ```
+   */
+  // eslint-disable-next-line complexity
+  toSQL(tableName) {
+    const parts = [];
+    const selectParts = [];
+    if (this._selectFields.length > 0) {
+      selectParts.push(...this._selectFields.map((f) => `"${f}"`));
+    }
+    if (this._selectRawExpressions.length > 0) {
+      selectParts.push(...this._selectRawExpressions);
+    }
+    const selectClause = selectParts.length > 0 ? selectParts.join(", ") : "*";
+    parts.push(
+      `SELECT ${this._distinct ? "DISTINCT " : ""}${selectClause} FROM "${tableName}"`
+    );
+    for (const join4 of this._joins) {
+      const joinType = join4.type.toUpperCase();
+      const tableRef = join4.schema ? `"${join4.schema}"."${join4.table}"` : `"${join4.table}"`;
+      const aliasStr = join4.alias ? ` AS "${join4.alias}"` : "";
+      parts.push(
+        `${joinType} JOIN ${tableRef}${aliasStr} ON ${join4.condition}`
+      );
+    }
+    if (this._filters.length > 0 || this._rawConditions.length > 0) {
+      const whereParts = [];
+      for (const filter of this._filters) {
+        whereParts.push(`"${filter.field}" ${filter.operator} ?`);
+      }
+      for (const raw of this._rawConditions) {
+        whereParts.push(raw.clause);
+      }
+      parts.push(`WHERE ${whereParts.join(" AND ")}`);
+    }
+    if (this._groupByFields.length > 0) {
+      parts.push(
+        `GROUP BY ${this._groupByFields.map((f) => `"${f}"`).join(", ")}`
+      );
+    }
+    if (this._havingConditions.length > 0) {
+      const havingParts = this._havingConditions.map((h) => h.clause);
+      parts.push(`HAVING ${havingParts.join(" AND ")}`);
+    }
+    if (this._sort.length > 0) {
+      const orderParts = this._sort.map(
+        (s) => `"${s.field}" ${s.direction.toUpperCase()}`
+      );
+      parts.push(`ORDER BY ${orderParts.join(", ")}`);
+    }
+    if (this._pagination.limit !== void 0) {
+      parts.push(`LIMIT ${this._pagination.limit}`);
+    }
+    if (this._pagination.offset !== void 0) {
+      parts.push(`OFFSET ${this._pagination.offset}`);
+    }
+    return parts.join("\n");
+  }
+};
+
 // src/repository/BaseRepository.ts
 var BaseRepository = class {
   constructor(db, tableName, defaultConfig) {
@@ -7215,6 +8410,47 @@ var BaseRepository = class {
     __name(this, "BaseRepository");
   }
   defaultConfig;
+  /**
+   * Create a fluent QueryBuilder for this repository
+   *
+   * Returns a type-safe, chainable query builder that can execute queries
+   * directly against this repository.
+   *
+   * @returns QueryBuilder bound to this repository
+   *
+   * @example
+   * ```typescript
+   * // Fluent query with execute
+   * const result = await userRepository.query()
+   *   .where('status', 'eq', 'active')
+   *   .orderByDesc('createdAt')
+   *   .limit(20)
+   *   .execute();
+   *
+   * // Get data directly
+   * const users = await userRepository.query()
+   *   .where('role', 'eq', 'admin')
+   *   .getMany();
+   *
+   * // Get single record
+   * const user = await userRepository.query()
+   *   .where('email', 'eq', 'john@example.com')
+   *   .getOne();
+   *
+   * // Complex queries
+   * const orders = await orderRepository.query()
+   *   .where('status', 'eq', 'pending')
+   *   .andWhere('totalAmount', 'gte', 100)
+   *   .orWhere('priority', 'eq', 'high')
+   *   .whereIn('region', ['US', 'EU'])
+   *   .orderBy('createdAt', 'desc')
+   *   .paginate(1, 25)
+   *   .execute();
+   * ```
+   */
+  query() {
+    return QueryBuilder.forRepository(this);
+  }
   /**
    * Get the table name for this repository
    *
@@ -7265,18 +8501,28 @@ var BaseRepository = class {
   /**
    * Find multiple entities with optional filtering, sorting, and pagination
    *
-   * @param {QueryOptions<T>} [options] - Optional query configuration with type-safe fields
+   * Accepts either QueryOptions object or a QueryBuilder instance.
+   *
+   * @param {QueryOptions<T> | QueryBuilder<T>} [options] - Query configuration or QueryBuilder
    * @param {OperationConfig} [config] - Optional per-operation configuration (adapter selection, schema override, etc.)
    * @returns {Promise<DatabaseResult<PaginatedResult<T>>>} Promise resolving to paginated results
    *
    * @example
    * ```typescript
+   * // Using QueryOptions (traditional)
    * const result = await userRepository.findMany({
    *   filter: { field: 'status', operator: 'eq', value: 'active' },
    *   sort: [{ field: 'createdAt', direction: 'desc' }],
    *   pagination: { limit: 20, offset: 0 }
    * });
    *
+   * // Using QueryBuilder
+   * const query = QueryBuilder.create<User>()
+   *   .where('status', 'eq', 'active')
+   *   .orderByDesc('createdAt')
+   *   .limit(20);
+   * const result = await userRepository.findMany(query);
+   *
    * // Query from analytics database
    * const analyticsResult = await userRepository.findMany({}, {
    *   adapter: 'analytics'
@@ -7284,7 +8530,12 @@ var BaseRepository = class {
    * ```
    */
   async findMany(options, config) {
-    return this.db.list(this.tableName, options, this.mergeConfig(config));
+    const queryOptions = options instanceof QueryBuilder ? options.build() : options;
+    return this.db.list(
+      this.tableName,
+      queryOptions,
+      this.mergeConfig(config)
+    );
   }
   /**
    * Create a new entity in the database
@@ -7370,7 +8621,9 @@ var BaseRepository = class {
   /**
    * Count entities matching optional filter criteria
    *
-   * @param {Filter<T>} [filter] - Optional filter conditions with type-safe fields
+   * Accepts either a Filter object or a QueryBuilder instance.
+   *
+   * @param {Filter<T> | QueryBuilder<T>} [filter] - Filter conditions or QueryBuilder
    * @param {OperationConfig} [config] - Optional per-operation configuration (adapter selection, schema override, etc.)
    * @returns {Promise<DatabaseResult<number>>} Promise resolving to the count
    *
@@ -7381,6 +8634,12 @@ var BaseRepository = class {
    *   field: 'status', operator: 'eq', value: 'active'
    * });
    *
+   * // Using QueryBuilder
+   * const query = QueryBuilder.create<User>()
+   *   .where('status', 'eq', 'active')
+   *   .andWhere('verified', 'eq', true);
+   * const result = await userRepository.count(query);
+   *
    * // Count in specific adapter
    * const archiveCount = await userRepository.count(undefined, {
    *   adapter: 'archive'
@@ -7388,7 +8647,12 @@ var BaseRepository = class {
    * ```
    */
   async count(filter, config) {
-    return this.db.count(this.tableName, filter, this.mergeConfig(config));
+    const filterOptions = filter instanceof QueryBuilder ? filter.toFilters()[0] : filter;
+    return this.db.count(
+      this.tableName,
+      filterOptions,
+      this.mergeConfig(config)
+    );
   }
   /**
    * Check if an entity exists by ID
@@ -7425,7 +8689,9 @@ var BaseRepository = class {
   /**
    * Find the first entity matching filter criteria
    *
-   * @param {Filter<T>} filter - Filter conditions with type-safe fields
+   * Accepts either a Filter object or a QueryBuilder instance.
+   *
+   * @param {Filter<T> | QueryBuilder<T>} filter - Filter conditions or QueryBuilder
    * @param {OperationConfig} [config] - Optional per-operation configuration (adapter selection, schema override, etc.)
    * @returns {Promise<DatabaseResult<T | null>>} Promise resolving to first match or null
    *
@@ -7435,6 +8701,12 @@ var BaseRepository = class {
    *   field: 'email', operator: 'eq', value: 'john@example.com'
    * });
    *
+   * // Using QueryBuilder
+   * const query = QueryBuilder.create<User>()
+   *   .where('email', 'eq', 'john@example.com')
+   *   .andWhere('status', 'eq', 'active');
+   * const result = await userRepository.findOne(query);
+   *
    * // Find in specific adapter
    * const archivedUser = await userRepository.findOne({
    *   field: 'email', operator: 'eq', value: 'john@example.com'
@@ -7445,7 +8717,19 @@ var BaseRepository = class {
    * ```
    */
   async findOne(filter, config) {
-    return this.db.findOne(this.tableName, filter, this.mergeConfig(config));
+    const filterOptions = filter instanceof QueryBuilder ? filter.toFilters()[0] : filter;
+    if (!filterOptions) {
+      return {
+        success: false,
+        value: null,
+        error: new Error("findOne requires at least one filter condition")
+      };
+    }
+    return this.db.findOne(
+      this.tableName,
+      filterOptions,
+      this.mergeConfig(config)
+    );
   }
   /**
    * Soft delete an entity by ID (recoverable deletion)
@@ -11415,6 +12699,7 @@ exports.MigrationManager = MigrationManager;
 exports.MockAdapter = MockAdapter;
 exports.MultiReadAdapter = MultiReadAdapter;
 exports.MultiWriteAdapter = MultiWriteAdapter;
+exports.QueryBuilder = QueryBuilder;
 exports.ReadReplicaAdapter = ReadReplicaAdapter;
 exports.RedisCache = RedisCache;
 exports.SQLAdapter = SQLAdapter;