@simtlix/simfinity-js 3.15.0 → 3.16.0

package/README.md

@@ -36,7 +36,7 @@ Generated models store enum internal values with their own type (numbers, boolea
 
 Virtual fields (`extensions: { virtual: true }`, with the field's own `resolve`) get no path, no `[]` default and no index in generated models, on entities and embedded types, and no entry in the transactional integrity registry, so they need no `relation` in either mode and documents look the same with or without them. Generated writes never set or unset them, and Mongoose's strict mode drops a value that a controller assigns to a generated document for one. An embedded type whose members are all virtual becomes a strict subdocument without paths rather than a Mixed path, so nothing is stored for it but the `_id` of list items. With a generated model, values stored before a field became virtual stay in the documents: Mongoose drops an `$unset` of a path the model does not declare, so remove them with a driver-level update, such as `getModel(Type).collection.updateMany({}, { $unset: { busyRanges: '' } })`, or with `updateMany(filter, update, { strict: false })`; a generated update that sets an embedded parent rewrites it, which drops the stored keys of its virtual members. A supplied model keeps the paths it declares: documents stored earlier keep their values for the field, which nothing reads or writes until `$unset` removes them, and an index on such a path stays until you drop it. `buildQuery()` rejects a path through a virtual field with `INVALID_FILTER_FIELD` (400).
 
-Text filters compile to escaped regular expressions, so a value never becomes regex syntax: `LIKE` and `ILIKE` match anywhere, `STARTS_WITH` and `ISTARTS_WITH` are anchored with `^`, `ENDS_WITH` and `IENDS_WITH` with `\z` (so a trailing newline is part of the value), and `IEQ` with both. The `I` operators add the `i` option, which applies the Unicode simple case folding of the server's PCRE2 build (`É`/`é`, `ẞ`/`ß`, `σ`/`ς`, `µ`/`μ`, `ſ`/`s`), never a length-changing or Turkic folding (`ß`/`ss`, `İ`/`i`), and does not fold characters newer than that build, such as U+A7DC; the [queries guide](https://simtlix.github.io/simfinity.js/guide/queries.html) lists where PostgreSQL differs. Only `STARTS_WITH` reads a prefix range of an index on the field, a String list or an embedded path; the other text operators test every key of such an index, or every document without one, and `$regex` ignores collations, so a case-insensitive collation index does not serve them. A value whose escaped pattern is longer than MongoDB's 32,764-byte pattern limit fails with `INVALID_FILTER_VALUE` (400) before the query runs, also for `LIKE`. `createMongoAdapter()` declares every operator it compiles in `queryFeatures`; a copy of the adapter without it supports only the operators of 3.7.0.
+Text filters compile to escaped regular expressions, so a value never becomes regex syntax: `LIKE` and `ILIKE` match anywhere, `STARTS_WITH` and `ISTARTS_WITH` are anchored with `^`, `ENDS_WITH` and `IENDS_WITH` with `\z` (so a trailing newline is part of the value), and `IEQ` with both. The `I` operators add the `i` option, which applies the Unicode simple case folding of the server's PCRE2 build (`É`/`é`, `ẞ`/`ß`, `σ`/`ς`, `µ`/`μ`, `ſ`/`s`), never a length-changing or Turkic folding (`ß`/`ss`, `İ`/`i`), and does not fold characters newer than that build, such as U+A7DC; the [queries guide](https://simtlix.github.io/simfinity.js/guide/queries.html) lists where PostgreSQL differs. Only `STARTS_WITH` reads a prefix range of an index on the field, a String list or an embedded path; the other text operators test every key of such an index, or every document without one, and `$regex` ignores collations, so a case-insensitive collation index does not serve them. A value whose escaped pattern is longer than MongoDB's 32,764-byte pattern limit fails with `INVALID_FILTER_VALUE` (400) before the query runs, also for `LIKE`. `IIN`, `IN` ignoring case, compiles to `$in` of escaped regular expressions anchored as for `IEQ`, with the `i` option, one BSON regular expression per value, each within that limit; like `IEQ`, it tests every key of an index on the field, or every document without one. [`CONTAINS_ALL`](https://simtlix.github.io/simfinity.js/guide/queries.html#filters-on-lists) compiles to `$all` with each value cast as `IN` casts it, so an index on the list bounds one of the values. `createMongoAdapter()` declares every operator it compiles in `queryFeatures`; a copy of the adapter without it supports only the operators of 3.7.0.
 
 `IS_EMPTY` and `IS_NOT_EMPTY` take no value and compile to plain query operators inside the same `$match`, so they also filter counts, aggregates and batched collection reads (`$unionWith`): `$in: [null, ""]` and `$nin` on `String` fields, which an index on the field serves; `null` and `$ne: null` on other scalars, enums and the record identity `_id`; on an application scalar without a supported base, such as a `JSON` scalar, which MongoDB stores as written, `null` without arrays, `{ $and: [{ p: null }, { p: { $not: { $type: "array" } } }] }`, and its `$nor`, so that an array, also `[null]`, is a value, as reads return it; `"p.0": { $exists: false }` and `$exists: true` on scalar lists and embedded lists, which never look inside the items; and, on an embedded object, an `$or` of `null` and the `IS_EMPTY` form of every stored member, with its `$nor` for `IS_NOT_EMPTY`, so an object whose stored members are all empty, such as `{ w: null, label: "" }`, is empty. A term or group condition without a `path` tests the object or list field itself. Embedded `id` members are read where other filters read them, so an object of a supplied subdocument schema with an automatic `_id` is never empty, unlike on PostgreSQL. A path that continues inside an embedded list or a collection, such as `lines.qty` or `seasons.year`, fails with the permanent `INVALID_FILTER_PATH` (400), since emptiness of a value inside a list is not defined; the [queries guide](https://simtlix.github.io/simfinity.js/guide/queries.html#empty-values) has the rules and the other codes.
 
@@ -46,7 +46,7 @@ The adapter declares `queryFeatures.quantifiers: true`. Ordinary filter paths th
 
 A quantified frame uses one `$lookup` with the child scope, inner joins and the condition, followed by `$limit: 1` and `$project: { _id: 1 }`, tested by the presence or absence of `"__sf_qN.0"`. Collection frames correlated through a reference or embedded `_id` start with a non-null check on the child's connection field; legacy aggregate collection joins whose local key is not the root `_id` (a collection reached through a reference or an embedded object) use the same guard, avoiding orphan matches through missing parents. Root-anchored aggregate collection joins keep their form. Reference frames need no guard. `groupId` and fact paths preserve their collection joins and row cardinality, while other aggregate filters use frames anchored on the relevant joined row. Sort paths through a collection reject with `INVALID_FILTER_PATH` (400), also for counted pages; sorts through references remain available. Existing own-field and reference predicates, embedded-list predicates and 2b emptiness forms retain their pipelines. Generated and batched collection reads use the same frame pipelines unchanged inside `$unionWith`. These concise lookups require MongoDB 5.0 or later; see the [queries guide](https://simtlix.github.io/simfinity.js/guide/queries.html) for correlation, scopes, depth and compatibility rules.
 
-The facade registers generated models on your application's default Mongoose instance and does not change global Mongoose options such as `strictQuery`. Supplied models may use another connection, such as one from `mongoose.createConnection()`: generated mutations and `saveObject()` use the model's connection, and, in the default `referentialIntegrity: 'off'` mode, custom mutations use the default connection unless it is unused, never opened and without compiled models, also on its `useDb()` descendants, and the registered models share one MongoDB client; with transactional reference integrity they use the first protected model's connection. Named views need no session: they run the generated list path. Custom queries registered with `registerCustomQuery()` receive no session; a callback that needs a transaction opens it with the `transaction()` of the Mongoose connection whose models it reads. `createMongoAdapter().castId` accepts only an ObjectId or its 24-character hexadecimal string and throws `NOT_VALID_ID` (400) otherwise; create new identifiers with `new mongoose.Types.ObjectId()`. Owned transactions retry transient failures after a short random delay, and a write conflict that outlasts the retries fails with `TRANSACTION_RETRY_EXCEEDED` (409).
+The facade registers generated models on your application's default Mongoose instance and does not change global Mongoose options such as `strictQuery`. Supplied models may use another connection, such as one from `mongoose.createConnection()`: generated mutations and `saveObject()` use the model's connection, and, in the default `referentialIntegrity: 'off'` mode, custom mutations use the default connection unless it is unused, never opened and without compiled models, also on its `useDb()` descendants, and the registered models share one MongoDB client; with transactional reference integrity they use the first protected model's connection. Since 3.16.0, `updateObject()`, `deleteObject()` and `transitionObject()` are exported next to `saveObject()` and use the model's connection the same way, and `createSchema(…, { transaction })` adds a mutation that runs several generated mutations in one transaction, which requires the models it may write to share one `MongoClient` (`useDb()` siblings count as one) in both `referentialIntegrity` modes; models of different clients fail with `TRANSACTION_UNSUPPORTED` before a session opens. Named views need no session: they run the generated list path. Custom queries registered with `registerCustomQuery()` receive no session; a callback that needs a transaction opens it with the `transaction()` of the Mongoose connection whose models it reads. `createMongoAdapter().castId` accepts only an ObjectId or its 24-character hexadecimal string and throws `NOT_VALID_ID` (400) otherwise; create new identifiers with `new mongoose.Types.ObjectId()`. Owned transactions retry transient failures after a short random delay, and a write conflict that outlasts the retries fails with `TRANSACTION_RETRY_EXCEEDED` (409).
 
 Mongoose 8.24.2 or later within version 8 is required to exclude the update-casting prototype-pollution vulnerability. Existing applications should update Mongoose and their dependency lockfile, then run `npm audit`; upgrading Simfinity does not refresh every transitive dependency already locked by the application.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "3.15.0",
+  "version": "3.16.0",
   "description": "MongoDB/Mongoose adapter and compatibility facade for Simfinity GraphQL APIs",
   "main": "src/index.js",
   "types": "./types/index.d.ts",
@@ -29,8 +29,8 @@
     "owner": "simtlix"
   },
   "dependencies": {
-    "@simtlix/simfinity-core": "3.15.0",
-    "@simtlix/simfinity-mcp": "3.15.0"
+    "@simtlix/simfinity-core": "3.16.0",
+    "@simtlix/simfinity-mcp": "3.16.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -28,6 +28,9 @@ export const registerMutation = runtime.registerMutation;
 export const registerCustomQuery = runtime.registerCustomQuery;
 export const registerView = runtime.registerView;
 export const saveObject = runtime.saveObject;
+export const updateObject = runtime.updateObject;
+export const deleteObject = runtime.deleteObject;
+export const transitionObject = runtime.transitionObject;
 export const preventCreatingCollection = runtime.preventCreatingCollection;
 
 export const buildQuery = (...args) => mongoAdapter.buildQuery(...args);

package/src/mongo/adapter.js

@@ -135,6 +135,41 @@ const mapQueryIdCastErrors = (query, mapError = (error) => error) => {
   return query;
 };
 
+// MongoDB fails a command whose regular expression it cannot compile with Location51091. The query
+// compiler escapes every value and bounds every pattern by the 32,764 bytes the server accepts, but
+// ignoring case the server compiles each letter that has other case forms (k, K and the Kelvin sign)
+// to a class, so only a case-insensitive pattern can still be too large; then the client's filter
+// value is the cause. IIN (#108 part 4) sends its patterns as BSON regular expressions, the other
+// text operators as $regex with $options.
+const REGEX_INVALID = 51091;
+const ignoresCase = (options) => typeof options === 'string' && options.includes('i');
+const hasCaseInsensitiveRegex = (node) => {
+  if (Array.isArray(node)) return node.some(hasCaseInsensitiveRegex);
+  if (node === null || typeof node !== 'object') return false;
+  if (node._bsontype !== undefined) return node._bsontype === 'BSONRegExp' && ignoresCase(node.options);
+  if (typeof node.$regex === 'string' && ignoresCase(node.$options)) return true;
+  return Object.values(node).some(hasCaseInsensitiveRegex);
+};
+// The driver error stays available to logging, as on TRANSACTION_RETRY_EXCEEDED.
+const mapRegexError = (error, pipeline) => {
+  if (error?.code !== REGEX_INVALID || !hasCaseInsensitiveRegex(pipeline)) return error;
+  const tooLarge = new SimfinityError(
+    'Case-insensitive text filter value is too long: MongoDB cannot compile its regular expression when ignoring case, because letters such as k and s match more than one character',
+    'INVALID_FILTER_VALUE', 400,
+  );
+  tooLarge.cause = error;
+  tooLarge.getCause = () => tooLarge.cause;
+  return tooLarge;
+};
+// Runs an aggregate of a pipeline that the query compiler built from filters.
+const mapRegexErrors = async (pipeline, aggregate) => {
+  try {
+    return await aggregate;
+  } catch (error) {
+    throw mapRegexError(error, pipeline);
+  }
+};
+
 // Even a shared hook can branch on `this.op` or the filter shape. Preserve findOne semantics
 // whenever either query operation has hooks instead of inferring equivalence from function identity.
 const hasNoHooks = (hooks, operations) => {
@@ -280,14 +315,20 @@ export const createMongoAdapter = (options) => {
   // - registered models on several clients have no single client to choose.
   // Once the default connection has a client, nothing changes.
   const hasModels = (connection) => Object.keys(connection.models).length > 0;
-  // A child's otherDbs also lists its parent, so the walk visits each connection once, cycles
+  // The connection and everything its otherDbs reach: its useDb() parent, children and their siblings, at
+  // any depth. A child's otherDbs also lists its parent, so the walk visits each connection once, cycles
   // included: a Set iteration also visits the entries added while it runs.
-  const defaultClientHasModels = () => {
-    const seen = new Set([mongoose.connection]);
+  const connectionFamily = (start) => {
+    const seen = new Set([start]);
     for (const connection of seen) {
-      if (hasModels(connection)) return true;
       for (const other of connection.otherDbs) seen.add(other);
     }
+    return seen;
+  };
+  const defaultClientHasModels = () => {
+    for (const connection of connectionFamily(mongoose.connection)) {
+      if (hasModels(connection)) return true;
+    }
     return false;
   };
   const sessionModel = () => {
@@ -303,6 +344,21 @@ export const createMongoAdapter = (options) => {
     return found;
   };
 
+  // Whether two connections share one MongoDB client, hence one session. Two resolved clients decide by
+  // identity. While either has no client yet (before connect(), or a useDb() child created earlier), the
+  // connections of one useDb() family share the client the family will have, so connections whose
+  // families meet count as one. A family is found through otherDbs, never Mongoose's private _parent;
+  // a useDb(name, { noListener: true }) child lists its parent, which does not list it, so the families
+  // meet at the parent.
+  const sharesClient = (first, second) => {
+    const firstClient = first.getClient?.();
+    const secondClient = second.getClient?.();
+    if (firstClient && secondClient) return firstClient === secondClient;
+    const family = connectionFamily(first);
+    for (const connection of connectionFamily(second)) if (family.has(connection)) return true;
+    return false;
+  };
+
   // A supplied session or model is used as is; only an owned session without a model looks up
   // the registrations.
   const withOwnedTransaction = (session, body, Model, transactionOptions) => withMongoTransaction(
@@ -362,6 +418,20 @@ export const createMongoAdapter = (options) => {
         if (onModelCreated) onModelCreated(model);
       }, integrity.enabled ? { ...modelOptions, createCollection: false } : modelOptions);
     },
+    // The affinity check of the generated transaction field (#151), before its session opens. Every
+    // model must share the first one's client, in both referentialIntegrity modes, which run every write
+    // in a transaction. It never writes, and a connection that is still connecting is no error: its
+    // session waits for it. The error names the first model's type and the first type that cannot share
+    // its session, as the types of the registrations (a model that several types share, or has none, by
+    // its modelName), never the connections' addresses.
+    assertTransactionModels(models) {
+      const [first, ...others] = models.filter((model) => model?.db);
+      const conflict = others.find((model) => !sharesClient(first.db, model.db));
+      if (!conflict) return;
+      const registrations = getRegistrations();
+      const names = [first, conflict].map((model) => versionTypeName(model, registrations)).sort();
+      throw new SimfinityError(`Types ${names.join(', ')} cannot share one database transaction`, 'TRANSACTION_UNSUPPORTED', 500);
+    },
     // Relation inputs and batch keys: only an ObjectId or its hex form, never a newly minted one.
     castId: castObjectId,
     initialize: integrity.initialize,
@@ -484,18 +554,18 @@ export const createMongoAdapter = (options) => {
       // Mongoose does not cast aggregation stages, so cast the key type here, without setters.
       if (requiredId != null) pipeline.unshift({ $match: { _id: castModelId(Model, requiredId) } });
       if (pipeline.length === 0) return versionedRead(Model, withSession(Model.find({}), session), true);
-      return withSession(Model.aggregate(pipeline), session);
+      return mapRegexErrors(pipeline, withSession(Model.aggregate(pipeline), session));
     },
     async count(Model, gqltype, args, session) {
       integrity.assertReady();
       const pipeline = await queries.buildQuery(args, gqltype, true);
-      const result = await withSession(Model.aggregate(pipeline), session);
+      const result = await mapRegexErrors(pipeline, withSession(Model.aggregate(pipeline), session));
       return result[0] ? result[0].size : 0;
     },
     async aggregate(Model, gqltype, args, session) {
       integrity.assertReady();
       const pipeline = await queries.buildAggregationQuery(args, gqltype, args.aggregation);
-      return withSession(Model.aggregate(pipeline), session);
+      return mapRegexErrors(pipeline, withSession(Model.aggregate(pipeline), session));
     },
     async findChildren(Model, gqltype, connectionField, parentId, args, session) {
       integrity.assertReady();
@@ -509,7 +579,7 @@ export const createMongoAdapter = (options) => {
         throw error;
       }
       pipeline.unshift({ $match: { [connectionField]: parentKey } });
-      return withSession(Model.aggregate(pipeline), session);
+      return mapRegexErrors(pipeline, withSession(Model.aggregate(pipeline), session));
     },
   };
 
@@ -570,7 +640,7 @@ export const createMongoAdapter = (options) => {
       // overlap the remaining commands.
       const outcomes = await Promise.allSettled(commands);
       const failure = outcomes.find(({ status }) => status === 'rejected');
-      if (failure) throw failure.reason;
+      if (failure) throw mapRegexError(failure.reason, pipeline);
       for (const { value: rows } of outcomes) {
         for (const { i, d } of rows) lists[i].push(d);
       }

package/src/mongo/queries.js

@@ -12,7 +12,7 @@ import { SimfinityError, QLOperator, paginationStages } from '@simtlix/simfinity
 import {
   TEXT_QUERY_OPERATORS, aggregateJoinPrefixes, crossingKeys, describeEmptiness, effectiveScalarName, emptinessScopePaths,
   frameCollectionPaths, isEmptinessOperator, validateQuantifiedGroups,
-  textQueryOperator, validateTextFilterValue,
+  textQueryOperator, validateTextFilterValue, validateTextListFilterValue,
 } from '@simtlix/simfinity-core/internal/query-operators';
 import {
   getFieldStorageName, getListShape, hasStoredIdentity, isVirtualField, normalizeConnectionField,
@@ -39,6 +39,7 @@ export const MONGO_QUERY_OPERATORS = Object.freeze([
   'EQ', 'NE', 'LT', 'LTE', 'GT', 'GTE', 'BTW', 'IN', 'NIN', 'LIKE',
   'ILIKE', 'STARTS_WITH', 'ISTARTS_WITH', 'ENDS_WITH', 'IENDS_WITH', 'IEQ',
   'IS_EMPTY', 'IS_NOT_EMPTY',
+  'CONTAINS_ALL', 'IIN',
 ]);
 
 export const createMongoQueries = ({ getModel, getRegistrations }) => {
@@ -108,14 +109,18 @@ const escapeRegex = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 // which would report a client's long value as an internal error. Escaping adds a byte to each
 // metacharacter and the operators add their anchors, so the limit applies to the compiled pattern.
 const MAX_REGEX_PATTERN_BYTES = 32764;
-// A $regex match, rejected with INVALID_FILTER_VALUE before the query runs when MongoDB would reject
-// its pattern. `path` is the condition's GraphQL path, for the message.
-const regexMatch = (operator, pattern, ignoreCase, path) => {
+// MongoDB rejects a regular expression longer than 32,764 UTF-8 bytes on the server (Location51091). `path` is the
+// condition's GraphQL path, for the message. Returns the pattern.
+const assertPatternBytes = (operator, pattern, path) => {
   const bytes = Buffer.byteLength(pattern, 'utf8');
   if (bytes > MAX_REGEX_PATTERN_BYTES) {
     const where = path == null ? '' : ` on ${path}`;
     throw filterError(`${operator} value${where} is too long: MongoDB accepts regular expressions of at most ${MAX_REGEX_PATTERN_BYTES} bytes, and this one has ${bytes}`);
   }
+  return pattern;
+};
+const regexMatch = (operator, pattern, ignoreCase, path) => {
+  assertPatternBytes(operator, pattern, path);
   return ignoreCase ? { $regex: pattern, $options: 'i' } : { $regex: pattern };
 };
 
@@ -509,7 +514,8 @@ const rewriteContext = (gqltype, operation = 'find', aggregation) => {
 };
 
 // Cross references in the containing pipeline. Collection steps occur here only for an aggregate
-// anchor: all ordinary collection crossings have already become frames in the shared rewrite.
+// anchor, or inside the prefix witness of a hand-built implicit group that crosses a collection
+// before its end: all ordinary collection crossings have already become frames in the shared rewrite.
 const crossFramePath = async (gqltype, segments, scopes, build, lookups, included) => {
   let type = gqltype;
   let parent = { key: '', schemaPath: '', path: '' };
@@ -585,7 +591,9 @@ const compileFrame = async (ctx, quantifier, group) => {
   for (const [index, name] of segments.entries()) {
     const field = type.getFields()[name];
     if (field.extensions?.relation && !field.extensions.relation.embedded) {
-      if (index < segments.length - 1 && vector) multiplyingPrefix = true;
+      // A collection crossed before the end multiplies the prefix as an embedded-list vector does (#108 part 4): only a
+      // hand-built implicit group crosses one outside an anchor, and anchored groups skip the witness below.
+      if (index < segments.length - 1 && (vector || getListShape(field.type))) multiplyingPrefix = true;
       vector = false;
       if (!getModel(getNamedType(field.type))) throw filterError(`Related model is not available for ${joinPath(ctx.base, segments.join('.'))}`, 'INVALID_FILTER_PATH');
       if (!anchor.length || index >= anchor.length || getListShape(field.type)) paths.push(segments.slice(0, index + 1).join('.'));
@@ -601,7 +609,7 @@ const compileFrame = async (ctx, quantifier, group) => {
     }
   }
   const emptyAll = quantifier === 'ALL' && !['conditions', 'ANY', 'ALL', 'NONE', 'AND', 'OR'].some((key) => group[key]?.length);
-  // A vector prefix belongs to this predicate, not to the containing result set. A
+  // A vector or collection prefix belongs to this predicate, not to the containing result set. A
   // self-correlated witness keeps its joins local without discarding any target. Aggregate
   // anchors retain their intentional expansion. NONE tests the positive ANY witness; ALL
   // looks for a prefix whose complete ALL test fails, including vacuous empty prefixes.
@@ -719,7 +727,14 @@ const buildMatchesClause = (resolved, operator, value, path) => {
     const text = validateTextFilterValue(op, value, effectiveScalarName(resolved.fieldType), path);
     return { [resolved.mongoPath]: OP_TO_MONGO[op](text, path) };
   }
-  const collectionOperator = op === 'IN' || op === 'NIN' || op === 'BTW';
+  // IIN, IN ignoring case (#108 part 4): one anchored, escaped, case-insensitive regular expression per value inside
+  // $in, as a BSON regular expression, so the server receives exactly the pattern checked against its limit. Values
+  // are never cast; core's rule has accepted them.
+  if (op === 'IIN') {
+    const values = validateTextListFilterValue(op, value, effectiveScalarName(resolved.fieldType), path);
+    return { [resolved.mongoPath]: { $in: values.map((item) => new mongoose.mongo.BSONRegExp(assertPatternBytes(op, TEXT_PATTERNS.exact(escapeRegex(item)), path), 'i')) } };
+  }
+  const collectionOperator = op === 'IN' || op === 'NIN' || op === 'BTW' || op === 'CONTAINS_ALL';
   if (collectionOperator && (!Array.isArray(value) || (op === 'BTW' && value.length !== 2))) {
     throw filterError(`${op} requires ${op === 'BTW' ? 'exactly two values' : 'an array value'}`);
   }
@@ -734,6 +749,7 @@ const buildMatchesClause = (resolved, operator, value, path) => {
   const coerced = collectionOperator ? value.map(cast) : op === 'LIKE' ? value : cast(value);
   if (op === 'EQ') return { [resolved.mongoPath]: coerced };
   if (op === 'IN' || op === 'NIN') return { [resolved.mongoPath]: { [op === 'IN' ? '$in' : '$nin']: coerced } };
+  if (op === 'CONTAINS_ALL') return { [resolved.mongoPath]: { $all: coerced } };
   return { [resolved.mongoPath]: OP_TO_MONGO[op](coerced, path) };
 };
 

package/types/index.d.ts

@@ -118,7 +118,9 @@ export interface MongoAdapter extends DatabaseAdapter {
    * Frozen; lists every `QLOperator` value and declares `referenceEmptiness: true` and `quantifiers: true`. The literal text
    * operators compile to escaped regular expressions: `ILIKE` unanchored, `STARTS_WITH` and
    * `ISTARTS_WITH` anchored with `^`, `ENDS_WITH` and `IENDS_WITH` with `\z`, and `IEQ` with both, with
-   * the `i` option for the case-insensitive ones. `IS_EMPTY` and `IS_NOT_EMPTY` compile to plain query
+   * the `i` option for the case-insensitive ones. `CONTAINS_ALL` compiles to `$all` with cast values; `IIN` to `$in`
+   * of anchored, escaped, case-insensitive regular expressions, one per value, each within MongoDB's 32,764-byte
+   * limit. `IS_EMPTY` and `IS_NOT_EMPTY` compile to plain query
    * operators on the record's own fields, and through single references and at references and
    * collections to joins and frames (see {@link buildQuery}). A copy of the adapter without this member
    * supports only the operators of 3.7.0, and one whose declaration leaves out `referenceEmptiness`
@@ -131,6 +133,18 @@ export interface MongoAdapter extends DatabaseAdapter {
    * creates an identifier; use `new mongoose.Types.ObjectId()` for that.
    */
   castId(value: any): any;
+  /**
+   * The affinity check of the generated `transaction` field (see `CreateSchemaOptions.transaction`), run
+   * before each transaction opens. Synchronous: it never writes and opens no session. The models must
+   * share one MongoDB client: when every model's connection has a client they must be the same
+   * `MongoClient`, and while a connection has none yet (before `connect()`, or a `useDb()` child created
+   * earlier) the connections of one `useDb()` family count as one client. Otherwise it throws
+   * `TRANSACTION_UNSUPPORTED` (500), `Types <A>, <B> cannot share one database transaction`, naming the
+   * first model's type and the first type that cannot share its client, sorted, by their registrations
+   * (by `modelName` for a model that several types share). It never names a connection string. It applies
+   * in both `referentialIntegrity` modes, and an empty list passes.
+   */
+  assertTransactionModels(models: any[]): void;
   /** Returns null for a hydrated nested path whose stored value is an explicit null; otherwise the value. */
   readEmbeddedValue(value: any): any;
   /**
@@ -231,7 +245,11 @@ export function addNoEndpointType(gqltype: GraphQLObjectType): void;
  * constructed otherwise.
  * options.includedCustomQueries selects custom queries by name (see CreateSchemaOptions); an
  * invalid options argument throws INVALID_SCHEMA_OPTIONS (500), and an included custom query named
- * like an included generated query throws QUERY_NAME_CONFLICT (500), before models are created. A
+ * like an included generated query throws QUERY_NAME_CONFLICT (500), before models are created.
+ * options.transaction adds the generated transaction field (see CreateSchemaOptions): an invalid
+ * option throws INVALID_SCHEMA_OPTIONS (500) before models are created, except that a field name or
+ * derived type name taken in the built schema, or no operation left, is found once the models are
+ * prepared; an adapter without assertTransactionModels throws TRANSACTION_UNSUPPORTED (500). A
  * schema without mutation fields has no Mutation root.
  */
 export function createSchema(
@@ -307,11 +325,15 @@ export function configureQueryLimits(options?: QueryLimitsOptions): void;
 export function configureAfterCommit(options?: AfterCommitOptions): void;
 
 /**
- * Process-wide limit on nested added/updated/deleted entries per generated add, update or
- * state-action mutation; unlimited by default, restored by calling it without options.
- * Invalid configuration, including an unknown or misspelled option key, throws
- * INVALID_MUTATION_LIMITS (400) and keeps the current limit; a mutation over the limit
- * fails with NESTED_OPERATIONS_EXCEEDED (400) before its transaction starts.
+ * Process-wide mutation limits. `maxNestedOperations` caps the nested added/updated/deleted entries
+ * of one generated add, update or state-action mutation (unlimited by default; `null` = no limit),
+ * and `updateObject` and `transitionObject` apply it to their `input` in the same way.
+ * `maxTransactionOperations` caps the operations of one generated transaction mutation (a positive
+ * safe integer; 100 by default). Each call replaces both values, so an omitted option takes its
+ * default again, and calling it without options restores both defaults. Invalid configuration,
+ * including an unknown or misspelled option key, throws INVALID_MUTATION_LIMITS (400) and keeps the
+ * current limits. A mutation over the nested limit fails with NESTED_OPERATIONS_EXCEEDED (400)
+ * before its transaction starts.
  */
 export function configureMutationLimits(options?: MutationLimitsOptions): void;
 
@@ -344,6 +366,56 @@ export function saveObject(
   context?: any,
 ): Promise<any>;
 
+/**
+ * Run the lifecycle of the generated update mutation from code, in a transaction of its own or in the
+ * active session supplied (see the core `Runtime.updateObject`). `input` has the shape of the type's
+ * update input and is checked structurally before anything runs: enum fields take their internal
+ * values, scalars are not coerced and a reference is its record key as a string. A scalar field takes a
+ * primitive, a `Date` or plain data (objects and arrays, at most 256 levels deep); class instances such
+ * as `ObjectId`, `Buffer` or `Map` are rejected with `INVALID_INPUT`, an own `undefined` counts as
+ * omitted and a bare value is never wrapped into a list. It skips the root record's global middleware,
+ * as `saveObject` does. More nested entries than `maxNestedOperations` from `configureMutationLimits()`
+ * (`null` = no limit) reject with `NESTED_OPERATIONS_EXCEEDED` (400). The helper itself never commits,
+ * retries, aborts or cleans up a supplied session; an adapter may still abort it on a write error (for
+ * example MongoDB with transactional reference integrity). Rejects with `INVALID_OPERATION_TARGET` (500)
+ * for a type that is not a stored record type of this runtime, or that has no prepared update input with
+ * an id field (before `createSchema()`, with a `readOnly` id, or with an empty update input),
+ * `REQUIRED_VALUE` or `INVALID_INPUT` (400) for an invalid input, and `NOT_VALID_ID` (404) when no
+ * record has the ID. Resolves to the updated record.
+ */
+export function updateObject(
+  typeName: string,
+  input: Record<string, any>,
+  session?: any,
+  context?: any,
+): Promise<any>;
+
+/**
+ * Run the lifecycle of the generated delete mutation from code: `target` is `{ id }`, plus `version` on
+ * a type with optimistic concurrency (see the core `Runtime.deleteObject`). Its type is checked as
+ * `updateObject` checks it, without needing an update input; its target is checked before anything runs.
+ * Resolves to the deleted record, or `null` when no record has the ID.
+ */
+export function deleteObject(
+  typeName: string,
+  target: { id: string; version?: number },
+  session?: any,
+  context?: any,
+): Promise<any>;
+
+/**
+ * Run a state machine action from code with the lifecycle of its generated mutation (see the core
+ * `Runtime.transitionObject`). It checks its type and `input` as `updateObject` does, rejects with
+ * `UNKNOWN_ACTION` (500) for an action the type does not have, and resolves to the updated record.
+ */
+export function transitionObject(
+  typeName: string,
+  actionName: string,
+  input: Record<string, any>,
+  session?: any,
+  context?: any,
+): Promise<any>;
+
 /** Get the Mongoose model registered for a connected GraphQL type. */
 export function getModel(gqltype: GraphQLObjectType | { name: string }): any;