uql-orm 0.51.0 → 0.53.0

package/dist/mssql/mssqlDialect.d.ts

@@ -0,0 +1,155 @@
+import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, InsertIdSource, Query, QueryContext, QueryOptions, QueryPager, QuerySizeComparisonOps, Type, VectorDistance, VectorMetric } from '../type/index.js';
+/**
+ * Microsoft SQL Server 2017 and up - the floor `STRING_AGG` sets, every other construct here being
+ * 2016 or older.
+ *
+ * Identifiers are `"`-quoted rather than bracketed: `escapeIdChar` is one character that doubles to
+ * escape itself, `"` is the ANSI spelling, and `tedious` enables `QUOTED_IDENTIFIER` by default.
+ * Brackets would buy nothing and cost the shared dialect spec, which reads that one character.
+ */
+export declare class MsSqlDialect extends MergeSqlDialect {
+    #private;
+    protected readonly featureDefaults: DialectFeatures;
+    readonly dialectName = "mssql";
+    readonly autoIncrementSuffix = "IDENTITY(1,1)";
+    readonly tableOptions = "";
+    readonly beginTransactionCommand = "BEGIN TRANSACTION";
+    readonly commitTransactionCommand = "COMMIT TRANSACTION";
+    readonly rollbackTransactionCommand = "ROLLBACK TRANSACTION";
+    /**
+     * The level rides the `BEGIN` rather than preceding it as its own statement: a `SET TRANSACTION
+     * ISOLATION LEVEL` sent on its own would go to whichever pooled connection served it, not the one
+     * the transaction opens on, and would then stick to that connection for unrelated later queries.
+     * `MsSqlQuerier` reads the level back off this command and hands it to the driver.
+     */
+    readonly isolationLevelStrategy = "inline";
+    readonly dropIndexSyntax = "on-table";
+    readonly booleanLiteral = "integer";
+    /** [The hard server limit](https://github.com/yiisoft/yii2/issues/10371), not a driver preference. */
+    readonly maxBindValues = 2100;
+    /** `OUTPUT` has no trailing form: it sits between the column list and `VALUES`. */
+    readonly returningPosition = "after-target";
+    readonly insertIdSource: InsertIdSource;
+    /** Holds the update key lock across the insert; without it two concurrent upserts of one key race. */
+    protected readonly mergeTargetHint = " WITH (HOLDLOCK)";
+    protected readonly statementTerminator = ";";
+    /**
+     * `TOP (0)`, the only way this engine says "no rows": `FETCH NEXT 0 ROWS ONLY` is rejected
+     * outright ("the number of rows provided for a FETCH clause must be greater then zero").
+     */
+    protected selectModifier<E>(q: Query<E>): string;
+    /**
+     * `TOP (0)` is the whole page when nothing is wanted: the engine refuses `TOP` alongside an
+     * `OFFSET`, and a skip into an empty result changes nothing, so no clause follows it.
+     */
+    pager(ctx: QueryContext, opts: QueryPager & {
+        $distinct?: boolean;
+    }, sorted?: boolean): void;
+    /**
+     * `SET IDENTITY_INSERT` around the insert, where the payload states a key the engine would
+     * otherwise generate: writing one is refused outright ("cannot insert explicit value for identity
+     * column ... when IDENTITY_INSERT is set to OFF") rather than ignored.
+     *
+     * Emitted only for that case, because the setting is per-session and only one table may hold it at
+     * a time, so it is turned back off in the same batch it was turned on.
+     */
+    insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
+    /** The table to toggle, or nothing when no record writes a key the engine would have generated. */
+    private identityInsertTarget;
+    /**
+     * A `DECIMAL` read back as the exact text it was written as, where the entity declared the field a
+     * `String`. `tedious` decodes the type to a JS number before anything here can see it, so the
+     * digits past 2^53 are gone at the wire unless the column is converted before it crosses - the same
+     * reason MariaDB reads a vector column through `VEC_ToText`. 41 characters covers `DECIMAL(38, s)`
+     * with room for the sign and the point.
+     */
+    protected selectFieldExpr(escapedColumn: string, field: FieldOptions): string;
+    /** Named parameters, which `tedious` binds by name rather than by position. */
+    placeholder(index: number): string;
+    /** `OUTPUT` reads the written row out of the `INSERTED` pseudo-table rather than `RETURNING` it. */
+    returningId<E>(meta: EntityMeta<E>): string;
+    protected returningIdExpression<E>(meta: EntityMeta<E>): string;
+    protected mergeReturning(expression: string): string;
+    /**
+     * A row lock is a hint on the table here, not a clause at the end of the statement, so
+     * {@link lockHint} emits it and this only keeps the guard - see the base declaration.
+     */
+    protected appendLock<E>(_ctx: QueryContext, entity: Type<E>, q: Query<E>): void;
+    protected lockHint<E>(q: Query<E>): string;
+    /**
+     * `N'...'`, always. A bare literal is `VARCHAR`, whose codepage silently destroys anything outside
+     * it, and every string column this dialect creates is `NVARCHAR`. Bound parameters need nothing -
+     * `tedious` binds a JS string as `NVarChar` already - so this reaches only inlined literals.
+     */
+    escape(value: unknown): string;
+    /**
+     * `REGEXP_LIKE` is SQL Server 2025 at database compatibility level 170; a server below that rejects
+     * it itself, neither the version nor the compatibility level being knowable here - the same terms
+     * `uuidv7()` is emitted on. It is a predicate rather than a value, so it stands alone.
+     */
+    protected regexCondition(operand: string, placeholder: string): string;
+    /**
+     * `VECTOR_DISTANCE('cosine', a, b)`, one function taking the metric by name; `dot` is the negated
+     * inner product, pgvector's `<#>` convention. Exact search, as on sqlite-vec: 2025's DiskANN index
+     * is a preview feature, and only `VECTOR_SEARCH` reads it, never an `ORDER BY VECTOR_DISTANCE`.
+     */
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, VectorMetric>;
+    /**
+     * `VECTOR_DISTANCE` refuses the `nvarchar` a vector binds as, so it is cast - to the value's own
+     * length, which is its dimension. A write would convert implicitly, and shares the cast anyway.
+     */
+    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
+    /** There is no `CREATE SCHEMA IF NOT EXISTS`, and `CREATE SCHEMA` has to be alone in its batch. */
+    createSchemaSql(schema: string): string;
+    /** The estimate the engine already keeps per partition, live without a stats refresh. */
+    estimatedCount<E>(ctx: QueryContext, entity: Type<E>): void;
+    protected numericCast(expr: string): string;
+    /**
+     * `JSON_VALUE` returns `NVARCHAR(4000)` and, in the lax mode that is the default, answers NULL
+     * rather than erroring for anything longer - so a long string read through it disappears without a
+     * word. `OPENJSON` has no such bound, so the path is split and its last segment matched as a key.
+     */
+    protected getJsonPathScalarExpr(escapedColumn: string, jsonPathStr: string): string;
+    /**
+     * The same read as the scalar one. `JSON_QUERY` answers NULL for anything that is not an object or
+     * an array, so it cannot serve the JSON access mode a boolean or a number operand asks for -
+     * `OPENJSON` returns both as text, and {@link jsonScalarParam} binds the operand as the matching
+     * text. An array or object comes back as its own JSON text, which is what `OPENJSON` takes next.
+     */
+    protected getJsonPathJsonbExpr(escapedColumn: string, jsonPathStr: string): string;
+    /**
+     * A value being *compared* against a JSON path, which reads back as the text `JSON_VALUE` yields:
+     * `'true'` for a boolean, `'12'` for a number. So only a boolean needs re-spelling; a number or a
+     * string already binds as the text it will be compared with.
+     *
+     * There is no "parse this text as JSON" cast to bind through the way `CAST(? AS JSON)` and
+     * `json(?)` serve the other families - `JSON_QUERY` marks text as JSON but answers NULL for a
+     * scalar - which is why reading and writing need the two different binders here.
+     */
+    protected jsonScalarParam(ctx: QueryContext, value: unknown): string;
+    /**
+     * A value being *written* to a JSON path, which takes the type the driver sent: a `BIT` becomes a
+     * JSON boolean, a number a JSON number, a string a JSON string. `normalizeValue` has already
+     * flattened a boolean to 1/0 for this engine's columns, so the cast is what restores it.
+     */
+    protected jsonWriteParam(ctx: QueryContext, value: unknown): string;
+    /** An exploded element compares as text here, so `$elemMatch` always expands per field. */
+    protected readonly jsonContainmentIsPartial = false;
+    protected jsonElemFrom(jsonField: string, _fields: readonly string[], alias: string): string;
+    /** `JSON_VALUE`'s 4000-character bound applies to an element's field, unlike a whole column. */
+    protected jsonElemRef(alias: string, field?: string): string;
+    protected jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
+    protected jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
+    /** `JSON_MODIFY` takes one path per call, so several keys chain into one expression. */
+    protected jsonSet(ctx: QueryContext, expr: string, set: Record<string, unknown>, _field?: FieldOptions): string;
+    /** `'append '` prefixing the path extends the array there, creating it where there is none. */
+    protected jsonPush(ctx: QueryContext, expr: string, push: Record<string, unknown>): string;
+    /** Assigning NULL to a path deletes it in lax mode, which is the default. */
+    protected jsonUnset(_ctx: QueryContext, expr: string, unset: readonly string[]): string;
+    /**
+     * The surviving elements are re-aggregated into an array and written back whole - there is no
+     * remove-by-value. `JSON_QUERY` is what marks the rebuilt text as JSON rather than a string.
+     */
+    protected jsonPullKey(ctx: QueryContext, expr: string, escapedCol: string, key: string, value: unknown): string;
+}

package/dist/mssql/mssqlDialect.js

@@ -0,0 +1,341 @@
+import { COUNT_ALIAS, JSON_ELEM_ALIAS_PREFIX } from '../dialect/aliases.js';
+import { jsonPath } from '../dialect/jsonSql.js';
+import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
+import { getMeta } from '../entity/index.js';
+import { fieldOptionsToCanonical } from '../schema/canonicalType.js';
+import { QueryRaw } from '../type/index.js';
+import { parseQueryLock } from '../type/index.js';
+import { isAutoIncrement } from '../util/field.util.js';
+import { assertNonNegativeInteger } from '../util/index.js';
+import { escapeSingleQuotes } from '../util/sqlLiteral.js';
+/**
+ * Microsoft SQL Server 2017 and up - the floor `STRING_AGG` sets, every other construct here being
+ * 2016 or older.
+ *
+ * Identifiers are `"`-quoted rather than bracketed: `escapeIdChar` is one character that doubles to
+ * escape itself, `"` is the ANSI spelling, and `tedious` enables `QUOTED_IDENTIFIER` by default.
+ * Brackets would buy nothing and cost the shared dialect spec, which reads that one character.
+ */
+export class MsSqlDialect extends MergeSqlDialect {
+    featureDefaults = {
+        explicitJsonCast: false,
+        nativeArrays: false,
+        supportsJsonb: false,
+        // Neither object takes an `IF NOT EXISTS`; both need a `sys` catalogue lookup around them, which
+        // the generator does not emit.
+        ifNotExists: false,
+        indexIfNotExists: false,
+        schemas: true,
+        dropTableCascade: false,
+        foreignKeyAlter: true,
+        primaryKeyAlter: true,
+        generatedColumnAdd: true,
+        // Extended properties are out-of-band metadata with their own procedures, not comments.
+        commentSyntax: 'none',
+        vectorIndexRequiresNotNull: false,
+        vectorSupportsLength: true,
+        supportsTimestamptz: false,
+        stringSizing: 'varchar',
+        supportsUnsigned: false,
+        serverSideCursors: false,
+    };
+    dialectName = 'mssql';
+    /** `OPENJSON`'s own output columns, which every JSON operator below reads through. */
+    #elem = {
+        value: this.escapeId('value'),
+        key: this.escapeId('key'),
+        type: this.escapeId('type'),
+    };
+    autoIncrementSuffix = 'IDENTITY(1,1)';
+    tableOptions = '';
+    beginTransactionCommand = 'BEGIN TRANSACTION';
+    commitTransactionCommand = 'COMMIT TRANSACTION';
+    rollbackTransactionCommand = 'ROLLBACK TRANSACTION';
+    /**
+     * The level rides the `BEGIN` rather than preceding it as its own statement: a `SET TRANSACTION
+     * ISOLATION LEVEL` sent on its own would go to whichever pooled connection served it, not the one
+     * the transaction opens on, and would then stick to that connection for unrelated later queries.
+     * `MsSqlQuerier` reads the level back off this command and hands it to the driver.
+     */
+    isolationLevelStrategy = 'inline';
+    dropIndexSyntax = 'on-table';
+    booleanLiteral = 'integer';
+    /** [The hard server limit](https://github.com/yiisoft/yii2/issues/10371), not a driver preference. */
+    maxBindValues = 2100;
+    /** `OUTPUT` has no trailing form: it sits between the column list and `VALUES`. */
+    returningPosition = 'after-target';
+    insertIdSource = 'returning';
+    /** Holds the update key lock across the insert; without it two concurrent upserts of one key race. */
+    mergeTargetHint = ' WITH (HOLDLOCK)';
+    statementTerminator = ';';
+    /**
+     * `TOP (0)`, the only way this engine says "no rows": `FETCH NEXT 0 ROWS ONLY` is rejected
+     * outright ("the number of rows provided for a FETCH clause must be greater then zero").
+     */
+    selectModifier(q) {
+        return q.$limit === 0 ? 'TOP (0) ' : '';
+    }
+    /**
+     * `TOP (0)` is the whole page when nothing is wanted: the engine refuses `TOP` alongside an
+     * `OFFSET`, and a skip into an empty result changes nothing, so no clause follows it.
+     */
+    pager(ctx, opts, sorted = false) {
+        if (opts.$limit === 0) {
+            assertNonNegativeInteger(opts.$skip ?? 0, '$skip');
+            return;
+        }
+        super.pager(ctx, opts, sorted);
+    }
+    /**
+     * `SET IDENTITY_INSERT` around the insert, where the payload states a key the engine would
+     * otherwise generate: writing one is refused outright ("cannot insert explicit value for identity
+     * column ... when IDENTITY_INSERT is set to OFF") rather than ignored.
+     *
+     * Emitted only for that case, because the setting is per-session and only one table may hold it at
+     * a time, so it is turned back off in the same batch it was turned on.
+     */
+    insert(ctx, entity, payload, opts) {
+        const table = this.identityInsertTarget(entity, payload);
+        if (table) {
+            ctx.append(`SET IDENTITY_INSERT ${table} ON; `);
+        }
+        super.insert(ctx, entity, payload, opts);
+        if (table) {
+            ctx.append(`; SET IDENTITY_INSERT ${table} OFF`);
+        }
+    }
+    /** The table to toggle, or nothing when no record writes a key the engine would have generated. */
+    identityInsertTarget(entity, payload) {
+        const meta = getMeta(entity);
+        const [idKey] = meta.ids;
+        const field = meta.ids.length === 1 ? meta.fields[idKey] : undefined;
+        if (!field || !isAutoIncrement(field, true)) {
+            return undefined;
+        }
+        const records = Array.isArray(payload) ? payload : [payload];
+        const stated = records.some((record) => record[idKey] !== undefined);
+        return stated ? this.escapedTableName(meta) : undefined;
+    }
+    /**
+     * A `DECIMAL` read back as the exact text it was written as, where the entity declared the field a
+     * `String`. `tedious` decodes the type to a JS number before anything here can see it, so the
+     * digits past 2^53 are gone at the wire unless the column is converted before it crosses - the same
+     * reason MariaDB reads a vector column through `VEC_ToText`. 41 characters covers `DECIMAL(38, s)`
+     * with room for the sign and the point.
+     */
+    selectFieldExpr(escapedColumn, field) {
+        const exactDecimal = field.type === String && fieldOptionsToCanonical(field).category === 'decimal';
+        return exactDecimal ? `CONVERT(NVARCHAR(41), ${escapedColumn})` : escapedColumn;
+    }
+    /** Named parameters, which `tedious` binds by name rather than by position. */
+    placeholder(index) {
+        return `@p${index}`;
+    }
+    /** `OUTPUT` reads the written row out of the `INSERTED` pseudo-table rather than `RETURNING` it. */
+    returningId(meta) {
+        const expression = this.returningIdExpression(meta);
+        return expression ? `OUTPUT ${expression}` : '';
+    }
+    returningIdExpression(meta) {
+        const [idKey] = meta.ids;
+        return meta.ids.length === 1 ? `INSERTED.${this.escapeId(this.columnOf(meta, idKey))} ${this.escapeId('id')}` : '';
+    }
+    mergeReturning(expression) {
+        return `OUTPUT ${expression}`;
+    }
+    /**
+     * A row lock is a hint on the table here, not a clause at the end of the statement, so
+     * {@link lockHint} emits it and this only keeps the guard - see the base declaration.
+     */
+    appendLock(_ctx, entity, q) {
+        this.assertLockSupported(entity, q);
+    }
+    lockHint(q) {
+        const wait = parseQueryLock(q.$lock);
+        if (!wait) {
+            return '';
+        }
+        // `READPAST` skips locked rows and `NOWAIT` raises instead of waiting - what `SKIP LOCKED` and
+        // `NOWAIT` mean elsewhere. `ROWLOCK` asks the engine not to escalate to a page or the table.
+        const extra = wait === 'skip' ? ', READPAST' : wait === 'nowait' ? ', NOWAIT' : '';
+        return ` WITH (UPDLOCK, ROWLOCK${extra})`;
+    }
+    /**
+     * `N'...'`, always. A bare literal is `VARCHAR`, whose codepage silently destroys anything outside
+     * it, and every string column this dialect creates is `NVARCHAR`. Bound parameters need nothing -
+     * `tedious` binds a JS string as `NVarChar` already - so this reaches only inlined literals.
+     */
+    escape(value) {
+        if (typeof value === 'string') {
+            return `N'${escapeSingleQuotes(value)}'`;
+        }
+        if (value instanceof Uint8Array) {
+            return `0x${Array.from(value, (byte) => byte.toString(16).padStart(2, '0')).join('')}`;
+        }
+        return super.escape(value);
+    }
+    /**
+     * `REGEXP_LIKE` is SQL Server 2025 at database compatibility level 170; a server below that rejects
+     * it itself, neither the version nor the compatibility level being knowable here - the same terms
+     * `uuidv7()` is emitted on. It is a predicate rather than a value, so it stands alone.
+     */
+    regexCondition(operand, placeholder) {
+        return `REGEXP_LIKE(${operand}, ${placeholder})`;
+    }
+    /**
+     * `VECTOR_DISTANCE('cosine', a, b)`, one function taking the metric by name; `dot` is the negated
+     * inner product, pgvector's `<#>` convention. Exact search, as on sqlite-vec: 2025's DiskANN index
+     * is a preview feature, and only `VECTOR_SEARCH` reads it, never an `ORDER BY VECTOR_DISTANCE`.
+     */
+    vectorMetrics = new Map([
+        ['cosine', { fn: 'VECTOR_DISTANCE', metricArg: 'cosine' }],
+        ['l2', { fn: 'VECTOR_DISTANCE', metricArg: 'euclidean' }],
+        ['inner', { fn: 'VECTOR_DISTANCE', metricArg: 'dot' }],
+    ]);
+    /**
+     * `VECTOR_DISTANCE` refuses the `nvarchar` a vector binds as, so it is cast - to the value's own
+     * length, which is its dimension. A write would convert implicitly, and shares the cast anyway.
+     */
+    appendVectorValue(ctx, value) {
+        ctx.append('CAST(');
+        super.appendVectorValue(ctx, value);
+        ctx.append(` AS VECTOR(${value.length}))`);
+    }
+    /** There is no `CREATE SCHEMA IF NOT EXISTS`, and `CREATE SCHEMA` has to be alone in its batch. */
+    createSchemaSql(schema) {
+        const literal = escapeSingleQuotes(schema);
+        const quoted = escapeSingleQuotes(this.escapeId(schema, true));
+        return `IF SCHEMA_ID(N'${literal}') IS NULL EXEC(N'CREATE SCHEMA ${quoted}')`;
+    }
+    /** The estimate the engine already keeps per partition, live without a stats refresh. */
+    estimatedCount(ctx, entity) {
+        const meta = getMeta(entity);
+        ctx.append(`SELECT SUM(p.rows) ${this.escapeId(COUNT_ALIAS, true)} FROM sys.partitions p` +
+            ` JOIN sys.objects o ON o.object_id = p.object_id` +
+            ` JOIN sys.schemas s ON s.schema_id = o.schema_id` +
+            ` WHERE p.index_id IN (0, 1) AND o.name = `);
+        ctx.addValue(this.resolveTableAlias(meta));
+        ctx.append(' AND s.name = ');
+        ctx.addValue(this.resolveSchema(meta) ?? 'dbo');
+    }
+    numericCast(expr) {
+        return `TRY_CAST(${expr} AS FLOAT)`;
+    }
+    /**
+     * `JSON_VALUE` returns `NVARCHAR(4000)` and, in the lax mode that is the default, answers NULL
+     * rather than erroring for anything longer - so a long string read through it disappears without a
+     * word. `OPENJSON` has no such bound, so the path is split and its last segment matched as a key.
+     */
+    getJsonPathScalarExpr(escapedColumn, jsonPathStr) {
+        const dot = jsonPathStr.lastIndexOf('.');
+        const parent = dot === -1 ? '$' : `$.${jsonPathStr.slice(0, dot).split('.').map(escapeSingleQuotes).join('.')}`;
+        const leaf = escapeSingleQuotes(jsonPathStr.slice(dot + 1));
+        return `(SELECT ${this.#elem.value} FROM OPENJSON(${escapedColumn}, '${parent}') WHERE ${this.#elem.key} = N'${leaf}')`;
+    }
+    /**
+     * The same read as the scalar one. `JSON_QUERY` answers NULL for anything that is not an object or
+     * an array, so it cannot serve the JSON access mode a boolean or a number operand asks for -
+     * `OPENJSON` returns both as text, and {@link jsonScalarParam} binds the operand as the matching
+     * text. An array or object comes back as its own JSON text, which is what `OPENJSON` takes next.
+     */
+    getJsonPathJsonbExpr(escapedColumn, jsonPathStr) {
+        return this.getJsonPathScalarExpr(escapedColumn, jsonPathStr);
+    }
+    /**
+     * A value being *compared* against a JSON path, which reads back as the text `JSON_VALUE` yields:
+     * `'true'` for a boolean, `'12'` for a number. So only a boolean needs re-spelling; a number or a
+     * string already binds as the text it will be compared with.
+     *
+     * There is no "parse this text as JSON" cast to bind through the way `CAST(? AS JSON)` and
+     * `json(?)` serve the other families - `JSON_QUERY` marks text as JSON but answers NULL for a
+     * scalar - which is why reading and writing need the two different binders here.
+     */
+    jsonScalarParam(ctx, value) {
+        return (this.#jsonCompound(ctx, value) ??
+            this.addValue(ctx.values, typeof value === 'boolean' ? JSON.stringify(value) : value));
+    }
+    /**
+     * A value being *written* to a JSON path, which takes the type the driver sent: a `BIT` becomes a
+     * JSON boolean, a number a JSON number, a string a JSON string. `normalizeValue` has already
+     * flattened a boolean to 1/0 for this engine's columns, so the cast is what restores it.
+     */
+    jsonWriteParam(ctx, value) {
+        const compound = this.#jsonCompound(ctx, value);
+        if (compound) {
+            return compound;
+        }
+        const placeholder = this.addValue(ctx.values, value);
+        return typeof value === 'boolean' ? `CAST(${placeholder} AS BIT)` : placeholder;
+    }
+    /**
+     * An object or array bound as JSON, which is the half both binders spell the same way, or
+     * `undefined` for a scalar - where they diverge.
+     */
+    #jsonCompound(ctx, value) {
+        if (value === null || typeof value !== 'object' || value instanceof QueryRaw) {
+            return undefined;
+        }
+        ctx.pushValue(JSON.stringify(value));
+        return `JSON_QUERY(${this.placeholder(ctx.values.length)})`;
+    }
+    /** An exploded element compares as text here, so `$elemMatch` always expands per field. */
+    jsonContainmentIsPartial = false;
+    jsonElemFrom(jsonField, _fields, alias) {
+        return `OPENJSON(${jsonField}) ${alias}`;
+    }
+    /** `JSON_VALUE`'s 4000-character bound applies to an element's field, unlike a whole column. */
+    jsonElemRef(alias, field) {
+        return field === undefined
+            ? `${alias}.${this.#elem.value}`
+            : `JSON_VALUE(${alias}.${this.#elem.value}, ${jsonPath(field)})`;
+    }
+    jsonAll(ctx, jsonField, value) {
+        const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
+        const conditions = value.map((val) => `EXISTS (SELECT 1 FROM OPENJSON(${jsonField}) ${alias} WHERE ${alias}.${this.#elem.value} = ${this.jsonScalarParam(ctx, val)})`);
+        return `(${conditions.join(' AND ')})`;
+    }
+    jsonSize(ctx, jsonField, value) {
+        const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
+        return this.buildFragment(ctx, (fragmentCtx) => this.buildSizeComparison(fragmentCtx, () => fragmentCtx.append(`(SELECT COUNT(*) FROM OPENJSON(${jsonField}) ${alias})`), value));
+    }
+    /** `JSON_MODIFY` takes one path per call, so several keys chain into one expression. */
+    jsonSet(ctx, expr, set, _field) {
+        for (const [key, value] of Object.entries(set)) {
+            if (value === null) {
+                throw new TypeError(`mssql cannot $set '${key}' to null: JSON_MODIFY deletes the key instead. Use $unset, or store a JSON null through a whole-column write.`);
+            }
+        }
+        return Object.entries(set).reduce((acc, [key, value]) => `JSON_MODIFY(${acc}, ${jsonPath(key)}, ${this.jsonWriteParam(ctx, value)})`, `COALESCE(${expr}, '{}')`);
+    }
+    /** `'append '` prefixing the path extends the array there, creating it where there is none. */
+    jsonPush(ctx, expr, push) {
+        return Object.entries(push).reduce((acc, [key, value]) => `JSON_MODIFY(${acc}, 'append ${jsonPath(key).slice(1, -1)}', ${this.jsonWriteParam(ctx, value)})`, `COALESCE(${expr}, '{}')`);
+    }
+    /** Assigning NULL to a path deletes it in lax mode, which is the default. */
+    jsonUnset(_ctx, expr, unset) {
+        return unset.reduce((acc, key) => `JSON_MODIFY(${acc}, ${jsonPath(key)}, NULL)`, expr);
+    }
+    /**
+     * The surviving elements are re-aggregated into an array and written back whole - there is no
+     * remove-by-value. `JSON_QUERY` is what marks the rebuilt text as JSON rather than a string.
+     */
+    jsonPullKey(ctx, expr, escapedCol, key, value) {
+        const alias = ctx.nextAlias(JSON_ELEM_ALIAS_PREFIX);
+        const val = `${alias}.${this.#elem.value}`;
+        // `OPENJSON` hands back a string element unquoted and a null one as SQL NULL, so each survivor is
+        // re-encoded from its reported `type` before the array is put back together - concatenated raw,
+        // the result is text the engine then refuses to parse as JSON.
+        const encoded = `CASE ${alias}.${this.#elem.type}` +
+            ` WHEN 0 THEN 'null'` +
+            ` WHEN 1 THEN '"' + STRING_ESCAPE(${val}, 'json') + '"'` +
+            ` ELSE ${val} END`;
+        // `IS NULL OR` because a JSON null element reads back as SQL NULL, and `<>` against one is
+        // unknown rather than true - which silently dropped every null from the array it rebuilt.
+        const kept = `SELECT '[' + STRING_AGG(${encoded}, ',') + ']' FROM OPENJSON(${escapedCol}, ${jsonPath(key)}) ${alias}` +
+            ` WHERE ${val} IS NULL OR ${val} <> ${this.jsonScalarParam(ctx, value)}`;
+        // `JSON_MODIFY` creates a path it does not find, so a `$pull` against an absent key would add an
+        // empty array where the other engines leave the document alone.
+        const path = jsonPath(key);
+        return `CASE WHEN JSON_QUERY(${escapedCol}, ${path}) IS NULL THEN ${expr} ELSE JSON_MODIFY(${expr}, ${path}, JSON_QUERY(COALESCE((${kept}), '[]'))) END`;
+    }
+}

package/dist/mssql/mssqlQuerier.d.ts

@@ -0,0 +1,23 @@
+import type { ConnectionPool } from 'mssql';
+import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
+import type { ExtraOptions, QueryUpdateResult } from '../type/index.js';
+import type { MsSqlDialect } from './mssqlDialect.js';
+/**
+ * A connection is a `ConnectionPool` handle here rather than a checked-out socket: `mssql` owns its
+ * own pool and hands out `Request`s, so what UQL holds is the pool plus, once a transaction opens,
+ * the `Transaction` every later request has to be bound to.
+ */
+export declare class MsSqlQuerier extends AbstractPoolQuerier<ConnectionPool> {
+    #private;
+    constructor(connect: () => Promise<ConnectionPool>, dialect: MsSqlDialect, extra?: ExtraOptions);
+    internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
+    internalRun(query: string, values?: unknown[]): Promise<QueryUpdateResult>;
+    /**
+     * `tedious` streams by event, not by async iterator, so rows are handed over as they arrive rather
+     * than collected first - buffering the whole result set would make this `all()` with extra steps.
+     * The `query` promise is awaited at the end so its rejection surfaces rather than going unhandled.
+     */
+    internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, unknown>;
+    /** The pool owns the socket; releasing a querier only drops this one's claim on it. */
+    protected releaseConn(_conn: ConnectionPool, _discard: boolean): Promise<void>;
+}

package/dist/mssql/mssqlQuerier.js

@@ -0,0 +1,137 @@
+import { ISOLATION_LEVEL } from 'mssql';
+import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
+import { decodeWireTypes } from './mssqlWireTypes.js';
+/**
+ * A connection is a `ConnectionPool` handle here rather than a checked-out socket: `mssql` owns its
+ * own pool and hands out `Request`s, so what UQL holds is the pool plus, once a transaction opens,
+ * the `Transaction` every later request has to be bound to.
+ */
+export class MsSqlQuerier extends AbstractPoolQuerier {
+    #transaction;
+    constructor(connect, dialect, extra) {
+        super(dialect, connect, extra);
+    }
+    /**
+     * Values bind by name, `@p1` upward, matching {@link MsSqlDialect.placeholder}. `tedious` infers
+     * a type from the JS value, which is why a `Date` and a `Uint8Array` reach it unconverted - the
+     * inference is right for both, and wrong only for a bare `null`, which it calls `NVarChar`.
+     */
+    #request(values) {
+        const request = this.#transaction ? this.#transaction.request() : this.getConn().request();
+        values?.forEach((value, index) => request.input(`p${index + 1}`, value));
+        return request;
+    }
+    async internalAll(query, values) {
+        const res = (await this.#request(values).query(query));
+        return decodeWireTypes(res.recordset, res.recordset?.columns);
+    }
+    async internalRun(query, values) {
+        if (await this.#driveTransaction(query)) {
+            return { changes: 0 };
+        }
+        const res = (await this.#request(values).query(query));
+        return this.buildUpdateResult({
+            // `rowsAffected` carries one entry per statement, and a `MERGE` upsert emits its `OUTPUT`
+            // alongside the write, so the counts are summed rather than read at [0].
+            changes: res.rowsAffected.reduce((total, count) => total + count, 0),
+            rows: decodeWireTypes(res.recordset, res.recordset?.columns),
+        });
+    }
+    /**
+     * `tedious` streams by event, not by async iterator, so rows are handed over as they arrive rather
+     * than collected first - buffering the whole result set would make this `all()` with extra steps.
+     * The `query` promise is awaited at the end so its rejection surfaces rather than going unhandled.
+     */
+    async *internalStream(query, values) {
+        const request = this.#request(values);
+        request.stream = true;
+        let pending = [];
+        let done = false;
+        let failure;
+        let wake;
+        const arrived = () => {
+            wake?.();
+            wake = undefined;
+        };
+        request.on('row', (row) => {
+            pending.push(row);
+            arrived();
+        });
+        request.on('error', (err) => {
+            failure ??= err;
+            arrived();
+        });
+        request.on('done', () => {
+            done = true;
+            arrived();
+        });
+        const completed = request.query(query).catch((err) => {
+            failure ??= err instanceof Error ? err : new Error(String(err));
+            arrived();
+        });
+        try {
+            while (true) {
+                if (pending.length) {
+                    const batch = pending;
+                    pending = [];
+                    yield* batch;
+                    continue;
+                }
+                if (failure)
+                    throw failure;
+                if (done)
+                    return;
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+            }
+        }
+        finally {
+            // `completed` is awaited rather than left floating so a late rejection is handled; its own
+            // `catch` has already recorded it, and the loop above is what raises one to the caller.
+            request.cancel();
+            await completed;
+        }
+    }
+    /**
+     * `mssql` owns its pool and hands out a `Request` per call, so a `BEGIN TRANSACTION` sent as text
+     * would open one on a connection the next call may not be given. Its `Transaction` object is the
+     * only thing that pins them together, so the three commands the dialect names are driven through
+     * it here instead of being sent. Compared against the dialect's own strings rather than literals,
+     * so renaming one cannot silently turn it back into text.
+     */
+    async #driveTransaction(query) {
+        const { beginTransactionCommand, commitTransactionCommand, rollbackTransactionCommand } = this.dialect;
+        if (query.startsWith(beginTransactionCommand)) {
+            this.#transaction = this.getConn().transaction();
+            await this.#transaction.begin(isolationLevelOf(query.slice(beginTransactionCommand.length)));
+            return true;
+        }
+        if (query !== commitTransactionCommand && query !== rollbackTransactionCommand) {
+            return false;
+        }
+        const transaction = this.#transaction;
+        this.#transaction = undefined;
+        await (query === commitTransactionCommand ? transaction?.commit() : transaction?.rollback());
+        return true;
+    }
+    /** The pool owns the socket; releasing a querier only drops this one's claim on it. */
+    async releaseConn(_conn, _discard) {
+        const transaction = this.#transaction;
+        this.#transaction = undefined;
+        // A querier handed back mid-transaction would otherwise leave it open on a pooled connection.
+        await transaction?.rollback().catch(() => undefined);
+    }
+}
+/**
+ * The driver constant for the level the dialect spelled into its `BEGIN`, so it applies to the
+ * connection the transaction actually opens on. Undefined leaves the server's own default.
+ */
+function isolationLevelOf(suffix) {
+    const level = suffix
+        .replace(/^\s*ISOLATION LEVEL\s*/i, '')
+        .trim()
+        .toUpperCase()
+        .replaceAll(' ', '_');
+    return level ? ISOLATION_LEVEL[level] : undefined;
+}