uql-orm 0.51.0 → 0.52.0

package/README.md

@@ -50,7 +50,7 @@ The query is just JSON: build it dynamically, store it, diff it, or send it from
 
 - **Serializable queries (JSON), not method chains.** Plain JSON in, typed rows out. No DSL to learn.
 - **Type-safe to the leaf, nothing to generate.** Every key is checked against your entity, down into populated relations and [JSON/JSONB](https://uql-orm.dev/querying/json) dot-paths, so `$like` on a numeric column is a compile error. Entities are plain classes on the standard TC39 decorators: no `.prisma` file, no generated client, no `reflect-metadata`, no `experimentalDecorators`.
-- **One API, everywhere it runs.** PostgreSQL, PGlite, CockroachDB, MySQL, MariaDB, SQLite, Turso, libSQL, Neon, Cloudflare D1, Bun's native SQL, and even MongoDB. The same code on Node 24+, Bun, Deno, [Cloudflare Workers](https://uql-orm.dev/cloudflare-d1), [AWS Lambda and Vercel](https://uql-orm.dev/serverless), and [the browser](https://uql-orm.dev/browser), with no native binaries on the `fetch`-based drivers.
+- **One API, everywhere it runs.** PostgreSQL, PGlite, CockroachDB, MySQL, MariaDB, MSSQL, SQLite, Turso, libSQL, Neon, Cloudflare D1, Bun's native SQL, and even MongoDB. The same code on Node 24+, Bun, Deno, [Cloudflare Workers](https://uql-orm.dev/cloudflare-d1), [AWS Lambda and Vercel](https://uql-orm.dev/serverless), and [the browser](https://uql-orm.dev/browser), with no native binaries on the `fetch`-based drivers.
 - **Relations without N+1.** [`$populate`](https://uql-orm.dev/querying/relations) loads a to-many with one query for all parents, not one per parent. Nothing is lazy, so nothing fires behind your back in a serializer.
 - **Migrations you read before they run.** Edit an entity, run `uql-migrate generate:entities`, review the SQL in the PR like any other file. [`drift:check`](https://uql-orm.dev/migrations) catches a database that no longer matches.
 - **Raw SQL when you want it.** [`raw()`](https://uql-orm.dev/querying/raw-sql) fits anywhere in a query, [computed fields](https://uql-orm.dev/entities/computed-fields) are expressions you can filter on, and a migration can be plain SQL.

package/dist/bunSql/bunSql.util.d.ts

@@ -1,25 +1,48 @@
-import type { ReservedSQL, SQL } from 'bun';
-import type { PrimaryKey, RawRow, SqlDialectName } from '../type/index.js';
+import type { SQL } from 'bun';
+import type { PrimaryKey, RawRow } from '../type/index.js';
 export type BunSqlResult<T = RawRow> = T[] & {
     count?: number;
     affectedRows?: number;
     lastInsertRowid?: PrimaryKey;
 };
-export declare function getAffectedRows(res: BunSqlResult): number;
-export declare function isReservedConnection(conn: unknown): conn is ReservedSQL;
-export declare function isPoolableDialect(dialectName: SqlDialectName): boolean;
 /**
- * Robustly infers the UQL SqlDialect from a Bun SQL.Options object.
+ * The connection a {@link BunSqlQuerier} holds. `ReservedSQL` satisfies it as it is; the SQLite
+ * adapter, which has no reservation, is given the pool's own handle with an inert `release`.
  */
-export declare function inferDialectName(config: SQL.Options): SqlDialectName;
+export type BunSqlConn = Pick<SQL, 'unsafe'> & {
+    release(): void;
+};
+/**
+ * The engines `bun:sql` can drive. Its own union rather than {@link SqlDialectName}: every other
+ * engine uql supports reaches it through a dedicated pool, and keeping this one total means Bun
+ * gaining an adapter is a compile error here until the dialect is named.
+ */
+export type BunSqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb' | 'sqlite';
+/**
+ * Rows a statement read or wrote, from whichever field this adapter fills: Postgres, CockroachDB and
+ * SQLite report `count` and leave `affectedRows` null, MySQL and MariaDB the other way around - and
+ * `count` is 0 on a MySQL write, so the two are read in that order rather than coalesced.
+ *
+ * `undefined` when the header carries neither, which leaves the returned rows to answer for it -
+ * `buildUpdateResult` already falls back to their count, and it is the only one that should.
+ */
+export declare function getAffectedRows(res: BunSqlResult): number | undefined;
 /**
  * Normalizes SQL.Options into a structure that Bun's SQL engine expects for a given dialect.
  * Crucially handles 'filename' mapping for SQLite and alias resolution for Cockroach/MariaDB.
  */
-export declare function normalizeBunOpts(config: SQL.Options, dialectName: SqlDialectName): SQL.Options;
+export declare function normalizeBunOpts(config: SQL.Options, dialectName: BunSqlDialectName): SQL.Options;
+/**
+ * Robustly infers the UQL SqlDialect from a Bun SQL.Options object.
+ */
+export declare function inferDialectName(config: SQL.Options): BunSqlDialectName;
 /**
- * Normalizes Bun result rows into plain JavaScript objects and coerces BigInts to numbers.
- * This ensures compatibility with UQL's expected return types and reliable JSON serialization.
+ * Coerces the BigInts Bun returns (`bigint: true`, set by {@link normalizeBunOpts}) back to numbers.
+ *
+ * The `bun:sql` counterpart of `postgres/pgNumericTypes.ts`, and at the driver for the same reason:
+ * `type: Number` maps to BIGINT, and everything crosses this decode exactly once - entity reads,
+ * `RETURNING id`, counts, raw SQL - while hydration only ever sees entity reads. Exact to 2^53, which
+ * covers any auto-increment id.
  */
 export declare function normalizeRows<T>(res: BunSqlResult<T>): T[];
 /**

package/dist/bunSql/bunSql.util.js

@@ -1,46 +1,14 @@
-export function getAffectedRows(res) {
-    if (Array.isArray(res) && res.length) {
-        return res.length;
-    }
-    return res.affectedRows || res.count || 0;
-}
-export function isReservedConnection(conn) {
-    return !!(conn && typeof conn.release === 'function');
-}
-export function isPoolableDialect(dialectName) {
-    return dialectName !== 'sqlite';
-}
 /**
- * Robustly infers the UQL SqlDialect from a Bun SQL.Options object.
+ * Rows a statement read or wrote, from whichever field this adapter fills: Postgres, CockroachDB and
+ * SQLite report `count` and leave `affectedRows` null, MySQL and MariaDB the other way around - and
+ * `count` is 0 on a MySQL write, so the two are read in that order rather than coalesced.
+ *
+ * `undefined` when the header carries neither, which leaves the returned rows to answer for it -
+ * `buildUpdateResult` already falls back to their count, and it is the only one that should.
  */
-export function inferDialectName(config) {
-    if (config.filename)
-        return 'sqlite';
-    const opts = config;
-    if (opts.url) {
-        const urlStr = opts.url.toString();
-        if (urlStr === ':memory:' || urlStr.endsWith('.db') || urlStr.endsWith('.sqlite')) {
-            return 'sqlite';
-        }
-        const scheme = urlStr.split(':')[0];
-        const dialect = DialectMap[scheme];
-        if (dialect)
-            return dialect;
-    }
-    if (opts.adapter)
-        return opts.adapter;
-    return 'postgres';
+export function getAffectedRows(res) {
+    return res.affectedRows || res.count || undefined;
 }
-const DialectMap = {
-    postgres: 'postgres',
-    postgresql: 'postgres',
-    mysql: 'mysql',
-    mysql2: 'mysql',
-    mariadb: 'mariadb',
-    sqlite: 'sqlite',
-    sqlite3: 'sqlite',
-    cockroachdb: 'cockroachdb',
-};
 /**
  * Normalizes SQL.Options into a structure that Bun's SQL engine expects for a given dialect.
  * Crucially handles 'filename' mapping for SQLite and alias resolution for Cockroach/MariaDB.
@@ -71,8 +39,55 @@ export function normalizeBunOpts(config, dialectName) {
     return opts;
 }
 /**
- * Normalizes Bun result rows into plain JavaScript objects and coerces BigInts to numbers.
- * This ensures compatibility with UQL's expected return types and reliable JSON serialization.
+ * Robustly infers the UQL SqlDialect from a Bun SQL.Options object.
+ */
+export function inferDialectName(config) {
+    if (config.filename)
+        return 'sqlite';
+    const opts = config;
+    if (opts.url) {
+        const urlStr = opts.url.toString();
+        if (urlStr === ':memory:' || urlStr.endsWith('.db') || urlStr.endsWith('.sqlite')) {
+            return 'sqlite';
+        }
+        const scheme = urlStr.split(':')[0] ?? '';
+        const elsewhere = ElsewhereMap[scheme];
+        if (elsewhere) {
+            throw new TypeError(`Bun SQL has no ${elsewhere} driver; use the dedicated uql-orm/${elsewhere} pool`);
+        }
+        const dialect = DialectMap[scheme];
+        if (dialect)
+            return dialect;
+    }
+    // Every Bun adapter name is a key here, so the same map answers both questions.
+    return (opts.adapter && DialectMap[opts.adapter]) || 'postgres';
+}
+const DialectMap = {
+    postgres: 'postgres',
+    postgresql: 'postgres',
+    mysql: 'mysql',
+    mysql2: 'mysql',
+    mariadb: 'mariadb',
+    sqlite: 'sqlite',
+    sqlite3: 'sqlite',
+    cockroachdb: 'cockroachdb',
+};
+/**
+ * Engines uql drives elsewhere but Bun cannot dial. Named rather than left out: Bun's `SQL` falls
+ * back to Postgres for any scheme it does not know, so an unlisted `mssql://` would have connected
+ * as Postgres and failed on the first statement instead of on the pool.
+ */
+const ElsewhereMap = {
+    mssql: 'mssql',
+    sqlserver: 'mssql',
+};
+/**
+ * Coerces the BigInts Bun returns (`bigint: true`, set by {@link normalizeBunOpts}) back to numbers.
+ *
+ * The `bun:sql` counterpart of `postgres/pgNumericTypes.ts`, and at the driver for the same reason:
+ * `type: Number` maps to BIGINT, and everything crosses this decode exactly once - entity reads,
+ * `RETURNING id`, counts, raw SQL - while hydration only ever sees entity reads. Exact to 2^53, which
+ * covers any auto-increment id.
  */
 export function normalizeRows(res) {
     const rows = [];

package/dist/bunSql/bunSqlQuerier.d.ts

@@ -1,20 +1,25 @@
-import type { ReservedSQL, SQL } from 'bun';
+import type { SQL } from 'bun';
 import type { AbstractSqlDialect } from '../dialect/index.js';
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import type { ExtraOptions } from '../type/index.js';
+import { type BunSqlConn } from './bunSql.util.js';
 /**
  * Querier for `bun:sql`, Bun's built-in driver for Postgres, MySQL, MariaDB, CockroachDB and SQLite.
- *
- * @remarks Deliberately does not override `internalStream`, which every other SQL driver here does:
- * Bun's `SQL.Query` is a `Promise` with no cursor or async-iterator API, so `findManyStream` falls back
- * to the base class buffering the whole result, as `PgliteQuerier` does for the same reason.
  */
-export declare class BunSqlQuerier extends AbstractPoolQuerier<ReservedSQL> {
+export declare class BunSqlQuerier extends AbstractPoolQuerier<BunSqlConn> {
     readonly sql: SQL;
     readonly extra?: ExtraOptions | undefined;
-    constructor(sql: SQL, dialect: AbstractSqlDialect, connFactory: () => Promise<ReservedSQL>, extra?: ExtraOptions | undefined);
+    constructor(sql: SQL, dialect: AbstractSqlDialect, connFactory: () => Promise<BunSqlConn>, extra?: ExtraOptions | undefined);
     internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
+    /**
+     * A server-side cursor where the engine has one, the base class's buffering where it does not.
+     *
+     * Bun's `SQL.Query` is a `Promise` with no cursor or async-iterator API
+     * ([oven-sh/bun#17181](https://github.com/oven-sh/bun/issues/17181)), so the rows have to be paged
+     * in SQL instead - which the Postgres wire family can do and MySQL and SQLite cannot.
+     */
+    protected internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, any>;
     private execute;
-    protected releaseConn(conn: ReservedSQL): Promise<void>;
+    protected releaseConn(conn: BunSqlConn): Promise<void>;
 }

package/dist/bunSql/bunSqlQuerier.js

@@ -1,11 +1,8 @@
+import { streamViaCursor } from '../postgres/pgCursorStream.js';
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
-import { getAffectedRows, getInsertId, isReservedConnection, normalizeRows } from './bunSql.util.js';
+import { getAffectedRows, getInsertId, normalizeRows } from './bunSql.util.js';
 /**
  * Querier for `bun:sql`, Bun's built-in driver for Postgres, MySQL, MariaDB, CockroachDB and SQLite.
- *
- * @remarks Deliberately does not override `internalStream`, which every other SQL driver here does:
- * Bun's `SQL.Query` is a `Promise` with no cursor or async-iterator API, so `findManyStream` falls back
- * to the base class buffering the whole result, as `PgliteQuerier` does for the same reason.
  */
 export class BunSqlQuerier extends AbstractPoolQuerier {
     sql;
@@ -30,14 +27,26 @@ export class BunSqlQuerier extends AbstractPoolQuerier {
             upsertStatus: res.affectedRows,
         });
     }
+    /**
+     * A server-side cursor where the engine has one, the base class's buffering where it does not.
+     *
+     * Bun's `SQL.Query` is a `Promise` with no cursor or async-iterator API
+     * ([oven-sh/bun#17181](https://github.com/oven-sh/bun/issues/17181)), so the rows have to be paged
+     * in SQL instead - which the Postgres wire family can do and MySQL and SQLite cannot.
+     */
+    async *internalStream(query, values) {
+        if (!this.dialect.features.serverSideCursors) {
+            yield* super.internalStream(query, values);
+            return;
+        }
+        yield* streamViaCursor((sql, params) => this.internalAll(sql, params), query, values, this.hasOpenTransaction);
+    }
     async execute(query, values) {
         // Safe: UQL parameters are strictly bound. .unsafe() correctly bypasses Bun's tagged template
         // literal parsing requirement so we can execute our dynamically compiled AST strings natively.
         return this.getConn().unsafe(query, values);
     }
     async releaseConn(conn) {
-        if (isReservedConnection(conn)) {
-            await conn.release();
-        }
+        conn.release();
     }
 }

package/dist/bunSql/bunSqlQuerierPool.d.ts

@@ -1,12 +1,13 @@
 import { SQL } from 'bun';
 import type { AbstractSqlDialect } from '../dialect/abstractSqlDialect.js';
 import { AbstractSqlQuerierPool } from '../querier/index.js';
-import type { ExtraOptions, SqlDialectName, SqlPoolCompat } from '../type/index.js';
+import type { ExtraOptions, SqlPoolCompat } from '../type/index.js';
+import { type BunSqlDialectName } from './bunSql.util.js';
 import { BunSqlQuerier } from './bunSqlQuerier.js';
 export declare class BunSqlQuerierPool extends AbstractSqlQuerierPool<BunSqlQuerier, AbstractSqlDialect> {
     readonly config: SQL.Options;
     readonly sql: SQL;
-    readonly sqlDialectName: SqlDialectName;
+    readonly sqlDialectName: BunSqlDialectName;
     private foreignKeysOn?;
     constructor(config: SQL.Options, extra?: ExtraOptions);
     /**
@@ -15,5 +16,12 @@ export declare class BunSqlQuerierPool extends AbstractSqlQuerierPool<BunSqlQuer
      */
     get pool(): SqlPoolCompat;
     getQuerier(): Promise<BunSqlQuerier>;
+    /**
+     * Bun's SQLite adapter does not support connection reservation (it's unpooled), and leaves
+     * `foreign_keys` off as `bun:sqlite` does, so without the pragma the constraints uql emits in its
+     * own DDL are decorative. One connection means one pragma, issued on the first acquisition, and a
+     * `release` that does nothing: the handle is the pool's, and outlives every querier over it.
+     */
+    private acquire;
     end(): Promise<void>;
 }

package/dist/bunSql/bunSqlQuerierPool.js

@@ -1,19 +1,28 @@
 import { SQL } from 'bun';
+import { CockroachDialect } from '../cockroachdb/cockroachDialect.js';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { MariaDialect } from '../maria/mariaDialect.js';
 import { MySqlDialect } from '../mysql/mysqlDialect.js';
+import { PostgresDialect } from '../postgres/postgresDialect.js';
+import { POSTGRES_WIRE_DRIVER_CAPABILITIES } from '../postgres/postgresWireDriverCapabilities.js';
 import { AbstractSqlQuerierPool } from '../querier/index.js';
-import { getAffectedRows, inferDialectName, isPoolableDialect, normalizeBunOpts, normalizeRows, } from './bunSql.util.js';
-import { BunSqlCockroachDialect } from './bunSqlCockroachDialect.js';
-import { BunSqlPostgresDialect } from './bunSqlPostgresDialect.js';
+import { SqliteDialect } from '../sqlite/sqliteDialect.js';
+import { getAffectedRows, inferDialectName, normalizeBunOpts, normalizeRows, } from './bunSql.util.js';
 import { BunSqlQuerier } from './bunSqlQuerier.js';
-import { BunSqliteDialect } from './bunSqliteDialect.js';
+/**
+ * The dialect each engine `bun:sql` drives is given, and how this driver shapes its parameters.
+ *
+ * The engine dialects themselves, not `bun:sql` subclasses of them: what Bun changes is the binding,
+ * never the SQL, and a per-instance `driverCapabilities` is where the base class already takes that -
+ * so the Postgres and CockroachDB entries differ from `PgQuerierPool`'s only by naming the same
+ * constant. Total over {@link BunSqlDialectName}, so a new Bun adapter has to be answered here.
+ */
 const DialectMap = {
-    postgres: BunSqlPostgresDialect,
-    mysql: MySqlDialect,
-    mariadb: MariaDialect,
-    sqlite: BunSqliteDialect,
-    cockroachdb: BunSqlCockroachDialect,
+    postgres: [PostgresDialect, POSTGRES_WIRE_DRIVER_CAPABILITIES],
+    cockroachdb: [CockroachDialect, POSTGRES_WIRE_DRIVER_CAPABILITIES],
+    mysql: [MySqlDialect],
+    mariadb: [MariaDialect],
+    sqlite: [SqliteDialect],
 };
 export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
     config;
@@ -22,7 +31,8 @@ export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
     foreignKeysOn;
     constructor(config, extra) {
         const dialectName = inferDialectName(config);
-        super(new DialectMap[dialectName](dialectOptionsFrom(extra)), extra);
+        const [Dialect, driverCapabilities] = DialectMap[dialectName];
+        super(new Dialect({ ...dialectOptionsFrom(extra), driverCapabilities }), extra);
         this.config = config;
         this.sqlDialectName = dialectName;
         const opts = normalizeBunOpts(config, dialectName);
@@ -34,28 +44,31 @@ export class BunSqlQuerierPool extends AbstractSqlQuerierPool {
      */
     get pool() {
         return {
-            query: (text, values) => this.sql.unsafe(text, this.dialect.normalizeValues(values)).then((res) => ({
-                rows: normalizeRows(res),
-                rowCount: getAffectedRows(res),
-            })),
+            query: (text, values) => this.sql.unsafe(text, this.dialect.normalizeValues(values)).then((res) => {
+                const rows = normalizeRows(res);
+                return { rows, rowCount: getAffectedRows(res) ?? rows.length };
+            }),
             on: () => {
                 /* no-op for event listeners */
             },
         };
     }
     async getQuerier() {
-        const connFactory = async () => {
-            // Bun's SQLite adapter does not support connection reservation (it's unpooled), and leaves
-            // `foreign_keys` off as `bun:sqlite` does, so without the pragma the constraints uql emits in
-            // its own DDL are decorative. One connection means one pragma, issued on the first acquisition.
-            if (!isPoolableDialect(this.sqlDialectName)) {
-                this.foreignKeysOn ??= this.sql.unsafe('PRAGMA foreign_keys = ON');
-                await this.foreignKeysOn;
-                return this.sql;
-            }
+        return new BunSqlQuerier(this.sql, this.dialect, () => this.acquire(), this.extra);
+    }
+    /**
+     * Bun's SQLite adapter does not support connection reservation (it's unpooled), and leaves
+     * `foreign_keys` off as `bun:sqlite` does, so without the pragma the constraints uql emits in its
+     * own DDL are decorative. One connection means one pragma, issued on the first acquisition, and a
+     * `release` that does nothing: the handle is the pool's, and outlives every querier over it.
+     */
+    async acquire() {
+        if (this.sqlDialectName !== 'sqlite') {
             return this.sql.reserve();
-        };
-        return new BunSqlQuerier(this.sql, this.dialect, connFactory, this.extra);
+        }
+        this.foreignKeysOn ??= this.sql.unsafe('PRAGMA foreign_keys = ON');
+        await this.foreignKeysOn;
+        return { unsafe: this.sql.unsafe.bind(this.sql), release: () => { } };
     }
     async end() {
         await this.sql.close();

package/dist/bunSql/index.d.ts

@@ -1,5 +1,3 @@
-export * from './bunSqliteDialect.js';
-export * from './bunSqlCockroachDialect.js';
-export * from './bunSqlPostgresDialect.js';
+export type { BunSqlConn, BunSqlDialectName, BunSqlResult } from './bunSql.util.js';
 export * from './bunSqlQuerier.js';
 export * from './bunSqlQuerierPool.js';

package/dist/bunSql/index.js

@@ -1,5 +1,2 @@
-export * from './bunSqliteDialect.js';
-export * from './bunSqlCockroachDialect.js';
-export * from './bunSqlPostgresDialect.js';
 export * from './bunSqlQuerier.js';
 export * from './bunSqlQuerierPool.js';

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryFilter, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { type EntityData, type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryBuildFn, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryFilter, type QueryGroupMap, type QueryGroupOp, type QueryHavingMap, type QueryOptions, type QueryPager, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorNear, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
 import { type ParentPartition } from '../util/index.js';
 import type { HydrateKind } from './hydrateColumn.js';
 import { type JsonAccessMode } from './jsonSql.js';
@@ -6,6 +6,15 @@ import { type QueryJoins, type QuerySortOptions } from './queryJoins.js';
 import { VectorSqlDialect } from './vectorSqlDialect.js';
 /** How a column's values are bound: see {@link AbstractSqlDialect.persistKind}. */
 type PersistKind = 'plain' | 'json' | 'vector';
+/** What {@link AbstractSqlDialect.insertShape} resolves once for a write, indexed in step. */
+type InsertShape<E> = {
+    readonly meta: EntityMeta<E>;
+    readonly payloads: EntityData<E>[];
+    readonly keys: FieldKey<E>[];
+    readonly fields: (FieldOptions | undefined)[];
+    readonly columns: string[];
+    readonly kinds: PersistKind[];
+};
 /** One entry of {@link AbstractSqlDialect.hydratableFields}: a field key and how it decodes. */
 type HydratableField = readonly [string, HydrateKind];
 export type { HydrateKind };
@@ -111,6 +120,11 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected returningIdExpression<E>(meta: EntityMeta<E>): string;
     search<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, joins?: QueryJoins): void;
     selectFields<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelectValue<E> | undefined, opts?: QuerySelectOptions, exclude?: QueryExclude<E>): void;
+    /**
+     * What follows `SELECT` before the projection. Empty everywhere but SQL Server, whose `FETCH` will
+     * not take a zero and which spells "no rows" as `TOP (0)` instead.
+     */
+    protected selectModifier<E>(_q: Query<E>): string;
     /**
      * The expression a scalar field is read through, the plain column by default. MariaDB reads a
      * vector column back with `VEC_ToText`, since selecting it raw yields its binary form.
@@ -280,7 +294,9 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected jsonScalarParam(ctx: QueryContext, value: unknown): string;
     /** {@link resolveOperandField}, appended. */
     getComparisonKey<E>(ctx: QueryContext, entity: Type<E>, key: FieldKey<E>, opts?: QueryOptions): void;
-    sort<E>(ctx: QueryContext, entity: Type<E>, sort: QuerySortMap<E> | undefined, opts?: QuerySortOptions): void;
+    /** Appends the `ORDER BY`, reporting whether there was one - which {@link pager} needs on the
+     * engines that refuse to page an unordered statement. */
+    sort<E>(ctx: QueryContext, entity: Type<E>, sort: QuerySortMap<E> | undefined, opts?: QuerySortOptions): boolean;
     /**
      * Walks `$sort` against the metadata of the entity each level addresses, rather than flattening it
      * to dotted strings and reading every key off the root: only that way does a related column resolve
@@ -293,7 +309,11 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      * `$agg` alias - is an output alias, which is never table-qualified and needs no resolving.
      */
     private sortColumn;
-    pager(ctx: QueryContext, opts: QueryPager): void;
+    /**
+     * `LIMIT`/`OFFSET`. `sorted` says whether an `ORDER BY` was emitted just before, which
+     * {@link MergeSqlDialect} needs: SQL Server refuses to page a statement that has none.
+     */
+    pager(ctx: QueryContext, opts: QueryPager, _sorted?: boolean): void;
     /** Whether this engine has row locks at all. The SQLite family locks the database instead. */
     readonly supportsRowLocks: boolean;
     /**
@@ -306,6 +326,12 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     readonly supportsLockOf: boolean;
     /** Validated before the querier checks for a transaction, so the clearer error wins. */
     assertLockSupported<E>(entity: Type<E>, q: Query<E>, joins?: QueryJoins): void;
+    /**
+     * The lock as a hint on the table itself, for the engine that has no trailing `FOR UPDATE`. Empty
+     * everywhere else, which is where {@link appendLock} does the work instead - the two are the same
+     * lock spelled at opposite ends of the statement, so exactly one of them ever emits.
+     */
+    protected lockHint<E>(_q: Query<E>): string;
     /**
      * The trailing `FOR UPDATE`. Narrowing to the queried table is not a nicety once a relation is
      * joined: Postgres refuses a bare `FOR UPDATE` over the nullable side of an outer join outright,
@@ -354,11 +380,32 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected readonly totalOverExpr = "COUNT(*) OVER ()";
     find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
     insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
+    /**
+     * Where the clause reporting an insert's generated ids goes. `suffix` is `RETURNING ...` at the end
+     * of the statement, which every engine here but one spells that way; SQL Server's `OUTPUT` has no
+     * trailing form and sits between the column list and `VALUES`.
+     *
+     * A knob rather than a pair of hooks: one concept decides where the string {@link returningId}
+     * already built ends up, so the two ends cannot disagree.
+     */
+    readonly returningPosition: 'suffix' | 'after-target';
     /**
      * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
      * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
      */
-    protected appendInsertValues<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[]): void;
+    protected appendInsertValues<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], 
+    /** Spliced between the column list and `VALUES`; see {@link returningPosition}. */
+    afterTarget?: string): void;
+    /**
+     * The columns an insert writes and the records it writes them from, resolved once.
+     *
+     * Split out of {@link appendInsertValues} because a `MERGE` needs the same rows as a `VALUES` row
+     * source rather than as an `INSERT`, and both have to apply `onInsert` defaults and the
+     * JSON/vector binding rules identically.
+     */
+    protected insertShape<E>(entity: Type<E>, payload: E | E[]): InsertShape<E>;
+    /** `(a, b), (c, d)` - the row constructor an INSERT and a MERGE source both write. */
+    protected appendValueRows<E>(ctx: QueryContext, { payloads, keys, fields, kinds }: InsertShape<E>): void;
     /**
      * Emit the value for a column a payload record does not provide (the column list is the union
      * across all records). `DEFAULT` delegates to the database default; SQLite overrides this since
@@ -587,6 +634,13 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
     escape(value: unknown): string;
     protected get regexpOp(): string;
+    /**
+     * The `$regex` predicate. An infix operator on the MySQL family (`REGEXP`) and the Postgres one
+     * (`~`), but a function on Oracle and SQL Server 2025 (`REGEXP_LIKE(col, ?)`) - which is why this
+     * is a method rather than the operator token alone. An engine with no regex at all overrides it to
+     * throw, the way {@link appendTextSearch} already does.
+     */
+    protected regexCondition(operand: string, placeholder: string): string;
     protected get likeFn(): string;
     /**
      * Not-equal operator token for non-null comparisons.