@cleverbrush/knex-schema 0.0.0-beta-20260413145651

package/dist/SchemaQueryBuilder.d.ts

@@ -0,0 +1,567 @@
+import type { InferType } from '@cleverbrush/schema';
+import { 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 }>
+ * ```
+ */
+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.
+     */
+    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');
+     * ```
+     */
+    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
+     * ```
+     */
+    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' });
+     * ```
+     */
+    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();
+     * ```
+     */
+    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());
+     * ```
+     */
+    apply(fn: (builder: Knex.QueryBuilder) => void): this;
+    /**
+     * 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()
+     * ```
+     */
+    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 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>>;
+}
+/**
+ * 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;

package/dist/columns.d.ts

@@ -0,0 +1,27 @@
+import { ObjectSchemaBuilder } from '@cleverbrush/schema';
+import type { ColumnRef } from './types.js';
+interface ColumnMapResult {
+    propToCol: Map<string, string>;
+    colToProp: Map<string, string>;
+}
+/**
+ * Build a bidirectional column map from an ObjectSchemaBuilder's properties.
+ * Uses `getExtension('columnName')` per property, falling back to the property key.
+ * Result is cached per schema instance via WeakMap.
+ */
+export declare function buildColumnMap(schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>): ColumnMapResult;
+/**
+ * Resolve a ColumnRef to a plain SQL column name.
+ *
+ * - String refs are treated as **property keys** and translated to column
+ *   names via the column map.
+ * - Function refs (property accessor) are resolved via PropertyDescriptorTree,
+ *   then translated to column names.
+ */
+export declare function resolveColumnRef(ref: ColumnRef<any>, schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>, label: string): string;
+/**
+ * Resolve a ColumnRef to the **property key** (not the column name).
+ * Used for result mapping.
+ */
+export declare function resolvePropertyKey(ref: ColumnRef<any>, schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>, label: string): string;
+export {};