uql-orm 0.20.1 → 0.21.0

package/dist/dialect/abstractDialect.d.ts

@@ -1,4 +1,4 @@
-import type { DialectFeatures, DialectName, EntityMeta, FieldOptions, InsertIdSource, NamingStrategy, Type } from '../type/index.js';
+import type { DialectFeatures, DialectName, EntityMeta, FieldOptions, InsertIdSource, NamingStrategy, QueryOptions, QueryWhere, QueryWhereMap, Type } from '../type/index.js';
 /**
  * Options for initializing a dialect.
  */
@@ -36,5 +36,16 @@ export declare abstract class AbstractDialect {
      * Resolve the column/field name for a property, applying naming strategy if necessary.
      */
     resolveColumnName(key: string, field: FieldOptions | undefined): string;
+    /**
+     * {@link resolveColumnName} for a field key of `meta` - the form query builders need, so reading a
+     * column never depends on looking the field up by hand first. `MongoDialect` overrides it to map the
+     * primary key to `_id`.
+     */
+    columnOf<E>(meta: EntityMeta<E>, key: string): string;
+    /**
+     * A `$where` normalized to a map with the entity's active filters merged in - the only way any
+     * dialect should enter a new query scope, so a scope cannot be rendered with its `security: true`
+     * filters skipped. Recursion within one scope renders the returned map directly instead.
+     */
+    protected scopedWhereMap<E>(meta: EntityMeta<E>, where?: QueryWhere<E>, opts?: QueryOptions): QueryWhereMap<E>;
 }
-//# sourceMappingURL=abstractDialect.d.ts.map

package/dist/dialect/abstractDialect.js

@@ -1,3 +1,4 @@
+import { applyFilters, buildQueryWhereAsMap } from '../util/dialect.util.js';
 /**
  * Base abstract class for all database dialects (SQL and NoSQL).
  */
@@ -37,5 +38,20 @@ export class AbstractDialect {
         }
         return this.namingStrategy.columnName(field.name);
     }
+    /**
+     * {@link resolveColumnName} for a field key of `meta` - the form query builders need, so reading a
+     * column never depends on looking the field up by hand first. `MongoDialect` overrides it to map the
+     * primary key to `_id`.
+     */
+    columnOf(meta, key) {
+        return this.resolveColumnName(key, meta.fields[key]);
+    }
+    /**
+     * A `$where` normalized to a map with the entity's active filters merged in - the only way any
+     * dialect should enter a new query scope, so a scope cannot be rendered with its `security: true`
+     * filters skipped. Recursion within one scope renders the returned map directly instead.
+     */
+    scopedWhereMap(meta, where = {}, opts) {
+        return applyFilters(meta, buildQueryWhereAsMap(meta, where), opts);
+    }
 }
-//# sourceMappingURL=abstractDialect.js.map

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, type QueryPopulate, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelect, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationOptions, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, type QueryPopulate, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelect, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationOptions, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
 import { VectorSqlDialect } from './vectorSqlDialect.js';
 export declare abstract class AbstractSqlDialect extends VectorSqlDialect implements QueryDialect, SqlQueryDialect {
     abstract readonly dialectName: SqlDialectName;
@@ -66,6 +66,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     compare<E>(ctx: QueryContext, entity: Type<E>, key: string, val: unknown, opts?: QueryComparisonOptions): void;
     protected compareLogicalOperator<E>(ctx: QueryContext, entity: Type<E>, key: '$and' | '$or' | '$not' | '$nor', val: QueryWhereArray<E>, opts: QueryComparisonOptions): void;
     /** Simple comparison operators: `getComparisonKey → op → addValue`. */
+    /** Memoizes {@link escapedColumnName}; see there for why it is per dialect instance. */
+    private readonly escapedColumns;
     private static readonly NEGATE_OP_MAP;
     private static readonly COMPARE_OP_MAP;
     private static readonly LIKE_OP_MAP;
@@ -188,7 +190,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected having(ctx: QueryContext, having: QueryHavingMap, aggregateExpressions: Record<string, string>): void;
     private static readonly SORT_DIRECTION_MAP;
     private resolveSortDirection;
-    private static readonly havingOpMap;
+    /** Scalar comparison operators shared by `HAVING` conditions and `$size` comparisons. */
+    private static readonly comparisonOpMap;
     protected havingCondition(ctx: QueryContext, expr: string, condition: QueryHavingMap[string]): void;
     find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions): void;
     insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
@@ -204,7 +207,14 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected getUpsertConflictPathsStr<E>(meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>): string;
     delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
     escapeId(val: string, forbidQualified?: boolean, addDot?: boolean): string;
-    protected formatPersistableValue<E>(ctx: QueryContext, field: FieldOptions | undefined, value: unknown): void;
+    /**
+     * The single type dispatch for a persisted value. 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.
+     */
+    protected formatPersistableValue(ctx: QueryContext, field: FieldOptions | undefined, value: unknown): void;
+    protected appendJsonValue(ctx: QueryContext, value: unknown, _type: JsonColumnType): void;
+    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
     /**
      * 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
@@ -274,21 +284,24 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     private normalizeWhereValue;
     /**
-     * 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.
      */
+    private escapedColumnName;
+    private escapedColumn;
+    /** As {@link escapedColumn}, but qualified by the query alias when the parent is nested. */
+    private escapedParentColumn;
     /**
-     * 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`.
      */
-    private resolveRelationParent;
+    private appendRelationSubquery;
+    /** Filter by relation: a parent matches when {@link appendRelationSubquery} finds one target row. */
     protected compareRelation<E>(ctx: QueryContext, entity: Type<E>, key: string, val: QueryWhereMap<unknown>, rel: RelationOptions, opts: QueryComparisonOptions): void;
-    /**
-     * Filter by relation size using a `COUNT(*)` subquery.
-     * Supports all cardinalities: mm (via junction), 1m.
-     */
+    /** Filter by relation size: the same subquery, counting instead of testing for existence. */
     protected compareRelationSize<E>(ctx: QueryContext, entity: Type<E>, key: string, sizeVal: number | QuerySizeComparisonOps, rel: RelationOptions, opts: QueryComparisonOptions): void;
     /**
      * Build a complete `$size` comparison expression.
@@ -319,4 +332,3 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected numericCast(expr: string): string;
     toString(): string;
 }
-//# sourceMappingURL=abstractSqlDialect.d.ts.map

package/dist/dialect/abstractSqlDialect.js

@@ -1,7 +1,7 @@
 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, getFieldKeys, 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 { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
 import { JSON_ELEM_ALIAS_PREFIX, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
@@ -81,7 +81,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 = {}) {
@@ -239,9 +239,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 = {}) {
@@ -322,13 +321,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 +379,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 +796,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 +857,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 +898,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} `);
@@ -916,29 +914,36 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const meta = getMeta(entity);
         const payloads = fillOnFields(meta, payload, 'onInsert');
         const keys = getInsertFieldKeys(meta, payloads);
-        const columns = keys.map((key) => {
-            const field = meta.fields[key];
-            return this.escapeId(this.resolveColumnName(key, field));
-        });
+        // 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);
+        for (let i = 0; i < width; i++) {
+            const key = keys[i];
+            fields[i] = meta.fields[key];
+            columns[i] = this.escapedColumnName(meta, key);
+        }
         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 {
-                    this.formatPersistableValue(ctx, field, it[key]);
+                    this.formatPersistableValue(ctx, fields[i], value);
                 }
-            });
-        });
+            }
+        }
         ctx.append(')');
     }
     /**
@@ -955,13 +960,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 +975,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) {
@@ -1039,21 +1044,33 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     escapeId(val, forbidQualified, addDot) {
         return escapeSqlId(val, this.escapeIdChar, forbidQualified, addDot);
     }
+    /**
+     * The single type dispatch for a persisted value. 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) {
         if (value instanceof QueryRaw) {
             this.getRawValue(ctx, { value });
             return;
         }
-        if (isJsonType(field?.type)) {
-            ctx.addValue(value == null ? null : JSON.stringify(value));
+        const type = field?.type;
+        if (isJsonType(type)) {
+            this.appendJsonValue(ctx, value, type);
             return;
         }
-        if (field?.type === 'vector' && Array.isArray(value)) {
-            ctx.addValue(`[${value.join(',')}]`);
+        if (type === 'vector' && Array.isArray(value)) {
+            this.appendVectorValue(ctx, value);
             return;
         }
         ctx.addValue(value);
     }
+    appendJsonValue(ctx, value, _type) {
+        ctx.addValue(value == null ? null : JSON.stringify(value));
+    }
+    appendVectorValue(ctx, value) {
+        ctx.addValue(`[${value.join(',')}]`);
+    }
     /**
      * 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 +1225,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 +1336,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 +1391,3 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return this.dialectName;
     }
 }
-//# sourceMappingURL=abstractSqlDialect.js.map

package/dist/dialect/index.d.ts

@@ -6,4 +6,3 @@ export * from './abstractDialect.js';
 export * from './abstractSqlDialect.js';
 export * from './mysqlLikeSqlDialect.js';
 export * from './queryContext.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/dialect/index.js

@@ -6,4 +6,3 @@ export * from './abstractDialect.js';
 export * from './abstractSqlDialect.js';
 export * from './mysqlLikeSqlDialect.js';
 export * from './queryContext.js';
-//# sourceMappingURL=index.js.map

package/dist/dialect/jsonArrayElemMatchUtils.d.ts

@@ -6,4 +6,3 @@
  * identical - they used to take different code paths and emit different SQL.
  */
 export declare function buildElemMatchConditions(match: Record<string, unknown>, onCondition: (field: string, op: string, value: unknown) => string): string[];
-//# sourceMappingURL=jsonArrayElemMatchUtils.d.ts.map

package/dist/dialect/jsonArrayElemMatchUtils.js

@@ -11,4 +11,3 @@ export function buildElemMatchConditions(match, onCondition) {
         ? Object.entries(value).map(([op, opVal]) => onCondition(field, op, opVal))
         : onCondition(field, '$eq', value));
 }
-//# sourceMappingURL=jsonArrayElemMatchUtils.js.map

package/dist/dialect/jsonSql.d.ts

@@ -41,4 +41,3 @@ export declare function jsonSetTarget(expr: string, field: FieldOptions | undefi
 export declare function jsonRemoveCall(fn: string, expr: string, keys: readonly string[]): string;
 /** `WHERE` is omitted for an empty `$elemMatch`, which asks only that the array has an element. */
 export declare function jsonElemExists(from: string, conditions: readonly string[]): string;
-//# sourceMappingURL=jsonSql.d.ts.map

package/dist/dialect/jsonSql.js

@@ -1,4 +1,4 @@
-import { escapeSingleQuotes } from '../util/ansiSqlLiteral.js';
+import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 /**
  * Alias prefix for the derived table a dialect explodes a JSON array into to test `$all`/
  * `$elemMatch` (e.g. SQLite's `json_each(col) AS _uql_elem_1`). Passed to
@@ -54,4 +54,3 @@ export function jsonElemExists(from, conditions) {
     const where = conditions.length ? ` WHERE ${conditions.join(' AND ')}` : '';
     return `EXISTS (SELECT 1 FROM ${from}${where})`;
 }
-//# sourceMappingURL=jsonSql.js.map

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -72,4 +72,3 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     protected jsonElemFrom(jsonField: string, fields: readonly string[], alias: string, asJson?: boolean): string;
     protected jsonElemRef(alias: string, field?: string, asJson?: boolean): string;
 }
-//# sourceMappingURL=mysqlLikeSqlDialect.d.ts.map

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -1,5 +1,4 @@
-import SqlString from 'sqlstring';
-import { escapeSingleQuotes } from '../util/ansiSqlLiteral.js';
+import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS, jsonAssignCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.js';
 /**
@@ -46,7 +45,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     insertIdSource = 'firstId';
     maxBindValues = 65535;
     escape(value) {
-        return SqlString.escape(value);
+        return escapeMysqlSqlLiteral(value);
     }
     numericCast(expr) {
         return `CAST(${expr} AS DECIMAL)`;
@@ -132,4 +131,3 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         return asJson ? this.jsonCast(ref) : ref;
     }
 }
-//# sourceMappingURL=mysqlLikeSqlDialect.js.map