turbine-orm 0.16.0 → 0.18.0

package/dist/query/builder.d.ts

@@ -114,6 +114,14 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly columnArrayTypeMap;
     /** Tracks tables that have already triggered a deep-with warning (one-time) */
     private readonly deepWithWarned;
+    /**
+     * Per-table memo of date columns keyed by their camelCase FIELD name.
+     * `meta.dateColumns` is keyed by raw snake_case column name, which matches
+     * top-level rows from pg. Nested relation rows arrive from json_build_object
+     * with camelCase keys, so they need this camelCase-keyed set to be coerced
+     * to Date as well (otherwise nested dates leak through as strings).
+     */
+    private readonly camelDateFieldCache;
     /** True when this QI runs inside an active transaction (set via _txScoped option). */
     private readonly txScoped;
     /** Original options reference — forwarded to child QIs in nested writes. */
@@ -251,6 +259,24 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildCount(args?: CountArgs<T>): DeferredQuery<number>;
     groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
     buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
+    /**
+     * Build the SQL fragments for a {@link HavingClause}.
+     *
+     * Each aggregate expression (`COUNT(*)`, `SUM("col")`, etc.) is constructed
+     * from a **schema-validated, quoted** column identifier — `this.toColumn()`
+     * throws {@link ValidationError} for unknown fields and `this.q()` quotes via
+     * the dialect, so no unvalidated identifier ever reaches the SQL string. Every
+     * comparison value is pushed onto the shared `params` array and referenced by
+     * a `$N` placeholder via {@link buildHavingNumericClauses} — there is no string
+     * interpolation of user values.
+     */
+    private buildHavingClauses;
+    /**
+     * Convert a single having filter into one or more parameterized SQL
+     * comparisons against the given aggregate expression. A bare number is
+     * shorthand for equality. Unknown operator keys throw {@link ValidationError}.
+     */
+    private buildHavingNumericClauses;
     aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
     buildAggregate(args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;
     /**
@@ -311,6 +337,19 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private collectJsonFilterParams;
     /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
     private collectArrayFilterParams;
+    /**
+     * Collect params for an orderBy clause. Only vector KNN ordering pushes a
+     * param (the `$n::vector` query vector); plain direction ordering is
+     * parameterless. Mirrors buildOrderBy's push order exactly so the cached-SQL
+     * param re-collection stays in lockstep.
+     */
+    private collectOrderByParams;
+    /**
+     * Collect params for a vector distance WHERE filter. Mirrors
+     * {@link buildVectorFilterClauses}: the `$n::vector` query vector first, then
+     * the comparison threshold(s).
+     */
+    private collectVectorFilterParams;
     /**
      * Produce a fingerprint for a `with` clause tree. Recursion mirrors
      * buildSelectWithRelations / buildRelationSubquery.
@@ -368,9 +407,40 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Each operator key becomes its own clause, all ANDed together.
      */
     private buildOperatorClauses;
-    /** Build ORDER BY clause from an object */
+    /**
+     * Build ORDER BY clause from an object.
+     *
+     * Each value is either a plain direction (`'asc'`/`'desc'`) or — for pgvector
+     * columns — a `{ distance: { to, metric, direction? } }` KNN ordering object.
+     * Vector ordering binds the query vector as a `$n::vector` param, so a `params`
+     * array MUST be supplied when a vector ordering may be present (top-level
+     * findMany path). When `params` is omitted (groupBy / relation path) a vector
+     * ordering throws — KNN ordering is only supported at the top level.
+     */
     private buildOrderBy;
+    /**
+     * Resolve a {@link VectorMetric} to its pgvector distance operator from a
+     * fixed allow-list, validating the target column is actually a `vector`
+     * column. Throws {@link ValidationError} for an unknown metric or a
+     * non-vector column — a user-supplied string can never become a SQL operator.
+     */
+    private vectorOperator;
+    /**
+     * Validate and bind a query vector as a single `$n::vector` parameter.
+     * Every element must be a finite number (no NaN / Infinity / strings) so a
+     * malformed array can never produce a broken `::vector` literal, and the array
+     * is NEVER string-interpolated into the SQL text. Returns the `$n::vector`
+     * placeholder string.
+     */
+    private pushVectorParam;
     /** Parse a flat row: convert snake_case to camelCase + Date coercion */
+    /**
+     * Returns the set of camelCase field names for a table's date columns,
+     * derived once from `meta.dateColumns` (snake_case) via reverseColumnMap and
+     * memoized per table. Used so nested relation rows (camelCase keys) coerce
+     * dates the same way top-level rows do.
+     */
+    private getCamelDateFields;
     private parseRow;
     /** Parse a row that may contain JSON nested relation columns */
     private parseNestedRow;
@@ -509,6 +579,27 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *          evaluates to a JSON array (hasMany) or a JSON object (belongsTo/hasOne).
      */
     private buildRelationSubquery;
+    /**
+     * Build the json_agg subquery for a `manyToMany` relation, JOINing the target
+     * table through a junction (join) table.
+     *
+     * Shape (no LIMIT/ORDER):
+     * ```sql
+     * SELECT COALESCE(json_agg(json_build_object(...)), '[]'::json)
+     * FROM <target> <talias>
+     * JOIN <junction> <jalias> ON <jalias>.<targetKey> = <talias>.<targetPK>
+     * WHERE <jalias>.<sourceKey> = <parentRef>.<referenceKey>
+     * ```
+     *
+     * With LIMIT/ORDER, the rows are wrapped in an inner subquery so the LIMIT
+     * applies BEFORE aggregation (identical strategy to hasMany).
+     *
+     * Cardinality is always 'many' → empty-array fallback, never NULL.
+     *
+     * IMPORTANT: every `params.push` here MUST be mirrored, in the same order, in
+     * {@link collectRelationSubqueryParams} or pipeline batching will desync.
+     */
+    private buildManyToManySubquery;
     /**
      * Get the Postgres type for a column (e.g. 'jsonb', 'text', '_int4').
      * Used to detect JSONB/array columns for specialized operators.
@@ -530,6 +621,18 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Supports: has, hasEvery, hasSome, isEmpty.
      */
     private buildArrayFilterClauses;
+    /**
+     * Build SQL clauses for a pgvector distance WHERE filter:
+     *
+     *   `"embedding" <-> $1::vector < $2`
+     *
+     * The query vector is bound as a `$n::vector` param (never interpolated), the
+     * metric maps to an operator via a fixed allow-list, and each comparison
+     * threshold (`lt`/`lte`/`gt`/`gte`) is its own bound param. Emits one clause
+     * per supplied comparator (all ANDed). Param push order matches
+     * {@link collectVectorFilterParams}.
+     */
+    private buildVectorFilterClauses;
     /**
      * Build SQL clause for full-text search using to_tsvector @@ to_tsquery.
      * The config name is validated to prevent injection (only alphanumeric + underscore).