uql-orm 0.79.0 → 0.80.0

package/dist/mongo/mongoDialect.d.ts

@@ -36,9 +36,6 @@ export declare class MongoDialect extends AbstractDialect {
     readonly features: DialectFeatures;
     readonly dialectName = "mongodb";
     readonly insertIdSource = "returning";
-    private static readonly ID_KEY;
-    /** Atlas rejects a `$vectorSearch` asking for more candidates than this. */
-    private static readonly MAX_NUM_CANDIDATES;
     /**
      * MongoDB stores the primary key as `_id`; everything else resolves as usual. Projections, sorts,
      * `$group` refs and `$where` keys all map through here, so no read path can address a property name
@@ -70,14 +67,6 @@ export declare class MongoDialect extends AbstractDialect {
      * relation subquery can no more read out-of-scope rows than a direct query on the target can.
      */
     private appendRelationLookup;
-    /** Adds `expr` to `filter`'s `$expr`, `AND`ed with any already there. */
-    private static andExpr;
-    /**
-     * `$size` against bounds, which MongoDB's own `$size` takes only as a number: the array at `path` counted
-     * in an `$expr`, which no other value satisfies. `$and` may evaluate every operand, so the count reads an
-     * empty array in place of any other value.
-     */
-    private static arraySize;
     /**
      * The correlated `$lookup` for the target rows of one relation `where` narrows, as `temp`: straight at
      * the target, or for a many-to-many from inside its junction's rows. The caller's filter bypass is not
@@ -91,8 +80,6 @@ export declare class MongoDialect extends AbstractDialect {
      * Each end is one field matched against one `_id`, so both sides must be sole-keyed.
      */
     private junctionOf;
-    /** `count` compared with `size`, a number or its bounds, as an aggregation expression. */
-    private static compareCount;
     /** Whether a query subtracts `key` from the projection, via `$exclude` or a negative `$select`. */
     private subtractsKey;
     /** `raw()` renders SQL, so it has no MongoDB equivalent - say so instead of emitting `{}`. */
@@ -103,10 +90,6 @@ export declare class MongoDialect extends AbstractDialect {
      * apply to JSON paths.
      */
     private assertKnownPathRoot;
-    /** String operators -> { pattern: (v) => regex, caseInsensitive } */
-    private static readonly REGEX_OP_MAP;
-    /** MongoDB native operators - pass through as-is. */
-    private static readonly NATIVE_OPS;
     /**
      * Transform UQL operators to MongoDB operators.
      */
@@ -271,10 +254,6 @@ export declare class MongoDialect extends AbstractDialect {
      * filters included, so each relation aggregate among them is put on the document first.
      */
     private buildGroupSpec;
-    /** `1` where `ref` holds a value, `0` where it is null or missing, which an expression tells apart. */
-    private static countOf;
-    /** Whether `ref` is null or missing: an expression compares a missing field as neither. */
-    private static isNullExpr;
     /** The field a grouped path reads, on the document or on the joined one its lookup unwound. */
     private groupedPath;
     /**

package/dist/mongo/mongoDialect.js

@@ -1,6 +1,7 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
 import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, nullsSortField, sortAggregateField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
+import { GROUP_OPS, groupClauses, isGroupOp } from '../dialect/operators.js';
 import { aggregateColumnField, groupPathField, resolveGroupJoins, relationSortTerms, resolveQueryJoins, resolveSortableJoin, } from '../dialect/queryJoins.js';
 import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/query.js';
@@ -15,7 +16,6 @@ const EMPTY_SORT_PLAN = { sort: {}, stages: [], fields: [] };
 const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
 /** Default {@link DialectFeatures} for MongoDB. */
 export const mongoDialectFeatures = {
-    ifNotExists: false,
     indexIfNotExists: false,
     schemas: false, // the connection picks the database, and a collection name takes no dot
     dropTableCascade: false,
@@ -39,29 +39,93 @@ const HEX_24 = /^[0-9a-f]{24}$/i;
 function declaredTypeName(type) {
     return typeof type === 'function' ? type.name : String(type);
 }
+const ID_KEY = '_id';
+/** Atlas rejects a `$vectorSearch` asking for more candidates than this. */
+const MAX_NUM_CANDIDATES = 10_000;
+/** Adds `expr` to `filter`'s `$expr`, `AND`ed with any already there. */
+function andExpr(filter, expr) {
+    filter['$expr'] = filter['$expr'] ? { $and: [filter['$expr'], expr] } : expr;
+}
+/**
+ * `$size` against bounds, which MongoDB's own `$size` takes only as a number: the array at `path` counted
+ * in an `$expr`, which no other value satisfies. `$and` may evaluate every operand, so the count reads an
+ * empty array in place of any other value.
+ */
+function arraySize(path, size) {
+    const value = `$${path}`;
+    const count = { $size: { $cond: [{ $isArray: value }, value, []] } };
+    return { $and: [{ $isArray: value }, compareCount(count, size)] };
+}
+/** `count` compared with `size`, a number or its bounds, as an aggregation expression. */
+function compareCount(count, size) {
+    if (typeof size === 'number') {
+        return { $eq: [count, size] };
+    }
+    const comparisons = Object.entries(size)
+        .filter(([, bound]) => bound !== undefined)
+        .flatMap(([op, bound]) => op === '$between' && Array.isArray(bound)
+        ? [{ $gte: [count, bound[0]] }, { $lte: [count, bound[1]] }]
+        : [{ [op]: [count, bound] }]);
+    if (!comparisons.length) {
+        throw new UqlUsageError('$size needs at least one comparison');
+    }
+    return comparisons.length === 1 ? comparisons[0] : { $and: comparisons };
+}
+/** String operators -> { pattern: (v) => regex, caseInsensitive } */
+const REGEX_OP_MAP = new Map([
+    ['$startsWith', { wrap: (v) => `^${v}`, ci: false }],
+    ['$istartsWith', { wrap: (v) => `^${v}`, ci: true }],
+    ['$endsWith', { wrap: (v) => `${v}$`, ci: false }],
+    ['$iendsWith', { wrap: (v) => `${v}$`, ci: true }],
+    ['$includes', { wrap: (v) => String(v), ci: false }],
+    ['$iincludes', { wrap: (v) => String(v), ci: true }],
+    ['$like', { wrap: (v) => String(v).replace(/%/g, '.*').replace(/_/g, '.'), ci: false }],
+    ['$ilike', { wrap: (v) => String(v).replace(/%/g, '.*').replace(/_/g, '.'), ci: true }],
+]);
+/** MongoDB native operators - pass through as-is. */
+const NATIVE_OPS = new Set([
+    '$all',
+    '$size',
+    '$elemMatch',
+    '$eq',
+    '$ne',
+    '$lt',
+    '$lte',
+    '$gt',
+    '$gte',
+    '$in',
+    '$nin',
+    '$regex',
+    '$not',
+]);
+/** `1` where `ref` holds a value, `0` where it is null or missing, which an expression tells apart. */
+function countOf(ref) {
+    return { $cond: [isNullExpr(ref), 0, 1] };
+}
+/** Whether `ref` is null or missing: an expression compares a missing field as neither. */
+function isNullExpr(ref) {
+    return { $eq: [{ $ifNull: [ref, null] }, null] };
+}
 export class MongoDialect extends AbstractDialect {
     features = mongoDialectFeatures;
     dialectName = 'mongodb';
     // The MongoDB driver reports the exact `_id` of every inserted document (`insertedIds`).
     insertIdSource = 'returning';
-    static ID_KEY = '_id';
-    /** Atlas rejects a `$vectorSearch` asking for more candidates than this. */
-    static MAX_NUM_CANDIDATES = 10_000;
     /**
      * MongoDB stores the primary key as `_id`; everything else resolves as usual. Projections, sorts,
      * `$group` refs and `$where` keys all map through here, so no read path can address a property name
      * the document does not use.
      */
     columnOf(meta, key) {
-        if (key === MongoDialect.ID_KEY) {
-            return MongoDialect.ID_KEY;
+        if (key === ID_KEY) {
+            return ID_KEY;
         }
         if (meta.fields[key]?.isId) {
             // A document has one `_id`. A composite key is a different document shape - a sub-document,
             // whose field order decides equality - rather than a translation, so it is refused here, which
             // every read reaches, and in `getPersistables`, which every write reaches.
             assertSoleId(meta, 'MongoDB');
-            return MongoDialect.ID_KEY;
+            return ID_KEY;
         }
         return super.columnOf(meta, key);
     }
@@ -99,7 +163,7 @@ export class MongoDialect extends AbstractDialect {
         for (const [rawKey, rawVal] of Object.entries(where)) {
             let key = rawKey;
             let val = rawVal;
-            if (MongoDialect.isGroupOp(key)) {
+            if (isGroupOp(key)) {
                 this.appendLogicalOperator(filter, entity, key, val, lookups);
             }
             else if (key === '$text') {
@@ -126,7 +190,7 @@ export class MongoDialect extends AbstractDialect {
                 }
                 const isReference = !!meta.fields[key]?.references;
                 key = this.pathOf(meta, key);
-                if ((key === MongoDialect.ID_KEY || isReference) && !isOperatorObject(val)) {
+                if ((key === ID_KEY || isReference) && !isOperatorObject(val)) {
                     val = this.toWireId(val);
                 }
                 if (!isOperatorObject(val)) {
@@ -139,7 +203,7 @@ export class MongoDialect extends AbstractDialect {
                     filter[key] = this.transformOperators(val);
                 }
                 else {
-                    MongoDialect.andExpr(filter, MongoDialect.arraySize(key, size));
+                    andExpr(filter, arraySize(key, size));
                     if (hasKeys(ops)) {
                         filter[key] = this.transformOperators(ops);
                     }
@@ -153,8 +217,8 @@ export class MongoDialect extends AbstractDialect {
      * wrapped in one `$and`), dropping empty clauses, since MongoDB refuses an empty operator.
      */
     appendLogicalOperator(filter, entity, key, val, lookups) {
-        const { join, negate } = MongoDialect.GROUP_OPS[key];
-        const parts = MongoDialect.groupClauses(key, val)
+        const { join, negate } = GROUP_OPS[key];
+        const parts = groupClauses(key, val)
             .map((filterIt) => {
             this.assertNoRaw(filterIt);
             return this.renderFilter(entity, filterIt, lookups);
@@ -187,23 +251,9 @@ export class MongoDialect extends AbstractDialect {
             filter[`${temp}.0`] = { $exists: true };
         }
         else {
-            MongoDialect.andExpr(filter, MongoDialect.compareCount(this.tally(temp), sizeVal));
+            andExpr(filter, compareCount(this.tally(temp), sizeVal));
         }
     }
-    /** Adds `expr` to `filter`'s `$expr`, `AND`ed with any already there. */
-    static andExpr(filter, expr) {
-        filter['$expr'] = filter['$expr'] ? { $and: [filter['$expr'], expr] } : expr;
-    }
-    /**
-     * `$size` against bounds, which MongoDB's own `$size` takes only as a number: the array at `path` counted
-     * in an `$expr`, which no other value satisfies. `$and` may evaluate every operand, so the count reads an
-     * empty array in place of any other value.
-     */
-    static arraySize(path, size) {
-        const value = `$${path}`;
-        const count = { $size: { $cond: [{ $isArray: value }, value, []] } };
-        return { $and: [{ $isArray: value }, MongoDialect.compareCount(count, size)] };
-    }
     /**
      * The correlated `$lookup` for the target rows of one relation `where` narrows, as `temp`: straight at
      * the target, or for a many-to-many from inside its junction's rows. The caller's filter bypass is not
@@ -226,7 +276,7 @@ export class MongoDialect extends AbstractDialect {
             $lookup: {
                 from,
                 localField: junction.target,
-                foreignField: MongoDialect.ID_KEY,
+                foreignField: ID_KEY,
                 pipeline: [...targetMatch, { $limit: 1 }],
                 as: REL_NESTED_KEY,
             },
@@ -254,28 +304,13 @@ export class MongoDialect extends AbstractDialect {
         return {
             lookup: {
                 from: this.resolveTableName(throughMeta),
-                localField: MongoDialect.ID_KEY,
+                localField: ID_KEY,
                 foreignField: this.columnOf(throughMeta, parentJoin.joined),
             },
             scope: hasKeys(scope) ? [{ $match: scope }] : [],
             target: this.columnOf(throughMeta, targetColumn),
         };
     }
-    /** `count` compared with `size`, a number or its bounds, as an aggregation expression. */
-    static compareCount(count, size) {
-        if (typeof size === 'number') {
-            return { $eq: [count, size] };
-        }
-        const comparisons = Object.entries(size)
-            .filter(([, bound]) => bound !== undefined)
-            .flatMap(([op, bound]) => op === '$between' && Array.isArray(bound)
-            ? [{ $gte: [count, bound[0]] }, { $lte: [count, bound[1]] }]
-            : [{ [op]: [count, bound] }]);
-        if (!comparisons.length) {
-            throw new UqlUsageError('$size needs at least one comparison');
-        }
-        return comparisons.length === 1 ? comparisons[0] : { $and: comparisons };
-    }
     /** Whether a query subtracts `key` from the projection, via `$exclude` or a negative `$select`. */
     subtractsKey(key, select, exclude) {
         const at = (map) => map?.[key];
@@ -294,38 +329,11 @@ export class MongoDialect extends AbstractDialect {
      */
     assertKnownPathRoot(meta, key) {
         const root = key.includes('.') ? key.slice(0, key.indexOf('.')) : key;
-        if (root === MongoDialect.ID_KEY || meta.fields[root]) {
+        if (root === ID_KEY || meta.fields[root]) {
             return;
         }
         throw new UqlUsageError(`path ${key} does not exist in ${entityName(meta)}`);
     }
-    /** String operators -> { pattern: (v) => regex, caseInsensitive } */
-    static REGEX_OP_MAP = new Map([
-        ['$startsWith', { wrap: (v) => `^${v}`, ci: false }],
-        ['$istartsWith', { wrap: (v) => `^${v}`, ci: true }],
-        ['$endsWith', { wrap: (v) => `${v}$`, ci: false }],
-        ['$iendsWith', { wrap: (v) => `${v}$`, ci: true }],
-        ['$includes', { wrap: (v) => String(v), ci: false }],
-        ['$iincludes', { wrap: (v) => String(v), ci: true }],
-        ['$like', { wrap: (v) => String(v).replace(/%/g, '.*').replace(/_/g, '.'), ci: false }],
-        ['$ilike', { wrap: (v) => String(v).replace(/%/g, '.*').replace(/_/g, '.'), ci: true }],
-    ]);
-    /** MongoDB native operators - pass through as-is. */
-    static NATIVE_OPS = new Set([
-        '$all',
-        '$size',
-        '$elemMatch',
-        '$eq',
-        '$ne',
-        '$lt',
-        '$lte',
-        '$gt',
-        '$gte',
-        '$in',
-        '$nin',
-        '$regex',
-        '$not',
-    ]);
     /**
      * Transform UQL operators to MongoDB operators.
      */
@@ -339,6 +347,11 @@ export class MongoDialect extends AbstractDialect {
                 result[op] = this.held(val);
                 continue;
             }
+            // `$not` wraps a condition too, so a uql-only operator inside it (`$isNull`, `$startsWith`) is mapped.
+            if (op === '$not' && isOperatorObject(val)) {
+                result[op] = this.transformOperators(val);
+                continue;
+            }
             // An object or an array is matched by what it holds, as the SQL engines read it, where native `$all`
             // compares the whole element. MongoDB takes `$elemMatch` there only when every value is one.
             if (op === '$all' && Array.isArray(val) && val.some((value) => Array.isArray(value) || isOperatorMap(value))) {
@@ -346,12 +359,12 @@ export class MongoDialect extends AbstractDialect {
                 continue;
             }
             // Native MongoDB operators - pass through directly
-            if (MongoDialect.NATIVE_OPS.has(op)) {
+            if (NATIVE_OPS.has(op)) {
                 result[op] = val;
                 continue;
             }
             // String/pattern -> regex operators (8 variants including $like/$ilike)
-            const regexEntry = MongoDialect.REGEX_OP_MAP.get(op);
+            const regexEntry = REGEX_OP_MAP.get(op);
             if (regexEntry) {
                 result['$regex'] = regexEntry.wrap(val);
                 if (regexEntry.ci)
@@ -443,7 +456,7 @@ export class MongoDialect extends AbstractDialect {
         // `_id: 0` - the one inclusion/exclusion mix MongoDB allows - or `$exclude: { id: true }` would
         // have no effect at all.
         if (this.subtractsKey(soleIdOf(meta, 'MongoDB'), selectMap, exclude)) {
-            projection[MongoDialect.ID_KEY] = 0;
+            projection[ID_KEY] = 0;
         }
         return projection;
     }
@@ -669,7 +682,7 @@ export class MongoDialect extends AbstractDialect {
                 $lookup: {
                     from,
                     localField: `${temp}.${junction.target}`,
-                    foreignField: MongoDialect.ID_KEY,
+                    foreignField: ID_KEY,
                     ...pipeline,
                     as: relKey,
                 },
@@ -846,7 +859,7 @@ export class MongoDialect extends AbstractDialect {
             const relationProjection = this.pipelineProjection(join.entity, join.query);
             // MongoDB returns `_id` unless a projection subtracts it, so dropping the key from the map is
             // how a joined document keeps its own id, as it does on the SQL dialects.
-            delete relationProjection?.[MongoDialect.ID_KEY];
+            delete relationProjection?.[ID_KEY];
             const lookupPipeline = [
                 ...(hasKeys(relationFilter) ? [{ $match: relationFilter }] : []),
                 ...this.lookupStages(join.meta, joins, join),
@@ -879,9 +892,9 @@ export class MongoDialect extends AbstractDialect {
             // rows of every key that agrees on it. The other branch is refused by `columnOf` below, whose
             // key *is* an id column; this one names a plain foreign key, so it has to say so itself.
             assertSoleId(relMeta, 'MongoDB');
-            return { localField: this.columnOf(meta, relOpts.references[0].local), foreignField: MongoDialect.ID_KEY };
+            return { localField: this.columnOf(meta, relOpts.references[0].local), foreignField: ID_KEY };
         }
-        return { localField: MongoDialect.ID_KEY, foreignField: this.columnOf(relMeta, relOpts.references[0].foreign) };
+        return { localField: ID_KEY, foreignField: this.columnOf(relMeta, relOpts.references[0].foreign) };
     }
     /** `[column, key]` for the fields whose stored name differs from their property name, memoized per entity. */
     renamedColumns(meta) {
@@ -914,7 +927,7 @@ export class MongoDialect extends AbstractDialect {
             return doc;
         }
         const res = doc;
-        const _id = MongoDialect.ID_KEY;
+        const _id = ID_KEY;
         // `!== undefined`, not truthiness: `0` is a key MongoDB accepts and a truthy test dropped it.
         if (res[_id] !== undefined) {
             const idKey = soleIdOf(meta, 'MongoDB');
@@ -1079,7 +1092,7 @@ export class MongoDialect extends AbstractDialect {
                 // Nothing named the key, so the database is being asked to mint one.
                 this.assertMintableKey(meta, fieldOf(meta, idKey));
             }
-            const doc = named ? { [MongoDialect.ID_KEY]: this.toWireId(it[idKey]) } : {};
+            const doc = named ? { [ID_KEY]: this.toWireId(it[idKey]) } : {};
             for (const key of filterFieldKeys(meta, it, callbackKey)) {
                 if (key === idKey)
                     continue;
@@ -1166,7 +1179,7 @@ export class MongoDialect extends AbstractDialect {
             }
             else if (entry.op === '$count') {
                 // COUNT(field) counts the non-null values, as SQL does.
-                accumulators[entry.alias] = { $sum: read(MongoDialect.countOf(ref), 0) };
+                accumulators[entry.alias] = { $sum: read(countOf(ref), 0) };
             }
             else {
                 // `$sum`, `$avg`, `$min` and `$max` are MongoDB accumulators of the same name, and skip a null.
@@ -1174,20 +1187,12 @@ export class MongoDialect extends AbstractDialect {
             }
             if (entry.op === '$sum' && !entry.distinct) {
                 const counted = `${SUM_COUNT_ALIAS}_${entry.alias}`;
-                accumulators[counted] = { $sum: read(MongoDialect.countOf(ref), 0) };
+                accumulators[counted] = { $sum: read(countOf(ref), 0) };
                 columns[entry.alias] = { $cond: [{ $eq: [`$${counted}`, 0] }, null, `$${entry.alias}`] };
             }
         }
         return { groupId, accumulators, columns, named };
     }
-    /** `1` where `ref` holds a value, `0` where it is null or missing, which an expression tells apart. */
-    static countOf(ref) {
-        return { $cond: [MongoDialect.isNullExpr(ref), 0, 1] };
-    }
-    /** Whether `ref` is null or missing: an expression compares a missing field as neither. */
-    static isNullExpr(ref) {
-        return { $eq: [{ $ifNull: [ref, null] }, null] };
-    }
     /** The field a grouped path reads, on the document or on the joined one its lookup unwound. */
     groupedPath(meta, joins, path, named) {
         const { key, join } = groupPathField(joins, path);
@@ -1209,9 +1214,9 @@ export class MongoDialect extends AbstractDialect {
         const terms = getKeys(where)
             .filter((key) => where[key] !== undefined)
             .map((key) => {
-            if (MongoDialect.isGroupOp(key)) {
-                const { join, negate } = MongoDialect.GROUP_OPS[key];
-                const clauses = MongoDialect.groupClauses(key, where[key]).map((clause) => {
+            if (isGroupOp(key)) {
+                const { join, negate } = GROUP_OPS[key];
+                const clauses = groupClauses(key, where[key]).map((clause) => {
                     if (clause instanceof QueryRaw) {
                         throw new UqlUsageError('raw SQL is not supported in an aggregate $where on MongoDB');
                     }
@@ -1225,19 +1230,19 @@ export class MongoDialect extends AbstractDialect {
             const val = where[key];
             named.push(key);
             const path = this.pathOf(meta, key);
-            const wire = (value) => path === MongoDialect.ID_KEY || meta.fields[key]?.references ? this.toWireId(value) : value;
+            const wire = (value) => path === ID_KEY || meta.fields[key]?.references ? this.toWireId(value) : value;
             return this.fieldExpression(`$${path}`, val, wire);
         });
         return terms.length === 1 ? terms[0] : { $and: terms };
     }
     /** One field's condition as an expression: a value it equals, a list it is in, or a map of comparisons. */
     fieldExpression(ref, val, wire) {
-        const equals = (value) => (value === null ? MongoDialect.isNullExpr(ref) : { $eq: [ref, wire(value)] });
+        const equals = (value) => (value === null ? isNullExpr(ref) : { $eq: [ref, wire(value)] });
         if (!isOperatorMap(val)) {
             return Array.isArray(val) ? { $in: [ref, wire(val)] } : equals(val);
         }
         // A null or missing field compares below every value in an expression, where SQL leaves it unmatched.
-        const present = { $not: [MongoDialect.isNullExpr(ref)] };
+        const present = { $not: [isNullExpr(ref)] };
         const terms = Object.entries(val).map(([op, operand]) => {
             switch (op) {
                 case '$eq':
@@ -1259,9 +1264,9 @@ export class MongoDialect extends AbstractDialect {
                     return { $and: [{ $gte: [ref, wire(min)] }, { $lte: [ref, wire(max)] }] };
                 }
                 case '$isNull':
-                    return operand ? MongoDialect.isNullExpr(ref) : present;
+                    return operand ? isNullExpr(ref) : present;
                 case '$isNotNull':
-                    return operand ? present : MongoDialect.isNullExpr(ref);
+                    return operand ? present : isNullExpr(ref);
                 default:
                     throw new UqlUsageError(`aggregate $where operator '${op}' is not supported on MongoDB`);
             }
@@ -1331,7 +1336,7 @@ export class MongoDialect extends AbstractDialect {
             queryVector: [...search.$vector],
             // `$candidates` is the caller's own budget; the fallback is 10x the limit, which is what Atlas
             // suggests as a floor. Either way it is clamped: Atlas rejects a stage asking for more.
-            numCandidates: Math.min(candidates ?? limit * 10, MongoDialect.MAX_NUM_CANDIDATES),
+            numCandidates: Math.min(candidates ?? limit * 10, MAX_NUM_CANDIDATES),
             limit,
         };
         // Pre-filter: merge $where into $vectorSearch.filter

package/dist/mongo/mongodbQuerier.js

@@ -2,7 +2,8 @@ import { AGGREGATE_VALUE_ALIAS } from '../dialect/aliases.js';
 import { hasRequiredJoin } from '../dialect/queryJoins.js';
 import { fieldOf, getMeta, namesKey, soleIdOf } from '../entity/index.js';
 import { AbstractQuerier, enrichError } from '../querier/index.js';
-import { clone, getKeys, getSoftDeleteValue, hasKeys, populatesRelations, textSortOf, throwNoPendingTransaction, throwPendingTransaction, vectorCandidates, withoutSoftDeleteFilter, } from '../util/index.js';
+import { clone, getKeys, getSoftDeleteValue, hasKeys, hasTriggers, populatesRelations, textSortOf, throwNoPendingTransaction, throwPendingTransaction, vectorCandidates, withoutSoftDeleteFilter, } from '../util/index.js';
+import { UqlUsageError } from '../util/uqlError.js';
 /**
  * `$limit: 0` asks for no rows, the way it does on every SQL dialect - but MongoDB reads `limit(0)`
  * as *unlimited*, so a read that passed it straight to the driver came back with the whole
@@ -11,6 +12,16 @@ import { clone, getKeys, getSoftDeleteValue, hasKeys, populatesRelations, textSo
 function asksForNoRows(q) {
     return q.$limit === 0;
 }
+/**
+ * MongoDB has no triggers, so a write to an entity declaring one - a stamp included - would skip it
+ * silently. Refused instead, as a query naming SQL is.
+ */
+function refuseTriggers(entity) {
+    if (hasTriggers(getMeta(entity))) {
+        throw new UqlUsageError(`'${entity.name}' declares triggers, which MongoDB has none of: a write here would skip them. ` +
+            'Keep the entity on a SQL engine, or drop its triggers and stamps.');
+    }
+}
 export class MongodbQuerier extends AbstractQuerier {
     dialect;
     conn;
@@ -173,6 +184,7 @@ export class MongodbQuerier extends AbstractQuerier {
         return this.timed('estimatedCount', undefined, async () => this.execute((session) => this.collection(entity).estimatedDocumentCount({ session })));
     }
     async internalInsertMany(entity, rows) {
+        refuseTriggers(entity);
         return this.timed('internalInsertMany', undefined, async () => {
             const meta = getMeta(entity);
             const persistables = this.dialect.getPersistables(meta, rows, 'onInsert');
@@ -186,6 +198,7 @@ export class MongodbQuerier extends AbstractQuerier {
         });
     }
     async internalUpdateMany(entity, qm, payload, opts) {
+        refuseTriggers(entity);
         return this.timed('internalUpdateMany', undefined, async () => {
             const persistable = this.dialect.getPersistable(getMeta(entity), payload, 'onUpdate');
             const filter = this.dialect.where(entity, qm.$where, opts);
@@ -217,6 +230,7 @@ export class MongodbQuerier extends AbstractQuerier {
         return this.dialect.where(entity, where);
     }
     async internalUpsertOne(entity, conflictPaths, payload) {
+        refuseTriggers(entity);
         return this.timed('upsertOne', undefined, async () => {
             payload = clone(payload);
             const meta = getMeta(entity);
@@ -237,6 +251,7 @@ export class MongodbQuerier extends AbstractQuerier {
         });
     }
     async internalUpsertMany(entity, conflictPaths, payload) {
+        refuseTriggers(entity);
         return this.timed('upsertMany', undefined, async () => {
             if (!payload?.length) {
                 return { changes: 0 };
@@ -271,6 +286,7 @@ export class MongodbQuerier extends AbstractQuerier {
         });
     }
     async internalDeleteMany(entity, qm, opts = {}) {
+        refuseTriggers(entity);
         return this.timed('internalDeleteMany', undefined, async () => {
             const meta = getMeta(entity);
             // Soft-delete (stamp) unless `hardDelete` is requested or the entity has no soft-delete field.

package/dist/mssql/mssqlDialect.d.ts

@@ -1,7 +1,7 @@
 import { type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
 import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
-import type { EntityMeta, FieldOptions, InsertIdSource, Query, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import type { EntityMeta, FieldOptions, InsertIdSource, Query, QueryConflictPaths, QueryContext, QueryOptions, QueryPager, SqlDialectFeatures, Type, VectorDistance, VectorMetric } from '../type/index.js';
 /** Microsoft SQL Server 2017 and up. Identifiers are `"`-quoted, the ANSI spelling `tedious` enables. */
 export declare class MsSqlDialect extends MergeSqlDialect {
     #private;
@@ -23,6 +23,8 @@ export declare class MsSqlDialect extends MergeSqlDialect {
     readonly maxBindValues = 2100;
     /** `OUTPUT` has no trailing form: it sits between the column list and `VALUES`. */
     readonly returningPosition = "after-target";
+    /** `OUTPUT` reads the written row off the `INSERTED` pseudo-table. */
+    protected readonly returnedRowPrefix = "INSERTED.";
     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)";
@@ -39,10 +41,6 @@ export declare class MsSqlDialect extends MergeSqlDialect {
     pager(ctx: QueryContext, opts: QueryPager & {
         $distinct?: boolean;
     }, sorted?: boolean): void;
-    /**
-     * `SET IDENTITY_INSERT` around an insert that states a key the engine would generate, which it otherwise
-     * refuses; turned off in the same batch, since one table per session may hold it.
-     */
     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;
@@ -65,9 +63,20 @@ export declare class MsSqlDialect extends MergeSqlDialect {
     };
     /** 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. */
+    /**
+     * `OUTPUT` reads the written row out of the `INSERTED` pseudo-table rather than `RETURNING` it, and
+     * always `INTO` a table variable: SQL Server refuses an `OUTPUT` straight back to the client on a table
+     * carrying a trigger, and through a table it works whether one is there or not.
+     */
     returningId<E>(meta: EntityMeta<E>): string;
-    protected returningIdExpression<E>(meta: EntityMeta<E>): string;
+    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
+    /**
+     * A statement writing rows, `write`, wrapped in what SQL Server needs around one. The table variable its
+     * `OUTPUT` fills, typed as the id column is, and the read handing that back, uncounted so the batch
+     * reports the rows written alone; none on a composite key, which has no id to hand back. And `SET
+     * IDENTITY_INSERT` where a row states a key the engine would generate, turned off in the same batch.
+     */
+    private writeRows;
     protected mergeReturning(expression: string): string;
     /** A row lock is a hint on the table here, which `rowLocks.placement` says instead of a trailing clause. */
     protected lockHint<E>(q: Query<E>): string;
@@ -98,6 +107,8 @@ export declare class MsSqlDialect extends MergeSqlDialect {
     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;
+    /** Null-safe on every version, `EXCEPT` comparing NULLs as equal: `IS DISTINCT FROM` needs 2022. */
+    neExpr(field: string, ph: string): string;
     protected numericCast(expr: string): string;
     /**
      * `OPENJSON` at the path's parent, matching its last segment as a key, in either reading: `JSON_VALUE`