turbine-orm 0.15.0 → 0.18.0

package/dist/nested-write.js

@@ -3,8 +3,8 @@
  *
  * Tree-walking create/update that resolves relation fields in `data` into
  * batched SQL operations within a transaction. Supports create, connect,
- * connectOrCreate, disconnect, set, and delete on related records at
- * arbitrary depth (capped at 10).
+ * connectOrCreate, disconnect, set, delete, update, and upsert on related
+ * records at arbitrary depth (capped at 10).
  *
  * This module is imported by `query/builder.ts` when the `data` argument
  * of `create()` or `update()` contains relation fields. It never imports
@@ -15,7 +15,7 @@ import { CircularRelationError, RelationError, ValidationError } from './errors.
 import { normalizeKeyColumns } from './schema.js';
 const MAX_DEPTH = 10;
 const CREATE_ONLY_OPS = new Set(['create', 'connect', 'connectOrCreate']);
-const UPDATE_ONLY_OPS = new Set(['disconnect', 'set', 'delete']);
+const UPDATE_ONLY_OPS = new Set(['disconnect', 'set', 'delete', 'update', 'upsert']);
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for testing)
 // ---------------------------------------------------------------------------
@@ -93,7 +93,7 @@ function validateOps(relationName, ops, isUpdate) {
     for (const opName of Object.keys(ops)) {
         if (!CREATE_ONLY_OPS.has(opName) && !UPDATE_ONLY_OPS.has(opName)) {
             throw new ValidationError(`[turbine] Unknown nested write operation "${opName}" on relation "${relationName}". ` +
-                `Valid operations: create, connect, connectOrCreate${isUpdate ? ', disconnect, set, delete' : ''}.`);
+                `Valid operations: create, connect, connectOrCreate${isUpdate ? ', disconnect, set, delete, update, upsert' : ''}.`);
         }
         if (!isUpdate && UPDATE_ONLY_OPS.has(opName)) {
             throw new ValidationError(`[turbine] Operation "${opName}" on relation "${relationName}" is only valid inside update(), not create().`);
@@ -137,17 +137,29 @@ export async function executeNestedCreate(ctx, tableName, data, depth = 0, path
         }
         validateOps(relName, ops, false);
     }
-    // Insert the parent row
-    const parentRow = (await ctx.tx.table(tableName).create({ data: scalars }));
-    // Process each relation
+    // belongsTo relations put the foreign key on the PARENT row, so they must be
+    // resolved BEFORE the parent is inserted — otherwise a NOT NULL FK column
+    // fails on the initial INSERT. We resolve each belongsTo op (create/connect/
+    // connectOrCreate) to its referenced row and fold the FK values into the
+    // parent's own INSERT.
+    const belongsToFks = {};
+    for (const [relName, ops] of Object.entries(relations)) {
+        const rel = tableMeta.relations[relName];
+        if (rel.type === 'belongsTo') {
+            Object.assign(belongsToFks, await resolveBelongsToForCreate(ctx, rel, ops, tableName, depth, path, relName));
+        }
+    }
+    // Insert the parent row (scalars + resolved belongsTo foreign keys)
+    const parentRow = (await ctx.tx.table(tableName).create({
+        data: { ...scalars, ...belongsToFks },
+    }));
+    // Process hasMany / hasOne relations — their FK lives on the CHILD, so they
+    // need the parent row to exist first.
     for (const [relName, ops] of Object.entries(relations)) {
         const rel = tableMeta.relations[relName];
         if (rel.type === 'hasMany' || rel.type === 'hasOne') {
             await processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relName);
         }
-        else if (rel.type === 'belongsTo') {
-            await processBelongsToCreate(ctx, rel, ops, parentRow, tableName, depth, path, relName);
-        }
     }
     // Build the `with` clause for the final read to return the full tree
     const withClause = {};
@@ -216,9 +228,25 @@ export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0
             if (ops.delete !== undefined) {
                 await processDelete(ctx, rel, ops.delete);
             }
+            // update
+            if (ops.update !== undefined) {
+                await processNestedUpdate(ctx, rel, ops.update);
+            }
+            // upsert
+            if (ops.upsert !== undefined) {
+                await processNestedUpsert(ctx, rel, ops.upsert, parentRow);
+            }
         }
         else if (rel.type === 'belongsTo') {
             await processBelongsToCreate(ctx, rel, ops, parentRow, tableName, depth, path, relName);
+            // update (belongsTo — derive where from parent FK)
+            if (ops.update !== undefined) {
+                await processBelongsToUpdate(ctx, rel, ops.update, parentRow, tableName);
+            }
+            // upsert (belongsTo)
+            if (ops.upsert !== undefined) {
+                await processBelongsToUpsert(ctx, rel, ops.upsert, parentRow, tableName);
+            }
             if (ops.disconnect !== undefined) {
                 // For belongsTo disconnect, null out the FK on the parent
                 const fks = normalizeKeyColumns(rel.foreignKey);
@@ -296,6 +324,58 @@ async function processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relNa
 // ---------------------------------------------------------------------------
 // belongsTo create operations
 // ---------------------------------------------------------------------------
+/**
+ * Resolve a belongsTo relation's create/connect/connectOrCreate op to the
+ * foreign-key value(s) that belong on the PARENT row, returning them keyed by
+ * the parent's own field names so they can be merged into the parent INSERT.
+ *
+ * Used by the create path only. (The update path uses processBelongsToCreate,
+ * which UPDATEs the FK after the parent already exists.)
+ */
+async function resolveBelongsToForCreate(ctx, rel, ops, parentTable, depth, path, relName) {
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    const parentMeta = ctx.schema.tables[parentTable];
+    const relatedTable = ctx.schema.tables[rel.to];
+    let relatedRow = null;
+    if (ops.create !== undefined) {
+        const items = toArray(ops.create);
+        if (items.length > 0) {
+            relatedRow = (await executeNestedCreate(ctx, rel.to, items[0], depth + 1, [...path, relName]));
+        }
+    }
+    else if (ops.connect !== undefined) {
+        const items = toArray(ops.connect);
+        if (items.length > 0) {
+            const target = items[0];
+            relatedRow = (await ctx.tx.table(rel.to).findUnique({ where: target }));
+            if (!relatedRow) {
+                throw new ValidationError(`[turbine] connect on "${relName}": no ${rel.to} row found matching ${JSON.stringify(target)}.`);
+            }
+        }
+    }
+    else if (ops.connectOrCreate !== undefined) {
+        const items = toArray(ops.connectOrCreate);
+        if (items.length > 0) {
+            const op = items[0];
+            relatedRow = (await ctx.tx.table(rel.to).findUnique({ where: op.where }));
+            if (!relatedRow) {
+                // For belongsTo the FK lives on the parent, so the related row is
+                // created plainly (no FK injection) and we read its reference key.
+                relatedRow = (await ctx.tx.table(rel.to).create({ data: op.create }));
+            }
+        }
+    }
+    const fkScalars = {};
+    if (relatedRow) {
+        for (let i = 0; i < fks.length; i++) {
+            const fkField = parentMeta.reverseColumnMap[fks[i]] ?? fks[i];
+            const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+            fkScalars[fkField] = relatedRow[refField];
+        }
+    }
+    return fkScalars;
+}
 async function processBelongsToCreate(ctx, rel, ops, parentRow, parentTable, depth, path, relName) {
     const fks = normalizeKeyColumns(rel.foreignKey);
     const refs = normalizeKeyColumns(rel.referenceKey);
@@ -452,6 +532,80 @@ async function processSet(ctx, rel, setItems, parentRow) {
         await ctx.tx.table(rel.to).update({ where: target, data: updateData });
     }
 }
+// ---------------------------------------------------------------------------
+// update / upsert operations (update-context only)
+// ---------------------------------------------------------------------------
+async function processNestedUpdate(ctx, rel, updateArg) {
+    const items = toArray(updateArg);
+    for (const item of items) {
+        if (!item.where || !item.data) {
+            throw new ValidationError(`[turbine] Nested update on "${rel.name}" requires both "where" and "data" fields.`);
+        }
+        await ctx.tx.table(rel.to).update({ where: item.where, data: item.data });
+    }
+}
+async function processNestedUpsert(ctx, rel, upsertArg, parentRow) {
+    const items = toArray(upsertArg);
+    for (const item of items) {
+        if (!item.where || !item.create || !item.update) {
+            throw new ValidationError(`[turbine] Nested upsert on "${rel.name}" requires "where", "create", and "update" fields.`);
+        }
+        const existing = await ctx.tx.table(rel.to).findUnique({ where: item.where });
+        if (existing) {
+            await ctx.tx.table(rel.to).update({ where: item.where, data: item.update });
+        }
+        else {
+            const injected = injectForeignKey(item.create, rel, parentRow, ctx.schema);
+            await ctx.tx.table(rel.to).create({ data: injected });
+        }
+    }
+}
+async function processBelongsToUpdate(ctx, rel, updateArg, parentRow, parentTable) {
+    const item = updateArg;
+    if (!item.data) {
+        throw new ValidationError(`[turbine] Nested update on belongsTo "${rel.name}" requires a "data" field.`);
+    }
+    // Derive where from parent's FK values
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    const parentMeta = ctx.schema.tables[parentTable];
+    const relatedTable = ctx.schema.tables[rel.to];
+    const where = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = parentMeta?.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+        where[refField] = parentRow[fkField];
+    }
+    await ctx.tx.table(rel.to).update({ where, data: item.data });
+}
+async function processBelongsToUpsert(ctx, rel, upsertArg, parentRow, parentTable) {
+    const item = upsertArg;
+    if (!item.where || !item.create || !item.update) {
+        throw new ValidationError(`[turbine] Nested upsert on belongsTo "${rel.name}" requires "where", "create", and "update" fields.`);
+    }
+    const existing = await ctx.tx.table(rel.to).findUnique({ where: item.where });
+    if (existing) {
+        await ctx.tx.table(rel.to).update({ where: item.where, data: item.update });
+    }
+    else {
+        // Create the related row, then update parent's FK to point at it
+        const createdRow = (await ctx.tx.table(rel.to).create({ data: item.create }));
+        const fks = normalizeKeyColumns(rel.foreignKey);
+        const refs = normalizeKeyColumns(rel.referenceKey);
+        const parentMeta = ctx.schema.tables[parentTable];
+        const relatedTable = ctx.schema.tables[rel.to];
+        const updateData = {};
+        for (let i = 0; i < fks.length; i++) {
+            const fkField = parentMeta.reverseColumnMap[fks[i]] ?? fks[i];
+            const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+            updateData[fkField] = createdRow[refField];
+        }
+        await ctx.tx.table(parentTable).update({
+            where: pkWhere(parentMeta, parentRow),
+            data: updateData,
+        });
+    }
+}
 async function processDelete(ctx, rel, deleteArg) {
     const items = toArray(deleteArg);
     for (const target of items) {

package/dist/observe.d.ts

@@ -0,0 +1,36 @@
+/**
+ * turbine-orm — Observability module
+ *
+ * Buffers query metrics in memory (keyed by model:action per minute bucket),
+ * then periodically flushes aggregates (count, avg, p50, p95, p99, errors)
+ * to a dedicated _turbine_metrics table. Uses a separate 1-connection pool
+ * so metrics writes never contend with the application pool.
+ */
+import type { QueryEventListener } from './query/index.js';
+export interface ObserveConfig {
+    connectionString: string;
+    flushIntervalMs?: number;
+    retentionDays?: number;
+}
+export interface ObserveHandle {
+    stop(): Promise<void>;
+}
+declare function floorToMinute(date: Date): Date;
+declare function percentile(sorted: number[], p: number): number;
+export declare class ObserveEngine {
+    private readonly pool;
+    private readonly buffer;
+    private currentBucket;
+    private readonly flushIntervalMs;
+    private readonly retentionDays;
+    private timer;
+    private readonly listener;
+    private stopped;
+    constructor(config: ObserveConfig);
+    getListener(): QueryEventListener;
+    init(): Promise<void>;
+    flush(): Promise<void>;
+    stop(): Promise<void>;
+}
+export { floorToMinute, percentile };
+//# sourceMappingURL=observe.d.ts.map

package/dist/observe.js

@@ -0,0 +1,141 @@
+/**
+ * turbine-orm — Observability module
+ *
+ * Buffers query metrics in memory (keyed by model:action per minute bucket),
+ * then periodically flushes aggregates (count, avg, p50, p95, p99, errors)
+ * to a dedicated _turbine_metrics table. Uses a separate 1-connection pool
+ * so metrics writes never contend with the application pool.
+ */
+import pg from 'pg';
+function floorToMinute(date) {
+    const d = new Date(date);
+    d.setSeconds(0, 0);
+    return d;
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.ceil(p * sorted.length) - 1;
+    return sorted[Math.max(0, idx)];
+}
+// ---------------------------------------------------------------------------
+// Schema DDL
+// ---------------------------------------------------------------------------
+const SCHEMA_DDL = `
+CREATE TABLE IF NOT EXISTS _turbine_metrics (
+  id          BIGSERIAL PRIMARY KEY,
+  bucket      TIMESTAMPTZ NOT NULL,
+  model       TEXT NOT NULL,
+  action      TEXT NOT NULL,
+  count       INTEGER NOT NULL DEFAULT 0,
+  avg_ms      REAL NOT NULL DEFAULT 0,
+  p50_ms      REAL NOT NULL DEFAULT 0,
+  p95_ms      REAL NOT NULL DEFAULT 0,
+  p99_ms      REAL NOT NULL DEFAULT 0,
+  error_count INTEGER NOT NULL DEFAULT 0,
+  UNIQUE(bucket, model, action)
+);
+CREATE INDEX IF NOT EXISTS idx_turbine_metrics_bucket ON _turbine_metrics(bucket);
+`;
+const UPSERT_SQL = `
+INSERT INTO _turbine_metrics (bucket, model, action, count, avg_ms, p50_ms, p95_ms, p99_ms, error_count)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+ON CONFLICT (bucket, model, action) DO UPDATE SET
+  count = _turbine_metrics.count + EXCLUDED.count,
+  avg_ms = (_turbine_metrics.avg_ms * _turbine_metrics.count + EXCLUDED.avg_ms * EXCLUDED.count)
+           / (_turbine_metrics.count + EXCLUDED.count),
+  p50_ms = EXCLUDED.p50_ms,
+  p95_ms = EXCLUDED.p95_ms,
+  p99_ms = EXCLUDED.p99_ms,
+  error_count = _turbine_metrics.error_count + EXCLUDED.error_count
+`;
+const RETENTION_SQL = `DELETE FROM _turbine_metrics WHERE bucket < NOW() - INTERVAL '1 day' * $1`;
+// ---------------------------------------------------------------------------
+// Observe engine
+// ---------------------------------------------------------------------------
+export class ObserveEngine {
+    pool;
+    buffer = new Map();
+    currentBucket;
+    flushIntervalMs;
+    retentionDays;
+    timer;
+    listener;
+    stopped = false;
+    constructor(config) {
+        this.pool = new pg.Pool({ connectionString: config.connectionString, max: 1 });
+        this.flushIntervalMs = config.flushIntervalMs ?? 60_000;
+        this.retentionDays = config.retentionDays ?? 30;
+        this.currentBucket = floorToMinute(new Date());
+        this.listener = (event) => {
+            if (this.stopped)
+                return;
+            const nowBucket = floorToMinute(new Date());
+            if (nowBucket.getTime() !== this.currentBucket.getTime()) {
+                this.currentBucket = nowBucket;
+            }
+            const key = `${event.model}:${event.action}`;
+            let entry = this.buffer.get(key);
+            if (!entry) {
+                entry = { durations: [], errors: 0 };
+                this.buffer.set(key, entry);
+            }
+            entry.durations.push(event.duration);
+            if (event.error)
+                entry.errors++;
+        };
+    }
+    getListener() {
+        return this.listener;
+    }
+    async init() {
+        await this.pool.query(SCHEMA_DDL);
+        this.timer = setInterval(() => {
+            this.flush().catch(() => { });
+        }, this.flushIntervalMs);
+        // Unref so it doesn't keep the process alive
+        if (this.timer && typeof this.timer === 'object' && 'unref' in this.timer) {
+            this.timer.unref();
+        }
+    }
+    async flush() {
+        if (this.buffer.size === 0)
+            return;
+        const bucket = this.currentBucket;
+        const entries = new Map(this.buffer);
+        this.buffer.clear();
+        for (const [key, entry] of entries) {
+            const [model, action] = key.split(':');
+            const sorted = entry.durations.slice().sort((a, b) => a - b);
+            const count = sorted.length;
+            const avg = sorted.reduce((s, v) => s + v, 0) / count;
+            const p50 = percentile(sorted, 0.5);
+            const p95 = percentile(sorted, 0.95);
+            const p99 = percentile(sorted, 0.99);
+            try {
+                await this.pool.query(UPSERT_SQL, [bucket, model, action, count, avg, p50, p95, p99, entry.errors]);
+            }
+            catch {
+                // Fire-and-forget — never throw from flush
+            }
+        }
+        try {
+            await this.pool.query(RETENTION_SQL, [this.retentionDays]);
+        }
+        catch {
+            // Best effort
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        await this.flush();
+        await this.pool.end();
+    }
+}
+// ---------------------------------------------------------------------------
+// Exported helpers for testing
+// ---------------------------------------------------------------------------
+export { floorToMinute, percentile };
+//# sourceMappingURL=observe.js.map

package/dist/query/builder.d.ts

@@ -36,6 +36,18 @@ export type MiddlewareFn = (params: {
     action: string;
     args: Record<string, unknown>;
 }) => Promise<unknown>) => Promise<unknown>;
+/** Emitted after every query execution (success or failure). */
+export interface QueryEvent {
+    sql: string;
+    params: unknown[];
+    duration: number;
+    model: string;
+    action: string;
+    rows: number;
+    timestamp: Date;
+    error?: Error;
+}
+export type QueryEventListener = (event: QueryEvent) => void;
 /** Options passed from TurbineClient to QueryInterface */
 export interface QueryInterfaceOptions {
     /** Default LIMIT applied to findMany() when no limit is specified */
@@ -69,6 +81,8 @@ export interface QueryInterfaceOptions {
     dialect?: Dialect;
     /** @internal Set by TransactionClient — signals that this QI runs inside an active transaction. */
     _txScoped?: boolean;
+    /** @internal Callback from TurbineClient for query event emission. */
+    _onQuery?: (event: QueryEvent) => void;
 }
 export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
@@ -100,10 +114,20 @@ 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. */
     private readonly options?;
+    /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
+    private currentAction;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
     /** Quote an identifier through the active SQL dialect. */
     private q;
@@ -133,6 +157,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * exactly once per table without bleeding state between assertions.
      */
     resetUnlimitedWarnings(): void;
+    private emitQueryEvent;
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
@@ -234,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>>;
     /**
@@ -294,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.
@@ -351,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;
@@ -492,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.
@@ -513,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).