uql-orm 0.66.0 → 0.67.0

package/dist/dialect/jsonSql.d.ts

@@ -36,36 +36,15 @@ export declare function jsonElemExists(from: string, conditions: readonly string
  */
 export type JsonAccessMode = 'json' | 'numeric' | 'text';
 /**
- * How a JSON scalar has to be compared against `value` (or, for `$in`/`$nin`, against every element
- * of it). Extracting a JSON value yields *text*, which loses the type, so each operand type is
- * compared in the representation every engine agrees on:
- * - `numeric` - cast the accessor. Keeps `1` equal to a stored `1.0`, which strict JSON equality
- *   would not, and satisfies drivers that send typed parameters (`text = integer` otherwise).
- * - `json` - compare the JSON value against a JSON-encoded parameter. No cast recovers a boolean
- *   portably: PostgreSQL raises `text = boolean` and MySQL matches `'true'` against `1`.
- * - `text` - compare as extracted, which is also what the string operators need.
- *
- * Mixed operand types fall back to `text`, since one comparison cannot be two shapes at once.
+ * How a JSON scalar compares against `value`, since extraction yields text: `numeric` casts (so `1` equals
+ * `1.0`), `json` compares JSON values (the only portable boolean), and `text` compares as extracted,
+ * also for mixed operands.
  */
 export declare function jsonCompareMode(value: unknown): JsonAccessMode;
-/**
- * The mode a *declared* type asks for: {@link jsonCompareMode}'s twin, reading the type instead of an
- * operand. An index over a JSON path is only reachable by a comparison that extracts it the same way,
- * so the two have to answer alike - which is why they are one pair over one vocabulary.
- *
- * Reads the type through `util/field.util`'s own classifier, which the dialects already carry:
- * resolving it through `schema/canonicalType` instead pulls that whole module into every consumer
- * bundle.
- */
+/** The mode a declared type asks for, {@link jsonCompareMode}'s twin: an index over a path is reached only by a comparison extracting it alike. */
 export declare function jsonTypeMode(type: FieldType): JsonAccessMode;
 /**
- * Whether the operator reads the JSON *value* instead of its text form. The array operators always
- * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in
- * a way no cast recovers portably: PostgreSQL raises `operator does not exist: text = boolean`,
- * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `JSON_EXTRACT` yields
- * `1`. Comparing the JSON value against a JSON-encoded parameter is exact on every dialect.
- *
- * Numbers stay on the text accessor with a numeric cast, which keeps `1` equal to `1.0` - JSON
- * equality would not.
+ * Whether the operator reads the JSON value rather than its text: the array operators, and equality
+ * against a boolean, which no cast recovers portably from text.
  */
 export declare function isJsonbOp(op: string, value?: unknown): boolean;

package/dist/dialect/jsonSql.js

@@ -53,16 +53,9 @@ export function jsonElemExists(from, conditions) {
     return `EXISTS (SELECT 1 FROM ${from}${where})`;
 }
 /**
- * How a JSON scalar has to be compared against `value` (or, for `$in`/`$nin`, against every element
- * of it). Extracting a JSON value yields *text*, which loses the type, so each operand type is
- * compared in the representation every engine agrees on:
- * - `numeric` - cast the accessor. Keeps `1` equal to a stored `1.0`, which strict JSON equality
- *   would not, and satisfies drivers that send typed parameters (`text = integer` otherwise).
- * - `json` - compare the JSON value against a JSON-encoded parameter. No cast recovers a boolean
- *   portably: PostgreSQL raises `text = boolean` and MySQL matches `'true'` against `1`.
- * - `text` - compare as extracted, which is also what the string operators need.
- *
- * Mixed operand types fall back to `text`, since one comparison cannot be two shapes at once.
+ * How a JSON scalar compares against `value`, since extraction yields text: `numeric` casts (so `1` equals
+ * `1.0`), `json` compares JSON values (the only portable boolean), and `text` compares as extracted,
+ * also for mixed operands.
  */
 export function jsonCompareMode(value) {
     const operands = Array.isArray(value) ? value : [value];
@@ -74,15 +67,7 @@ export function jsonCompareMode(value) {
     }
     return operands.every((operand) => typeof operand === 'number') ? 'numeric' : 'text';
 }
-/**
- * The mode a *declared* type asks for: {@link jsonCompareMode}'s twin, reading the type instead of an
- * operand. An index over a JSON path is only reachable by a comparison that extracts it the same way,
- * so the two have to answer alike - which is why they are one pair over one vocabulary.
- *
- * Reads the type through `util/field.util`'s own classifier, which the dialects already carry:
- * resolving it through `schema/canonicalType` instead pulls that whole module into every consumer
- * bundle.
- */
+/** The mode a declared type asks for, {@link jsonCompareMode}'s twin: an index over a path is reached only by a comparison extracting it alike. */
 export function jsonTypeMode(type) {
     const family = columnFamily(type);
     if (family === 'numeric') {
@@ -91,14 +76,8 @@ export function jsonTypeMode(type) {
     return family === 'boolean' ? 'json' : 'text';
 }
 /**
- * Whether the operator reads the JSON *value* instead of its text form. The array operators always
- * do. Equality joins them for boolean operands, because extracting JSON as text loses the type in
- * a way no cast recovers portably: PostgreSQL raises `operator does not exist: text = boolean`,
- * MySQL compares `'true'` to `1` and silently matches nothing, and SQLite's `JSON_EXTRACT` yields
- * `1`. Comparing the JSON value against a JSON-encoded parameter is exact on every dialect.
- *
- * Numbers stay on the text accessor with a numeric cast, which keeps `1` equal to `1.0` - JSON
- * equality would not.
+ * Whether the operator reads the JSON value rather than its text: the array operators, and equality
+ * against a boolean, which no cast recovers portably from text.
  */
 export function isJsonbOp(op, value) {
     if (op === '$all' || op === '$size' || op === '$elemMatch') {

package/dist/dialect/mergeSqlDialect.d.ts

@@ -1,33 +1,15 @@
 import type { QueryConflictPaths, QueryContext, QueryPager, Type } from '../type/index.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
-/**
- * Shared SQL between SQL Server and Oracle: the two engines that spell paging and upsert the way the
- * standard does, where the Postgres and MySQL families each predate it.
- *
- * A family base rather than a pair of knobs, the way {@link PgLikeSqlDialect} and
- * {@link MysqlLikeSqlDialect} already are - `pager` and `upsert` are both plain overrides, so nothing
- * in the core has to learn that a second spelling exists.
- */
+/** What SQL Server and Oracle share: paging and upsert spelled as the standard does. */
 export declare abstract class MergeSqlDialect extends AbstractSqlDialect {
     readonly escapeIdChar = "\"";
-    /**
-     * `OFFSET ... ROWS FETCH NEXT ... ROWS ONLY`, and an `ORDER BY` where the statement has none.
-     *
-     * SQL Server refuses to page an unordered statement. A constant `ORDER BY` costs one clause the
-     * optimizer discards and keeps `$limit` and `$skip` meaning the same thing here as everywhere
-     * else; the alternative, `TOP (n)` in the select list, needs a second hook and still leaves a
-     * `$skip` with no `$sort` unanswerable.
-     */
+    /** `OFFSET ... FETCH NEXT`, and a constant `ORDER BY` where there is none, since SQL Server refuses to page without one. */
     pager(ctx: QueryContext, opts: QueryPager & {
         $distinct?: boolean;
     }, sorted?: boolean): void;
     /**
-     * `MERGE`, which both engines take in place of the `ON CONFLICT`/`ON DUPLICATE KEY` the other
-     * families have. The rows go in as a `VALUES` row source rather than an `INSERT`, built by
-     * {@link AbstractSqlDialect.insertShape} so both shapes apply `onInsert` defaults identically.
-     *
-     * Every value binds before the assignments are rendered, so a `?`-placeholder engine needs none of
-     * the scratch-context reordering `ON CONFLICT` does - the source is read positionally, in order.
+     * `MERGE`, its rows a `VALUES` source built by {@link AbstractSqlDialect.insertShape}. Every value binds
+     * before the assignments, so `?` placeholders read in order.
      */
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
     /** `<target>.<col> = <source>.<col>` for every conflict key, which is what makes a row "the same". */

package/dist/dialect/mergeSqlDialect.js

@@ -2,24 +2,10 @@ import { getMeta } from '../entity/index.js';
 import { assertNonNegativeInteger, getKeys } from '../util/index.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { UPSERT_SOURCE_ALIAS } from './aliases.js';
-/**
- * Shared SQL between SQL Server and Oracle: the two engines that spell paging and upsert the way the
- * standard does, where the Postgres and MySQL families each predate it.
- *
- * A family base rather than a pair of knobs, the way {@link PgLikeSqlDialect} and
- * {@link MysqlLikeSqlDialect} already are - `pager` and `upsert` are both plain overrides, so nothing
- * in the core has to learn that a second spelling exists.
- */
+/** What SQL Server and Oracle share: paging and upsert spelled as the standard does. */
 export class MergeSqlDialect extends AbstractSqlDialect {
     escapeIdChar = '"';
-    /**
-     * `OFFSET ... ROWS FETCH NEXT ... ROWS ONLY`, and an `ORDER BY` where the statement has none.
-     *
-     * SQL Server refuses to page an unordered statement. A constant `ORDER BY` costs one clause the
-     * optimizer discards and keeps `$limit` and `$skip` meaning the same thing here as everywhere
-     * else; the alternative, `TOP (n)` in the select list, needs a second hook and still leaves a
-     * `$skip` with no `$sort` unanswerable.
-     */
+    /** `OFFSET ... FETCH NEXT`, and a constant `ORDER BY` where there is none, since SQL Server refuses to page without one. */
     pager(ctx, opts, sorted = false) {
         if (opts.$limit === undefined && opts.$skip === undefined) {
             return;
@@ -35,12 +21,8 @@ export class MergeSqlDialect extends AbstractSqlDialect {
         }
     }
     /**
-     * `MERGE`, which both engines take in place of the `ON CONFLICT`/`ON DUPLICATE KEY` the other
-     * families have. The rows go in as a `VALUES` row source rather than an `INSERT`, built by
-     * {@link AbstractSqlDialect.insertShape} so both shapes apply `onInsert` defaults identically.
-     *
-     * Every value binds before the assignments are rendered, so a `?`-placeholder engine needs none of
-     * the scratch-context reordering `ON CONFLICT` does - the source is read positionally, in order.
+     * `MERGE`, its rows a `VALUES` source built by {@link AbstractSqlDialect.insertShape}. Every value binds
+     * before the assignments, so `?` placeholders read in order.
      */
     upsert(ctx, entity, conflictPaths, payload, extraReturning = '') {
         const meta = getMeta(entity);

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -1,18 +1,10 @@
-import type { DialectFeatures, EntityMeta, FieldOptions, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, Type } from '../type/index.js';
+import type { EntityMeta, FieldOptions, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, QuerySizeComparisonOps, QueryTextSearchOptions, SqlDialectFeatures, Type } from '../type/index.js';
 import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from './abstractSqlDialect.js';
-/**
- * Shared JSON-array / JSON-object operator implementation between MySQL and MariaDB.
- *
- * Both dialects support the MySQL-compatible JSON functions/operators used by:
- * - `$size` (JSON_LENGTH)
- * - `$all` (JSON_CONTAINS)
- * - `$elemMatch` (JSON_TABLE, or fast JSON_CONTAINS for the simple case)
- * - the update operators `$set` (JSON_SET), `$unset` (JSON_REMOVE), `$push` (JSON_MERGE_PRESERVE)
- *   and `$pull` (JSON_REPLACE over JSON_TABLE)
- */
+/** What the MySQL-family engines have. */
+export declare const MYSQL_FEATURES: SqlDialectFeatures;
+/** What MySQL and MariaDB share, their JSON functions above all: `JSON_LENGTH`, `JSON_CONTAINS`, `JSON_TABLE`, `JSON_SET`. */
 export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
-    /** Default {@link DialectFeatures} for MySQL-compatible SQL dialects. */
-    protected readonly featureDefaults: DialectFeatures;
+    readonly features: SqlDialectFeatures;
     /**
      * `information_schema` keeps InnoDB's own row estimate, which is live enough to answer before
      * anything has been analyzed. `DATABASE()` where the entity names no schema, so the estimate comes
@@ -21,13 +13,7 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     estimatedCount<E>(ctx: QueryContext, entity: Type<E>): void;
     /** `OFFSET` is only legal after a `LIMIT` here, so a bare `$skip` needs one. */
     pager(ctx: QueryContext, opts: QueryPager): void;
-    /**
-     * Signed, though MySQL's own convention is `UNSIGNED`: a foreign key column takes its type from the
-     * key it points at, resolved through the *canonical* type, which has no way to know this string said
-     * `UNSIGNED`. The two then disagree and the engine refuses the constraint - the same trap knex hit
-     * (knex#6129) and MikroORM still carries (mikro-orm#5485). Signed is also the portable half: no
-     * other engine here has unsigned integers, so an `@Id` means one range everywhere.
-     */
+    /** A signed key, so a foreign key taking its type from it matches, as MySQL refuses an `UNSIGNED` mismatch. */
     readonly autoIncrementSuffix = "AUTO_INCREMENT";
     readonly escapeIdChar = "`";
     readonly tableOptions = "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4";
@@ -42,19 +28,11 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     readonly booleanLiteral = "integer";
     readonly insertIdSource: InsertIdSource;
     /**
-     * `INSERT ... ON DUPLICATE KEY UPDATE`, and `INSERT IGNORE` when every non-conflict column is itself a
-     * conflict key so there is nothing to assign. Neither form takes a conflict target: MySQL picks the
-     * unique index for you.
-     *
-     * The update assignments are built into their own context and pushed afterwards, since they read
-     * the inserted row rather than binding, and any value they *do* bind (an `onUpdate` field absent from
-     * the payload) has to land after the insert's for a `?`-placeholder driver.
+     * `INSERT ... ON DUPLICATE KEY UPDATE`, or `INSERT IGNORE` where there is nothing to assign. The
+     * assignments bind after the insert, where a `?` reads them.
      */
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
-    /**
-     * Appended to both branches above. Empty on MySQL, which has no `INSERT ... RETURNING`; MariaDB
-     * 10.5+ has it, and used to restate this whole method just to add it.
-     */
+    /** Appended to both branches above: empty on MySQL, which has no `INSERT ... RETURNING`. */
     protected upsertReturning<E>(_meta: EntityMeta<E>): string;
     /**
      * The alias the inserted row is given after the values list, and read back by the assignments.
@@ -132,12 +110,8 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     protected jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
     protected jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
     /**
-     * `JSON_TABLE` needs its columns declared upfront, so the object form maps `fields` to columns.
-     * The scalar form's column is `JSON`, not `TEXT`, when `asJson` - `TEXT PATH '$'` silently reads
-     * a compound (array/object) element as `NULL`, since MySQL doesn't coerce those to text; only a
-     * true scalar element survives that coercion. A nested `$elemMatch` (each element being an array
-     * that itself gets exploded) always requests `asJson`, so this is what makes that case reach the
-     * inner elements at all rather than finding nothing.
+     * `JSON_TABLE` with its columns declared up front. A scalar element reads as `JSON` where `asJson`,
+     * since `TEXT` reads a nested array as `NULL`.
      */
     protected jsonElemFrom(jsonField: string, fields: readonly string[], alias: string, asJson?: boolean): string;
     protected jsonElemRef(alias: string, field?: string, asJson?: boolean): string;

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -11,34 +11,36 @@ import { aggregatesRelations } from './queryJoins.js';
  * and the largest `group_concat_max_len` either engine takes.
  */
 const MAX_LIMIT = BigInt.asUintN(64, -1n);
-/**
- * Shared JSON-array / JSON-object operator implementation between MySQL and MariaDB.
- *
- * Both dialects support the MySQL-compatible JSON functions/operators used by:
- * - `$size` (JSON_LENGTH)
- * - `$all` (JSON_CONTAINS)
- * - `$elemMatch` (JSON_TABLE, or fast JSON_CONTAINS for the simple case)
- * - the update operators `$set` (JSON_SET), `$unset` (JSON_REMOVE), `$push` (JSON_MERGE_PRESERVE)
- *   and `$pull` (JSON_REPLACE over JSON_TABLE)
- */
+/** What the MySQL-family engines have. */
+export const MYSQL_FEATURES = {
+    ifNotExists: true,
+    indexIfNotExists: false,
+    schemas: true,
+    dropTableCascade: false,
+    foreignKeyAlter: true,
+    primaryKeyAlter: true,
+    generatedColumnAdd: true,
+    commentSyntax: 'inline',
+    vectorIndexRequiresNotNull: false,
+    vectorSupportsLength: false,
+    supportsTimestamptz: false,
+    stringSizing: 'varchar',
+    supportsUnsigned: true,
+    serverSideCursors: false,
+    rowLocks: true,
+    rowLockWithWindow: true,
+    rowLockOf: true,
+    orderedUpsertReturning: true,
+    orderedJsonAggregates: true,
+    partialJsonContainment: true,
+    typedJsonElements: false,
+    narrowVectorTypes: false,
+    vectorTuningNeedsTransaction: false,
+    serialDeclaresPrimaryKey: false,
+};
+/** What MySQL and MariaDB share, their JSON functions above all: `JSON_LENGTH`, `JSON_CONTAINS`, `JSON_TABLE`, `JSON_SET`. */
 export class MysqlLikeSqlDialect extends AbstractSqlDialect {
-    /** Default {@link DialectFeatures} for MySQL-compatible SQL dialects. */
-    featureDefaults = {
-        ifNotExists: true,
-        indexIfNotExists: false,
-        schemas: true,
-        dropTableCascade: false,
-        foreignKeyAlter: true,
-        primaryKeyAlter: true,
-        generatedColumnAdd: true,
-        commentSyntax: 'inline',
-        vectorIndexRequiresNotNull: false,
-        vectorSupportsLength: false,
-        supportsTimestamptz: false,
-        stringSizing: 'varchar',
-        supportsUnsigned: true,
-        serverSideCursors: false,
-    };
+    features = MYSQL_FEATURES;
     /**
      * `information_schema` keeps InnoDB's own row estimate, which is live enough to answer before
      * anything has been analyzed. `DATABASE()` where the entity names no schema, so the estimate comes
@@ -64,13 +66,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         }
         super.pager(ctx, opts);
     }
-    /**
-     * Signed, though MySQL's own convention is `UNSIGNED`: a foreign key column takes its type from the
-     * key it points at, resolved through the *canonical* type, which has no way to know this string said
-     * `UNSIGNED`. The two then disagree and the engine refuses the constraint - the same trap knex hit
-     * (knex#6129) and MikroORM still carries (mikro-orm#5485). Signed is also the portable half: no
-     * other engine here has unsigned integers, so an `@Id` means one range everywhere.
-     */
+    /** A signed key, so a foreign key taking its type from it matches, as MySQL refuses an `UNSIGNED` mismatch. */
     autoIncrementSuffix = 'AUTO_INCREMENT';
     escapeIdChar = '`';
     tableOptions = 'ENGINE=InnoDB DEFAULT CHARSET=utf8mb4';
@@ -87,13 +83,8 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     // `innodb_autoinc_lock_mode` caveat on `buildUpdateResult` in `util/sql.util.ts`.
     insertIdSource = 'firstId';
     /**
-     * `INSERT ... ON DUPLICATE KEY UPDATE`, and `INSERT IGNORE` when every non-conflict column is itself a
-     * conflict key so there is nothing to assign. Neither form takes a conflict target: MySQL picks the
-     * unique index for you.
-     *
-     * The update assignments are built into their own context and pushed afterwards, since they read
-     * the inserted row rather than binding, and any value they *do* bind (an `onUpdate` field absent from
-     * the payload) has to land after the insert's for a `?`-placeholder driver.
+     * `INSERT ... ON DUPLICATE KEY UPDATE`, or `INSERT IGNORE` where there is nothing to assign. The
+     * assignments bind after the insert, where a `?` reads them.
      */
     upsert(ctx, entity, conflictPaths, payload) {
         const meta = getMeta(entity);
@@ -113,10 +104,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         ctx.append(returning);
         ctx.pushValue(...insertCtx.values);
     }
-    /**
-     * Appended to both branches above. Empty on MySQL, which has no `INSERT ... RETURNING`; MariaDB
-     * 10.5+ has it, and used to restate this whole method just to add it.
-     */
+    /** Appended to both branches above: empty on MySQL, which has no `INSERT ... RETURNING`. */
     upsertReturning(_meta) {
         return '';
     }
@@ -250,12 +238,8 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`JSON_LENGTH(${jsonField})`), value));
     }
     /**
-     * `JSON_TABLE` needs its columns declared upfront, so the object form maps `fields` to columns.
-     * The scalar form's column is `JSON`, not `TEXT`, when `asJson` - `TEXT PATH '$'` silently reads
-     * a compound (array/object) element as `NULL`, since MySQL doesn't coerce those to text; only a
-     * true scalar element survives that coercion. A nested `$elemMatch` (each element being an array
-     * that itself gets exploded) always requests `asJson`, so this is what makes that case reach the
-     * inner elements at all rather than finding nothing.
+     * `JSON_TABLE` with its columns declared up front. A scalar element reads as `JSON` where `asJson`,
+     * since `TEXT` reads a nested array as `NULL`.
      */
     jsonElemFrom(jsonField, fields, alias, asJson = false) {
         const columns = fields.length

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -1,27 +1,18 @@
-import { type DialectFeatures, type DriverCapabilities, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type Type } from '../type/index.js';
+import { type DriverCapabilities, type EntityMeta, type FieldOptions, type JsonColumnType, type Query, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type SqlDialectFeatures, type Type } from '../type/index.js';
 import type { DialectOptions } from './abstractDialect.js';
 import { AbstractSqlDialect, type RelationRows } from './abstractSqlDialect.js';
 /** A Postgres-wire dialect's options: the base's, and how its driver binds a parameter. */
 export type PgLikeDialectOptions = DialectOptions & {
     readonly driverCapabilities?: Partial<DriverCapabilities>;
 };
-/**
- * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
- * CockroachDB (wire- and SQL-compatible for everything below, including `TO_TSVECTOR`/`TO_TSQUERY`
- * and pgvector's `<=>`/`<->`/`<#>` distance operators, which CockroachDB implements natively).
- * `xmax`-based upsert `created` detection is Postgres-only (CockroachDB has no `xmax`/`ctid`) and
- * stays in {@link PostgresDialect}, along with the `vectorExtension`/`vectorIndexStyle` values that
- * differ (Postgres needs `CREATE EXTENSION vector` and pgvector's `USING ivfflat/hnsw` index
- * syntax; CockroachDB's vector type and `CREATE VECTOR INDEX` syntax are both native).
- */
+/** What the Postgres-wire engines have. */
+export declare const PG_FEATURES: SqlDialectFeatures;
+/** What Postgres and CockroachDB share: JSONB, full-text search, pgvector's operators, and the upsert. */
 export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     /** How the driver binds a parameter: node-`pg`'s, unless the pool states its own. */
     readonly driverCapabilities: DriverCapabilities;
     constructor(options?: PgLikeDialectOptions);
-    /** `FOR UPDATE` and a window function cannot share a statement here. See the base declaration. */
-    readonly supportsWindowWithRowLock = false;
-    /** Default {@link DialectFeatures} for Postgres-wire dialects. */
-    protected readonly featureDefaults: DialectFeatures;
+    readonly features: SqlDialectFeatures;
     readonly escapeIdChar = "\"";
     readonly autoIncrementSuffix: string;
     readonly tableOptions = "";
@@ -53,8 +44,6 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
         readonly op: string;
         readonly opsSuffix: string;
     }>;
-    /** `SET LOCAL` applies to the enclosing transaction and to nothing at all without one. */
-    readonly vectorTuningNeedsTransaction = true;
     /**
      * The GUC each pgvector index type reads for "how much of the index to explore". They are not the
      * same quantity - `ef_search` is a candidate-list size, `probes` a count of lists - which is why
@@ -62,11 +51,8 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      */
     private static readonly ANN_SETTINGS;
     /**
-     * `SET LOCAL hnsw.ef_search = N`, plus `hnsw.iterative_scan` when the query also filters by
-     * distance. Without iterative scan, HNSW returns its candidate list and the predicate then removes
-     * from it, so a `$near` can hand back fewer rows than qualify - the recall bug `$candidates`
-     * exists to answer. `strict_order`, never `relaxed_order`: the latter returns rows out of distance
-     * order, which would quietly contradict the `ORDER BY` the caller asked for.
+     * `SET LOCAL hnsw.ef_search = N`, plus `hnsw.iterative_scan = strict_order` where the query also filters
+     * by distance, which would otherwise drop rows the candidate list missed.
      */
     vectorTuningStatements<E>(meta: EntityMeta<E>, q: Query<E>): readonly string[];
     normalizeValue(value: unknown): unknown;
@@ -89,7 +75,7 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     protected readonly caseInsensitiveMatch = "ilike";
     protected get neOp(): string;
     /** One array parameter, which a context that inlines values has none of: it lists them instead. */
-    protected formatIn(ctx: QueryContext, values: unknown[], negate: boolean): string;
+    protected formatIn(ctx: QueryContext, operand: string, values: unknown[], negate: boolean): string;
     protected numericCast(expr: string): string;
     protected appendJsonValue(ctx: QueryContext, value: unknown, type: JsonColumnType): void;
     /**

package/dist/dialect/pgLikeSqlDialect.js

@@ -7,15 +7,34 @@ import { BYTES_PREFIX } from './hydrateColumn.js';
 import { jsonSetTarget } from './jsonSql.js';
 import { PG_VECTOR_METRICS } from './pgVectorMetrics.js';
 import { resolveVectorCast, toSparsevecLiteral } from './vectorCast.js';
-/**
- * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
- * CockroachDB (wire- and SQL-compatible for everything below, including `TO_TSVECTOR`/`TO_TSQUERY`
- * and pgvector's `<=>`/`<->`/`<#>` distance operators, which CockroachDB implements natively).
- * `xmax`-based upsert `created` detection is Postgres-only (CockroachDB has no `xmax`/`ctid`) and
- * stays in {@link PostgresDialect}, along with the `vectorExtension`/`vectorIndexStyle` values that
- * differ (Postgres needs `CREATE EXTENSION vector` and pgvector's `USING ivfflat/hnsw` index
- * syntax; CockroachDB's vector type and `CREATE VECTOR INDEX` syntax are both native).
- */
+/** What the Postgres-wire engines have. */
+export const PG_FEATURES = {
+    ifNotExists: true,
+    indexIfNotExists: true,
+    schemas: true,
+    dropTableCascade: true,
+    foreignKeyAlter: true,
+    primaryKeyAlter: true,
+    generatedColumnAdd: true,
+    commentSyntax: 'statement',
+    vectorIndexRequiresNotNull: false,
+    vectorSupportsLength: true,
+    supportsTimestamptz: true,
+    stringSizing: 'bounded-text',
+    supportsUnsigned: false,
+    serverSideCursors: true,
+    rowLocks: true,
+    rowLockWithWindow: false,
+    rowLockOf: true,
+    orderedUpsertReturning: true,
+    orderedJsonAggregates: true,
+    partialJsonContainment: true,
+    typedJsonElements: false,
+    narrowVectorTypes: false,
+    vectorTuningNeedsTransaction: true,
+    serialDeclaresPrimaryKey: false,
+};
+/** What Postgres and CockroachDB share: JSONB, full-text search, pgvector's operators, and the upsert. */
 export class PgLikeSqlDialect extends AbstractSqlDialect {
     /** How the driver binds a parameter: node-`pg`'s, unless the pool states its own. */
     driverCapabilities;
@@ -23,25 +42,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         super(options);
         this.driverCapabilities = { nativeArrays: true, explicitJsonCast: false, ...options.driverCapabilities };
     }
-    /** `FOR UPDATE` and a window function cannot share a statement here. See the base declaration. */
-    supportsWindowWithRowLock = false;
-    /** Default {@link DialectFeatures} for Postgres-wire dialects. */
-    featureDefaults = {
-        ifNotExists: true,
-        indexIfNotExists: true,
-        schemas: true,
-        dropTableCascade: true,
-        foreignKeyAlter: true,
-        primaryKeyAlter: true,
-        generatedColumnAdd: true,
-        commentSyntax: 'statement',
-        vectorIndexRequiresNotNull: false,
-        vectorSupportsLength: true,
-        supportsTimestamptz: true,
-        stringSizing: 'bounded-text',
-        supportsUnsigned: false,
-        serverSideCursors: true,
-    };
+    features = PG_FEATURES;
     escapeIdChar = '"';
     // Shared default for both dialects. CockroachDB docs flag sequential PKs as a hotspotting risk
     // under heavy concurrent insert load (writes concentrate on one range); this default still beats
@@ -80,8 +81,6 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     insertIdSource = 'returning';
     maxBindValues = 65535;
     vectorMetrics = PG_VECTOR_METRICS;
-    /** `SET LOCAL` applies to the enclosing transaction and to nothing at all without one. */
-    vectorTuningNeedsTransaction = true;
     /**
      * The GUC each pgvector index type reads for "how much of the index to explore". They are not the
      * same quantity - `ef_search` is a candidate-list size, `probes` a count of lists - which is why
@@ -92,11 +91,8 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         ['ivfflat', 'ivfflat.probes'],
     ]);
     /**
-     * `SET LOCAL hnsw.ef_search = N`, plus `hnsw.iterative_scan` when the query also filters by
-     * distance. Without iterative scan, HNSW returns its candidate list and the predicate then removes
-     * from it, so a `$near` can hand back fewer rows than qualify - the recall bug `$candidates`
-     * exists to answer. `strict_order`, never `relaxed_order`: the latter returns rows out of distance
-     * order, which would quietly contradict the `ORDER BY` the caller asked for.
+     * `SET LOCAL hnsw.ef_search = N`, plus `hnsw.iterative_scan = strict_order` where the query also filters
+     * by distance, which would otherwise drop rows the candidate list missed.
      */
     vectorTuningStatements(meta, q) {
         const indexType = this.tunedVectorIndex(meta, q)?.type;
@@ -162,11 +158,12 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         return 'IS DISTINCT FROM';
     }
     /** One array parameter, which a context that inlines values has none of: it lists them instead. */
-    formatIn(ctx, values, negate) {
-        if (values.length === 0 || ctx.inlineValues)
-            return super.formatIn(ctx, values, negate);
+    formatIn(ctx, operand, values, negate) {
+        if (!values.length || ctx.inlineValues) {
+            return super.formatIn(ctx, operand, values, negate);
+        }
         const ph = this.addValue(ctx, values);
-        return negate ? ` <> ALL(${ph})` : ` = ANY(${ph})`;
+        return negate ? `${operand} <> ALL(${ph})` : `${operand} = ANY(${ph})`;
     }
     numericCast(expr) {
         return `(${expr})::numeric`;

package/dist/dialect/queryContext.d.ts

@@ -1,11 +1,5 @@
 import type { QueryContext, SqlQueryDialect } from '../type/index.js';
-/**
- * SqlQueryContext is an implementation of the QueryContext interface specifically for SQL-based dialects.
- * It follows the "Accumulator" or "Builder" pattern to construct SQL queries and their corresponding parameters.
- *
- * This pattern solves the problem of building complex SQL strings while safely managing parameterized values,
- * preventing SQL injection and handling dialect-specific parameter placeholders (e.g., '?' for MySQL, '$n' for PostgreSQL).
- */
+/** A SQL statement being built: its text, and the values it binds, placeholders numbered by the dialect. */
 export declare class SqlQueryContext implements QueryContext {
     readonly dialect: SqlQueryDialect;
     private readonly statement?;
@@ -14,14 +8,8 @@ export declare class SqlQueryContext implements QueryContext {
     private readonly params;
     private readonly tableAliases;
     /**
-     * @param dialect The SQL dialect used to determine how values should be formatted as placeholders.
-     * @param params An existing values array to bind into instead of a fresh one - shared by a
-     * fragment context built via {@link AbstractSqlDialect.buildFragment}, so a bound value's
-     * placeholder is numbered correctly against the real query from the moment it's added, rather
-     * than needing to be reconciled after the fact.
-     * @param statement The context this one renders a fragment of, which owns the claimed aliases: a
-     * fragment is part of one statement, so its aliases have to be unique across the whole of it.
-     * @param inlineValues See {@link QueryContext.inlineValues}; a fragment takes its statement's.
+     * `params` and `statement` are a fragment's parent's, so a value numbers against the whole statement and
+     * an alias is unique across it; a fragment inlines values where its statement does.
      */
     constructor(dialect: SqlQueryDialect, params?: unknown[], statement?: SqlQueryContext | undefined, inlineValues?: boolean);
     createFragment(): QueryContext;
@@ -37,13 +25,7 @@ export declare class SqlQueryContext implements QueryContext {
      * where this context inlines values.
      */
     addValue(value: unknown): this;
-    /**
-     * Pushes values to the parameters list without appending placeholders to the SQL.
-     * This is useful when the placeholder is already present in the SQL string or handled elsewhere.
-     *
-     * @param values The values to be added to the parameters.
-     * @returns The current context instance for method chaining.
-     */
+    /** Binds values whose placeholders the SQL already carries. */
     pushValue(...values: unknown[]): this;
     claimAlias(name: string, parent?: string): string;
     /**