turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/query/where.d.ts

@@ -0,0 +1,548 @@
+/**
+ * turbine-orm: WHERE-clause compilation (extracted from builder.ts)
+ *
+ * The whole WHERE web: the top-level build/collect/fingerprint trio, the
+ * table-scoped trio for relation-filter EXISTS sub-wheres and relation
+ * `with`-clause wheres, the leaf JSON/array/vector/text-search clause builders,
+ * operator-clause + column-reference compilation, and the client-level
+ * global-filter helpers. All functions take a {@link BuilderCtx} as their first
+ * argument: the privacy-preserving view of the owning {@link QueryInterface}
+ * instance (built once in its constructor) exposing exactly the class-resident
+ * primitives this module needs. See builder.ts for the thin delegating methods.
+ */
+import type pg from 'pg';
+import type { Dialect } from '../dialect.js';
+import { ValidationError } from '../errors.js';
+import type { RelationDef, SchemaMetadata, TableMetadata } from '../schema.js';
+import type { ArrayFilter, ColumnRef, GlobalFilters, JsonFilter, JsonPathOrderBy, SkipGlobalFilters, TextSearchFilter, VectorFilter, WhereClause, WhereOperator } from './types.js';
+import { type SqlCacheEntry } from './utils.js';
+import { type WhereHost, type WhereRecord } from './where-compile.js';
+/**
+ * The privacy-preserving view of a {@link QueryInterface} instance passed as the
+ * first argument to every function in this module. Built once as an object
+ * literal in the QueryInterface constructor (mirroring the `whereHost`
+ * precedent). Data fields are live references to the instance's own state;
+ * `currentSkip` is a live getter (it is reassigned per `build*` call). The
+ * method members are the class-resident primitives these functions still need.
+ */
+export interface BuilderCtx {
+    readonly dialect: Dialect;
+    readonly table: string;
+    readonly schema: SchemaMetadata;
+    readonly tableMeta: TableMetadata;
+    readonly whereHost: WhereHost;
+    readonly globalFilters?: GlobalFilters;
+    readonly scopedHostCache: Map<string, WhereHost>;
+    readonly columnPgTypeMap: Map<string, string>;
+    readonly columnArrayTypeMap: Map<string, string>;
+    /**
+     * The client's `utcTimestamps` setting, when the owning QueryInterface
+     * supplies it. Optional so an older ctx literal (and every test that builds
+     * one by hand) keeps the default. `false` opts out of BOTH the UTC read
+     * parsing and the symmetric UTC bind rewriting for zone-less `date` /
+     * `timestamp` columns (see `coerceWriteValue` in writes.ts).
+     */
+    readonly utcTimestamps?: boolean;
+    readonly crossSchemaTypeColumns: Set<string>;
+    /**
+     * The active query's `skipGlobalFilters` opt-out. A live getter/setter over
+     * the owning instance's field: `build*` methods set it at their top, and the
+     * synchronous SQL-build + param-collect tree reads it deep inside
+     * `resolveGlobalFilter`.
+     */
+    currentSkip: SkipGlobalFilters | undefined;
+    q(name: string): string;
+    p(index: number): string;
+    inParam(values: unknown): unknown;
+    inClause(expr: string, paramRef: string, negated: boolean): string;
+    toColumn(field: string): string;
+    castAgg(expr: string, target: 'int' | 'float'): string;
+    parseRow(row: Record<string, unknown>, table: string): Record<string, unknown>;
+    nullsSuffix(nulls: 'first' | 'last' | undefined): string;
+    isRelationOrderByValue(value: unknown): boolean;
+    resolveOrderByColumn(table: string, meta: TableMetadata, key: string): string;
+    buildJsonPathOrderEntry(table: string, meta: TableMetadata, field: string, spec: JsonPathOrderBy, prefix: string, params?: unknown[]): string;
+    toSqlColumn(field: string): string;
+    mutationInsertId(result: pg.QueryResult): unknown;
+    acquireSql(cacheKey: string, build: (params: unknown[]) => string): SqlCacheEntry;
+    crossCheckCache(op: string, cacheKey: string, entry: SqlCacheEntry, build: (params: unknown[]) => string, collectedParams: unknown[]): void;
+    readonly jsonEncoding: 'object' | 'positional';
+    readonly camelDateFieldCache: Map<string, Set<string>>;
+    limitOneClause(): string;
+    buildPagination(limitPh: string | undefined, offsetPh: string | undefined, hasOrderBy: boolean): string;
+    paginationRef(value: unknown, params: unknown[], arg?: string): string;
+    /**
+     * Coerce + validate a LIMIT/OFFSET argument (non-negative safe integer).
+     * The cache-hit param-collect paths call it directly, so a warmed template
+     * can never bind an unvalidated NaN (which Postgres reads as "no limit").
+     */
+    paginationValue(value: unknown, arg?: string): number;
+}
+/**
+ * Column-reference resolution context threaded into
+ * {@link QueryInterface.buildOperatorClauses} / `collectOperatorParams`: the
+ * table whose fields a `{ col }` reference may name, plus the SQL prefix
+ * (`''` top-level, `"table".` in relation-filter subqueries, `t0.` against a
+ * relation alias) the compiled identifier must carry so it resolves in the
+ * same scope as the operator's own column.
+ */
+interface ColumnRefContext {
+    meta: TableMetadata;
+    table: string;
+    prefix: string;
+    /**
+     * The operator's own RAW (unquoted) column name. The `column` argument the
+     * operator builders receive is already quoted on the build side and raw on
+     * the collect side, so the temporal bind rewrite resolves the column's type
+     * from here instead — the one value both sides pass identically.
+     */
+    rawColumn: string;
+}
+/**
+ * A table-scoped WHERE compilation context for a sub-where that is NOT the
+ * top-level `this.tableMeta` clause. Both relation-filter `EXISTS` sub-wheres
+ * (correlated against the bare target table, `"target".col`) and relation
+ * `with`-clause `where` filters (against a per-subquery alias, `t0.col`) compile
+ * an arbitrary target table's where against a column qualifier. They differ ONLY
+ * in that qualifier, the correlation parent handed to `buildRelationFilter`, and
+ * the unknown-column error wording — so a single scoped build/collect/fingerprint
+ * trio, driven by the SAME canonical {@link walkWhere} the top level uses, serves
+ * both. See `buildScopedWhere` / `collectScopedWhereParams` / `fingerprintScopedWhere`.
+ */
+interface WhereScope {
+    /** The target table's metadata (column map, relations, types). */
+    meta: TableMetadata;
+    /** The target table name (used for host binding + error messages). */
+    table: string;
+    /** SQL prefix before `q(col)` — `"target".` for EXISTS sub-wheres, `t0.` for aliases. */
+    qualifier: string;
+    /** The `parentTable` correlation argument for nested `buildRelationFilter` calls. */
+    relationParent: string;
+    /** {@link WhereHost} bound to `meta`, so {@link walkWhere} enumerates this scope's keys. */
+    host: WhereHost;
+    /** Typed error for an unknown column reference (wording differs per scope). */
+    unknownColumn: (field: string) => ValidationError;
+}
+/**
+ * Produce a value-invariant fingerprint of a where clause.
+ * Same keys + same operator shapes + same combinator structure => same string.
+ * Different values (e.g. id=1 vs id=999) => identical fingerprint.
+ *
+ * @internal Exposed as package-private for testing via class access.
+ */
+export declare function fingerprintWhere(qi: BuilderCtx, where: Record<string, unknown>): string;
+/**
+ * Fingerprint the present branches of a normalized relation filter, in the
+ * fixed order some→every→none→is→isNot. A `null` branch tokenizes as
+ * `<branch>(null)`; a present branch recurses through
+ * {@link fingerprintRelFilter} so the FULL inner shape is captured (two
+ * different sub-wheres must never collide on one cached SQL text).
+ */
+export declare function fingerprintRelationParts(qi: BuilderCtx, relDef: RelationDef, filterObj: WhereRecord): string[];
+/**
+ * Fingerprint a relation filter sub-where for some/every/none. Thin wrapper
+ * over the unified {@link fingerprintScopedWhere}. When the target table is
+ * unknown, an empty-relations host makes every key scalar (matching the old
+ * `meta?.relations` short-circuit).
+ */
+export declare function fingerprintRelFilter(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>): string;
+/**
+ * Walk a where clause and push ONLY values into `params`, in the EXACT same
+ * order that `buildWhereClause` pushes them. Used on cache hit to fill params
+ * without rebuilding SQL.
+ *
+ * @internal Exposed as package-private for testing.
+ */
+export declare function collectWhereParams(qi: BuilderCtx, where: Record<string, unknown>, params: unknown[]): void;
+/**
+ * Push a scalar WHERE value's params, mirroring {@link buildScalarClause}'s
+ * emissions exactly. Both resolve the value's shape via the shared
+ * {@link classifyScalarForSql}, so a cache HIT binds each `$N` to the value
+ * the cached SQL expects. A JSON/array-shaped value on a non-JSON/array column
+ * (`jsonThrow`/`arrayThrow`) falls through to the equality path here, the
+ * same fall-through the collect path has always taken (the build path's typed
+ * error there is only reachable on a MISS, before anything is cached).
+ */
+export declare function collectScalarParams(qi: BuilderCtx, key: string, value: unknown, params: unknown[]): void;
+/**
+ * Param-collect mirror of {@link buildRelationFilter} for one relation-filter
+ * object (`{ some/every/none/is/isNot }`, already normalized). Pushes, per
+ * present branch and in the canonical order some→none→every→is→isNot, the
+ * branch's sub-where params THEN the target table's global-filter params —
+ * exactly the order buildRelationFilter emits. When no global filter applies
+ * the gf calls are no-ops, so this stays byte-identical to the pre-0.28 path.
+ * Shared by every collect site that mirrors buildRelationFilter
+ * (collectWhereParams, collectRelFilterParams, collectAliasWhereParams).
+ */
+export declare function collectRelationFilterParams(qi: BuilderCtx, relDef: RelationDef, filterObj: Record<string, unknown>, params: unknown[]): void;
+export declare function collectRelFilterParams(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>, params: unknown[]): void;
+/**
+ * Collect params from operator clauses. Mirrors buildOperatorClauses:
+ * {@link ColumnRef} values compile into the SQL text, so they push NOTHING -
+ * but they re-run the same validation (unknown ref / insensitive mode) so a
+ * warmed cache can never skip a check the build path enforces.
+ */
+export declare function collectOperatorParams(qi: BuilderCtx, column: string, op: WhereOperator, params: unknown[], refCtx?: ColumnRefContext): void;
+/**
+ * Collect params from JSON filter. Mirrors buildJsonFilterClauses exactly:
+ * the `path` is bound at most once (its placeholder is shared by every
+ * extraction clause), then equals/contains/hasKey values, then the range
+ * comparison values in {@link JSON_RANGE_OPERATORS} order.
+ */
+export declare function collectJsonFilterParams(qi: BuilderCtx, filter: JsonFilter, params: unknown[], column: string): void;
+/** Collect params from array filter. Mirrors buildArrayFilterClauses. */
+export declare function collectArrayFilterParams(qi: BuilderCtx, filter: ArrayFilter, params: unknown[]): void;
+/**
+ * Collect params for a vector distance WHERE filter. Mirrors
+ * {@link buildVectorFilterClauses}: the `$n::vector` query vector first, then
+ * the comparison threshold(s).
+ */
+export declare function collectVectorFilterParams(qi: BuilderCtx, field: string, rawColumn: string, filter: VectorFilter, params: unknown[]): void;
+/** Build WHERE clause from a where object (supports operators, NULL, OR) */
+export declare function buildWhere<T extends object>(qi: BuilderCtx, where: WhereClause<T>): {
+    sql: string;
+    params: unknown[];
+};
+/**
+ * Resolve the configured global filter for `table`, evaluating a function
+ * filter, honoring the active query's `skipGlobalFilters`. Returns `null` when
+ * no filter applies, the query opted out, or the filter is empty.
+ */
+export declare function resolveGlobalFilter(qi: BuilderCtx, table: string, skip?: SkipGlobalFilters | undefined): Record<string, unknown> | null;
+/**
+ * AND-merge this table's resolved global filter into a user `where`. Either
+ * side may be absent. When no filter applies the user where is returned by
+ * reference, so fingerprints/SQL stay byte-identical to the pre-0.28 path.
+ */
+export declare function mergeGlobalFilter(qi: BuilderCtx, userWhere: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/**
+ * SQL clause for `targetTable`'s global filter rendered against `alias`
+ * (relation subqueries, `_count`, relation `orderBy`). Pushes its params to
+ * `params`; returns `''` when no filter applies. Mirror:
+ * {@link collectTargetGlobalFilterAlias}.
+ */
+export declare function targetGlobalFilterAlias(qi: BuilderCtx, targetTable: string, alias: string, params: unknown[]): string;
+/** Param-collect mirror of {@link targetGlobalFilterAlias}. */
+export declare function collectTargetGlobalFilterAlias(qi: BuilderCtx, targetTable: string, params: unknown[]): void;
+/**
+ * SQL clause for `targetTable`'s global filter rendered against the bare
+ * (unaliased) table name — the form used inside relation-filter `EXISTS`
+ * subqueries. Pushes its params; `''` when none. Mirror:
+ * {@link collectTargetGlobalFilterExists}.
+ */
+export declare function targetGlobalFilterExists(qi: BuilderCtx, targetTable: string, params: unknown[]): string;
+/** Param-collect mirror of {@link targetGlobalFilterExists}. */
+export declare function collectTargetGlobalFilterExists(qi: BuilderCtx, targetTable: string, params: unknown[]): void;
+/**
+ * Value-invariant SQL-cache-key segment for the active global-filter
+ * environment. Relation-subquery / relation-filter / `_count` / relation-
+ * `orderBy` global filters are rendered at build time but their SHAPE is not
+ * otherwise in the where/with fingerprint, so this segment guards the cache:
+ * two different filter shapes never collide on one cached SQL text, while two
+ * function-filter results of the SAME shape (differing only in values) share
+ * the entry and bind their own params. Empty (`''`) when no filter applies, so
+ * cache keys stay byte-identical when the feature is unused.
+ */
+export declare function globalFilterCacheSegment(qi: BuilderCtx): string;
+/**
+ * True when the USER-supplied `where` compiles to no predicate (`{}`,
+ * `{ id: undefined }`, `{ OR: [{ a: undefined }] }`, …). This is the exact
+ * signal the empty-`where` guard needs — the compiled emptiness, NOT the
+ * fingerprint (which is non-empty for an all-undefined `OR`/`AND`). It ignores
+ * any configured global filter, so a global filter never lets an unguarded
+ * mass mutation through.
+ */
+export declare function userPredicateIsEmpty(qi: BuilderCtx, userWhere: Record<string, unknown>): boolean;
+export declare function assertMutationHasPredicate(qi: BuilderCtx, operation: 'update' | 'updateMany' | 'delete' | 'deleteMany', whereSql: string, allowFullTableScan: boolean | undefined): void;
+/**
+ * Build the inner WHERE expression (without the WHERE keyword).
+ * Returns null if no conditions exist.
+ * Supports: equality, operators, NULL, OR, AND, NOT, relation filters (some/every/none).
+ */
+export declare function buildWhereClause(qi: BuilderCtx, where: Record<string, unknown>, params: unknown[]): string | null;
+/**
+ * Emit the SQL clause(s) for one scalar WHERE key onto `andClauses`, pushing
+ * any params. The shape decision comes from the shared
+ * {@link classifyScalarForSql} so {@link collectScalarParams} pushes an
+ * identical param list on a cache hit. The `*Throw` branches preserve the
+ * strict-validation errors for a JSON/array operator on the wrong column type.
+ */
+export declare function buildScalarClause(qi: BuilderCtx, key: string, value: unknown, params: unknown[], andClauses: string[]): void;
+/**
+ * A {@link WhereHost} with no relations — used to fingerprint a sub-where
+ * whose target table is unknown (`schema.tables[t]` miss). `walkWhere` reads
+ * only `tableMeta.relations`, so every key falls to the scalar path, matching
+ * the pre-unification `meta?.relations` short-circuit.
+ */
+export declare function emptyRelationsHost(qi: BuilderCtx, table: string): WhereHost;
+export declare function scopedWhereHost(qi: BuilderCtx, meta: TableMetadata): WhereHost;
+/** Build the scope for a relation-filter EXISTS sub-where over the bare target table. */
+export declare function relationWhereScope(qi: BuilderCtx, targetTable: string, meta: TableMetadata): WhereScope;
+/** Build the scope for a relation `with`-clause `where` compiled against `alias`. */
+export declare function aliasWhereScope(qi: BuilderCtx, targetTable: string, meta: TableMetadata, alias: string): WhereScope;
+/**
+ * Compile a scoped sub-where to SQL. Serves BOTH the relation-filter EXISTS
+ * body ({@link buildSubWhereForRelation}) and the relation `with`-clause
+ * `where` ({@link buildAliasWhere}) — the emitted SQL is byte-identical to the
+ * former hand-mirrored walkers, since it renders the same clauses in the same
+ * ({@link walkWhere}-canonical) key order.
+ */
+export declare function buildScopedWhere(qi: BuilderCtx, scope: WhereScope, where: Record<string, unknown>, params: unknown[]): string | null;
+/**
+ * Emit the SQL clause(s) for one scalar key of a scoped sub-where. Reproduces
+ * the null / JSON / array / operator / equality fall-through both former
+ * walkers shared (relation sub-wheres and alias wheres carry no vector or
+ * text-search scalar surface, so — unlike the top-level {@link buildScalarClause}
+ * — those shapes are not special-cased here and keep their historical
+ * equality-guard behavior).
+ */
+export declare function buildScopedScalarClause(qi: BuilderCtx, scope: WhereScope, field: string, value: unknown, params: unknown[], clauses: string[]): void;
+/**
+ * Cache-hit param-collect mirror of {@link buildScopedWhere}: pushes the exact
+ * same params in the exact same order (driven by the same {@link walkWhere}),
+ * without rebuilding SQL. Serves both {@link collectRelFilterParams} and
+ * {@link collectAliasWhereParams}.
+ */
+export declare function collectScopedWhereParams(qi: BuilderCtx, scope: WhereScope, where: Record<string, unknown>, params: unknown[]): void;
+/** Param-collect mirror of {@link buildScopedScalarClause}. */
+export declare function collectScopedScalarParams(qi: BuilderCtx, scope: WhereScope, field: string, value: unknown, params: unknown[]): void;
+/**
+ * Value-invariant fingerprint of a scoped sub-where. Same canonical
+ * {@link walkWhere} as {@link fingerprintWhere}, so two shapes that compile to
+ * different SQL never collide on one cached SQL string. Serves both
+ * {@link fingerprintRelFilter} and {@link fingerprintAliasWhere}. Fingerprint
+ * bytes are process-local cache keys (never persisted), so their exact text
+ * may differ from the pre-unification walkers as long as collisions stay
+ * impossible.
+ */
+export declare function fingerprintScopedWhere(qi: BuilderCtx, host: WhereHost, where: Record<string, unknown>): string;
+/**
+ * Build relation filter SQL: WHERE EXISTS / NOT EXISTS subquery
+ * Supports: some (EXISTS), every (NOT EXISTS ... NOT), none (NOT EXISTS)
+ */
+export declare function buildRelationFilter(qi: BuilderCtx, _relName: string, relDef: RelationDef, filterObj: Record<string, unknown>, params: unknown[], parentTable?: string): string | null;
+/**
+ * Build WHERE clause conditions for a relation filter subquery.
+ * Uses the target table's column mapping to resolve field names.
+ */
+export declare function buildSubWhereForRelation(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>, params: unknown[]): string | null;
+/**
+ * Resolve a column's Postgres type from an arbitrary table's metadata
+ * (relation targets, not just `qi.table`).
+ */
+export declare function pgTypeForColumn(_qi: BuilderCtx, meta: TableMetadata, column: string): string;
+/**
+ * Rewrite a WHERE operand bound against `column` the same way the write path
+ * rewrites a `data` value ({@link coerceTemporalValue}): a JS `Date` on a
+ * `time` / `timetz` column becomes a time-of-day literal (Postgres otherwise
+ * answers `22007 invalid input syntax for type time` for the ISO timestamp the
+ * driver would send), and on a zone-less `date` / `timestamp` column it becomes
+ * the UTC-component literal, so a predicate matches the value a write of the
+ * same `Date` stored.
+ *
+ * This is a VALUE transform only — it never changes the emitted SQL — so the
+ * SQL-template cache is unaffected, and it is applied on the cache-hit
+ * param-collect path as well as the build path.
+ *
+ * `timestamptz` and every non-temporal column are returned by identity.
+ */
+export declare function coerceWhereOperand(qi: BuilderCtx, meta: TableMetadata, column: string, value: unknown): unknown;
+/**
+ * The Postgres enum type name for a column, when the schema knows one.
+ *
+ * Introspection stores each column's `udt_name` in `pgTypes` and every
+ * database enum in `schema.enums` (typname → labels); a column whose type
+ * matches an enum key needs an explicit `::"EnumName"` cast on its write
+ * binds — bulk-insert forms like `UNNEST($1::text[])` otherwise type the
+ * value as text and Postgres refuses the implicit text→enum coercion
+ * ("column X is of type Y but expression is of type text").
+ *
+ * Postgres-only by construction: gated on the active dialect being
+ * `postgresql` AND on `schema.enums` having entries (only PG introspection
+ * produces them — `defineSchema` and the other engines leave it empty), so
+ * SQLite/MySQL/MSSQL/PowDB output is byte-identical.
+ */
+export declare function enumTypeForColumn(qi: BuilderCtx, column: string): string | null;
+/**
+ * `::"EnumName"` cast suffix for a write-bind placeholder on an enum
+ * column; `''` for every other column, so non-enum SQL stays byte-identical.
+ * The type name is an introspected identifier and is quoted via the dialect.
+ */
+export declare function enumCastSuffix(qi: BuilderCtx, column: string): string;
+/**
+ * Equality-fallthrough guard shared by every SQL-build path AND every
+ * cache-hit param-collect path. A plain object literal that matched no known
+ * filter shape on a non-JSON column is almost always a misspelled operator
+ * (`startWith` for `startsWith`); binding it as `col = $1` silently returns
+ * wrong rows. Class instances (Buffer for bytea, Decimal wrappers, ...) are
+ * legitimate bind values and pass through, as do objects on json/jsonb
+ * columns (object equality).
+ */
+export declare function assertBindableEqualityValue(qi: BuilderCtx, rawColumn: string, value: unknown, columnPgType: string, table: string): void;
+/**
+ * Build the user-supplied `where` filter of a relation `with` clause against
+ * the relation's table alias. Supports the same scalar surface as the
+ * top-level WHERE builder — equality, IS NULL, operator objects (incl.
+ * `mode: 'insensitive'`), and OR/AND/NOT combinators. Unknown operator
+ * objects throw via {@link assertBindableEqualityValue}.
+ *
+ * Param push order MUST mirror {@link collectAliasWhereParams} exactly, or
+ * cache hits and pipeline batching will desync.
+ */
+export declare function buildAliasWhere(qi: BuilderCtx, targetTable: string, targetMeta: TableMetadata, alias: string, where: Record<string, unknown>, params: unknown[]): string | null;
+/** Mirrors {@link buildAliasWhere} param-push order for the cache-hit collect path. */
+export declare function collectAliasWhereParams(qi: BuilderCtx, targetTable: string, targetMeta: TableMetadata, where: Record<string, unknown>, params: unknown[]): void;
+/**
+ * Value-invariant, shape-aware fingerprint for a relation `with` clause's
+ * `where` filter. Must distinguish every SQL shape {@link buildAliasWhere}
+ * can emit — equality vs null vs operator sets vs combinators — or two
+ * differently-shaped wheres would share one cached SQL string.
+ */
+export declare function fingerprintAliasWhere(qi: BuilderCtx, where: Record<string, unknown>, targetTable?: string): string;
+/**
+ * Validate a `{ col }` column reference against its table and return the
+ * resolved snake_case column name. Shared by the SQL-build path
+ * ({@link buildOperatorClauses}) and the cache-hit param-collect path
+ * (`collectOperatorParams`) so both always throw identically: a warmed
+ * cache can never skip the check.
+ */
+export declare function resolveColumnRef(_qi: BuilderCtx, ref: ColumnRef, ctx: ColumnRefContext, mode?: 'default' | 'insensitive'): string;
+/**
+ * Compile a `{ col }` reference to its quoted, prefix-matched SQL identifier.
+ * NO param is bound: the referenced column is part of the SQL text (and of
+ * the where fingerprint, via `fingerprintOperatorShape` in `filters.ts`).
+ */
+export declare function columnRefSql(qi: BuilderCtx, ref: ColumnRef, ctx: ColumnRefContext | undefined, mode?: 'default' | 'insensitive'): string;
+/**
+ * Build SQL clauses for a single operator object on a column.
+ * Each operator key becomes its own clause, all ANDed together.
+ *
+ * `equals`/`not`/`gt`/`gte`/`lt`/`lte` also accept a {@link ColumnRef}
+ * (`{ col: 'otherField' }`) which compiles to a column-to-column comparison
+ * against `refCtx`: no param bound, so `collectOperatorParams` mirrors by
+ * pushing nothing and the referenced name lives in the fingerprint.
+ */
+export declare function buildOperatorClauses(qi: BuilderCtx, column: string, op: WhereOperator, params: unknown[], refCtx?: ColumnRefContext): string[];
+/**
+ * Gate the full-text `search` filter on {@link Dialect.supportsFullTextSearch}.
+ * The clause it guards is `to_tsvector(...) @@ to_tsquery(...)`, which only
+ * PostgreSQL parses, so every other engine gets a typed
+ * {@link UnsupportedFeatureError} (E017) instead of a raw driver syntax error.
+ * Called from BOTH the build and the param-collect side (mirroring the vector
+ * gate) so the two paths can never diverge.
+ */
+export declare function requireFullTextSearch(qi: BuilderCtx): void;
+/**
+ * Gate the array filter operators (`has` / `hasEvery` / `hasSome` / `isEmpty`)
+ * on {@link Dialect.supportsArrayColumns}. They compile to PostgreSQL array
+ * operators (`= ANY(col)`, `@>`, `&&`, `cardinality(col)`) over a native array
+ * column, which no other supported engine has. Called from BOTH the build and
+ * the param-collect side.
+ */
+export declare function requireArrayColumns(qi: BuilderCtx): void;
+/**
+ * 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.
+ */
+export declare function vectorOperator(qi: BuilderCtx, field: string, rawColumn: string, metric: string): string;
+/**
+ * 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.
+ */
+export declare function pushVectorParam(qi: BuilderCtx, field: string, _rawColumn: string, to: unknown, params: unknown[]): string;
+/**
+ * Prisma-compat: a plain object on a to-one relation key —
+ * `where: { vendor: { name: { contains: 'x' } } }` — is an implicit `is`
+ * filter. Normalize it to `{ is: obj }` so all downstream handling (SQL,
+ * params, fingerprint) sees one canonical shape. To-many relations still
+ * require an explicit `some`/`every`/`none` (a bare object there is
+ * ambiguous and was never valid in Prisma either).
+ */
+export declare function normalizeRelationFilter(_qi: BuilderCtx, relDef: RelationDef, filterObj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Case-insensitive json/jsonb column-type check. Postgres reports lowercase
+ * udt_names, but SQLite/MySQL introspection surfaces the DECLARED type
+ * (e.g. `JSON`), so every JSON-feature gate compares through this predicate
+ * — build and collect sides alike, keeping the SQL-cache lockstep.
+ */
+export declare function isJsonColumnType(_qi: BuilderCtx, colType: string): boolean;
+export declare function getColumnPgType(qi: BuilderCtx, column: string): string;
+/**
+ * Get the Postgres base element type for an array column.
+ * E.g. '_text' → 'text', '_int4' → 'integer'
+ */
+export declare function getArrayElementType(_qi: BuilderCtx, pgType: string): string;
+/**
+ * Validate and enumerate the range comparisons (`gt`/`gte`/`lt`/`lte`) on a
+ * JSON filter, in the fixed {@link JSON_RANGE_OPERATORS} order. Shared by
+ * the SQL-build path ({@link buildJsonFilterClauses}) and the cache-hit
+ * param-collect path ({@link collectJsonFilterParams}) so both always agree
+ * on which params are pushed — and both throw identically for invalid
+ * shapes, so a warmed cache can never skip validation.
+ */
+export declare function jsonRangeEntries(_qi: BuilderCtx, filter: JsonFilter, column: string): {
+    sqlOp: string;
+    value: number | string;
+}[];
+/**
+ * Build SQL clauses for JSONB filter operators on a column.
+ * Supports: path, equals, contains, hasKey, gt, gte, lt, lte.
+ *
+ * The `path` param is bound at most once and its placeholder is shared by
+ * every clause that extracts it (equals + range ops), so the param list
+ * stays byte-identical to {@link collectJsonFilterParams}.
+ */
+export declare function buildJsonFilterClauses(qi: BuilderCtx, column: string, filter: JsonFilter, params: unknown[]): string[];
+/**
+ * Bind value for a JSON path parameter, encoded per dialect. PostgreSQL's
+ * `#>>` takes a `text[]` (the segments as strings — or `nativeForm` when the
+ * caller has a specific native binding, e.g. JsonFilter's raw path array).
+ * Every other engine's JSON function (`json_extract` / `JSON_EXTRACT` /
+ * `JSON_VALUE`) takes a `'$'`-rooted JSONPath STRING: binding the raw array
+ * would arrive as `'["a"]'` (the driver shims JSON.stringify non-primitive
+ * params) and fail at runtime with the engine's bad-JSON-path error. The
+ * encoded path stays a bound parameter — never spliced into SQL text — so
+ * the build/collect param mirrors stay in lockstep and injection-safe.
+ */
+export declare function jsonPathParam(qi: BuilderCtx, path: readonly (string | number)[], nativeForm?: unknown): unknown;
+/**
+ * Cast an extracted JSON path text value to a numeric type for range
+ * comparison. PostgreSQL uses `(expr)::numeric` (exact — the right way to
+ * compare JSON numbers, and `::float` would lose precision on big ints);
+ * other dialects route through {@link Dialect.castAggregate} (SQLite/MySQL/
+ * SQL Server have no `::` operator) as a float cast.
+ */
+export declare function castJsonNumeric(qi: BuilderCtx, extract: string): string;
+/**
+ * Build SQL clauses for Array filter operators on a column.
+ * Supports: has, hasEvery, hasSome, isEmpty.
+ */
+export declare function buildArrayFilterClauses(qi: BuilderCtx, column: string, filter: ArrayFilter, params: unknown[], pgType: string): string[];
+/**
+ * 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}.
+ */
+export declare function buildVectorFilterClauses(qi: BuilderCtx, field: string, rawColumn: string, filter: VectorFilter, params: unknown[]): string[];
+/**
+ * Build SQL clause for full-text search using to_tsvector @@ to_tsquery.
+ * The config name is validated to prevent injection (only alphanumeric + underscore).
+ */
+export declare function buildTextSearchClause(qi: BuilderCtx, column: string, filter: TextSearchFilter, params: unknown[]): string;
+/**
+ * Get the Postgres array type for a column (used by UNNEST in createMany).
+ * Uses pre-computed Map for O(1) lookup instead of linear scan.
+ */
+export declare function getColumnArrayType(qi: BuilderCtx, column: string): string;
+export {};