uql-orm 0.20.2 → 0.22.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,12 +1,13 @@
 import { getMeta } from '../entity/index.js';
 import { QueryRaw, RAW_ALIAS, RAW_VALUE, } from '../type/index.js';
-import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/ansiSqlLiteral.js';
-import { applyFilters, asSelectMap, buildQueryWhereAsMap, buildSortMap, escapeSqlId, fillOnFields, filterFieldKeys, flatObject, getFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, hasMultipleKeys, isJsonType, isJsonUpdateOp, isOperatorObject, isOperatorOnlyObject, isPopulatingRelations, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, buildQueryWhereAsMap, buildSortMap, escapeSqlId, fillOnFields, filterFieldKeys, flatObject, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, hasMultipleKeys, isJsonType, isJsonUpdateOp, isOperatorObject, isOperatorOnlyObject, isPopulatingRelations, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, parseRelationSize, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
+import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
+import { IndexSqlDialect } from './indexSqlDialect.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
 import { JSON_ELEM_ALIAS_PREFIX, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
-import { VectorSqlDialect } from './vectorSqlDialect.js';
-export class AbstractSqlDialect extends VectorSqlDialect {
+import { isVectorFieldType } from './vectorCast.js';
+export class AbstractSqlDialect extends IndexSqlDialect {
     isolationLevelStrategy = 'inline';
     alterColumnStrategy = 'single-statement';
     alterColumnSyntax = 'ALTER COLUMN';
@@ -81,7 +82,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     returningId(entity) {
         const meta = getMeta(entity);
         const idKey = (meta.id ?? 'id');
-        const idName = this.resolveColumnName(idKey, meta.fields[idKey]);
+        const idName = this.columnOf(meta, idKey);
         return `RETURNING ${this.escapeId(idName)} ${this.escapeId('id')}`;
     }
     search(ctx, entity, q = {}, opts = {}) {
@@ -135,7 +136,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 const field = meta.fields[key];
                 if (!field)
                     return;
-                const columnName = this.resolveColumnName(key, field);
                 if (field.virtual) {
                     this.getRawValue(ctx, {
                         value: raw(field.virtual[RAW_VALUE], key),
@@ -143,17 +143,35 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                         escapedPrefix,
                         autoPrefixAlias: opts.autoPrefixAlias,
                     });
+                    return;
                 }
-                else {
-                    ctx.append(escapedPrefix + this.escapeId(columnName));
-                }
-                if (!field.virtual && (columnName !== key || opts.autoPrefixAlias)) {
-                    const aliasStr = prefix + key;
-                    ctx.append(' ' + this.escapeId(aliasStr, true));
+                const columnName = this.resolveColumnName(key, field);
+                const column = escapedPrefix + this.escapeId(columnName);
+                const expr = this.selectFieldExpr(column, field);
+                ctx.append(expr);
+                // An expression needs the alias too, or the row comes back keyed by the expression text.
+                if (expr !== column || columnName !== key || opts.autoPrefixAlias) {
+                    ctx.append(' ' + this.escapeId(prefix + key, true));
                 }
             }
         });
     }
+    /**
+     * 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.
+     */
+    selectFieldExpr(escapedColumn, _field) {
+        return escapedColumn;
+    }
+    /**
+     * The `$text` full-text predicate, which every engine spells differently: `MATCH ... AGAINST`
+     * (MySQL family), `to_tsvector @@ websearch_to_tsquery` (Postgres-wire), an FTS5 `MATCH` against
+     * the table itself (SQLite). No portable form exists, so a dialect without one says so here rather
+     * than inheriting another engine's syntax.
+     */
+    appendTextSearch(_ctx, _entity, _meta, _search) {
+        throw new TypeError(`${this.dialectName} does not support $text full-text search`);
+    }
     select(ctx, entity, select, exclude, populate, opts = {}, distinct, sort) {
         const meta = getMeta(entity);
         const tableName = this.resolveTableName(entity, meta);
@@ -239,9 +257,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     where(ctx, entity, where = {}, opts = {}) {
         const meta = getMeta(entity);
-        // Apply this entity's filters once, at the scope entry point; recursion uses `renderWhere`.
-        const whereMap = applyFilters(meta, buildQueryWhereAsMap(meta, where), opts);
-        this.renderWhere(ctx, entity, whereMap, opts);
+        // Filters are applied once, here at the scope entry point; recursion uses `renderWhere`.
+        this.renderWhere(ctx, entity, this.scopedWhereMap(meta, where, opts), opts);
     }
     /** Renders a `$where` tree without applying entity filters (used for same-scope `$and`/`$or` recursion). */
     renderWhere(ctx, entity, where = {}, opts = {}) {
@@ -297,16 +314,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             return;
         }
         if (key === '$text') {
-            const search = val;
-            const searchFields = search.$fields ?? getFieldKeys(meta.fields);
-            const fields = searchFields.map((fKey) => {
-                const field = meta.fields[fKey];
-                const columnName = this.resolveColumnName(fKey, field);
-                return this.escapeId(columnName);
-            });
-            ctx.append(`MATCH(${fields.join(', ')}) AGAINST(`);
-            ctx.addValue(search.$value);
-            ctx.append(')');
+            this.appendTextSearch(ctx, entity, meta, val);
             return;
         }
         if (key === '$and' || key === '$or' || key === '$not' || key === '$nor') {
@@ -322,13 +330,11 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         if (key.includes('.')) {
             throw new TypeError(`path ${key} does not exist in ${meta.name}`);
         }
-        // Detect relation filtering
         const rel = meta.relations[key];
         if (rel) {
-            // Check if this is a $size query on a relation (count filtering)
-            const valObj = val;
-            if (valObj && typeof valObj === 'object' && '$size' in valObj && Object.keys(valObj).length === 1) {
-                this.compareRelationSize(ctx, entity, key, valObj['$size'], rel, opts);
+            const sizeVal = parseRelationSize(val);
+            if (sizeVal !== undefined) {
+                this.compareRelationSize(ctx, entity, key, sizeVal, rel, opts);
                 return;
             }
             this.compareRelation(ctx, entity, key, val, rel, opts);
@@ -382,6 +388,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
     }
     /** Simple comparison operators: `getComparisonKey → op → addValue`. */
+    /** Memoizes {@link escapedColumnName}; see there for why it is per dialect instance. */
+    escapedColumns = new WeakMap();
     static NEGATE_OP_MAP = new Map([
         ['$not', '$and'],
         ['$nor', '$or'],
@@ -797,9 +805,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 if (!sqlFn) {
                     throw TypeError(`unsupported aggregate operator: ${entry.op}`);
                 }
-                const sqlArg = entry.fieldRef === '*'
-                    ? '*'
-                    : this.escapeId(this.resolveColumnName(entry.fieldRef, meta.fields[entry.fieldRef]));
+                const sqlArg = entry.fieldRef === '*' ? '*' : this.escapeId(this.columnOf(meta, entry.fieldRef));
                 const expr = `${sqlFn}(${entry.distinct ? 'DISTINCT ' : ''}${sqlArg})`;
                 aggregateExpressions[entry.alias] = expr;
                 selectParts.push(`${expr} ${this.escapeId(entry.alias)}`);
@@ -860,7 +866,8 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         return direction;
     }
-    static havingOpMap = new Map([
+    /** Scalar comparison operators shared by `HAVING` conditions and `$size` comparisons. */
+    static comparisonOpMap = new Map([
         ['$eq', '='],
         ['$ne', '<>'],
         ['$gt', '>'],
@@ -900,7 +907,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 ctx.append(this.neExpr(expr, this.addValue(ctx.values, val)));
             }
             else {
-                const sqlOp = AbstractSqlDialect.havingOpMap.get(op);
+                const sqlOp = AbstractSqlDialect.comparisonOpMap.get(op);
                 if (!sqlOp)
                     throw TypeError(`unsupported HAVING operator: ${op}`);
                 ctx.append(`${expr} ${sqlOp} `);
@@ -913,32 +920,58 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         this.search(ctx, entity, q, opts);
     }
     insert(ctx, entity, payload, opts) {
+        this.appendInsertValues(ctx, entity, payload, opts);
+        // Every engine whose ids come back from the statement itself wants the same clause, so it is
+        // appended once here instead of in an identical `insert` override per dialect.
+        if (this.insertIdSource === 'returning') {
+            ctx.append(` ${this.returningId(entity)}`);
+        }
+    }
+    /**
+     * `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.
+     */
+    appendInsertValues(ctx, entity, payload, opts) {
         const meta = getMeta(entity);
         const payloads = fillOnFields(meta, payload, 'onInsert');
         const keys = getInsertFieldKeys(meta, payloads);
-        const columns = keys.map((key) => {
+        // Resolve each key's field and escaped column once, then index into them: re-reading
+        // `meta.fields[key]` per record cost 40 redundant lookups on a 10-row, 4-column insert.
+        const width = keys.length;
+        const fields = new Array(width);
+        const columns = new Array(width);
+        const kinds = new Array(width);
+        for (let i = 0; i < width; i++) {
+            const key = keys[i];
             const field = meta.fields[key];
-            return this.escapeId(this.resolveColumnName(key, field));
-        });
+            fields[i] = field;
+            columns[i] = this.escapedColumnName(meta, key);
+            kinds[i] = this.persistKind(field);
+        }
         const tableName = this.resolveTableName(entity, meta);
         ctx.append(`INSERT INTO ${this.escapeId(tableName)} (${columns.join(', ')}) VALUES (`);
-        payloads.forEach((it, recordIndex) => {
-            if (recordIndex > 0) {
+        for (let r = 0; r < payloads.length; r++) {
+            if (r > 0) {
                 ctx.append('), (');
             }
-            keys.forEach((key, keyIndex) => {
-                if (keyIndex > 0) {
+            const record = payloads[r];
+            for (let i = 0; i < width; i++) {
+                if (i > 0) {
                     ctx.append(', ');
                 }
-                const field = meta.fields[key];
-                if (it[key] === undefined) {
-                    this.appendDefaultInsertValue(ctx, field);
+                const value = record[keys[i]];
+                if (value === undefined) {
+                    this.appendDefaultInsertValue(ctx, fields[i]);
+                }
+                else if (kinds[i] === 'plain' && !(value instanceof QueryRaw)) {
+                    // The overwhelmingly common case in a bulk insert, so it binds without a dispatch.
+                    ctx.addValue(value);
                 }
                 else {
-                    this.formatPersistableValue(ctx, field, it[key]);
+                    this.writePersistableValue(ctx, kinds[i], fields[i], value);
                 }
-            });
-        });
+            }
+        }
         ctx.append(')');
     }
     /**
@@ -955,13 +988,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const keys = filterFieldKeys(meta, filledPayload, 'onUpdate');
         const tableName = this.resolveTableName(entity, meta);
         ctx.append(`UPDATE ${this.escapeId(tableName)} SET `);
-        keys.forEach((key, index) => {
-            if (index > 0) {
+        for (let i = 0; i < keys.length; i++) {
+            if (i > 0) {
                 ctx.append(', ');
             }
+            const key = keys[i];
             const field = meta.fields[key];
-            const columnName = this.resolveColumnName(key, field);
-            const escapedCol = this.escapeId(columnName);
+            const escapedCol = this.escapedColumnName(meta, key);
             const value = filledPayload[key];
             if (isJsonUpdateOp(value)) {
                 this.formatJsonUpdate(ctx, escapedCol, value, field);
@@ -970,7 +1003,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 ctx.append(`${escapedCol} = `);
                 this.formatPersistableValue(ctx, field, value);
             }
-        });
+        }
         this.search(ctx, entity, q, opts);
     }
     upsert(ctx, entity, conflictPaths, payload) {
@@ -978,13 +1011,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const updateCtx = this.createContext();
         const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `VALUES(${name})`);
         if (update) {
-            this.insert(ctx, entity, payload);
+            this.appendInsertValues(ctx, entity, payload);
             ctx.append(` ON DUPLICATE KEY UPDATE ${update}`);
             ctx.pushValue(...updateCtx.values);
         }
         else {
             const insertCtx = this.createContext();
-            this.insert(insertCtx, entity, payload);
+            this.appendInsertValues(insertCtx, entity, payload);
             ctx.append(insertCtx.sql.replace(/^INSERT/, 'INSERT IGNORE'));
             ctx.pushValue(...insertCtx.values);
         }
@@ -1039,21 +1072,46 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     escapeId(val, forbidQualified, addDot) {
         return escapeSqlId(val, this.escapeIdChar, forbidQualified, addDot);
     }
+    /**
+     * Bind one persisted value, classifying its column on the spot. Dialects override
+     * {@link appendJsonValue} and {@link appendVectorValue} rather than this, so the chain runs once per
+     * value - overriding this and delegating back to `super` ran every check twice, measurably slowing
+     * every INSERT/UPDATE.
+     */
     formatPersistableValue(ctx, field, value) {
+        this.writePersistableValue(ctx, this.persistKind(field), field, value);
+    }
+    /**
+     * How a column's values are written. A function of the column, not of the value, so a bulk insert
+     * classifies each column once instead of re-deciding per row: a 20-row, 6-column insert asked
+     * `isJsonType` and `isVectorFieldType` 120 times to get the same six answers.
+     */
+    persistKind(field) {
+        const type = field?.type;
+        if (isJsonType(type)) {
+            return 'json';
+        }
+        return isVectorFieldType(type) ? 'vector' : 'plain';
+    }
+    /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
+    writePersistableValue(ctx, kind, field, value) {
         if (value instanceof QueryRaw) {
             this.getRawValue(ctx, { value });
             return;
         }
-        if (isJsonType(field?.type)) {
-            ctx.addValue(value == null ? null : JSON.stringify(value));
+        if (kind === 'json') {
+            this.appendJsonValue(ctx, value, field?.type);
             return;
         }
-        if (field?.type === 'vector' && Array.isArray(value)) {
-            ctx.addValue(`[${value.join(',')}]`);
+        if (kind === 'vector' && Array.isArray(value)) {
+            this.appendVectorValue(ctx, value, field);
             return;
         }
         ctx.addValue(value);
     }
+    appendJsonValue(ctx, value, _type) {
+        ctx.addValue(value == null ? null : JSON.stringify(value));
+    }
     /**
      * Reads `operand` as a JSON value. Passing the `?` placeholder yields the cast for a bound
      * parameter, and passing an expression re-reads text as JSON - the same SQL either way, which is
@@ -1208,97 +1266,85 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return { $eq: val };
     }
     /**
-     * Filter by relation using an EXISTS subquery.
-     * Supports all cardinalities: mm (via junction), 1m, m1, and 11.
+     * A field key's mapped column (`@Field({ name })`), escaped, memoized per dialect instance: field
+     * metadata is shared between dialects while this result is not, since `escapeIdChar` and the naming
+     * strategy differ. Weakly keyed so a transient entity's metadata stays collectable.
      */
+    escapedColumnName(meta, key) {
+        const field = meta.fields[key];
+        if (!field) {
+            return this.escapeId(this.columnOf(meta, key));
+        }
+        let escaped = this.escapedColumns.get(field);
+        if (escaped === undefined) {
+            escaped = this.escapeId(this.columnOf(meta, key));
+            this.escapedColumns.set(field, escaped);
+        }
+        return escaped;
+    }
+    escapedColumn(table, meta, key) {
+        return this.escapeId(table, false, true) + this.escapedColumnName(meta, key);
+    }
+    /** As {@link escapedColumn}, but qualified by the query alias when the parent is nested. */
+    escapedParentColumn(parentTable, meta, opts, key) {
+        return opts.prefix
+            ? this.escapeId(opts.prefix, true, true) + this.escapedColumnName(meta, key)
+            : this.escapedColumn(parentTable, meta, key);
+    }
     /**
-     * The parent side of a relation-filtering subquery: its table name, escaped id reference, and a
-     * guard against a relation with no configured references. Shared by
-     * `compareRelation`/`compareRelationSize`. `rel.references` is asserted non-null at call sites
-     * relying on this guard, since the check lives here instead of in the caller's own scope.
+     * The single path from a relation operator to its target, so none can emit an unscoped subquery:
+     * the target's `$where` is merged with its active filters, making a trashed or out-of-scope row
+     * invisible here just as it is to a joined `$populate`. The caller's filter bypass is deliberately
+     * not propagated (`withDeleted()` does not reach into relations), matching `selectRelationJoins`.
      */
-    resolveRelationParent(entity, key, rel, opts) {
+    appendRelationSubquery(ctx, entity, key, rel, opts, projection, val) {
         const meta = getMeta(entity);
         const parentTable = this.resolveTableName(entity, meta);
         if (!rel.references?.length) {
             throw new TypeError(`Relation '${key}' on '${parentTable}' has no references defined`);
         }
-        const escapedParentId = (opts.prefix ? this.escapeId(opts.prefix, true, true) : this.escapeId(parentTable, false, true)) +
-            this.escapeId(meta.id);
-        return { parentTable, escapedParentId };
-    }
-    compareRelation(ctx, entity, key, val, rel, opts) {
-        const { parentTable, escapedParentId } = this.resolveRelationParent(entity, key, rel, opts);
         const references = rel.references;
+        const escapedParentId = this.escapedParentColumn(parentTable, meta, opts, meta.id);
         const relatedEntity = rel.entity();
         const relatedMeta = getMeta(relatedEntity);
         const relatedTable = this.resolveTableName(relatedEntity, relatedMeta);
-        ctx.append('EXISTS (SELECT 1 FROM ');
+        // Resolved before any SQL is emitted: it also decides whether the mm form reaches the target.
+        const targetWhere = this.scopedWhereMap(relatedMeta, val);
+        ctx.append(`(SELECT ${projection} FROM `);
         if (rel.cardinality === 'mm' && rel.through) {
-            // ManyToMany: EXISTS (SELECT 1 FROM JunctionTable WHERE junction.localFk = parent.id AND junction.foreignFk IN (SELECT related.id FROM Related WHERE ...))
             const throughEntity = rel.through();
             const throughMeta = getMeta(throughEntity);
             const throughTable = this.resolveTableName(throughEntity, throughMeta);
-            const localFk = references[0].local;
-            const foreignFk = references[1].local;
-            const relatedId = relatedMeta.id;
             ctx.append(this.escapeId(throughTable));
-            ctx.append(` WHERE ${this.escapeId(throughTable, false, true)}${this.escapeId(localFk)} = ${escapedParentId}`);
-            ctx.append(` AND ${this.escapeId(throughTable, false, true)}${this.escapeId(foreignFk)} IN (`);
-            ctx.append(`SELECT ${this.escapeId(relatedTable, false, true)}${this.escapeId(relatedId)} FROM ${this.escapeId(relatedTable)}`);
-            this.where(ctx, relatedEntity, val, {
-                prefix: relatedTable,
-                clause: 'WHERE',
-                filters: { softDelete: false },
-            });
-            ctx.append(')');
+            ctx.append(` WHERE ${this.escapedColumn(throughTable, throughMeta, references[0].local)} = ${escapedParentId}`);
+            // The junction is a row being read too: a soft-deleted link is not a link.
+            this.where(ctx, throughEntity, {}, { prefix: throughTable, clause: 'AND' });
+            if (hasKeys(targetWhere)) {
+                ctx.append(` AND ${this.escapedColumn(throughTable, throughMeta, references[1].local)} IN (`);
+                ctx.append(`SELECT ${this.escapedColumn(relatedTable, relatedMeta, relatedMeta.id)} FROM ${this.escapeId(relatedTable)}`);
+                this.renderWhere(ctx, relatedEntity, targetWhere, { prefix: relatedTable, clause: 'WHERE' });
+                ctx.append(')');
+            }
         }
         else {
-            // 1m / m1 / 11: EXISTS (SELECT 1 FROM Related WHERE related.fk_or_pk = parent.pk_or_fk AND ...)
-            // Left side is always relatedTable.references[0].foreign
-            // Right side is the parent's PK (1m) or the parent's FK (m1/11)
-            const joinLeft = `${this.escapeId(relatedTable, false, true)}${this.escapeId(references[0].foreign)}`;
+            const joinLeft = this.escapedColumn(relatedTable, relatedMeta, references[0].foreign);
             const joinRight = rel.cardinality === '1m'
                 ? escapedParentId
-                : (opts.prefix ? this.escapeId(opts.prefix, true, true) : this.escapeId(parentTable, false, true)) +
-                    this.escapeId(references[0].local);
+                : this.escapedParentColumn(parentTable, meta, opts, references[0].local);
             ctx.append(this.escapeId(relatedTable));
             ctx.append(` WHERE ${joinLeft} = ${joinRight}`);
-            this.where(ctx, relatedEntity, val, {
-                prefix: relatedTable,
-                clause: 'AND',
-                filters: { softDelete: false },
-            });
+            this.renderWhere(ctx, relatedEntity, targetWhere, { prefix: relatedTable, clause: 'AND' });
         }
         ctx.append(')');
     }
-    /**
-     * Filter by relation size using a `COUNT(*)` subquery.
-     * Supports all cardinalities: mm (via junction), 1m.
-     */
+    /** Filter by relation: a parent matches when {@link appendRelationSubquery} finds one target row. */
+    compareRelation(ctx, entity, key, val, rel, opts) {
+        ctx.append('EXISTS ');
+        this.appendRelationSubquery(ctx, entity, key, rel, opts, '1', val);
+    }
+    /** Filter by relation size: the same subquery, counting instead of testing for existence. */
     compareRelationSize(ctx, entity, key, sizeVal, rel, opts) {
-        const { escapedParentId } = this.resolveRelationParent(entity, key, rel, opts);
-        const appendSubquery = () => {
-            ctx.append('(SELECT COUNT(*) FROM ');
-            if (rel.cardinality === 'mm' && rel.through) {
-                const throughEntity = rel.through();
-                const throughMeta = getMeta(throughEntity);
-                const throughTable = this.resolveTableName(throughEntity, throughMeta);
-                const localFk = rel.references[0].local;
-                ctx.append(this.escapeId(throughTable));
-                ctx.append(` WHERE ${this.escapeId(throughTable, false, true)}${this.escapeId(localFk)} = ${escapedParentId}`);
-            }
-            else {
-                const relatedEntity = rel.entity();
-                const relatedMeta = getMeta(relatedEntity);
-                const relatedTable = this.resolveTableName(relatedEntity, relatedMeta);
-                const joinLeft = `${this.escapeId(relatedTable, false, true)}${this.escapeId(rel.references[0].foreign)}`;
-                ctx.append(this.escapeId(relatedTable));
-                ctx.append(` WHERE ${joinLeft} = ${escapedParentId}`);
-            }
-            ctx.append(')');
-        };
-        this.buildSizeComparison(ctx, appendSubquery, sizeVal);
+        this.buildSizeComparison(ctx, () => this.appendRelationSubquery(ctx, entity, key, rel, opts, 'COUNT(*)', {}), sizeVal);
     }
     /**
      * Build a complete `$size` comparison expression.
@@ -1331,42 +1377,20 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * Append a single size comparison operator and value to the context.
      */
     appendSizeOp(ctx, op, val) {
-        switch (op) {
-            case '$eq':
-                ctx.append(' = ');
-                ctx.addValue(val);
-                break;
-            case '$ne':
-                ctx.append(' <> ');
-                ctx.addValue(val);
-                break;
-            case '$gt':
-                ctx.append(' > ');
-                ctx.addValue(val);
-                break;
-            case '$gte':
-                ctx.append(' >= ');
-                ctx.addValue(val);
-                break;
-            case '$lt':
-                ctx.append(' < ');
-                ctx.addValue(val);
-                break;
-            case '$lte':
-                ctx.append(' <= ');
-                ctx.addValue(val);
-                break;
-            case '$between': {
-                const [min, max] = val;
-                ctx.append(' BETWEEN ');
-                ctx.addValue(min);
-                ctx.append(' AND ');
-                ctx.addValue(max);
-                break;
-            }
-            default:
-                throw TypeError(`unsupported $size comparison operator: ${op}`);
+        if (op === '$between') {
+            const [min, max] = val;
+            ctx.append(' BETWEEN ');
+            ctx.addValue(min);
+            ctx.append(' AND ');
+            ctx.addValue(max);
+            return;
+        }
+        const sqlOp = AbstractSqlDialect.comparisonOpMap.get(op);
+        if (!sqlOp) {
+            throw TypeError(`unsupported $size comparison operator: ${op}`);
         }
+        ctx.append(` ${sqlOp} `);
+        ctx.addValue(val);
     }
     /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
     escape(value) {
@@ -1408,4 +1432,3 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return this.dialectName;
     }
 }
-//# sourceMappingURL=abstractSqlDialect.js.map

package/dist/dialect/index.d.ts

@@ -4,6 +4,6 @@ export { PostgresDialect } from '../postgres/postgresDialect.js';
 export { SqliteDialect } from '../sqlite/sqliteDialect.js';
 export * from './abstractDialect.js';
 export * from './abstractSqlDialect.js';
+export * from './indexSqlDialect.js';
 export * from './mysqlLikeSqlDialect.js';
 export * from './queryContext.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/dialect/index.js

@@ -4,6 +4,6 @@ export { PostgresDialect } from '../postgres/postgresDialect.js';
 export { SqliteDialect } from '../sqlite/sqliteDialect.js';
 export * from './abstractDialect.js';
 export * from './abstractSqlDialect.js';
+export * from './indexSqlDialect.js';
 export * from './mysqlLikeSqlDialect.js';
 export * from './queryContext.js';
-//# sourceMappingURL=index.js.map

package/dist/dialect/indexSqlDialect.d.ts

@@ -0,0 +1,57 @@
+import { type IndexColumnSchema, type IndexFeature, type IndexSchema } from '../type/index.js';
+import { VectorSqlDialect } from './vectorSqlDialect.js';
+/**
+ * `CREATE INDEX` for SQL dialects: the statement and the fragments each engine spells differently.
+ *
+ * A layer of its own for the same reason as {@link VectorSqlDialect} below it - it needs only
+ * `escapeId` and `features.indexIfNotExists` from the SQL dialect above, so keeping it here spares
+ * that 2000-line class thirteen more members. What each engine can express at all is data
+ * ({@link indexFeatures}), validated once, rather than a throw per feature per dialect.
+ */
+export declare abstract class IndexSqlDialect extends VectorSqlDialect {
+    /**
+     * The `CREATE INDEX` statement for this dialect. The form here is the portable one, which SQLite
+     * (and so libSQL, Turso and D1) takes verbatim: no access-method clause, no operator classes, no
+     * tuning parameters. Dialects that have those override the fragments below rather than this.
+     */
+    getCreateIndexStatement(tableName: string, index: IndexSchema, opts?: {
+        ifNotExists?: boolean;
+    }): string;
+    /**
+     * Index features this dialect can express. Everything here is supported by at least one engine and
+     * refused by at least one other, so an index asking for a missing one is rejected rather than
+     * emitted: each of them is a hard error at the server, not a slower plan.
+     */
+    protected readonly indexFeatures: ReadonlySet<IndexFeature>;
+    private assertIndexFeatures;
+    /**
+     * The column-level declaration for a vector index that lives inside `CREATE TABLE` rather than in
+     * its own statement, which the `inlineVectorIndex` feature flags. Only MariaDB has one.
+     */
+    getInlineVectorIndexDeclaration(index: IndexSchema): string;
+    /** Only CockroachDB's native vector index replaces the `INDEX` keyword. */
+    protected indexKeyword(_index: IndexSchema): string;
+    /** One index entry: what is indexed, its operator class if any, then its stored order. */
+    protected indexColumn(entry: IndexColumnSchema, index: IndexSchema): string;
+    /**
+     * A quoted column, optionally prefix-limited, or an expression in its own parentheses - the form
+     * `((lower("email")))` that MySQL requires and Postgres, CockroachDB and SQLite all accept, so one
+     * rendering serves every engine that has expression indexes.
+     */
+    protected indexColumnTarget(entry: IndexColumnSchema): string;
+    /** Postgres-wire dialects put a vector or user-declared operator class here. */
+    protected indexColumnOpsClass(_entry: IndexColumnSchema, _index: IndexSchema): string;
+    /** `ASC` is every engine's default, so only `DESC` is worth emitting. */
+    protected indexColumnOrder(entry: IndexColumnSchema): string;
+    /** ` INCLUDE (...)`: non-key columns stored for index-only scans. Postgres-wire only. */
+    protected indexInclude(_index: IndexSchema): string;
+    /** ` USING <method>`, which SQLite's grammar has no place for at all. */
+    protected indexAccessMethod(_index: IndexSchema): string;
+    /** pgvector's ` WITH (m = ..., ef_construction = ..., lists = ...)`. */
+    protected indexTuning(_index: IndexSchema): string;
+    /**
+     * The partial-index predicate. Dialects without partial indexes throw instead of dropping it:
+     * silently widening a partial unique index changes which rows the database accepts.
+     */
+    protected indexPredicate(index: IndexSchema): string;
+}