@warlock.js/cascade 4.0.135 → 4.0.137

package/esm/drivers/postgres/postgres-query-builder.d.ts

@@ -1,824 +1,254 @@
 /**
  * PostgreSQL Query Builder
  *
- * Implements the QueryBuilderContract for PostgreSQL databases.
- * Provides a fluent API for building SQL queries with proper
- * parameter handling and type safety.
+ * Extends the pure QueryBuilder base with PostgreSQL-specific execution,
+ * SQL generation, relation hydration, and scope management.
  *
  * @module cascade/drivers/postgres
  */
 import type { GenericObject } from "@mongez/reinforcements";
-import type { ChunkCallback, CursorPaginationOptions, CursorPaginationResult, GroupByInput, HavingInput, JoinOptions, OrderDirection, PaginationOptions, PaginationResult, QueryBuilderContract, RawExpression, WhereCallback, WhereObject, WhereOperator } from "../../contracts/query-builder.contract";
+import type { ChunkCallback, CursorPaginationOptions, CursorPaginationResult, DriverQuery, PaginationOptions, PaginationResult, QueryBuilderContract } from "../../contracts/query-builder.contract";
 import type { DataSource } from "../../data-source/data-source";
-import type { GlobalScopeDefinition, LocalScopeCallback } from "../../model/model";
-import { type PostgresParserOperation } from "./postgres-query-parser";
+import { QueryBuilder, type Op } from "../../query-builder/query-builder";
+type JoinRelationConfig = {
+    alias: string;
+    type: "belongsTo" | "hasOne" | "hasMany";
+    model?: unknown;
+    localKey?: string;
+    foreignKey?: string;
+    ownerKey?: string;
+    parentPath?: string | null;
+    relationName?: string;
+    parentModel?: unknown;
+    select?: string[];
+    /** Operations recorded by a joinWith constraint callback. */
+    constraintOps?: Op[];
+};
 /**
  * PostgreSQL Query Builder.
  *
- * Implements the Cascade QueryBuilderContract for PostgreSQL.
- * Collects query operations and delegates to PostgresQueryParser
- * for SQL generation.
+ * Collects query operations (via the base class) and delegates SQL generation
+ * to `PostgresQueryParser`. Owns execution, hydration, and relation loading.
  *
  * @example
  * ```typescript
- * const users = await queryBuilder('users')
- *   .select(['id', 'name', 'email'])
- *   .where('status', 'active')
- *   .where('age', '>', 18)
- *   .orderBy('createdAt', 'desc')
+ * const users = await User.query()
+ *   .select(["id", "name", "email"])
+ *   .where("status", "active")
+ *   .orderBy("createdAt", "desc")
  *   .limit(10)
  *   .get();
  * ```
  */
-export declare class PostgresQueryBuilder<T = unknown> implements QueryBuilderContract<T> {
+export declare class PostgresQueryBuilder<T = unknown> extends QueryBuilder<T> implements QueryBuilderContract<T> {
     readonly table: string;
-    /**
-     * Collected operations to be parsed into SQL.
-     */
-    operations: PostgresParserOperation[];
-    /**
-     * Data source instance.
-     */
+    /** Data source backing this builder. */
     readonly dataSource: DataSource;
-    /**
-     * Hydrate callback for transforming results.
-     */
+    /** Hydration callback for transforming result rows into model instances. */
     hydrateCallback?: (data: unknown, index: number) => unknown;
-    /**
-     * Callback invoked before query execution.
-     */
+    /** Invoked before query execution. */
     private fetchingCallback?;
-    /**
-     * Callback invoked after records fetched but before hydration.
-     */
+    /** Invoked after fetch but before hydration. */
     private hydratingCallback?;
-    /**
-     * Callback invoked after records fetched and hydrated.
-     */
+    /** Invoked after fetch and hydration. */
     private fetchedCallback?;
     /**
-     * Pending global scopes.
+     * Map of relations registered via `joinWith()`.
+     * Keyed by dot-notation path (e.g. "organizationAiModel.aiModel").
      */
-    pendingGlobalScopes?: Map<string, GlobalScopeDefinition>;
+    joinRelations: Map<string, JoinRelationConfig>;
     /**
-     * Available local scopes.
-     */
-    availableLocalScopes?: Map<string, LocalScopeCallback>;
-    /**
-     * Disabled global scope names.
-     */
-    disabledGlobalScopes: Set<string>;
-    /**
-     * Whether scopes have been applied.
-     */
-    scopesApplied: boolean;
-    /**
-     * Create a new query builder.
-     *
      * @param table - Target table name
-     * @param dataSource - Optional data source (uses default if not provided)
+     * @param dataSource - Optional (uses default data source from registry if omitted)
      */
     constructor(table: string, dataSource?: DataSource);
-    /**
-     * Get the PostgreSQL driver instance.
-     */
     private get driver();
+    clone(): this;
     /**
-     * Add an operation to the operations list.
+     * Native-query escape hatch. Passes `operations[]` to the callback for
+     * direct manipulation. Use sparingly — only when fluent API is insufficient.
      *
-     * @param type - Operation type
-     * @param data - Operation data
+     * @example
+     * q.raw(ops => ops.push({ type: "whereRaw", data: { expression: "1=1" } }))
      */
-    private addOperation;
+    raw(callback: (operations: Op[]) => void): this;
     /**
-     * Clone this query builder with all current operations.
+     * Record a DISTINCT flag AND auto-select the field(s).
+     * In PostgreSQL, DISTINCT ON (col) requires the col to appear in SELECT.
      *
-     * @returns New query builder instance
+     * @example
+     * q.distinctValues("category")               // SELECT category … DISTINCT ON (category)
+     * q.distinctValues(["category", "status"])   // both fields in DISTINCT ON and SELECT
      */
-    clone(): this;
+    distinctValues(fields?: string | string[]): this;
     /**
-     * Set a hydration callback to transform each result row.
+     * Nearest-neighbour vector similarity search via pgvector cosine distance.
      *
-     * @param callback - Transform function
-     * @returns This builder for chaining
-     */
-    hydrate(callback: (data: unknown, index: number) => unknown): this;
-    /**
-     * Register callback invoked before query execution.
+     * Adds two operations atomically:
+     * 1. `selectRaw` → `1 - (column <=> $n::vector) AS <alias>`
+     *    Makes the similarity score available on every returned row.
+     * 2. `orderByRaw` → `column <=> $n::vector`
+     *    Tells the PostgreSQL query planner to use the IVFFlat/HNSW vector index.
+     *    Using the alias in ORDER BY would bypass the index — the raw expression is required.
      *
-     * @param callback - Callback function
-     * @returns Unsubscribe function
-     */
+     * @example
+     * ```typescript
+     * const results = await Vector.query()
+     *   .where({ organization_id: "org-123", content_type: "summary" })
+     *   .nearestTo("embedding", queryEmbedding)
+     *   .limit(5)
+     *   .get<VectorRow & { score: number }>();
+     * ```
+     */
+    nearestTo(column: string, embedding: number[], alias?: string): this;
+    /** Set a hydration callback that transforms each result row. */
+    hydrate(callback: (data: unknown, index: number) => unknown): this;
+    /** Register a callback invoked before query execution. */
     onFetching(callback: (query: this) => void | Promise<void>): () => void;
-    /**
-     * Register callback invoked after fetch but before hydration.
-     *
-     * @param callback - Callback function
-     * @returns Unsubscribe function
-     */
+    /** Register a callback invoked after fetch but before hydration. */
     onHydrating(callback: (records: unknown[], context: unknown) => void | Promise<void>): () => void;
-    /**
-     * Register callback invoked after fetch and hydration.
-     *
-     * @param callback - Callback function
-     * @returns Unsubscribe function
-     */
+    /** Register a callback invoked after fetch and hydration. */
     onFetched(callback: (records: unknown[], context: unknown) => void | Promise<void>): () => void;
-    /**
-     * Disable one or more global scopes for this query.
-     *
-     * @param scopeNames - Scope names to disable
-     * @returns This builder for chaining
-     */
-    withoutGlobalScope(...scopeNames: string[]): this;
-    /**
-     * Disable all global scopes for this query.
-     *
-     * @returns This builder for chaining
-     */
-    withoutGlobalScopes(): this;
-    /**
-     * Apply a local scope to this query.
-     *
-     * @param scopeName - Name of the local scope
-     * @returns This builder for chaining
-     */
-    scope(scopeName: string): this;
-    /**
-     * Apply pending global scopes before query execution.
-     */
+    /** Apply pending global scopes to the operations list. */
     private applyPendingScopes;
-    /**
-     * Add a WHERE clause to filter records.
-     */
-    where(field: string, value: unknown): this;
-    where(field: string, operator: WhereOperator, value: unknown): this;
-    where(conditions: WhereObject): this;
-    where(callback: WhereCallback<T>): this;
-    /**
-     * Add an OR WHERE clause.
-     */
-    orWhere(field: string, value: unknown): this;
-    orWhere(field: string, operator: WhereOperator, value: unknown): this;
-    orWhere(conditions: WhereObject): this;
-    orWhere(callback: WhereCallback<T>): this;
-    /**
-     * Add a raw WHERE clause.
-     */
-    whereRaw(expression: RawExpression, bindings?: unknown[]): this;
-    /**
-     * Add a raw OR WHERE clause.
-     */
-    orWhereRaw(expression: RawExpression, bindings?: unknown[]): this;
-    /**
-     * Compare two columns.
-     */
-    whereColumn(first: string, operator: WhereOperator, second: string): this;
-    /**
-     * Compare two columns with OR.
-     */
-    orWhereColumn(first: string, operator: WhereOperator, second: string): this;
-    /**
-     * Compare multiple column pairs.
-     */
-    whereColumns(comparisons: Array<[left: string, operator: WhereOperator, right: string]>): this;
-    /**
-     * Check if field is between two columns.
-     */
-    whereBetweenColumns(field: string, lowerColumn: string, upperColumn: string): this;
-    /**
-     * Filter by date (ignoring time).
-     */
-    whereDate(field: string, value: Date | string): this;
-    /**
-     * Alias for whereDate.
-     */
-    whereDateEquals(field: string, value: Date | string): this;
-    /**
-     * Filter for dates before a value.
-     */
-    whereDateBefore(field: string, value: Date | string): this;
-    /**
-     * Filter for dates after a value.
-     */
-    whereDateAfter(field: string, value: Date | string): this;
-    /**
-     * Filter by time.
-     */
-    whereTime(field: string, value: string): this;
-    /**
-     * Filter by day of month.
-     */
-    whereDay(field: string, value: number): this;
-    /**
-     * Filter by month.
-     */
-    whereMonth(field: string, value: number): this;
-    /**
-     * Filter by year.
-     */
-    whereYear(field: string, value: number): this;
-    /**
-     * Check if JSON contains value.
-     */
-    whereJsonContains(path: string, value: unknown): this;
-    /**
-     * Check if JSON doesn't contain value.
-     */
-    whereJsonDoesntContain(path: string, value: unknown): this;
-    /**
-     * Check if JSON contains key.
-     */
-    whereJsonContainsKey(path: string): this;
-    /**
-     * Check JSON array/string length.
-     */
-    whereJsonLength(path: string, operator: WhereOperator, value: number): this;
-    /**
-     * Check if JSON is array.
-     */
-    whereJsonIsArray(path: string): this;
-    /**
-     * Check if JSON is object.
-     */
-    whereJsonIsObject(path: string): this;
-    /**
-     * Check array length.
-     */
-    whereArrayLength(field: string, operator: WhereOperator, value: number): this;
-    /**
-     * Filter by ID.
-     */
-    whereId(value: string | number): this;
-    /**
-     * Filter by multiple IDs.
-     */
-    whereIds(values: Array<string | number>): this;
-    /**
-     * Filter by UUID.
-     */
-    whereUuid(value: string): this;
-    /**
-     * Filter by ULID.
-     */
-    whereUlid(value: string): this;
-    /**
-     * Full-text search.
-     */
-    whereFullText(fields: string | string[], query: string): this;
-    /**
-     * Full-text search with OR.
-     */
-    orWhereFullText(fields: string | string[], query: string): this;
-    /**
-     * Alias for whereFullText.
-     */
-    whereSearch(field: string, query: string): this;
-    /**
-     * Negate conditions.
-     */
-    whereNot(callback: WhereCallback<T>): this;
-    /**
-     * Negate conditions with OR.
-     */
-    orWhereNot(callback: WhereCallback<T>): this;
-    /**
-     * Filter by value in array.
-     */
-    whereIn(field: string, values: unknown[]): this;
-    /**
-     * Filter by value not in array.
-     */
-    whereNotIn(field: string, values: unknown[]): this;
-    /**
-     * Filter by NULL value.
-     */
-    whereNull(field: string): this;
-    /**
-     * Filter by NOT NULL value.
-     */
-    whereNotNull(field: string): this;
-    /**
-     * Filter by range (inclusive).
-     */
-    whereBetween(field: string, range: [unknown, unknown]): this;
-    /**
-     * Filter by not in range.
-     */
-    whereNotBetween(field: string, range: [unknown, unknown]): this;
-    /**
-     * Filter by LIKE pattern (case-insensitive).
-     */
-    whereLike(field: string, pattern: RegExp | string): this;
-    /**
-     * Filter by NOT LIKE pattern.
-     */
-    whereNotLike(field: string, pattern: RegExp | string): this;
-    /**
-     * Filter by prefix.
-     */
-    whereStartsWith(field: string, value: string | number): this;
-    /**
-     * Filter by not starting with prefix.
-     */
-    whereNotStartsWith(field: string, value: string | number): this;
-    /**
-     * Filter by suffix.
-     */
-    whereEndsWith(field: string, value: string | number): this;
-    /**
-     * Filter by not ending with suffix.
-     */
-    whereNotEndsWith(field: string, value: string | number): this;
-    /**
-     * Filter by date range.
-     */
-    whereDateBetween(field: string, range: [Date, Date]): this;
-    /**
-     * Filter by not in date range.
-     */
-    whereDateNotBetween(field: string, range: [Date, Date]): this;
-    /**
-     * Check if field/subquery exists.
-     */
-    whereExists(field: string): this;
-    whereExists(callback: WhereCallback<T>): this;
-    /**
-     * Check if field/subquery doesn't exist.
-     */
-    whereNotExists(field: string): this;
-    whereNotExists(callback: WhereCallback<T>): this;
-    /**
-     * Check array size.
-     */
-    whereSize(field: string, size: number): this;
-    whereSize(field: string, operator: WhereOperator, size: number): this;
-    /**
-     * Perform a full-text search.
-     */
-    textSearch(query: string, filters?: WhereObject): this;
-    /**
-     * Constrain an array field to contain the given value.
-     */
+    /** Array field contains a value (or object with key). */
     whereArrayContains(field: string, value: unknown, key?: string): this;
-    /**
-     * Constrain an array field to not contain the given value.
-     */
+    /** Array field does NOT contain a value (or object with key). */
     whereArrayNotContains(field: string, value: unknown, key?: string): this;
-    /**
-     * Constrain an array field to contain the value OR be empty.
-     */
+    /** Array field contains value OR is empty. */
     whereArrayHasOrEmpty(field: string, value: unknown, key?: string): this;
-    /**
-     * Constrain an array field to not contain the value OR be empty.
-     */
+    /** Array field does NOT contain value OR is empty. */
     whereArrayNotHaveOrEmpty(field: string, value: unknown, key?: string): this;
     /**
-     * Add a JOIN clause.
-     */
-    join(table: string, localField: string, foreignField: string): this;
-    join(options: JoinOptions): this;
-    /**
-     * Add a LEFT JOIN clause.
-     */
-    leftJoin(table: string, localField: string, foreignField: string): this;
-    leftJoin(options: JoinOptions): this;
-    /**
-     * Add a RIGHT JOIN clause.
-     */
-    rightJoin(table: string, localField: string, foreignField: string): this;
-    rightJoin(options: JoinOptions): this;
-    /**
-     * Add an INNER JOIN clause.
-     */
-    innerJoin(table: string, localField: string, foreignField: string): this;
-    innerJoin(options: JoinOptions): this;
-    /**
-     * Add a FULL OUTER JOIN clause.
-     */
-    fullJoin(table: string, localField: string, foreignField: string): this;
-    fullJoin(options: JoinOptions): this;
-    /**
-     * Add a CROSS JOIN clause.
-     */
-    crossJoin(table: string): this;
-    /**
-     * Add a raw JOIN clause.
-     */
-    joinRaw(expression: RawExpression, bindings?: unknown[]): this;
-    /**
-     * Select specific columns.
-     */
-    select(fields: string[]): this;
-    select(fields: Record<string, 0 | 1 | boolean>): this;
-    select(...fields: Array<string | string[]>): this;
-    /**
-     * Select a field with alias.
-     */
-    selectAs(field: string, alias: string): this;
-    /**
-     * Select raw expression.
-     */
-    selectRaw(expression: RawExpression, bindings?: unknown[]): this;
-    /**
-     * Select multiple raw expressions.
-     */
-    selectRawMany(definitions: Array<{
-        alias: string;
-        expression: RawExpression;
-        bindings?: unknown[];
-    }>): this;
-    /**
-     * Select subquery.
-     */
-    selectSub(expression: RawExpression, alias: string): this;
-    /**
-     * Add subquery to existing selection.
-     */
-    addSelectSub(expression: RawExpression, alias: string): this;
-    /**
-     * Select aggregate value.
-     */
-    selectAggregate(field: string, aggregate: "sum" | "avg" | "min" | "max" | "count" | "first" | "last", alias: string): this;
-    /**
-     * Select existence check.
-     */
-    selectExists(field: string, alias: string): this;
-    /**
-     * Select count.
-     */
-    selectCount(field: string, alias: string): this;
-    /**
-     * Select CASE expression.
-     */
-    selectCase(cases: Array<{
-        when: RawExpression;
-        then: RawExpression | unknown;
-    }>, otherwise: RawExpression | unknown, alias: string): this;
-    /**
-     * Select conditional (IF/ELSE).
-     */
-    selectWhen(condition: RawExpression, thenValue: RawExpression | unknown, elseValue: RawExpression | unknown, alias: string): this;
-    /**
-     * Direct projection manipulation.
-     */
-    selectDriverProjection(callback: (projection: Record<string, unknown>) => void): this;
-    /**
-     * Select JSON path.
-     */
-    selectJson(path: string, alias?: string): this;
-    /**
-     * Select JSON path with raw expression.
-     */
-    selectJsonRaw(path: string, expression: RawExpression, alias: string): this;
-    /**
-     * Exclude JSON path.
-     */
-    deselectJson(path: string): this;
-    /**
-     * Concatenate fields.
-     */
-    selectConcat(fields: Array<string | RawExpression>, alias: string): this;
-    /**
-     * Coalesce values.
-     */
-    selectCoalesce(fields: Array<string | RawExpression>, alias: string): this;
-    /**
-     * Window function.
-     */
-    selectWindow(spec: RawExpression): this;
-    /**
-     * Exclude columns from projection.
-     */
-    deselect(fields: string[]): this;
-    /**
-     * Clear selection.
-     */
-    clearSelect(): this;
-    /**
-     * Select all columns.
-     */
-    selectAll(): this;
-    /**
-     * Restore default projection.
-     */
-    selectDefault(): this;
-    /**
-     * Select distinct values.
-     */
-    distinctValues(fields?: string | string[]): this;
-    /**
-     * Add additional select fields.
-     */
-    addSelect(fields: string[]): this;
-    /**
-     * Order results.
-     */
-    orderBy(field: string, direction?: OrderDirection): this;
-    orderBy(fields: Record<string, OrderDirection>): this;
-    /**
-     * Order descending.
-     */
-    orderByDesc(field: string): this;
-    /**
-     * Order with raw expression.
-     */
-    orderByRaw(expression: RawExpression, bindings?: unknown[]): this;
-    /**
-     * Order randomly.
-     */
-    orderByRandom(limit: number): this;
-    /**
-     * Get latest records.
-     */
-    latest(column?: string): Promise<T[]>;
-    /**
-     * Get oldest records.
-     */
-    oldest(column?: string): this;
-    /**
-     * Limit results.
-     */
-    limit(value: number): this;
-    /**
-     * Skip results.
-     */
-    skip(value: number): this;
-    /**
-     * Offset results.
-     */
-    offset(value: number): this;
-    /**
-     * Take first N results.
-     */
-    take(value: number): this;
-    /**
-     * Apply cursor pagination hints.
-     */
-    cursor(after?: unknown, before?: unknown): this;
-    /**
-     * Group results.
-     */
-    groupBy(input: GroupByInput): this;
-    /**
-     * Raw GROUP BY.
-     */
-    groupByRaw(expression: RawExpression, bindings?: unknown[]): this;
-    /**
-     * HAVING clause.
-     */
-    having(field: string, value: unknown): this;
-    having(field: string, operator: WhereOperator, value: unknown): this;
-    having(condition: HavingInput): this;
-    /**
-     * Raw HAVING clause.
+     * Load relations via SQL JOINs (single query) with optional per-relation constraints.
+     *
+     * Supports:
+     * - `joinWith("author")` / `joinWith(["author", "category"])`
+     * - `joinWith({ actions: q => q.where("status", "pending").limit(5) })`
+     * - `joinWith({ organizationAiModel: "id,name", actions: q => q.orderBy("sort_order") })`
+     *
+     * @example
+     * ChatMessage.joinWith({
+     *   actions: q => q.where("status", "pending").orderBy("sort_order", "asc").limit(5),
+     *   organizationAiModel: "id,createdAt",
+     * })
      */
-    havingRaw(expression: RawExpression, bindings?: unknown[]): this;
+    joinWith(...args: unknown[]): this;
+    /** Run a joinWith constraint callback against a sub-QB and capture its operations. */
+    private _resolveConstraintOps;
     /**
-     * Execute query and get all results.
+     * Execute the query and return all matching rows.
      */
     get<TResult = T>(): Promise<TResult[]>;
-    /**
-     * Apply JOIN operations for joinWith() relations.
-     */
-    private applyJoinRelations;
-    /**
-     * Extract joined relation data from raw records.
-     * Returns a map of record index to relation data.
-     */
-    private extractJoinedRelationData;
-    /**
-     * Attach joined relations to hydrated models.
-     */
-    private attachJoinedRelations;
-    /**
-     * Get first result.
-     */
+    /** Get first result. */
     first<TResult = T>(): Promise<TResult | null>;
-    /**
-     * Get last result.
-     */
+    /** Get last result (by id desc). */
     last<TResult = T>(): Promise<TResult | null>;
-    /**
-     * Get random results.
-     */
+    /** Get random results. */
     random<TResult = T>(limit?: number): Promise<TResult[]>;
-    /**
-     * Get first or throw.
-     */
+    /** Get first or throw. */
     firstOrFail<TResult = T>(): Promise<TResult>;
-    /**
-     * Get first or call callback.
-     */
+    /** Get first or call callback. */
     firstOr<TResult = T>(callback: () => TResult | Promise<TResult>): Promise<TResult>;
-    /**
-     * Get first or return default.
-     */
+    /** Get first or return null. */
     firstOrNull<TResult = T>(): Promise<TResult | null>;
-    /**
-     * Get first or create new.
-     */
+    /** Get first or return default. */
     firstOrNew<TResult = T>(defaults: GenericObject): Promise<TResult>;
-    /**
-     * Find by ID.
-     */
+    /** Find by primary key. */
     find<TResult = T>(id: number | string): Promise<TResult | null>;
-    /**
-     * Count results.
-     */
+    /** Count matching rows. */
     count(): Promise<number>;
-    /**
-     * Sum of field values.
-     */
+    /** SUM a numeric field. */
     sum(field: string): Promise<number>;
-    /**
-     * Average of field values.
-     */
+    /** AVG of a numeric field. */
     avg(field: string): Promise<number>;
-    /**
-     * Minimum field value.
-     */
+    /** MIN of a numeric field. */
     min(field: string): Promise<number>;
-    /**
-     * Maximum field value.
-     */
+    /** MAX of a numeric field. */
     max(field: string): Promise<number>;
-    /**
-     * Get distinct values.
-     */
+    /** Get distinct values for a field. */
     distinct<TResult = unknown>(field: string): Promise<TResult[]>;
-    /**
-     * Get array of values for field.
-     */
+    /** Get array of all values for a single field. */
     pluck(field: string): Promise<unknown[]>;
-    /**
-     * Get single scalar value.
-     */
+    /** Get a single scalar value. */
     value<TResult = unknown>(field: string): Promise<TResult | null>;
-    /**
-     * Check if records exist.
-     */
+    /** Check whether any matching rows exist. */
     exists(): Promise<boolean>;
-    /**
-     * Check if no records exist.
-     */
+    /** Check whether NO matching rows exist. */
     notExists(): Promise<boolean>;
-    /**
-     * Count distinct values.
-     */
+    /** COUNT DISTINCT a field. */
     countDistinct(field: string): Promise<number>;
-    /**
-     * Increment field value.
-     */
+    /** Get latest records ordered by a column. */
+    latest(column?: string): Promise<T[]>;
+    /** Increment a numeric field. Returns new value. */
     increment(field: string, amount?: number): Promise<number>;
-    /**
-     * Decrement field value.
-     */
+    /** Decrement a numeric field. Returns new value. */
     decrement(field: string, amount?: number): Promise<number>;
-    /**
-     * Increment for all matching.
-     */
+    /** Increment a field for all matching rows. Returns affected row count. */
     incrementMany(field: string, amount?: number): Promise<number>;
-    /**
-     * Decrement for all matching.
-     */
+    /** Decrement a field for all matching rows. Returns affected row count. */
     decrementMany(field: string, amount?: number): Promise<number>;
     /**
-     * Process results in chunks.
+     * Process results in memory-efficient chunks.
+     *
+     * @example
+     * await User.query().chunk(100, async (rows, idx) => { ... })
      */
     chunk(size: number, callback: ChunkCallback<T>): Promise<void>;
-    /**
-     * Page-based pagination.
-     */
+    /** Page-based pagination. */
     paginate(options?: PaginationOptions): Promise<PaginationResult<T>>;
     /**
-     * Cursor-based pagination.
+     * Set cursor pagination hints fluently.
+     * The recorded values are picked up by `cursorPaginate()` when no explicit
+     * options are passed.
+     *
+     * @example
+     * User.query().cursor(lastId).cursorPaginate({ limit: 20 })
      */
+    cursor(after?: unknown, before?: unknown): this;
+    /** Cursor-based pagination. */
     cursorPaginate(options?: CursorPaginationOptions): Promise<CursorPaginationResult<T>>;
-    /**
-     * Delete matching records.
-     */
+    /** Delete matching rows. Returns deleted count. */
     delete(): Promise<number>;
-    /**
-     * Delete first matching record.
-     */
+    /** Delete the first matching row. */
     deleteOne(): Promise<number>;
-    /**
-     * Update matching records.
-     */
+    /** Update matching rows. */
     update(fields: Record<string, unknown>): Promise<number>;
-    /**
-     * Unset fields from matching records.
-     */
+    /** Unset fields from matching rows. */
     unset(...fields: string[]): Promise<number>;
-    /**
-     * Get the raw SQL query.
-     */
-    parse(): {
-        sql: string;
-        params: unknown[];
-    };
-    /**
-     * Get formatted SQL string.
-     */
+    /** Return the SQL + bindings without executing. */
+    parse(): DriverQuery;
+    /** Formatted SQL string (for logging/debugging). */
     pretty(): string;
-    /**
-     * Get query execution plan.
-     */
+    /** Run EXPLAIN ANALYZE on the query. */
     explain(): Promise<unknown>;
-    /**
-     * Add driver-specific raw modifications to the query.
-     */
-    raw(builder: (native: unknown) => unknown): this;
-    /**
-     * Extend the query builder with driver-specific extensions.
-     */
+    /** Extend the builder with a driver-specific extension. */
     extend<R>(extension: string, ..._args: unknown[]): R;
+    /** Pluck scalar values for a single field (alias for pluck). */
+    pluckOne<TResult = unknown>(field: string): Promise<TResult[]>;
     /**
-     * Tap into the query builder for side-effects.
-     */
-    tap(callback: (builder: this) => void): this;
-    /**
-     * Conditionally apply query modifications.
-     */
-    when<V>(condition: V | boolean, callback: (builder: this, value: V) => void, otherwise?: (builder: this) => void): this;
-    /**
-     * Build WHERE clause from current operations.
-     */
-    private buildFilter;
-    /**
-     * Relations to eagerly load.
+     * Before `get()` runs the parser, consume any joinWith ops recorded by the base
+     * class and expand them into the joinRelations Map.
      */
-    eagerLoadRelations: Map<string, boolean | ((query: QueryBuilderContract) => void)>;
+    private _processJoinWithOps;
     /**
-     * Relations to count.
+     * Translate each entry in `joinRelations` into actual JOIN + selectRelatedColumns operations.
      */
-    countRelations: string[];
-    /**
-     * Relations to load via JOIN (single query).
-     */
-    joinRelations: Map<string, {
-        alias: string;
-        type: "belongsTo" | "hasOne" | "hasMany";
-    }>;
-    /**
-     * Relation definitions from the model.
-     */
-    relationDefinitions?: Record<string, any>;
-    /**
-     * Model class reference.
-     */
-    modelClass?: any;
-    /**
-     * Load relations using database JOINs in a single query.
-     *
-     * Unlike `with()` which uses separate queries, `joinWith()` uses
-     * LEFT JOIN to fetch related data in a single query.
-     *
-     * @param relations - Relation names to load via JOIN
-     * @returns This builder for chaining
-     */
-    joinWith(...relations: string[]): this;
-    /**
-     * Eagerly load one or more relations.
-     *
-     * Supported patterns:
-     * - `with("posts")` - Load relation
-     * - `with("posts", "comments")` - Load multiple relations
-     * - `with("posts", callback)` - Load relation with constraint
-     * - `with({ posts: true, comments: callback })` - Object configuration
-     *
-     * @param args - Relation name(s), callbacks, or configuration object
-     */
-    with(...args: (string | Record<string, boolean | ((query: QueryBuilderContract) => void)> | ((query: QueryBuilderContract) => void))[]): this;
-    /**
-     * Add a count of related models as a virtual field.
-     * @param relations - Relation name(s) to count
-     */
-    withCount(...relations: string[]): this;
-    /**
-     * Filter results to only those that have related models.
-     * @param relation - Relation name
-     * @param operator - Optional comparison operator
-     * @param count - Optional count to compare against
-     */
-    has(relation: string, operator?: string, count?: number): this;
+    private applyJoinRelations;
     /**
-     * Filter results that have related models matching specific conditions.
-     * @param relation - Relation name
-     * @param callback - Callback to define conditions
+     * Extract per-relation data from raw DB rows (before hydration).
+     * Returns a Map of row index → nested relation data tree.
      */
-    whereHas(relation: string, callback: (query: QueryBuilderContract) => void): this;
+    private extractJoinedRelationData;
     /**
-     * Filter results that don't have any related models.
-     * @param relation - Relation name
+     * Attach extracted relation data to hydrated model instances.
      */
-    doesntHave(relation: string): this;
+    private attachJoinedRelations;
     /**
-     * Filter results that don't have related models matching specific conditions.
-     * @param relation - Relation name
-     * @param callback - Callback to define conditions
+     * Build a WHERE-only SQL fragment from `where*` operations on the current builder.
+     * Used by DELETE / UPDATE / increment paths.
      */
-    whereDoesntHave(relation: string, callback: (query: QueryBuilderContract) => void): this;
+    private buildFilter;
 }
+export {};
 //# sourceMappingURL=postgres-query-builder.d.ts.map