import { S as Sql } from '../types-YTdPe6Qz.cjs'; import '@dotdo/postgres-shared/errors'; /** * Type-safe Query Builder Types * * Core types for building type-safe SQL queries with full TypeScript inference. * These types ensure that queries are validated at compile time. */ /** * Base column definition with type information */ interface ColumnDefinition { readonly name: TName; readonly dataType: TType; readonly notNull: TNotNull; readonly hasDefault: TDefault; readonly _columnBrand: 'column'; } /** * Table definition with typed columns */ interface TableDefinition = Record> { readonly tableName: TName; readonly columns: TColumns; readonly _tableBrand: 'table'; } /** * Infer the row type from a table definition */ type InferTableRow = { [K in keyof T['columns']]: InferColumnType; }; /** * Infer the TypeScript type from a column definition */ type InferColumnType = T['notNull'] extends true ? T['dataType'] : T['dataType'] | null; /** * Infer insert type (required fields only) */ type InferInsertRow = { [K in keyof T['columns'] as RequiredInsertColumn extends true ? K : never]: T['columns'][K]['dataType']; } & { [K in keyof T['columns'] as RequiredInsertColumn extends true ? never : K]?: T['columns'][K]['dataType'] | null; }; type RequiredInsertColumn = T['notNull'] extends true ? T['hasDefault'] extends true ? false : true : false; /** * SQL expression with type information */ interface SQLExpression { readonly _type: TType; readonly _brand: 'sql_expression'; toSQL(): { sql: string; params: unknown[]; }; } /** * Column reference expression */ interface ColumnRef extends SQLExpression { readonly table: TTable; readonly column: TColumn; readonly _brand: 'sql_expression'; } type ComparisonOperator = '=' | '!=' | '<' | '<=' | '>' | '>=' | 'LIKE' | 'ILIKE' | 'IN' | 'NOT IN' | 'IS NULL' | 'IS NOT NULL'; /** * Aggregate function expression */ interface AggregateExpr extends SQLExpression { readonly fn: 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX'; readonly column: SQLExpression | '*'; readonly distinct?: boolean; } /** * Selection specification - what columns to select */ type SelectionSpec = '*' | (keyof T['columns'])[] | Record; /** * Infer result type from selection spec */ type InferSelectResult> = TSelection extends '*' ? InferTableRow : TSelection extends (keyof T['columns'])[] ? Pick, TSelection[number]> : TSelection extends Record ? { [K in keyof TSelection]: TSelection[K] extends SQLExpression ? U : TSelection[K] extends keyof T['columns'] ? InferColumnType : never; } : never; /** * WHERE clause type - accepts boolean expressions */ type WhereClause = SQLExpression | ((columns: ColumnRefs) => SQLExpression); /** * Column references for a table */ type ColumnRefs = { [K in keyof T['columns']]: ColumnRef; }; /** * ORDER BY specification */ type OrderBySpec = keyof T['columns'] | { column: keyof T['columns']; direction: 'ASC' | 'DESC'; } | { column: keyof T['columns']; direction: 'ASC' | 'DESC'; nulls?: 'FIRST' | 'LAST'; }; /** * Join types */ type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL'; /** * Join condition specification */ type JoinCondition = SQLExpression | { left: keyof TLeft['columns']; right: keyof TRight['columns']; }; /** * Result type for joined tables */ type JoinResult = TJoinType extends 'LEFT' ? InferTableRow & { [K in TRight['tableName']]: InferTableRow | null; } : TJoinType extends 'RIGHT' ? { [K in TLeft['tableName']]: InferTableRow | null; } & InferTableRow : TJoinType extends 'FULL' ? { [K in TLeft['tableName']]: InferTableRow | null; } & { [K in TRight['tableName']]: InferTableRow | null; } : InferTableRow & InferTableRow; /** * Combined table reference after join */ interface JoinedTables { left: TLeft; right: TRight; joinType: TJoinType; condition: SQLExpression; } /** * Insert values - single or array of rows */ type InsertValues = InferInsertRow | InferInsertRow[]; /** * On conflict action */ type OnConflictAction = 'DO NOTHING' | { doUpdate: Partial>; } | { doUpdate: (row: InferTableRow) => Partial>; }; /** * Conflict target columns */ type ConflictTarget = (keyof T['columns'])[] | { constraint: string; }; /** * Update set values */ type UpdateSet = Partial<{ [K in keyof T['columns']]: T['columns'][K]['dataType'] | SQLExpression; }>; /** * Base query builder interface */ interface QueryBuilder { /** * Get the generated SQL and parameters */ toSQL(): { sql: string; params: unknown[]; }; /** * Execute the query and return results */ execute(): Promise; } /** * SELECT query builder interface */ interface SelectQueryBuilder = '*', TResult = InferSelectResult[]> extends QueryBuilder { /** * Select specific columns or expressions */ select>(selection: TNewSelection): SelectQueryBuilder[]>; /** * Add WHERE clause */ where(condition: WhereClause): SelectQueryBuilder; /** * Add AND condition to WHERE clause */ andWhere(condition: WhereClause): SelectQueryBuilder; /** * Add OR condition to WHERE clause */ orWhere(condition: WhereClause): SelectQueryBuilder; /** * Add ORDER BY clause */ orderBy(...specs: OrderBySpec[]): SelectQueryBuilder; /** * Add LIMIT clause */ limit(count: number): SelectQueryBuilder; /** * Add OFFSET clause */ offset(count: number): SelectQueryBuilder; /** * Add GROUP BY clause */ groupBy(...columns: (keyof T['columns'])[]): SelectQueryBuilder; /** * Add HAVING clause */ having(condition: SQLExpression): SelectQueryBuilder; /** * Add DISTINCT */ distinct(): SelectQueryBuilder; /** * Execute and return first result or null */ first(): Promise; /** * Execute and return first result or throw */ firstOrThrow(): Promise; } /** * JOIN query builder interface */ interface JoinQueryBuilder[]> extends QueryBuilder { /** * Add WHERE clause */ where(condition: SQLExpression): JoinQueryBuilder; /** * Add ORDER BY clause */ orderBy(column: string, direction?: 'ASC' | 'DESC'): JoinQueryBuilder; /** * Add LIMIT clause */ limit(count: number): JoinQueryBuilder; /** * Select specific columns from joined tables */ select>(selection: TSelection): JoinQueryBuilder ? U : never; }[]>; } /** * INSERT query builder interface */ interface InsertQueryBuilder extends QueryBuilder { /** * Add RETURNING clause */ returning(): InsertQueryBuilder[]>; /** * Add RETURNING clause with specific columns */ returning(...columns: TColumns): InsertQueryBuilder, TColumns[number]>[]>; /** * Add ON CONFLICT clause */ onConflict(target: ConflictTarget, action: OnConflictAction): InsertQueryBuilder; } /** * UPDATE query builder interface */ interface UpdateQueryBuilder extends QueryBuilder { /** * Add WHERE clause */ where(condition: WhereClause): UpdateQueryBuilder; /** * Add RETURNING clause */ returning(): UpdateQueryBuilder[]>; /** * Add RETURNING clause with specific columns */ returning(...columns: TColumns): UpdateQueryBuilder, TColumns[number]>[]>; } /** * DELETE query builder interface */ interface DeleteQueryBuilder extends QueryBuilder { /** * Add WHERE clause */ where(condition: WhereClause): DeleteQueryBuilder; /** * Add RETURNING clause */ returning(): DeleteQueryBuilder[]>; /** * Add RETURNING clause with specific columns */ returning(...columns: TColumns): DeleteQueryBuilder, TColumns[number]>[]>; } /** * Main query builder factory interface */ interface QueryBuilderFactory { /** * Start a SELECT query */ select(): { from(table: T): SelectQueryBuilder; }; /** * Start a SELECT query with specific columns */ select>(selection: TSelection): { from(table: T): SelectQueryBuilder; }; /** * Start an INSERT query */ insert(table: T): { values(values: InsertValues): InsertQueryBuilder; }; /** * Start an UPDATE query */ update(table: T): { set(values: UpdateSet): UpdateQueryBuilder; }; /** * Start a DELETE query */ delete(table: T): DeleteQueryBuilder; /** * Create a JOIN */ join(left: TLeft, right: TRight, condition: JoinCondition): JoinQueryBuilder; /** * Create a LEFT JOIN */ leftJoin(left: TLeft, right: TRight, condition: JoinCondition): JoinQueryBuilder; /** * Create a RIGHT JOIN */ rightJoin(left: TLeft, right: TRight, condition: JoinCondition): JoinQueryBuilder; /** * Create a FULL OUTER JOIN */ fullJoin(left: TLeft, right: TRight, condition: JoinCondition): JoinQueryBuilder; } /** * Type-safe Query Builder Implementation * * Full implementation of the query builder with type-safe SQL generation. */ declare class InsertQueryBuilderImpl implements InsertQueryBuilder { private client; private table; private values; private _returning?; private _onConflict?; constructor(client: Sql, table: T, values: InsertValues); returning(): InsertQueryBuilder[]>; returning(...columns: TColumns): InsertQueryBuilder, TColumns[number]>[]>; onConflict(target: ConflictTarget, action: OnConflictAction): InsertQueryBuilder; toSQL(): { sql: string; params: unknown[]; }; execute(): Promise; } declare class UpdateQueryBuilderImpl implements UpdateQueryBuilder { private client; private table; private setValues; private _where?; private _returning?; constructor(client: Sql, table: T, setValues: UpdateSet); where(condition: WhereClause): UpdateQueryBuilder; returning(): UpdateQueryBuilder[]>; returning(...columns: TColumns): UpdateQueryBuilder, TColumns[number]>[]>; toSQL(): { sql: string; params: unknown[]; }; execute(): Promise; } /** * Create a query builder factory from a postgres.do client */ declare function createQueryBuilder(client: Sql): { /** * Start a SELECT query */ select = "*">(selection?: TSelection): { from(table: T): SelectQueryBuilder; }; /** * Start an INSERT query */ insert(table: T): { values(values: InsertValues): InsertQueryBuilderImpl; }; /** * Start an UPDATE query */ update(table: T): { set(values: UpdateSet): UpdateQueryBuilderImpl; }; /** * Start a DELETE query */ delete(table: T): DeleteQueryBuilder; /** * Create an INNER JOIN */ join(left: TLeft, right: TRight, condition: JoinCondition): JoinQueryBuilder; /** * Create a LEFT JOIN */ leftJoin(left: TLeft, right: TRight, condition: JoinCondition): JoinQueryBuilder; /** * Create a RIGHT JOIN */ rightJoin(left: TLeft, right: TRight, condition: JoinCondition): JoinQueryBuilder; /** * Create a FULL OUTER JOIN */ fullJoin(left: TLeft, right: TRight, condition: JoinCondition): JoinQueryBuilder; }; /** * Type-safe SQL Expression Builders * * Provides builder functions for creating type-safe SQL expressions. * All comparisons are validated at compile time. */ /** * Create an equality comparison (=) */ declare function eq(left: SQLExpression, right: TType | SQLExpression): SQLExpression; /** * Create an inequality comparison (!=) */ declare function ne(left: SQLExpression, right: TType | SQLExpression): SQLExpression; /** * Create a less than comparison (<) */ declare function lt(left: SQLExpression, right: TType | SQLExpression): SQLExpression; /** * Create a less than or equal comparison (<=) */ declare function lte(left: SQLExpression, right: TType | SQLExpression): SQLExpression; /** * Create a greater than comparison (>) */ declare function gt(left: SQLExpression, right: TType | SQLExpression): SQLExpression; /** * Create a greater than or equal comparison (>=) */ declare function gte(left: SQLExpression, right: TType | SQLExpression): SQLExpression; /** * Create a LIKE comparison */ declare function like(column: SQLExpression, pattern: string): SQLExpression; /** * Create a case-insensitive LIKE comparison (ILIKE) */ declare function ilike(column: SQLExpression, pattern: string): SQLExpression; /** * Create an IN comparison */ declare function inArray(column: SQLExpression, values: TType[]): SQLExpression; /** * Create a NOT IN comparison */ declare function notInArray(column: SQLExpression, values: TType[]): SQLExpression; /** * Create an IS NULL comparison */ declare function isNull(column: SQLExpression): SQLExpression; /** * Create an IS NOT NULL comparison */ declare function isNotNull(column: SQLExpression): SQLExpression; /** * Create a BETWEEN comparison */ declare function between(column: SQLExpression, min: TType, max: TType): SQLExpression; /** * Create a NOT BETWEEN comparison */ declare function notBetween(column: SQLExpression, min: TType, max: TType): SQLExpression; /** * Create an AND expression */ declare function and(...expressions: SQLExpression[]): SQLExpression; /** * Create an OR expression */ declare function or(...expressions: SQLExpression[]): SQLExpression; /** * Create a NOT expression */ declare function not(expression: SQLExpression): SQLExpression; /** * Create a COUNT aggregate */ declare function count(): AggregateExpr; declare function count(column: SQLExpression): AggregateExpr; /** * Create a COUNT DISTINCT aggregate */ declare function countDistinct(column: SQLExpression): AggregateExpr; /** * Create a SUM aggregate */ declare function sum(column: SQLExpression): AggregateExpr; /** * Create an AVG aggregate */ declare function avg(column: SQLExpression): AggregateExpr; /** * Create a MIN aggregate */ declare function min(column: SQLExpression): AggregateExpr; /** * Create a MAX aggregate */ declare function max(column: SQLExpression): AggregateExpr; /** * Create a CONCAT expression */ declare function concat(...values: (SQLExpression | string)[]): SQLExpression; /** * Create a LOWER expression */ declare function lower(value: SQLExpression): SQLExpression; /** * Create an UPPER expression */ declare function upper(value: SQLExpression): SQLExpression; /** * Create a TRIM expression */ declare function trim(value: SQLExpression): SQLExpression; /** * Create a COALESCE expression */ declare function coalesce(...values: (SQLExpression | TType)[]): SQLExpression; /** * Create a column reference */ declare function col(table: TTable, column: TColumn): ColumnRef; /** * Create column references for a table definition */ declare function columnsOf(table: T): ColumnRefs; /** * Create a raw SQL expression (use with caution!) */ declare function raw(sql: string, params?: unknown[]): SQLExpression; /** * Create a literal value expression */ declare function literal(value: TType): SQLExpression; /** * Create a SQL expression from a template literal */ declare function sql(strings: TemplateStringsArray, ...values: unknown[]): SQLExpression; /** * Type-safe Schema Definition * * Provides helpers for defining schemas that work with the query builder. * Also includes adapters for Drizzle ORM schemas. */ /** * Column builder for type-safe column definitions */ declare class ColumnBuilder { private _type; private _name; private _notNull; private _hasDefault; constructor(name: TName, _type: TType); /** * Mark column as NOT NULL */ notNull(): ColumnBuilder; /** * Mark column as having a default value */ default(_value: TValue): ColumnBuilder; /** * Mark as primary key (implies NOT NULL) */ primaryKey(): ColumnBuilder; /** * Build the column definition */ build(): ColumnDefinition; } /** * Create a serial (auto-incrementing integer) column */ declare function serial(name: TName): ColumnBuilder; /** * Create a bigserial (auto-incrementing bigint) column */ declare function bigserial(name: TName): ColumnBuilder; /** * Create an integer column */ declare function integer(name: TName): ColumnBuilder; /** * Create a bigint column */ declare function bigint(name: TName): ColumnBuilder; /** * Create a text column */ declare function text(name: TName): ColumnBuilder; /** * Create a varchar column */ declare function varchar(name: TName, _length?: number): ColumnBuilder; /** * Create a boolean column */ declare function boolean(name: TName): ColumnBuilder; /** * Create a timestamp column */ declare function timestamp(name: TName): ColumnBuilder; /** * Create a timestamp with timezone column */ declare function timestamptz(name: TName): ColumnBuilder; /** * Create a date column */ declare function date(name: TName): ColumnBuilder; /** * Create a time column */ declare function time(name: TName): ColumnBuilder; /** * Create a UUID column */ declare function uuid(name: TName): ColumnBuilder; /** * Create a JSON column */ declare function json(name: TName): ColumnBuilder; /** * Create a JSONB column */ declare function jsonb(name: TName): ColumnBuilder; /** * Create a numeric/decimal column */ declare function numeric(name: TName, _precision?: number, _scale?: number): ColumnBuilder; /** * Create a real (float4) column */ declare function real(name: TName): ColumnBuilder; /** * Create a double precision (float8) column */ declare function doublePrecision(name: TName): ColumnBuilder; type ColumnBuilderMap = Record>; type ExtractColumnDefs = { [K in keyof T]: T[K] extends ColumnBuilder ? ColumnDefinition : never; }; /** * Define a table with type-safe columns */ declare function defineTable(name: TName, columns: TColumns): TableDefinition>; /** * Options for converting Drizzle schema to query builder format */ interface DrizzleAdapterOptions { /** * Transform column names (e.g., from snake_case to camelCase) */ transformColumnNames?: (name: string) => string; } /** * Convert a Drizzle table to a query builder TableDefinition * * This enables using Drizzle schemas with the standalone query builder. * * @example * ```typescript * import { users } from './drizzle-schema' * import { fromDrizzleTable, createQueryBuilder } from 'postgres.do/query-builder' * * const usersTable = fromDrizzleTable(users) * const qb = createQueryBuilder(sql) * * // Type-safe queries using Drizzle schema * const results = await qb.select().from(usersTable).execute() * ``` */ declare function fromDrizzleTable(drizzleTable: TDrizzleTable, options?: DrizzleAdapterOptions): TableDefinition; /** * Infer the select result type for a table */ type SelectResult = InferTableRow; /** * Infer the insert type for a table */ type InsertType = InferInsertRow; /** * Get column keys for a table */ type ColumnKeys = keyof T['columns']; export { type AggregateExpr, type ColumnDefinition, type ColumnKeys, type ColumnRef, type ColumnRefs, type ComparisonOperator, type ConflictTarget, type DeleteQueryBuilder, type DrizzleAdapterOptions, type InferColumnType, type InferInsertRow, type InferSelectResult, type InferTableRow, type InsertQueryBuilder, type InsertType, type InsertValues, type JoinCondition, type JoinQueryBuilder, type JoinResult, type JoinType, type JoinedTables, type OnConflictAction, type OrderBySpec, type QueryBuilder, type QueryBuilderFactory, type SQLExpression, type SelectQueryBuilder, type SelectResult, type SelectionSpec, type TableDefinition, type UpdateQueryBuilder, type UpdateSet, type WhereClause, and, avg, between, bigint, bigserial, boolean, coalesce, col, columnsOf, concat, count, countDistinct, createQueryBuilder, date, defineTable, doublePrecision, eq, fromDrizzleTable, gt, gte, ilike, inArray, integer, isNotNull, isNull, json, jsonb, like, literal, lower, lt, lte, max, min, ne, not, notBetween, notInArray, numeric, or, raw, real, serial, sql, sum, text, time, timestamp, timestamptz, trim, upper, uuid, varchar };