workers-qb 1.12.0 → 1.14.0

package/dist/index.d.mts

@@ -16,7 +16,18 @@ declare enum ConflictTypes {
 declare enum JoinTypes {
     INNER = "INNER",
     LEFT = "LEFT",
-    CROSS = "CROSS"
+    CROSS = "CROSS",
+    RIGHT = "RIGHT",
+    FULL = "FULL",
+    NATURAL = "NATURAL"
+}
+declare enum SetOperationType {
+    UNION = "UNION",
+    UNION_ALL = "UNION ALL",
+    INTERSECT = "INTERSECT",
+    INTERSECT_ALL = "INTERSECT ALL",
+    EXCEPT = "EXCEPT",
+    EXCEPT_ALL = "EXCEPT ALL"
 }
 
 /**
@@ -88,8 +99,8 @@ type SchemaAware<S extends TableSchema, Strict, Loose> = IsEmptySchema<S> extend
 
 declare class Raw {
     isRaw: boolean;
-    content: any;
-    constructor(content: any);
+    content: string;
+    constructor(content: string);
 }
 declare class Query<Result = any, IsAsync extends boolean = true> {
     executeMethod: (query: Query<Result, IsAsync>) => MaybeAsync<IsAsync, Result>;
@@ -99,6 +110,28 @@ declare class Query<Result = any, IsAsync extends boolean = true> {
     constructor(executeMethod: (query: Query<Result, IsAsync>) => MaybeAsync<IsAsync, Result>, query: string, args?: Primitive[], fetchType?: FetchTypes);
     execute(): MaybeAsync<IsAsync, Result>;
     toObject(): RawQuery;
+    /**
+     * Returns the SQL query string and parameters without executing.
+     * Useful for debugging and logging.
+     *
+     * @example
+     * const { sql, params } = qb.select('users').where('id = ?', 1).getQueryAll().toSQL()
+     * // sql: "SELECT * FROM users WHERE id = ?"
+     * // params: [1]
+     */
+    toSQL(): {
+        sql: string;
+        params: Primitive[];
+    };
+    /**
+     * Returns the SQL query with parameters interpolated for debugging purposes.
+     * WARNING: This should NEVER be used to execute queries as it bypasses parameterization.
+     *
+     * @example
+     * const debugSql = qb.select('users').where('id = ?', 1).getQueryAll().toDebugSQL()
+     * // "SELECT * FROM users WHERE id = 1"
+     */
+    toDebugSQL(): string;
 }
 declare class QueryWithExtra<GenericResultWrapper, Result = any, IsAsync extends boolean = true> extends Query<Result, IsAsync> {
     private countQuery;
@@ -107,6 +140,10 @@ declare class QueryWithExtra<GenericResultWrapper, Result = any, IsAsync extends
 }
 declare function trimQuery(query: string): string;
 
+interface PaginateOptions {
+    page: number;
+    perPage: number;
+}
 interface SelectExecuteOptions {
     lazy?: boolean;
 }
@@ -119,9 +156,330 @@ declare class SelectBuilder<Schema extends TableSchema = {}, GenericResultWrappe
     setDebugger(state: boolean): void;
     tableName(tableName: SelectAll['tableName']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
     fields(fields: SelectAll['fields']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Enable DISTINCT selection to remove duplicate rows from results.
+     *
+     * @param columns - Optional array of columns for DISTINCT ON (PostgreSQL only).
+     *                  If not provided, applies simple DISTINCT.
+     *
+     * @example
+     * // Simple DISTINCT
+     * qb.select('users').distinct().execute()
+     * // SELECT DISTINCT * FROM users
+     *
+     * @example
+     * // DISTINCT ON specific columns (PostgreSQL)
+     * qb.select('users').distinct(['department']).fields(['department', 'name']).execute()
+     * // SELECT DISTINCT ON (department) department, name FROM users
+     */
+    distinct(columns?: Array<string>): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
     where(conditions: string | Array<string>, params?: Primitive | Primitive[]): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add an OR WHERE condition to the query.
+     * All previously added WHERE conditions are grouped together and ORed with the new condition.
+     * Subsequent `.where()` calls after `.orWhere()` are ANDed as independent conditions.
+     *
+     * @param conditions - The SQL condition string(s) (can use ? placeholders)
+     * @param params - The parameter(s) to bind to the ? placeholders
+     *
+     * @example
+     * // Simple OR condition
+     * qb.select('users').where('status = ?', 'active').orWhere('status = ?', 'pending').execute()
+     * // SELECT * FROM users WHERE (status = ?) OR (status = ?)
+     *
+     * @example
+     * // Multiple where conditions ORed together
+     * qb.select('users')
+     *   .where('tenant_id = ?', 1)
+     *   .where('status = ?', 'active')
+     *   .orWhere('role = ?', 'superadmin')
+     *   .execute()
+     * // SELECT * FROM users WHERE ((tenant_id = ?) AND (status = ?)) OR (role = ?)
+     */
+    orWhere(conditions: string | Array<string>, params?: Primitive | Primitive[]): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
     whereIn<T extends string | Array<string>, P extends T extends Array<string> ? Primitive[][] : Primitive[]>(fields: T, values: P): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Conditionally apply query modifications based on a runtime value.
+     * If condition is truthy, the callback is invoked with the current builder
+     * and its return value is used. If condition is falsy and an otherwise callback
+     * is provided, it is invoked instead. Otherwise, the builder is returned unchanged.
+     *
+     * @param condition - A value to check for truthiness
+     * @param callback - Function that receives the builder and returns a modified builder
+     * @param otherwise - Optional function applied when condition is falsy
+     *
+     * @example
+     * qb.select('users')
+     *   .when(nameFilter, q => q.where('name LIKE ?', [`%${nameFilter}%`]))
+     *   .when(sortByDate, q => q.orderBy({ created_at: 'DESC' }))
+     *   .execute()
+     *
+     * @example
+     * // With otherwise callback
+     * qb.select('products')
+     *   .when(
+     *     inStock,
+     *     q => q.where('stock > ?', 0),
+     *     q => q.where('stock = ?', 0)
+     *   )
+     *   .execute()
+     */
+    when<T>(condition: T | undefined | null | false | 0 | '', callback: (builder: SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>) => SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>, otherwise?: (builder: SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>) => SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a WHERE column IS NULL condition.
+     *
+     * @param column - The column name to check for NULL
+     *
+     * @example
+     * qb.select('users').whereNull('deleted_at').execute()
+     * // SELECT * FROM users WHERE deleted_at IS NULL
+     */
+    whereNull(column: string): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a WHERE column IS NOT NULL condition.
+     *
+     * @param column - The column name to check for NOT NULL
+     *
+     * @example
+     * qb.select('users').whereNotNull('email_verified_at').execute()
+     * // SELECT * FROM users WHERE email_verified_at IS NOT NULL
+     */
+    whereNotNull(column: string): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a WHERE column BETWEEN min AND max condition.
+     *
+     * @param column - The column name
+     * @param range - Tuple of [min, max] values
+     *
+     * @example
+     * qb.select('products').whereBetween('price', [10, 100]).execute()
+     * // SELECT * FROM products WHERE price BETWEEN ? AND ?
+     */
+    whereBetween(column: string, range: [Primitive, Primitive]): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a WHERE column NOT BETWEEN min AND max condition.
+     *
+     * @param column - The column name
+     * @param range - Tuple of [min, max] values
+     *
+     * @example
+     * qb.select('products').whereNotBetween('price', [10, 100]).execute()
+     * // SELECT * FROM products WHERE price NOT BETWEEN ? AND ?
+     */
+    whereNotBetween(column: string, range: [Primitive, Primitive]): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add an OR WHERE column IS NULL condition.
+     *
+     * @param column - The column name to check for NULL
+     *
+     * @example
+     * qb.select('users').where('active = ?', true).orWhereNull('deleted_at').execute()
+     * // SELECT * FROM users WHERE (active = ?) OR (deleted_at IS NULL)
+     */
+    orWhereNull(column: string): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add an OR WHERE column IS NOT NULL condition.
+     *
+     * @param column - The column name to check for NOT NULL
+     *
+     * @example
+     * qb.select('users').whereNull('deleted_at').orWhereNotNull('verified_at').execute()
+     * // SELECT * FROM users WHERE (deleted_at IS NULL) OR (verified_at IS NOT NULL)
+     */
+    orWhereNotNull(column: string): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add an OR WHERE column BETWEEN min AND max condition.
+     *
+     * @param column - The column name
+     * @param range - Tuple of [min, max] values
+     *
+     * @example
+     * qb.select('products').where('active = ?', true).orWhereBetween('price', [10, 100]).execute()
+     * // SELECT * FROM products WHERE (active = ?) OR (price BETWEEN ? AND ?)
+     */
+    orWhereBetween(column: string, range: [Primitive, Primitive]): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add an OR WHERE column NOT BETWEEN min AND max condition.
+     *
+     * @param column - The column name
+     * @param range - Tuple of [min, max] values
+     *
+     * @example
+     * qb.select('products').where('featured = ?', true).orWhereNotBetween('price', [10, 100]).execute()
+     * // SELECT * FROM products WHERE (featured = ?) OR (price NOT BETWEEN ? AND ?)
+     */
+    orWhereNotBetween(column: string, range: [Primitive, Primitive]): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a WHERE column LIKE pattern condition.
+     *
+     * @param column - The column name
+     * @param pattern - The LIKE pattern (e.g., '%search%')
+     *
+     * @example
+     * qb.select('users').whereLike('name', '%john%').execute()
+     * // SELECT * FROM users WHERE name LIKE ?
+     */
+    whereLike(column: string, pattern: string): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a WHERE column NOT LIKE pattern condition.
+     *
+     * @param column - The column name
+     * @param pattern - The LIKE pattern
+     *
+     * @example
+     * qb.select('users').whereNotLike('email', '%@spam.com').execute()
+     * // SELECT * FROM users WHERE email NOT LIKE ?
+     */
+    whereNotLike(column: string, pattern: string): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add an OR WHERE column LIKE pattern condition.
+     *
+     * @param column - The column name
+     * @param pattern - The LIKE pattern (e.g., '%search%')
+     *
+     * @example
+     * qb.select('users').whereLike('name', '%john%').orWhereLike('email', '%john%').execute()
+     * // SELECT * FROM users WHERE (name LIKE ?) OR (email LIKE ?)
+     */
+    orWhereLike(column: string, pattern: string): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add an OR WHERE column NOT LIKE pattern condition.
+     *
+     * @param column - The column name
+     * @param pattern - The LIKE pattern
+     *
+     * @example
+     * qb.select('users').where('active = ?', true).orWhereNotLike('email', '%@spam.com').execute()
+     * // SELECT * FROM users WHERE (active = ?) OR (email NOT LIKE ?)
+     */
+    orWhereNotLike(column: string, pattern: string): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a WHERE column NOT IN (values) condition.
+     *
+     * @param fields - Column name(s) to check
+     * @param values - Values to exclude
+     *
+     * @example
+     * qb.select('users').whereNotIn('status', ['banned', 'suspended']).execute()
+     * // SELECT * FROM users WHERE (status) NOT IN (VALUES (?), (?))
+     */
+    whereNotIn<T extends string | Array<string>, P extends T extends Array<string> ? Primitive[][] : Primitive[]>(fields: T, values: P): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
     join(join: SelectAll['join']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add an INNER JOIN to the query.
+     */
+    innerJoin(params: {
+        table: string;
+        on: string;
+        alias?: string;
+    }): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a LEFT JOIN to the query.
+     */
+    leftJoin(params: {
+        table: string;
+        on: string;
+        alias?: string;
+    }): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a RIGHT JOIN to the query.
+     */
+    rightJoin(params: {
+        table: string;
+        on: string;
+        alias?: string;
+    }): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a FULL OUTER JOIN to the query.
+     */
+    fullJoin(params: {
+        table: string;
+        on: string;
+        alias?: string;
+    }): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a CROSS JOIN to the query.
+     */
+    crossJoin(params: {
+        table: string;
+        alias?: string;
+    }): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Add a NATURAL JOIN to the query.
+     * Natural joins automatically match columns with the same name.
+     */
+    naturalJoin(table: string): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Define a Common Table Expression (CTE) using the WITH clause.
+     * CTEs allow you to define named temporary result sets that can be referenced
+     * in the main query, making complex queries more readable.
+     *
+     * @param name - The name of the CTE
+     * @param query - The query that defines the CTE
+     * @param columns - Optional column names for the CTE
+     *
+     * @example
+     * // Simple CTE
+     * qb.select('orders')
+     *   .with('active_users', qb.select('users').where('status = ?', 'active'))
+     *   .join({ table: 'active_users', on: 'orders.user_id = active_users.id' })
+     *   .execute()
+     *
+     * @example
+     * // Multiple CTEs
+     * qb.select('combined')
+     *   .with('cte1', qb.select('table1').where('x = ?', 1))
+     *   .with('cte2', qb.select('table2').where('y = ?', 2))
+     *   .execute()
+     */
+    with(name: string, query: SelectBuilder<any, any, any, any> | SelectAll, columns?: string[]): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Combine results with another query using UNION (removes duplicates).
+     *
+     * @param query - The query to union with
+     * @param all - If true, uses UNION ALL to keep duplicates
+     *
+     * @example
+     * qb.select('active_users').fields(['id', 'name'])
+     *   .union(qb.select('archived_users').fields(['id', 'name']))
+     *   .execute()
+     */
+    union(query: SelectBuilder<any, any, any, any> | SelectAll, all?: boolean): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Combine results with another query using UNION ALL (keeps duplicates).
+     *
+     * @param query - The query to union with
+     *
+     * @example
+     * qb.select('table1').fields(['id'])
+     *   .unionAll(qb.select('table2').fields(['id']))
+     *   .execute()
+     */
+    unionAll(query: SelectBuilder<any, any, any, any> | SelectAll): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Return only rows present in both queries using INTERSECT.
+     *
+     * @param query - The query to intersect with
+     * @param all - If true, uses INTERSECT ALL
+     *
+     * @example
+     * qb.select('users').fields(['id'])
+     *   .intersect(qb.select('admins').fields(['user_id']))
+     *   .execute()
+     */
+    intersect(query: SelectBuilder<any, any, any, any> | SelectAll, all?: boolean): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    /**
+     * Return rows from the first query that are not in the second query using EXCEPT.
+     *
+     * @param query - The query to except
+     * @param all - If true, uses EXCEPT ALL
+     *
+     * @example
+     * qb.select('all_users').fields(['id'])
+     *   .except(qb.select('blocked_users').fields(['user_id']))
+     *   .execute()
+     */
+    except(query: SelectBuilder<any, any, any, any> | SelectAll, all?: boolean): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
     groupBy(groupBy: SelectAll['groupBy']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
     having(conditions: string | Array<string>, params?: Primitive | Primitive[]): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
     orderBy(orderBy: SelectAll['orderBy']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
@@ -140,7 +498,69 @@ declare class SelectBuilder<Schema extends TableSchema = {}, GenericResultWrappe
     } ? true : false>;
     one(): MaybeAsync<IsAsync, OneResult<GenericResultWrapper, GenericResult>>;
     count(): MaybeAsync<IsAsync, CountResult<GenericResultWrapper>>;
+    /**
+     * Execute the query with pagination, returning results along with pagination metadata.
+     *
+     * @param options - Pagination options
+     * @param options.page - The page number (1-indexed)
+     * @param options.perPage - Number of results per page
+     *
+     * @example
+     * const result = await qb.select('users')
+     *   .where('active = ?', true)
+     *   .paginate({ page: 2, perPage: 20 })
+     *
+     * // Returns:
+     * // {
+     * //   results: [...],
+     * //   pagination: {
+     * //     page: 2,
+     * //     perPage: 20,
+     * //     total: 150,
+     * //     totalPages: 8,
+     * //     hasNext: true,
+     * //     hasPrev: true
+     * //   }
+     * // }
+     */
+    paginate(options: PaginateOptions): MaybeAsync<IsAsync, PaginatedResult<GenericResultWrapper, GenericResult>>;
     getOptions(): SelectAll;
+    /**
+     * Returns the SQL query string and parameters without executing.
+     * Useful for debugging and logging.
+     *
+     * @example
+     * const { sql, params } = qb.select('users').where('id = ?', 1).toSQL()
+     * // sql: "SELECT * FROM users WHERE id = ?"
+     * // params: [1]
+     */
+    toSQL(): {
+        sql: string;
+        params: Primitive[];
+    };
+    /**
+     * Returns the SQL query with parameters interpolated for debugging purposes.
+     * WARNING: This should NEVER be used to execute queries as it bypasses parameterization.
+     *
+     * @example
+     * const debugSql = qb.select('users').where('id = ?', 1).toDebugSQL()
+     * // "SELECT * FROM users WHERE id = 1"
+     */
+    toDebugSQL(): string;
+    /**
+     * Get the query plan for this query using EXPLAIN.
+     * Returns the query plan as an array of rows showing how the database will execute the query.
+     *
+     * @example
+     * const plan = await qb.select('users').where('id = ?', 1).explain()
+     * // Returns query plan rows
+     */
+    explain(): MaybeAsync<IsAsync, ArrayResult<GenericResultWrapper, {
+        id: number;
+        parent: number;
+        notused: number;
+        detail: string;
+    }, IsAsync>>;
 }
 
 type OmitIndexSignature<ObjectType> = {
@@ -161,8 +581,22 @@ type Primitive = null | string | number | boolean | bigint | ArrayBuffer | Raw |
 type QueryLoggerMeta = {
     duration?: number;
 };
+/**
+ * Hook called before a query is executed.
+ * Can modify the query or cancel execution by throwing.
+ */
+type BeforeQueryHook<IsAsync extends boolean = true> = (query: RawQuery, type: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'RAW') => MaybeAsync<IsAsync, RawQuery | void>;
+/**
+ * Hook called after a query is executed.
+ * Can modify the result or perform side effects.
+ */
+type AfterQueryHook<IsAsync extends boolean = true> = (result: any, query: RawQuery, duration: number) => MaybeAsync<IsAsync, any>;
 type QueryBuilderOptions<IsAsync extends boolean = true> = {
     logger?: (query: RawQuery, meta: QueryLoggerMeta) => MaybeAsync<IsAsync, void>;
+    /** Hook called before each query execution */
+    beforeQuery?: BeforeQueryHook<IsAsync>;
+    /** Hook called after each query execution */
+    afterQuery?: AfterQueryHook<IsAsync>;
 };
 type DefaultObject = Record<string, Primitive>;
 type DefaultReturnObject = Record<string, null | string | number | boolean | bigint | ArrayBuffer>;
@@ -187,6 +621,8 @@ type SelectOne = {
     offset?: number;
     subQueryPlaceholders?: Record<string, SelectAll>;
     subQueryTokenNextId?: number;
+    /** Enable DISTINCT selection. Can be true for simple DISTINCT or an array of columns for DISTINCT ON */
+    distinct?: boolean | Array<string>;
 };
 type RawQuery = {
     query: string;
@@ -200,9 +636,22 @@ type RawQueryFetchAll = Omit<RawQuery, 'fetchType'> & {
     fetchType: FetchTypes.ALL;
 };
 type RawQueryWithoutFetching = Omit<RawQuery, 'fetchType'>;
+type SetOperation = {
+    type: SetOperationType | string;
+    query: SelectAll;
+};
+type CTEDefinition = {
+    name: string;
+    query: SelectAll;
+    columns?: string[];
+};
 type SelectAll = SelectOne & {
     limit?: number;
     lazy?: boolean;
+    /** Set operations (UNION, INTERSECT, EXCEPT) to combine with this query */
+    setOperations?: SetOperation[];
+    /** Common Table Expressions (CTEs) for WITH clause */
+    cteDefinitions?: CTEDefinition[];
 };
 type ConflictUpsert = {
     column: string | Array<string>;
@@ -293,6 +742,18 @@ type OneResult<ResultWrapper, Result> = Merge<ResultWrapper, {
 type CountResult<GenericResultWrapper> = OneResult<GenericResultWrapper, {
     total: number;
 }>;
+type PaginationMeta = {
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+};
+type PaginatedResult<ResultWrapper, Result> = Merge<ResultWrapper, {
+    results?: Array<Result>;
+    pagination: PaginationMeta;
+}>;
 type AsyncType<T> = Promise<T>;
 type SyncType<T> = T;
 type MaybeAsync<IsAsync extends boolean, T> = IsAsync extends true ? AsyncType<T> : SyncType<T>;
@@ -354,15 +815,45 @@ type TypedDelete<S extends TableSchema, T extends TableName<S>> = {
  */
 type InferResult<S extends TableSchema, T extends TableName<S>, F> = F extends '*' ? S[T] : F extends ColumnName<S, T>[] ? Pick<S[T], F[number]> : F extends ColumnName<S, T> ? Pick<S[T], F> : S[T];
 
+type LoggerFunction = (query: RawQuery, meta: QueryLoggerMeta) => void | Promise<void>;
 declare function defaultLogger(query: RawQuery, meta: QueryLoggerMeta): any;
-declare function asyncLoggerWrapper<Async extends boolean = true>(query: Query<any, Async> | Query<any, Async>[], loggerFunction: CallableFunction | undefined, innerFunction: () => any): Promise<any>;
-declare function syncLoggerWrapper<Async extends boolean = false>(query: Query<any, Async> | Query<any, Async>[], loggerFunction: CallableFunction | undefined, innerFunction: () => any): any;
+declare function asyncLoggerWrapper<Async extends boolean = true>(query: Query<any, Async> | Query<any, Async>[], loggerFunction: LoggerFunction | undefined, innerFunction: () => any): Promise<any>;
+declare function syncLoggerWrapper<Async extends boolean = false>(query: Query<any, Async> | Query<any, Async>[], loggerFunction: LoggerFunction | undefined, innerFunction: () => any): any;
 
 declare class QueryBuilder<Schema extends TableSchema = {}, GenericResultWrapper = unknown, IsAsync extends boolean = true> {
     protected options: QueryBuilderOptions<IsAsync>;
     loggerWrapper: typeof asyncLoggerWrapper;
     constructor(options?: QueryBuilderOptions<IsAsync>);
     setDebugger(state: boolean): void;
+    /**
+     * Register a hook to be called before each query execution.
+     * The hook can modify the query or throw to cancel execution.
+     *
+     * @param hook - The hook function to call before query execution
+     *
+     * @example
+     * qb.beforeQuery((query, type) => {
+     *   // Add tenant filter to all SELECT/UPDATE/DELETE queries
+     *   if (type !== 'INSERT' && type !== 'RAW') {
+     *     query.query = query.query.replace('WHERE', `WHERE tenant_id = ${tenantId} AND`)
+     *   }
+     *   return query
+     * })
+     */
+    beforeQuery(hook: BeforeQueryHook<IsAsync>): this;
+    /**
+     * Register a hook to be called after each query execution.
+     * The hook receives the result and can modify it or perform side effects.
+     *
+     * @param hook - The hook function to call after query execution
+     *
+     * @example
+     * qb.afterQuery((result, query, duration) => {
+     *   metrics.record(query.query, duration)
+     *   return result
+     * })
+     */
+    afterQuery(hook: AfterQueryHook<IsAsync>): this;
     execute(query: Query<any, IsAsync>): MaybeAsync<IsAsync, any>;
     batchExecute(queryArray: Query<any, IsAsync>[]): MaybeAsync<IsAsync, any[]>;
     lazyExecute(query: Query<any, IsAsync>): IsAsync extends true ? Promise<AsyncIterable<any>> : Iterable<any>;
@@ -404,6 +895,7 @@ declare class QueryBuilder<Schema extends TableSchema = {}, GenericResultWrapper
     protected _update(params: Update): string;
     protected _delete(params: Delete): string;
     protected _select(params: SelectAll, queryArgs?: any[]): string;
+    protected _distinct(value?: boolean | Array<string>): string;
     protected _fields(value?: string | Array<string>): string;
     protected _where(value: Where | undefined, context?: {
         subQueryPlaceholders?: Record<string, SelectAll>;
@@ -472,7 +964,24 @@ declare class D1QB<Schema extends TableSchema = {}> extends QueryBuilder<Schema,
     constructor(db: D1Database, options?: QueryBuilderOptions);
     migrations(options: MigrationOptions): asyncMigrationsBuilder<D1Result>;
     execute(query: Query): Promise<any>;
+    private _getQueryType;
     batchExecute(queryArray: Query[]): Promise<any>;
+    /**
+     * Execute multiple queries atomically as a transaction.
+     * D1 uses batching for transactions - all queries succeed or all fail together.
+     *
+     * @param callback - A function that receives a transaction builder and returns queries to execute
+     * @returns Array of results from all queries in the transaction
+     *
+     * @example
+     * const results = await qb.transaction(async (tx) => {
+     *   return [
+     *     tx.insert({ tableName: 'orders', data: { user_id: 1, total: 100 } }),
+     *     tx.update({ tableName: 'users', data: { balance: 50 }, where: { conditions: 'id = ?', params: [1] } }),
+     *   ]
+     * })
+     */
+    transaction<T extends Query<any, true>[]>(callback: (tx: D1QB<Schema>) => T | Promise<T>): Promise<any[]>;
 }
 
 interface SqlStorage {
@@ -487,17 +996,96 @@ declare class DOQB<Schema extends TableSchema = {}> extends QueryBuilder<Schema,
     constructor(db: SqlStorage, options?: QueryBuilderOptions<false>);
     migrations(options: MigrationOptions): syncMigrationsBuilder<DOResult>;
     execute(query: Query<any, false>): any;
+    private _getQueryType;
     lazyExecute(query: Query<any, false>): Iterable<any>;
+    /**
+     * Execute multiple queries atomically as a transaction.
+     * Uses SQLite's BEGIN/COMMIT/ROLLBACK for atomicity.
+     * Note: This should be called within blockConcurrencyWhile for proper isolation in Durable Objects.
+     *
+     * @param callback - A function that receives the query builder and executes queries
+     * @returns The return value of the callback
+     *
+     * @example
+     * // Inside a Durable Object
+     * this.ctx.blockConcurrencyWhile(() => {
+     *   qb.transaction((tx) => {
+     *     tx.insert({ tableName: 'orders', data: { user_id: 1, total: 100 } }).execute()
+     *     tx.update({ tableName: 'users', data: { balance: 50 }, where: { conditions: 'id = ?', params: [1] } }).execute()
+     *   })
+     * })
+     */
+    transaction<T>(callback: (tx: DOQB<Schema>) => T): T;
 }
 
+declare class PGMigrationsBuilder extends asyncMigrationsBuilder<PGResult> {
+    initialize(): Promise<void>;
+    apply(): Promise<Array<{
+        name: string;
+        sql: string;
+    }>>;
+}
 declare class PGQB<Schema extends TableSchema = {}> extends QueryBuilder<Schema, PGResult, true> {
     db: any;
-    _migrationsBuilder: typeof asyncMigrationsBuilder;
     constructor(db: any, options?: QueryBuilderOptions);
-    migrations(options: MigrationOptions): asyncMigrationsBuilder<PGResult>;
+    migrations(options: MigrationOptions): PGMigrationsBuilder;
     connect(): Promise<void>;
     close(): Promise<void>;
     execute(query: Query): Promise<any>;
 }
 
-export { type ArrayResult, type AsyncType, type ColumnName, ConflictTypes, type ConflictUpsert, type CountResult, type D1Meta, D1QB, type D1Result, DOQB, type DOResult, type DefaultObject, type DefaultReturnObject, type Delete, type DeleteReturning, type DeleteWithoutReturning, FetchTypes, type FullArrayResult, type InferResult, type Insert, type InsertData, type InsertMultiple, type InsertOne, type InsertWithoutReturning, type IsEmptySchema, type IterableResult, type Join, JoinTypes, type MaybeAsync, type Migration, type MigrationEntry, type MigrationOptions, type OneResult, OrderTypes, PGQB, type PGResult, type Primitive, Query, QueryBuilder, type QueryBuilderOptions, type QueryLoggerMeta, QueryWithExtra, Raw, type RawQuery, type RawQueryFetchAll, type RawQueryFetchOne, type RawQueryWithoutFetching, type SchemaAware, type SelectAll, type SelectColumns, type SelectOne, type SyncType, type TableName, type TableSchema, type TypedDelete, type TypedInsert, type TypedSelectAll, type TypedSelectOne, type TypedUpdate, type Update, type UpdateData, type UpdateReturning, type UpdateWithoutReturning, type Where, asyncLoggerWrapper, asyncMigrationsBuilder, defaultLogger, syncLoggerWrapper, syncMigrationsBuilder, trimQuery };
+/**
+ * Custom error class for Query Builder errors with enhanced context.
+ * Provides helpful information about what went wrong and how to fix it.
+ */
+declare class QueryBuilderError extends Error {
+    query?: string;
+    expectedParams?: number;
+    receivedParams?: number;
+    hint?: string;
+    clause?: string;
+    constructor(message: string, options?: {
+        query?: string;
+        expectedParams?: number;
+        receivedParams?: number;
+        hint?: string;
+        clause?: string;
+    });
+}
+/**
+ * Error thrown when there's a parameter count mismatch.
+ */
+declare class ParameterMismatchError extends QueryBuilderError {
+    constructor(options: {
+        clause: string;
+        query?: string;
+        expectedParams: number;
+        receivedParams: number;
+    });
+}
+/**
+ * Error thrown when required data is missing.
+ */
+declare class MissingDataError extends QueryBuilderError {
+    constructor(operation: string, field: string);
+}
+/**
+ * Error thrown when an invalid configuration is detected.
+ */
+declare class InvalidConfigurationError extends QueryBuilderError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Error thrown when a subquery token is not found.
+ */
+declare class SubqueryTokenError extends QueryBuilderError {
+    constructor(token: string);
+}
+/**
+ * Error thrown when subquery context is missing.
+ */
+declare class MissingSubqueryContextError extends QueryBuilderError {
+    constructor();
+}
+
+export { type AfterQueryHook, type ArrayResult, type AsyncType, type BeforeQueryHook, type CTEDefinition, type ColumnName, ConflictTypes, type ConflictUpsert, type CountResult, type D1Meta, D1QB, type D1Result, DOQB, type DOResult, type DefaultObject, type DefaultReturnObject, type Delete, type DeleteReturning, type DeleteWithoutReturning, FetchTypes, type FullArrayResult, type InferResult, type Insert, type InsertData, type InsertMultiple, type InsertOne, type InsertWithoutReturning, InvalidConfigurationError, type IsEmptySchema, type IterableResult, type Join, JoinTypes, type MaybeAsync, type Migration, type MigrationEntry, type MigrationOptions, MissingDataError, MissingSubqueryContextError, type OneResult, OrderTypes, PGQB, type PGResult, type PaginatedResult, type PaginationMeta, ParameterMismatchError, type Primitive, Query, QueryBuilder, QueryBuilderError, type QueryBuilderOptions, type QueryLoggerMeta, QueryWithExtra, Raw, type RawQuery, type RawQueryFetchAll, type RawQueryFetchOne, type RawQueryWithoutFetching, type SchemaAware, type SelectAll, type SelectColumns, type SelectOne, type SetOperation, SetOperationType, SubqueryTokenError, type SyncType, type TableName, type TableSchema, type TypedDelete, type TypedInsert, type TypedSelectAll, type TypedSelectOne, type TypedUpdate, type Update, type UpdateData, type UpdateReturning, type UpdateWithoutReturning, type Where, asyncLoggerWrapper, asyncMigrationsBuilder, defaultLogger, syncLoggerWrapper, syncMigrationsBuilder, trimQuery };