@cleverbrush/knex-schema 3.1.0 → 4.1.0

package/dist/SchemaQueryBuilder.d.ts

@@ -1,640 +1,137 @@
 import type { InferType } from '@cleverbrush/schema';
-import { ObjectSchemaBuilder } from '@cleverbrush/schema';
+import { EXTRA_TYPE_BRAND, METHOD_LITERAL_BRAND, type ObjectSchemaBuilder } from '@cleverbrush/schema';
 import type { Knex } from 'knex';
-import type { ColumnRef, InsertType, JoinManySpec, JoinOneSpec, WithJoinedMany, WithJoinedOne } from './types.js';
-/**
- * Type-safe, schema-driven query builder for Knex.
- *
- * `SchemaQueryBuilder` wraps a Knex.QueryBuilder and adds:
- * - **Type-safe column references** — pass a property accessor (`t => t.name`)
- *   or a string property name; both are resolved to the correct SQL column
- *   through the schema's `hasColumnName()` metadata automatically.
- * - **Eager loading without N+1** — {@link joinOne} and {@link joinMany} use
- *   PostgreSQL CTEs and `jsonb_agg` to load related rows in a single query.
- * - **Bidirectional result mapping** — rows returned from Postgres (column
- *   names) are converted back to schema property names before being returned.
- * - **Thenable protocol** — the builder itself is `await`-able so you can
- *   write `await query(db, Schema)` without calling {@link execute} explicitly.
- *
- * Create instances via the {@link query} factory function rather than
- * calling the constructor directly.
- *
- * @typeParam TLocalSchema - The `ObjectSchemaBuilder` describing the main table.
- * @typeParam TResult - The inferred row type, widened automatically as joins
- *   are registered via {@link joinOne} / {@link joinMany}.
- *
- * @example
- * ```ts
- * import knex from 'knex';
- * import { query, object, string, number } from '@cleverbrush/knex-schema';
- *
- * const UserSchema = object({
- *     id:   number(),
- *     name: string(),
- *     age:  number().optional(),
- * }).hasTableName('users');
- *
- * const db = knex({ client: 'pg', connection: process.env.DB_URL });
- *
- * // Fetch all users older than 18, ordered by name
- * const adults = await query(db, UserSchema)
- *     .where(t => t.age, '>', 18)
- *     .orderBy(t => t.name);
- * // adults: Array<{ id: number; name: string; age?: number }>
- * ```
- */
+import { POLYMORPHIC_TYPE_BRAND } from './extension.js';
+import type { ColumnRef, CursorPaginationResult, InsertType, JoinManySpec, JoinOneSpec, PaginationResult, SelectProjection, SelectSelector } from './types.js';
+export { OnConflictBuilder } from './operations/insert.js';
+type ScopesOf<S> = S extends {
+    readonly [METHOD_LITERAL_BRAND]?: infer N;
+} ? Extract<N, string> : never;
+type ProjectionsOf<S> = S extends {
+    readonly [EXTRA_TYPE_BRAND]?: infer P;
+} ? P extends Record<string, readonly string[]> ? P : Record<never, never> : Record<never, never>;
+type ProjectionKeysOf<S, K extends keyof ProjectionsOf<S> & string> = ProjectionsOf<S>[K] extends readonly (infer T extends string)[] ? T : string;
+type QueryResultType<TLocalSchema> = TLocalSchema extends {
+    readonly [POLYMORPHIC_TYPE_BRAND]?: infer U;
+} ? NonNullable<U> : InferType<TLocalSchema>;
 export declare class SchemaQueryBuilder<TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TResult> {
-    #private;
-    /**
-     * @param knex - A configured Knex instance.
-     * @param localSchema - The `ObjectSchemaBuilder` for the primary table.
-     *   Must have a table name set via `.hasTableName()`.
-     * @param baseQuery - Optional pre-configured `Knex.QueryBuilder` to use as
-     *   the base query instead of the default `knex(tableName)`. Useful when you
-     *   need custom joins, CTEs, or other Knex features not exposed by this API.
-     */
     constructor(knex: Knex, localSchema: TLocalSchema, baseQuery?: Knex.QueryBuilder);
-    /**
-     * Eager-load a single related row (one-to-one / many-to-one relationship).
-     *
-     * The related rows are fetched using a single CTE + `jsonb_agg` — no N+1
-     * queries. The related object is attached to each result row under the
-     * field name specified by `spec.as`.
-     *
-     * @param spec - Join specification. Key fields:
-     *   - `foreignSchema` — the `ObjectSchemaBuilder` of the related table.
-     *   - `localColumn` — the local column that holds the foreign-table reference.
-     *   - `foreignColumn` — the primary/unique key on the foreign table.
-     *   - `as` — the property name to attach the related object under.
-     *   - `required` — if `true` (default), rows without a matching related
-     *     record are excluded (inner join); if `false`, they are included with
-     *     `null` (left join).
-     *   - `foreignQuery` — optional pre-filtered `Knex.QueryBuilder` for the
-     *     foreign table (e.g. to apply scopes).
-     *
-     * @returns `this` (with an updated `TResult` type that includes the new field)
-     *   for chaining.
-     *
-     * @example
-     * ```ts
-     * const PostSchema = object({
-     *     id:       number(),
-     *     title:    string(),
-     *     authorId: number(),
-     * }).hasTableName('posts');
-     *
-     * const AuthorSchema = object({
-     *     id:   number(),
-     *     name: string(),
-     * }).hasTableName('authors');
-     *
-     * const posts = await query(db, PostSchema)
-     *     .joinOne({
-     *         foreignSchema: AuthorSchema,
-     *         localColumn:   t => t.authorId,
-     *         foreignColumn: t => t.id,
-     *         as:            'author',
-     *     });
-     * // posts[0].author.name — typed as string ✓
-     * ```
-     */
-    joinOne<TForeignSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TFieldName extends string, TRequired extends boolean = true>(spec: JoinOneSpec<TLocalSchema, TForeignSchema, TFieldName, TRequired>): SchemaQueryBuilder<TLocalSchema, WithJoinedOne<TResult, TFieldName, TForeignSchema, TRequired>>;
-    /**
-     * Eager-load a collection of related rows (one-to-many relationship).
-     *
-     * Related rows are fetched via a single CTE + `jsonb_agg` query. The
-     * collection is attached to each result row under the field name specified
-     * by `spec.as`. Supports `limit`, `offset`, and `orderBy` per-parent
-     * using a `row_number()` window function to avoid fetching the full
-     * relation before slicing.
-     *
-     * @param spec - Join specification. Key fields:
-     *   - `foreignSchema` — the `ObjectSchemaBuilder` of the related table.
-     *   - `localColumn` — the primary/unique key on the local table.
-     *   - `foreignColumn` — the column on the foreign table that references `localColumn`.
-     *   - `as` — the property name to attach the array under.
-     *   - `limit` / `offset` — optional pagination per parent row.
-     *   - `orderBy` — optional `{ column, direction }` for the sub-collection.
-     *   - `foreignQuery` — optional pre-filtered `Knex.QueryBuilder`.
-     *
-     * @returns `this` (with an updated `TResult` type that includes the new field)
-     *   for chaining.
-     *
-     * @example
-     * ```ts
-     * const UserSchema = object({
-     *     id:   number(),
-     *     name: string(),
-     * }).hasTableName('users');
-     *
-     * const PostSchema = object({
-     *     id:       number(),
-     *     title:    string(),
-     *     authorId: number(),
-     * }).hasTableName('posts');
-     *
-     * const users = await query(db, UserSchema)
-     *     .joinMany({
-     *         foreignSchema: PostSchema,
-     *         localColumn:   t => t.id,
-     *         foreignColumn: t => t.authorId,
-     *         as:            'posts',
-     *         limit:         5,
-     *         orderBy:       { column: t => t.id, direction: 'desc' },
-     *     });
-     * // users[0].posts — typed as Array<{ id: number; title: string; authorId: number }>
-     * ```
-     */
-    joinMany<TForeignSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TFieldName extends string>(spec: JoinManySpec<TLocalSchema, TForeignSchema, TFieldName>): SchemaQueryBuilder<TLocalSchema, WithJoinedMany<TResult, TFieldName, TForeignSchema>>;
-    /**
-     * Add a `WHERE` clause to the query.
-     *
-     * Accepts a column reference, an optional operator, and a value:
-     * - `where(t => t.age, '>', 18)` — property accessor + operator + value.
-     * - `where('age', 18)` — string key + value (defaults to `=`).
-     * - `where({ name: 'Alice' })` — record object; property keys are mapped
-     *   to column names automatically.
-     * - `where(builder => { ... })` — Knex sub-builder callback for grouped
-     *   conditions.
-     * - `where(knex.raw('...'))` — raw SQL expression.
-     *
-     * Multiple `.where()` calls are combined with `AND`.
-     *
-     * @returns `this` for chaining.
-     */
+    select(...columns: (ColumnRef<TLocalSchema> | Knex.Raw)[]): this;
+    select<TSel extends SelectSelector<TLocalSchema>>(selector: TSel): SchemaQueryBuilder<TLocalSchema, SelectProjection<ReturnType<TSel>>>;
+    distinct(...columns: (ColumnRef<TLocalSchema> | Knex.Raw)[]): this;
+    count(column?: ColumnRef<TLocalSchema> | Knex.Raw): this;
+    countDistinct(column?: ColumnRef<TLocalSchema> | Knex.Raw): this;
+    min(column: ColumnRef<TLocalSchema> | Knex.Raw): this;
+    max(column: ColumnRef<TLocalSchema> | Knex.Raw): this;
+    sum(column: ColumnRef<TLocalSchema> | Knex.Raw): this;
+    avg(column: ColumnRef<TLocalSchema> | Knex.Raw): this;
+    selectRaw(sql: string, bindings?: any[]): this;
+    projected<K extends keyof ProjectionsOf<TLocalSchema> & string>(name: K): SchemaQueryBuilder<TLocalSchema, Pick<TResult, ProjectionKeysOf<TLocalSchema, K> & keyof TResult>>;
+    scoped<K extends ScopesOf<TLocalSchema>>(name: K): this;
+    unscoped(): this;
     where(column: ColumnRef<TLocalSchema>, operator: string, value: any): this;
     where(column: ColumnRef<TLocalSchema>, value: any): this;
     where(raw: Knex.Raw, operator: string, value: any): this;
     where(callback: (builder: Knex.QueryBuilder) => void): this;
     where(record: Record<string, any>): this;
     where(raw: Knex.Raw): this;
-    /**
-     * Alias for {@link where} — explicitly adds an `AND WHERE` clause.
-     * Identical to calling `.where()` when no logical-OR grouping is needed.
-     * @returns `this` for chaining.
-     */
     andWhere(column: ColumnRef<TLocalSchema>, operator: string, value: any): this;
     andWhere(column: ColumnRef<TLocalSchema>, value: any): this;
     andWhere(record: Record<string, any>): this;
     andWhere(callback: (builder: Knex.QueryBuilder) => void): this;
     andWhere(raw: Knex.Raw): this;
-    /**
-     * Add an `OR WHERE` clause. Use this to create alternative filter branches.
-     * @returns `this` for chaining.
-     */
     orWhere(column: ColumnRef<TLocalSchema>, operator: string, value: any): this;
     orWhere(column: ColumnRef<TLocalSchema>, value: any): this;
     orWhere(record: Record<string, any>): this;
     orWhere(callback: (builder: Knex.QueryBuilder) => void): this;
     orWhere(raw: Knex.Raw): this;
-    /**
-     * Add a `WHERE NOT` clause — negates the condition.
-     * @returns `this` for chaining.
-     */
     whereNot(column: ColumnRef<TLocalSchema>, operator: string, value: any): this;
     whereNot(column: ColumnRef<TLocalSchema>, value: any): this;
     whereNot(record: Record<string, any>): this;
     whereNot(callback: (builder: Knex.QueryBuilder) => void): this;
     whereNot(raw: Knex.Raw): this;
-    /**
-     * Add a `WHERE column IN (values)` clause.
-     * @param column - Column reference (property accessor or string key).
-     * @param values - Array of values or a sub-query.
-     * @returns `this` for chaining.
-     */
     whereIn(column: ColumnRef<TLocalSchema>, values: readonly any[] | Knex.QueryBuilder): this;
-    /**
-     * Add a `WHERE column NOT IN (values)` clause.
-     * @param column - Column reference.
-     * @param values - Array of values or a sub-query.
-     * @returns `this` for chaining.
-     */
     whereNotIn(column: ColumnRef<TLocalSchema>, values: readonly any[] | Knex.QueryBuilder): this;
-    /**
-     * Add an `OR WHERE column IN (values)` clause.
-     * @returns `this` for chaining.
-     */
     orWhereIn(column: ColumnRef<TLocalSchema>, values: readonly any[] | Knex.QueryBuilder): this;
-    /**
-     * Add an `OR WHERE column NOT IN (values)` clause.
-     * @returns `this` for chaining.
-     */
     orWhereNotIn(column: ColumnRef<TLocalSchema>, values: readonly any[] | Knex.QueryBuilder): this;
-    /**
-     * Add a `WHERE column IS NULL` clause.
-     * @returns `this` for chaining.
-     */
     whereNull(column: ColumnRef<TLocalSchema>): this;
-    /**
-     * Add a `WHERE column IS NOT NULL` clause.
-     * @returns `this` for chaining.
-     */
     whereNotNull(column: ColumnRef<TLocalSchema>): this;
-    /**
-     * Add an `OR WHERE column IS NULL` clause.
-     * @returns `this` for chaining.
-     */
     orWhereNull(column: ColumnRef<TLocalSchema>): this;
-    /**
-     * Add an `OR WHERE column IS NOT NULL` clause.
-     * @returns `this` for chaining.
-     */
     orWhereNotNull(column: ColumnRef<TLocalSchema>): this;
-    /**
-     * Add a `WHERE column BETWEEN low AND high` clause.
-     * @param range - A two-element tuple `[low, high]`.
-     * @returns `this` for chaining.
-     */
     whereBetween(column: ColumnRef<TLocalSchema>, range: readonly [any, any]): this;
-    /**
-     * Add a `WHERE column NOT BETWEEN low AND high` clause.
-     * @param range - A two-element tuple `[low, high]`.
-     * @returns `this` for chaining.
-     */
     whereNotBetween(column: ColumnRef<TLocalSchema>, range: readonly [any, any]): this;
-    /**
-     * Add a case-sensitive `WHERE column LIKE value` clause.
-     * @param value - A SQL LIKE pattern (e.g. `'Alice%'`).
-     * @returns `this` for chaining.
-     */
     whereLike(column: ColumnRef<TLocalSchema>, value: string): this;
-    /**
-     * Add a case-insensitive `WHERE column ILIKE value` clause (PostgreSQL).
-     * @param value - A SQL LIKE pattern (e.g. `'alice%'`).
-     * @returns `this` for chaining.
-     */
     whereILike(column: ColumnRef<TLocalSchema>, value: string): this;
-    /**
-     * Add a raw `WHERE` clause. Useful for database-specific expressions.
-     * @param sql - Raw SQL string with optional `:binding:` or `?` placeholders.
-     * @param bindings - Values for the placeholders.
-     * @returns `this` for chaining.
-     */
     whereRaw(sql: string, ...bindings: any[]): this;
-    /**
-     * Add a `WHERE EXISTS (subquery)` clause.
-     * @param callback - A Knex query callback or sub-query builder.
-     * @returns `this` for chaining.
-     */
     whereExists(callback: Knex.QueryCallback | Knex.QueryBuilder): this;
-    /**
-     * Order the results by a column.
-     * @param column - Column reference or raw expression.
-     * @param direction - `'asc'` (default) or `'desc'`.
-     * @returns `this` for chaining.
-     *
-     * @example
-     * ```ts
-     * query(db, UserSchema).orderBy(t => t.name).orderBy(t => t.createdAt, 'desc');
-     * ```
-     */
+    whereNotExists(callback: Knex.QueryCallback | Knex.QueryBuilder): this;
+    whereJsonPath(column: ColumnRef<TLocalSchema>, path: string, operator?: string, value?: any): this;
     orderBy(column: ColumnRef<TLocalSchema> | Knex.Raw, direction?: 'asc' | 'desc'): this;
-    /**
-     * Order the results by a raw SQL expression.
-     * @param sql - Raw SQL (e.g. `'LOWER(name) ASC'`).
-     * @returns `this` for chaining.
-     */
     orderByRaw(sql: string, ...bindings: any[]): this;
-    /**
-     * Add a `GROUP BY` clause.
-     * @param columns - One or more column references or raw expressions.
-     * @returns `this` for chaining.
-     */
     groupBy(...columns: (ColumnRef<TLocalSchema> | Knex.Raw)[]): this;
-    /**
-     * Add a raw `GROUP BY` expression.
-     * @returns `this` for chaining.
-     */
     groupByRaw(sql: string, ...bindings: any[]): this;
-    /**
-     * Add a `HAVING column operator value` clause (used with `GROUP BY`).
-     * @returns `this` for chaining.
-     */
     having(column: ColumnRef<TLocalSchema> | Knex.Raw, operator: string, value: any): this;
-    /**
-     * Add a raw `HAVING` expression.
-     * @returns `this` for chaining.
-     */
     havingRaw(sql: string, ...bindings: any[]): this;
-    /**
-     * Limit the number of rows returned.
-     * @param n - Maximum number of rows.
-     * @returns `this` for chaining.
-     */
     limit(n: number): this;
-    /**
-     * Skip the first `n` rows in the result set (for cursor/offset pagination).
-     * @param n - Number of rows to skip.
-     * @returns `this` for chaining.
-     */
     offset(n: number): this;
-    /**
-     * Select specific columns instead of `*`. Each column reference is
-     * resolved to its SQL column name through the schema.
-     * @param columns - One or more column references or raw expressions.
-     * @returns `this` for chaining.
-     */
-    select(...columns: (ColumnRef<TLocalSchema> | Knex.Raw)[]): this;
-    /**
-     * Add `DISTINCT` to the select clause. Duplicate rows are eliminated.
-     * @param columns - One or more column references or raw expressions.
-     * @returns `this` for chaining.
-     */
-    distinct(...columns: (ColumnRef<TLocalSchema> | Knex.Raw)[]): this;
-    /**
-     * Add a `COUNT(*)` or `COUNT(column)` aggregate to the select list.
-     * @param column - Optional column to count (defaults to `*`).
-     * @returns `this` for chaining.
-     */
-    count(column?: ColumnRef<TLocalSchema> | Knex.Raw): this;
-    /**
-     * Add a `COUNT(DISTINCT column)` aggregate to the select list.
-     * @param column - Optional column (defaults to `*`).
-     * @returns `this` for chaining.
-     */
-    countDistinct(column?: ColumnRef<TLocalSchema> | Knex.Raw): this;
-    /**
-     * Add a `MIN(column)` aggregate.
-     * @returns `this` for chaining.
-     */
-    min(column: ColumnRef<TLocalSchema> | Knex.Raw): this;
-    /**
-     * Add a `MAX(column)` aggregate.
-     * @returns `this` for chaining.
-     */
-    max(column: ColumnRef<TLocalSchema> | Knex.Raw): this;
-    /**
-     * Add a `SUM(column)` aggregate.
-     * @returns `this` for chaining.
-     */
-    sum(column: ColumnRef<TLocalSchema> | Knex.Raw): this;
-    /**
-     * Add an `AVG(column)` aggregate.
-     * @returns `this` for chaining.
-     */
-    avg(column: ColumnRef<TLocalSchema> | Knex.Raw): this;
-    /**
-     * Insert a single row into the table and return the inserted record.
-     *
-     * Property keys are mapped to SQL column names via the schema's
-     * `hasColumnName()` metadata before the `INSERT` is executed. The
-     * returned row is mapped back to property names.
-     *
-     * @param data - The object to insert. Keys must be valid schema property names.
-     * @returns The full inserted row (including database-generated fields).
-     *
-     * @example
-     * ```ts
-     * const user = await query(db, UserSchema).insert({ name: 'Alice', age: 30 });
-     * // user.id is populated by the database DEFAULT / SERIAL
-     * ```
-     */
+    paginate(opts: {
+        page: number;
+        pageSize: number;
+    }): Promise<PaginationResult<TResult>>;
+    paginateAfter(opts: {
+        cursor?: any;
+        limit: number;
+        column?: ColumnRef<TLocalSchema>;
+        direction?: 'asc' | 'desc';
+    }): Promise<CursorPaginationResult<TResult>>;
     insert(data: InsertType<TLocalSchema>): Promise<TResult>;
-    /**
-     * Insert multiple rows in a single `INSERT` statement and return all
-     * inserted records.
-     *
-     * @param data - Array of objects to insert.
-     * @returns The full inserted rows in insertion order.
-     */
     insertMany(data: InsertType<TLocalSchema>[]): Promise<TResult[]>;
-    /**
-     * Update all rows that match the current `WHERE` clause and return the
-     * updated records.
-     *
-     * Only the keys present in `data` are updated (partial update). Property
-     * keys are resolved to column names automatically.
-     *
-     * @param data - Partial schema object with fields to update.
-     * @returns All rows that were updated.
-     *
-     * @example
-     * ```ts
-     * const updated = await query(db, UserSchema)
-     *     .where(t => t.id, userId)
-     *     .update({ name: 'Bob' });
-     * ```
-     */
+    onConflict(...conflictColumns: ColumnRef<TLocalSchema>[]): import('./operations/insert.js').OnConflictBuilder<TLocalSchema, TResult>;
+    upsert(data: InsertType<TLocalSchema>, opts: {
+        conflictColumns: ColumnRef<TLocalSchema>[];
+        updateColumns?: ColumnRef<TLocalSchema>[];
+    }): Promise<TResult>;
+    bulkInsert(rows: InsertType<TLocalSchema>[], opts?: {
+        chunkSize?: number;
+        onConflict?: 'ignore' | 'merge';
+        conflictColumns?: ColumnRef<TLocalSchema>[];
+    }): Promise<TResult[]>;
+    bulkUpsert(rows: InsertType<TLocalSchema>[], opts: {
+        conflictColumns: ColumnRef<TLocalSchema>[];
+        chunkSize?: number;
+    }): Promise<TResult[]>;
     update(data: Partial<InferType<TLocalSchema>>): Promise<TResult[]>;
-    /**
-     * Delete all rows that match the current `WHERE` clause.
-     * @returns The number of rows deleted.
-     *
-     * @example
-     * ```ts
-     * const count = await query(db, UserSchema).where(t => t.id, id).delete();
-     * ```
-     */
+    bulkUpdate(updates: ReadonlyArray<{
+        where: Partial<InferType<TLocalSchema>>;
+        set: Partial<InferType<TLocalSchema>>;
+    }>): Promise<number>;
     delete(): Promise<number>;
-    /**
-     * Escape hatch: apply any Knex method to the underlying base query.
-     *
-     * Use this when you need a Knex feature not exposed by this API (e.g.
-     * `forUpdate()`, CTEs, `join()`, `union()`).
-     *
-     * @param fn - A callback that receives the raw `Knex.QueryBuilder` and
-     *   may mutate it in place.
-     * @returns `this` for chaining.
-     *
-     * @example
-     * ```ts
-     * query(db, UserSchema).apply(qb => qb.forUpdate().noWait());
-     * ```
-     */
+    withDeleted(): this;
+    onlyDeleted(): this;
+    hardDelete(): Promise<number>;
+    restore(): Promise<TResult[]>;
+    joinOne<TForeignSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TFieldName extends string, TRequired extends boolean = true>(spec: JoinOneSpec<TLocalSchema, TForeignSchema, TFieldName, TRequired>): SchemaQueryBuilder<TLocalSchema, import('./types.js').WithJoinedOne<TResult, TFieldName, TForeignSchema, TRequired>>;
+    joinMany<TForeignSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TFieldName extends string>(spec: JoinManySpec<TLocalSchema, TForeignSchema, TFieldName>): SchemaQueryBuilder<TLocalSchema, import('./types.js').WithJoinedMany<TResult, TFieldName, TForeignSchema>>;
+    include(relationName: string, customize?: (q: SchemaQueryBuilder<any, any>) => void): this;
+    includeVariant(variantKey: string, relationName: string, customize?: (q: SchemaQueryBuilder<any, any>) => void): this;
+    whereVariant(key: string, column: string, operator: string, value: any): this;
+    selectVariants(keys: string[]): this;
     apply(fn: (builder: Knex.QueryBuilder) => void): this;
-    /**
-     * Bind this query builder to a Knex transaction.
-     *
-     * Returns a **new** builder that runs all operations — SELECT, INSERT,
-     * UPDATE, DELETE, and eager-loaded sub-queries — within the given
-     * transaction. The original builder is left unchanged.
-     *
-     * Use this when you already have a transaction obtained from
-     * `knex.transaction()` and want all operations performed by the returned
-     * builder to participate in that transaction.
-     *
-     * @param trx - The Knex transaction obtained from `knex.transaction()`.
-     * @returns A new {@link SchemaQueryBuilder} bound to the transaction.
-     *
-     * @example
-     * ```ts
-     * async function createUser(
-     *     data: InsertType<typeof UserSchema>,
-     *     trx: Knex.Transaction
-     * ) {
-     *     return query(db, UserSchema).transacting(trx).insert(data);
-     * }
-     *
-     * await db.transaction(async trx => {
-     *     const user = await createUser({ name: 'Alice' }, trx);
-     *     await query(db, PostSchema).transacting(trx).insert({ authorId: user.id, title: 'Hello' });
-     * });
-     * ```
-     */
     transacting(trx: Knex.Transaction): SchemaQueryBuilder<TLocalSchema, TResult>;
-    /**
-     * Return the raw SQL string that would be executed, for debugging.
-     * Does not execute the query against the database.
-     */
     toQuery(): string;
-    /**
-     * Returns the underlying Knex query builder. Useful when passing this
-     * query as a `foreignQuery` in `.joinOne()` / `.joinMany()`, or any context
-     * that expects a raw `Knex.QueryBuilder`.
-     */
     toKnexQuery(): Knex.QueryBuilder;
-    /**
-     * Alias for {@link toQuery} — returns the raw SQL string.
-     */
     toString(): string;
-    /**
-     * Execute the query and return all matching rows, mapped back to schema
-     * property names.
-     *
-     * @returns A promise that resolves to an array of result objects typed as
-     *   `TResult[]`.
-     *
-     * @example
-     * ```ts
-     * const users = await query(db, UserSchema).execute();
-     * ```
-     */
     execute(): Promise<TResult[]>;
-    /**
-     * Execute the query and return only the first row, or `undefined` if no
-     * rows match.
-     *
-     * @example
-     * ```ts
-     * const user = await query(db, UserSchema).where(t => t.id, id).first();
-     * if (user) { /* ... *\/ }
-     * ```
-     */
     first(): Promise<TResult | undefined>;
-    /**
-     * Thenable implementation — allows the builder to be awaited directly
-     * without calling {@link execute} explicitly.
-     *
-     * @example
-     * ```ts
-     * const users = await query(db, UserSchema).where(t => t.name, 'Alice');
-     * // Equivalent to: await query(db, UserSchema).where(...).execute()
-     * ```
-     */
+    pluck<K extends keyof TResult & string>(column: ColumnRef<TLocalSchema>): Promise<TResult[K][]>;
     then<TReturn1 = TResult[], TReturn2 = never>(onfulfilled?: ((value: TResult[]) => TReturn1 | PromiseLike<TReturn1>) | null, onrejected?: ((reason: any) => TReturn2 | PromiseLike<TReturn2>) | null): Promise<TReturn1 | TReturn2>;
 }
-/**
- * Create a typed {@link SchemaQueryBuilder} for the table described by `schema`.
- *
- * The schema must have a table name configured via `.hasTableName()`.
- * Column name mappings set via `.hasColumnName()` are applied automatically
- * to all query methods. The returned builder is thenable — you can `await` it
- * directly to execute the query and get `TResult[]`.
- *
- * @param knex - A configured Knex instance.
- * @param schema - The `ObjectSchemaBuilder` describing the table.
- * @returns A new {@link SchemaQueryBuilder} ready for chaining.
- *
- * @example
- * ```ts
- * import knex from 'knex';
- * import { query, object, string, number } from '@cleverbrush/knex-schema';
- *
- * const UserSchema = object({ id: number(), name: string() }).hasTableName('users');
- * const db = knex({ client: 'pg', connection: process.env.DB_URL });
- *
- * const users = await query(db, UserSchema).where(t => t.name, 'like', 'A%');
- * ```
- */
-export declare function query<TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(knex: Knex, schema: TLocalSchema): SchemaQueryBuilder<TLocalSchema, InferType<TLocalSchema>>;
-/**
- * Create a typed {@link SchemaQueryBuilder} from an existing Knex query builder.
- *
- * Use this overload when you need to supply a pre-configured base query —
- * for example one that already has a sub-query, CTE, or a schema scope applied.
- *
- * @param knex - A configured Knex instance.
- * @param schema - The `ObjectSchemaBuilder` describing the table.
- * @param baseQuery - An existing `Knex.QueryBuilder` to use as the base.
- * @returns A new {@link SchemaQueryBuilder} wrapping `baseQuery`.
- *
- * @example
- * ```ts
- * // Use a scoped base query (e.g. soft-delete filter applied globally)
- * const base = db('users').where('deleted_at', null);
- * const activeUsers = await query(db, UserSchema, base).where(t => t.age, '>', 18);
- * ```
- */
-export declare function query<TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(knex: Knex, schema: TLocalSchema, baseQuery: Knex.QueryBuilder): SchemaQueryBuilder<TLocalSchema, InferType<TLocalSchema>>;
-/** Bound query function returned by {@link createQuery}. */
+export declare function query<TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(knex: Knex, schema: TLocalSchema): SchemaQueryBuilder<TLocalSchema, QueryResultType<TLocalSchema>>;
+export declare function query<TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(knex: Knex, schema: TLocalSchema, baseQuery: Knex.QueryBuilder): SchemaQueryBuilder<TLocalSchema, QueryResultType<TLocalSchema>>;
 export interface BoundQuery {
-    <TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: TLocalSchema): SchemaQueryBuilder<TLocalSchema, InferType<TLocalSchema>>;
-    <TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: TLocalSchema, baseQuery: Knex.QueryBuilder): SchemaQueryBuilder<TLocalSchema, InferType<TLocalSchema>>;
-    /**
-     * Return a version of this bound factory whose queries all run within the
-     * given Knex transaction. Equivalent to calling `.transacting(trx)` on
-     * each individual builder, but more convenient when every query in a block
-     * must share the same transaction.
-     *
-     * @example
-     * ```ts
-     * const db = createQuery(knex);
-     *
-     * await knex.transaction(async trx => {
-     *     const dbTrx = db.withTransaction(trx);
-     *     const user = await dbTrx(UserSchema).insert({ name: 'Alice' });
-     *     await dbTrx(PostSchema).insert({ authorId: user.id, title: 'Hello' });
-     * });
-     * ```
-     */
+    <TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: TLocalSchema): SchemaQueryBuilder<TLocalSchema, QueryResultType<TLocalSchema>>;
+    <TLocalSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(schema: TLocalSchema, baseQuery: Knex.QueryBuilder): SchemaQueryBuilder<TLocalSchema, QueryResultType<TLocalSchema>>;
     withTransaction(trx: Knex.Transaction): BoundQuery;
-    /**
-     * Start a Knex transaction and run `callback` inside it, passing a
-     * transaction-bound `BoundQuery` factory as the argument. The transaction
-     * is committed when the callback resolves and rolled back if it rejects.
-     *
-     * This is the callback-style counterpart to {@link withTransaction} — you
-     * don't need to obtain a `Knex.Transaction` object yourself.
-     *
-     * @param callback - An async function that receives a transaction-bound
-     *   `BoundQuery` and returns a value. The returned value is forwarded as
-     *   the resolved value of the outer `Promise`.
-     * @returns A `Promise` that resolves with the value returned by `callback`.
-     *
-     * @example
-     * ```ts
-     * const db = createQuery(knex);
-     *
-     * const user = await db.transaction(async dbTrx => {
-     *     const newUser = await dbTrx(UserSchema).insert({ name: 'Alice' });
-     *     await dbTrx(PostSchema).insert({ authorId: newUser.id, title: 'Hello' });
-     *     return newUser;
-     * });
-     * ```
-     */
     transaction<T>(callback: (db: BoundQuery) => Promise<T>): Promise<T>;
 }
-/**
- * Bind a Knex instance once and get back a `query(schema)` function that
- * doesn't require repeating the knex argument on every call.
- *
- * @param knex - A configured Knex instance.
- * @returns A bound query factory: `(schema, baseQuery?) => SchemaQueryBuilder`.
- *
- * @example
- * ```ts
- * import Knex from 'knex';
- * import { createQuery } from '@cleverbrush/knex-schema';
- *
- * const knex = Knex({ client: 'pg', connection: process.env.DB_URL });
- * const query = createQuery(knex);
- *
- * // No knex argument needed from here on
- * const users = await query(UserSchema).where(t => t.role, '=', 'admin');
- * const post = await query(PostSchema).where(t => t.id, '=', 42).first();
- *
- * // Optional base query (e.g. soft-delete scope applied globally)
- * const active = query(UserSchema, knex('users').where('deleted_at', null));
- * ```
- */
 export declare function createQuery(knexInstance: Knex): BoundQuery;