@simtlix/simfinity-js 3.8.0 → 3.10.0

package/README.md

@@ -26,7 +26,11 @@ 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).
 
-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. `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).
+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.
+
+`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. In this release, any other path that crosses or ends at a reference, a path that ends at a collection, such as `seasons`, and an embedded object with a reference or collection member fail with `UNSUPPORTED_QUERY` (400); the [queries guide](https://simtlix.github.io/simfinity.js/guide/queries.html#empty-values) has the rules and the other codes.
+
+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. 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.8.0",
+  "version": "3.10.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.8.0",
-    "@simtlix/simfinity-mcp": "3.8.0"
+    "@simtlix/simfinity-core": "3.10.0",
+    "@simtlix/simfinity-mcp": "3.10.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -22,6 +22,7 @@ export const getInputType = runtime.getInputType;
 export const getRegistrations = runtime.getRegistrations;
 export const use = runtime.use;
 export const registerMutation = runtime.registerMutation;
+export const registerCustomQuery = runtime.registerCustomQuery;
 export const saveObject = runtime.saveObject;
 export const preventCreatingCollection = runtime.preventCreatingCollection;
 

package/src/mongo/adapter.js

@@ -3,7 +3,7 @@ import { SimfinityError } from '@simtlix/simfinity-core';
 import { getListShape, normalizeConnectionField } from '@simtlix/simfinity-core/internal/relation-storage';
 
 import { createMongoModel } from './models.js';
-import { createMongoQueries } from './queries.js';
+import { MONGO_QUERY_OPERATORS, createMongoQueries } from './queries.js';
 import { withMongoTransaction } from './transactions.js';
 import { createMongoIntegrity } from './integrity.js';
 import {
@@ -12,6 +12,9 @@ import {
 
 const withSession = (query, session) => (session ? query.session(session) : query);
 
+// Every filter operator the query compiler supports; the runtime rejects any other one.
+const QUERY_FEATURES = Object.freeze({ operators: MONGO_QUERY_OPERATORS });
+
 // A write that fails only on malformed ObjectId values reports NOT_VALID_ID, not a driver error.
 const mapIdCastErrors = async (write) => {
   try {
@@ -216,6 +219,7 @@ export const createMongoAdapter = (options) => {
   };
 
   const adapter = {
+    queryFeatures: QUERY_FEATURES,
     bind(binding) {
       integrity.bind(binding);
       getRegistrations = binding.getRegistrations;

package/src/mongo/queries.js

@@ -2,12 +2,17 @@ import {
   GraphQLEnumType,
   GraphQLID,
   GraphQLObjectType,
-  GraphQLScalarType,
   getNamedType,
+  isAbstractType,
+  isScalarType,
 } from 'graphql';
 import mongoose from 'mongoose';
 
 import { SimfinityError, QLOperator, paginationStages } from '@simtlix/simfinity-core';
+import {
+  TEXT_QUERY_OPERATORS, describeEmptiness, effectiveScalarName, isEmptinessOperator, textQueryOperator,
+  validateTextFilterValue,
+} from '@simtlix/simfinity-core/internal/query-operators';
 import {
   getFieldStorageName, getListShape, hasStoredIdentity, isVirtualField, normalizeConnectionField,
 } from '@simtlix/simfinity-core/internal/relation-storage';
@@ -15,10 +20,6 @@ import {
 import { castObjectId } from './ids.js';
 import { resolveStorageScalar } from './models.js';
 
-const getEffectiveTypeName = (type) => (
-  type instanceof GraphQLScalarType ? resolveStorageScalar(type).name : type.name
-);
-
 const isGraphQLisoDate = (typeName) => (
   typeName === 'DateTime' || typeName === 'Date' || typeName === 'Time'
 );
@@ -26,6 +27,16 @@ const isGraphQLisoDate = (typeName) => (
 // GraphQL reserves `__` names, so these aliases never replace a stored field.
 const LOOKUP_ALIAS_PREFIX = '__sf_l';
 
+/**
+ * The filter operators this compiler supports, which the adapter declares as its queryFeatures. They
+ * are listed explicitly, so that a QLOperator value added later stays unsupported until it compiles.
+ */
+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',
+]);
+
 export const createMongoQueries = ({ getModel, getRegistrations }) => {
 // One alias per relation path for each query build, keyed by the build's `included` accumulator.
 const lookupAliases = new WeakMap();
@@ -62,6 +73,34 @@ const buildRelationLookup = ({
 
 const escapeRegex = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+// MongoDB rejects a $regex pattern longer than 32,764 UTF-8 bytes on the server (Location51091),
+// 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) => {
+  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 ignoreCase ? { $regex: pattern, $options: 'i' } : { $regex: pattern };
+};
+
+// The literal text operators: the escaped value, anchored with `^` at the start of the string and
+// `\z` at its very end (`$` would also match before a final newline), with the `i` option to ignore
+// case. Without the `m` option, `^` never matches after a newline.
+const TEXT_PATTERNS = {
+  contains: (escaped) => escaped,
+  prefix: (escaped) => `^${escaped}`,
+  suffix: (escaped) => `${escaped}\\z`,
+  exact: (escaped) => `^${escaped}\\z`,
+};
+const textRegex = (operator, { match, ignoreCase }) => (value, path) => (
+  regexMatch(operator, TEXT_PATTERNS[match](escapeRegex(value)), ignoreCase, path)
+);
+
 const PATH_SEGMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 const assertValidFilterPath = (path) => {
@@ -101,7 +140,8 @@ const OP_TO_MONGO = {
   GTE: (v) => ({ $gte: v }),
   NE: (v) => ({ $ne: v }),
   BTW: (v) => ({ $gte: v[0], $lte: v[1] }),
-  LIKE: (v) => ({ $regex: `.*${escapeRegex(v)}.*` }),
+  LIKE: (v, path) => regexMatch('LIKE', `.*${escapeRegex(v)}.*`, false, path),
+  ...Object.fromEntries(Object.entries(TEXT_QUERY_OPERATORS).map(([op, text]) => [op, textRegex(op, text)])),
 };
 
 const AGG_OP_TO_MONGO = {
@@ -190,6 +230,74 @@ const resolveQueryPath = (gqltype, path, aggregationsIncluded) => {
   throw filterError(`Invalid query path: ${path}`, 'INVALID_FILTER_PATH');
 };
 
+// The emptiness operators IS_EMPTY and IS_NOT_EMPTY (#108, part 2a). Core's describeEmptiness applies
+// their checks in the order every caller uses and describes what "empty" means for the path. It
+// rejects references, collections, interface and union fields and anything inside a list, so the
+// path and every member it reads are stored in the queried document, through single embedded objects.
+// The forms are plain query operators that need no lookup, valid wherever the $match runs.
+const isPathless = (path) => path == null || path === '';
+
+// The stored key of the member `name` of `type`, an object stored at `schemaPath` ('' at the root):
+// a non-object `id` member follows identifierLeaf, as resolveQueryPath does; others keep their name.
+const emptinessKey = (model, type, schemaPath, name) => {
+  const field = type.getFields()[name];
+  const leaf = name === 'id' && !(getNamedType(field.type) instanceof GraphQLObjectType)
+    ? identifierLeaf(model, schemaPath, type)
+    : name;
+  return schemaPath ? `${schemaPath}.${leaf}` : leaf;
+};
+
+// MongoDB stores the built-in scalars, dates and enums as single values, but keeps an application scalar
+// without a supported base as written, arrays included, and `{ p: null }` also matches an array that
+// holds a null. The null rule of such a scalar leaves arrays out, so `[null]` is a value, as GraphQL
+// reads it. The record identity `_id` is never an array, so it keeps the plain form.
+const SINGLE_VALUE_SCALARS = new Set(['String', 'ID', 'Int', 'Float', 'Boolean', 'DateTime', 'Date', 'Time']);
+const holdsArrays = (key, type) => (
+  key !== '_id' && isScalarType(type) && !SINGLE_VALUE_SCALARS.has(effectiveScalarName(type))
+);
+const nullForm = (key, type) => (holdsArrays(key, type)
+  ? { $and: [{ [key]: null }, { [key]: { $not: { $type: 'array' } } }] }
+  : { [key]: null });
+
+// The IS_EMPTY form of `shape` for the value stored at `key`; `type` is the named type of its field.
+// An object is missing, null, or has every stored member empty. Without stored members it is always
+// empty: MongoDB rejects an empty $and, so the empty query, which matches every document, stands in.
+const emptyForm = (model, shape, key, type) => {
+  if (shape.rule === 'string') return { [key]: { $in: [null, ''] } };
+  if (shape.rule === 'null') return nullForm(key, type);
+  if (shape.rule === 'list') return { [`${key}.0`]: { $exists: false } };
+  const fields = type.getFields();
+  const members = shape.members.map((member) => emptyForm(
+    model, member.shape, emptinessKey(model, type, key, member.name), getNamedType(fields[member.name].type),
+  ));
+  return { $or: [{ [key]: null }, members.length ? { $and: members } : {}] };
+};
+
+// IS_NOT_EMPTY is the exact complement: the positive form of a leaf, which an index can serve, or
+// the $nor of the IS_EMPTY form of an object or of a scalar that may hold arrays.
+const notEmptyForm = (model, shape, key, type) => {
+  if (shape.rule === 'string') return { [key]: { $nin: [null, ''] } };
+  if (shape.rule === 'null') return holdsArrays(key, type) ? { $nor: [nullForm(key, type)] } : { [key]: { $ne: null } };
+  if (shape.rule === 'list') return { [`${key}.0`]: { $exists: true } };
+  return { $nor: [emptyForm(model, shape, key, type)] };
+};
+
+// The match clause of one emptiness condition on `path`, the field itself or a dotted path from it.
+const buildEmptinessClause = (gqltype, path, operator, value) => {
+  const segments = path.split('.');
+  const shape = describeEmptiness(gqltype, segments, { operator, value, path });
+  const model = getModel(gqltype);
+  let type = gqltype;
+  let schemaPath = '';
+  for (const name of segments.slice(0, -1)) {
+    schemaPath = schemaPath ? `${schemaPath}.${name}` : name;
+    type = getNamedType(type.getFields()[name].type);
+  }
+  const name = segments.at(-1);
+  const form = operator === 'IS_EMPTY' ? emptyForm : notEmptyForm;
+  return form(model, shape, emptinessKey(model, type, schemaPath, name), getNamedType(type.getFields()[name].type));
+};
+
 const castFilterValue = (value, resolved) => {
   if (value === null) return null;
   if (value === undefined || Array.isArray(value)
@@ -204,7 +312,7 @@ const castFilterValue = (value, resolved) => {
     // ID representation is a persistence concern, including String/Number/custom _id schemas.
     if (schemaType && (scalar === GraphQLID || resolved.mongoPath.endsWith('._id') || resolved.mongoPath === '_id'
       || schemaType.instance === 'ObjectId')) return schemaType.cast(value);
-    const typeName = getEffectiveTypeName(scalar);
+    const typeName = effectiveScalarName(scalar);
     if (isGraphQLisoDate(typeName)) {
       const date = value instanceof Date ? value : new Date(value);
       if (Number.isNaN(date.getTime())) throw new Error('Invalid date');
@@ -225,16 +333,23 @@ const castFilterValue = (value, resolved) => {
   }
 };
 
-const buildMatchesClause = (resolved, operator, value) => {
+// `path` is the condition's GraphQL path, for messages.
+const buildMatchesClause = (resolved, operator, value, path) => {
   const op = operator ?? 'EQ';
   if (!QLOperator.getValues().some((entry) => entry.value === op)) {
     throw filterError(`Unsupported filter operator: ${op}`, 'INVALID_FILTER_OPERATOR');
   }
+  // Text operators take the value as is, once core's shared rule accepts it: a String field (a
+  // validated scalar by its base scalar) and a string without U+0000.
+  if (textQueryOperator(op)) {
+    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';
   if (collectionOperator && (!Array.isArray(value) || (op === 'BTW' && value.length !== 2))) {
     throw filterError(`${op} requires ${op === 'BTW' ? 'exactly two values' : 'an array value'}`);
   }
-  if (op === 'LIKE' && (typeof value !== 'string' || getEffectiveTypeName(resolved.fieldType) !== 'String')) {
+  if (op === 'LIKE' && (typeof value !== 'string' || effectiveScalarName(resolved.fieldType) !== 'String')) {
     throw filterError('LIKE requires a string field and string value');
   }
   if (value === null && op !== 'EQ' && op !== 'NE') throw filterError(`${op} does not accept null`);
@@ -245,7 +360,7 @@ const buildMatchesClause = (resolved, operator, value) => {
   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 } };
-  return { [resolved.mongoPath]: OP_TO_MONGO[op](coerced) };
+  return { [resolved.mongoPath]: OP_TO_MONGO[op](coerced, path) };
 };
 
 const buildQueryTerms = async (filterField, qlField, fieldName, gqltype, aggregationsIncluded) => {
@@ -254,17 +369,49 @@ const buildQueryTerms = async (filterField, qlField, fieldName, gqltype, aggrega
   if (!qlField) throw filterError(`Unknown filter field: ${fieldName}`, 'INVALID_FILTER_FIELD');
   if (filterField == null) return { aggregateClauses, matchesClauses };
   if (typeof filterField !== 'object' || Array.isArray(filterField)) throw filterError(`Invalid filter for ${fieldName}`);
-  const isObject = getNamedType(qlField.type) instanceof GraphQLObjectType;
+  const namedType = getNamedType(qlField.type);
+  const isObject = namedType instanceof GraphQLObjectType;
+  // Only trusted code writes an operator on an object filter, since QLTypeFilterExpression has none:
+  // an emptiness operator there fails instead of being dropped; other operators stay left out. Rule 1
+  // comes first, so a virtual field fails as it does in every other form.
+  if (isObject && isEmptinessOperator(filterField.operator)) {
+    const { operator } = filterField;
+    if (isVirtualField(qlField)) {
+      throw filterError(`Query path ${fieldName} uses the virtual field ${gqltype.name}.${fieldName}, which is not stored`, 'INVALID_FILTER_FIELD');
+    }
+    throw filterError(`Filter on ${fieldName} takes ${operator} only in a term; to test the field itself, use a term without a path: `
+      + `${fieldName}: { terms: [{ operator: ${operator} }] }`, 'MISSING_FILTER_PATH');
+  }
   if (isObject && (!Array.isArray(filterField.terms) || filterField.terms.length === 0)) {
     throw filterError(`Filter on ${fieldName} requires non-empty terms`, 'MISSING_FILTER_PATH');
   }
+  // QLTypeFilterExpression gives interface and union lists terms too. An emptiness operator beside
+  // them or in one of them tests the field itself, which rule 3 rejects, or a path through it, which
+  // rule 1 rejects: describeEmptiness throws both, in the order the gate reads them. Other operators
+  // keep reading the filter as a value.
+  if (isAbstractType(namedType) && Array.isArray(filterField.terms)) {
+    for (const term of [filterField, ...filterField.terms]) {
+      if (!isEmptinessOperator(term?.operator)) continue;
+      const pathed = term !== filterField && !isPathless(term.path);
+      if (pathed) assertValidFilterPath(term.path);
+      describeEmptiness(gqltype, pathed ? `${fieldName}.${term.path}` : fieldName, { operator: term.operator, value: term.value });
+    }
+  }
   const terms = isObject ? filterField.terms : [filterField];
   for (const term of terms) {
     if (!term || typeof term !== 'object' || Array.isArray(term)) throw filterError(`Invalid term for ${fieldName}`);
+    // An emptiness term whose path is omitted, null or "" tests the field itself.
+    if (isEmptinessOperator(term.operator)) {
+      const pathed = isObject && !isPathless(term.path);
+      if (pathed) assertValidFilterPath(term.path);
+      matchesClauses.push(buildEmptinessClause(gqltype, pathed ? `${fieldName}.${term.path}` : fieldName, term.operator, term.value));
+      continue;
+    }
     if (isObject) assertValidFilterPath(term.path);
-    const resolved = resolveQueryPath(gqltype, isObject ? `${fieldName}.${term.path}` : fieldName, aggregationsIncluded);
+    const path = isObject ? `${fieldName}.${term.path}` : fieldName;
+    const resolved = resolveQueryPath(gqltype, path, aggregationsIncluded);
     Object.assign(aggregateClauses, resolved.aggregateClauses);
-    matchesClauses.push(buildMatchesClause(resolved, term.operator, term.value));
+    matchesClauses.push(buildMatchesClause(resolved, term.operator, term.value, path));
   }
   return { aggregateClauses, matchesClauses };
 };
@@ -291,6 +438,13 @@ const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, agg
     for (const rawCondition of filterGroup.conditions) {
       if (!rawCondition || typeof rawCondition.field !== 'string') throw filterError('Filter conditions require a field');
       const condition = normalizeFilterCondition(rawCondition);
+      // An emptiness condition without a path tests its field, also an object field; a dotted field
+      // is resolved as a whole, as the query plan resolves it.
+      if (isEmptinessOperator(condition.operator)) {
+        const path = rawCondition.path ? `${rawCondition.field}.${rawCondition.path}` : rawCondition.field;
+        parts.push(buildEmptinessClause(gqltype, path, condition.operator, condition.value));
+        continue;
+      }
       const qlField = fields[condition.field];
       if (!qlField) {
         throw new SimfinityError(`Unknown filter field: ${condition.field}`, 'INVALID_FILTER_FIELD', 400);

package/types/index.d.ts

@@ -13,8 +13,10 @@ import type {
   GraphQLOutputType,
 } from 'graphql';
 import type {
+  CreateSchemaOptions,
   DatabaseAdapter,
   MutationLimitsOptions,
+  QueryFeatures,
   RuntimeRegistration,
   SimfinityError,
 } from '@simtlix/simfinity-core';
@@ -34,6 +36,7 @@ export type {
   AuthRule,
   AuthRuleFunction,
   AuthSchemaPlugin,
+  CreateSchemaOptions,
   EnvelopSchemaPlugin,
   FieldValidations,
   FieldValidator,
@@ -88,6 +91,16 @@ export interface MongoAdapterOptions {
  */
 export interface MongoAdapter extends DatabaseAdapter {
   readonly referentialIntegrity: 'off' | 'transactional';
+  /**
+   * Frozen; lists every `QLOperator` value. 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 operators on the record's own fields (see
+   * {@link buildQuery}); declaring them does not lift the `UNSUPPORTED_QUERY` that emptiness through
+   * references and collections gets in this release. A copy of the adapter without this member
+   * supports only the operators of 3.7.0.
+   */
+  readonly queryFeatures: QueryFeatures;
   /**
    * Accepts only an ObjectId or a 24-character hexadecimal string, normalized to lowercase, and
    * throws `NOT_VALID_ID` (400) for anything else, including undefined, null and numbers. It never
@@ -153,7 +166,7 @@ export function addNoEndpointType(gqltype: GraphQLObjectType): void;
 /**
  * Build the executable GraphQLSchema from every connected type. The first two
  * allowlists are matched against the GraphQLObjectType INSTANCES passed to
- * connect(); only custom mutations are matched by name. Scopes are validated
+ * connect(); custom queries and mutations are matched by name. Scopes are validated
  * (INVALID_SCOPE), and reachable types bound or reserved by another runtime, or
  * holding a field copied with toConfig() after another runtime generated its
  * relation resolver, keeping the generated resolver or its extensions, are rejected (TYPE_BOUND_TO_OTHER_RUNTIME), before models
@@ -180,14 +193,19 @@ export function addNoEndpointType(gqltype: GraphQLObjectType): void;
  * SimfinityRelationType) with a warning when it is in the process's first Simfinity schema. That
  * schema fixes the names: in a later createSchema(), an application type with one of the current
  * names (the original ones, or the fallback names after a rename) throws RESERVED_TYPE_NAME (500),
- * before models are created when it is an included endpoint type, a registered mutation's input or
+ * before models are created when it is an included endpoint type, a registered custom operation's input or
  * output type, an output type they reach or a field argument's type, and when the schema is
  * 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
+ * schema without mutation fields has no Mutation root.
  */
 export function createSchema(
   includedQueryTypes?: GraphQLObjectType[] | null,
   includedMutationTypes?: GraphQLObjectType[] | null,
   includedCustomMutations?: string[] | null,
+  options?: CreateSchemaOptions,
 ): GraphQLSchema;
 
 /** Register a custom mutation executed inside a transaction. */
@@ -199,6 +217,15 @@ export function registerMutation(
   callback: (input: any, session: any, context: any) => any,
 ): void;
 
+/** Register a custom query for a result that is not a stored record. No transaction or session wraps it. */
+export function registerCustomQuery(
+  name: string,
+  description: string,
+  inputModel: GraphQLInputObjectType | null | undefined,
+  outputModel: GraphQLOutputType,
+  callback: (input: any, context: any) => any,
+): void;
+
 /** Operation context for root operations, generated non-embedded relation reads, and nested collection writes. */
 export interface SimfinityMiddlewareContext {
   args: any;
@@ -294,7 +321,9 @@ export interface FilterGroupInput {
   conditions?: Array<{
     field: string;
     operator?: string;
+    /** Omitted or null for `IS_EMPTY` and `IS_NOT_EMPTY`. */
     value?: any;
+    /** Required on an object field, except for `IS_EMPTY` and `IS_NOT_EMPTY`, where it may be omitted, null or `""` to test the field itself. */
     path?: string;
   }>;
   [key: string]: any;
@@ -306,6 +335,25 @@ export interface FilterGroupInput {
  * built here. An embedded `.id` path uses the declared `id` member, except for entity types embedded
  * as lists and supplied subdocument schemas without an `id` path, which use the subdocument `_id`.
  * A filter, condition or sort path through a virtual field rejects with `INVALID_FILTER_FIELD` (400).
+ *
+ * `IS_EMPTY` and `IS_NOT_EMPTY` take no value and test the queried document's own fields, inside the
+ * same `$match`: `{ p: { $in: [null, ""] } }` and `{ p: { $nin: [null, ""] } }` on a `String` field (a
+ * validated scalar by its base scalar), `{ p: null }` and `{ p: { $ne: null } }` on any other scalar
+ * or enum and on the record identity `_id`, `{ $and: [{ p: null }, { p: { $not: { $type: "array" } } }] }`
+ * and its `$nor` on an application scalar without a supported base, which MongoDB stores as written,
+ * so that an array, also `[null]`, is a value, `{ "p.0": { $exists: false } }` and
+ * `$exists: true` on a scalar list or an embedded list, and, on an embedded object,
+ * `{ $or: [{ p: null }, { $and: [<each stored member's IS_EMPTY form>] }] }` and its `$nor`. A type
+ * without stored members is always empty (`{}` stands for the members). Embedded `id` members follow
+ * the `.id` rule above, so an object of a supplied subdocument schema with an automatic `_id` is never
+ * empty. A term without a path (omitted, null or `""`) and a group condition without a path test the
+ * field itself. The checks, and their codes, are those of `createQueryPlan` in the same order:
+ * `MISSING_FILTER_PATH` for an emptiness operator on an object filter without terms or beside terms,
+ * `INVALID_FILTER_PATH` for a value inside an embedded list or a collection and for an interface or
+ * union field or member, `INVALID_FILTER_OPERATOR` for an embedded type that reaches itself through
+ * single embedded members, `INVALID_FILTER_VALUE` for a value that is not omitted or null, and
+ * `UNSUPPORTED_QUERY` for a reference or collection on the path or among the members. Other operators
+ * keep their pipelines.
  */
 export function buildQuery(
   input: Record<string, any>,
@@ -315,7 +363,8 @@ export function buildQuery(
 
 /**
  * Translate a QLFilterGroup into a MongoDB `$match` expression, collecting required lookups. A
- * condition path through a virtual field rejects with `INVALID_FILTER_FIELD` (400).
+ * condition path through a virtual field rejects with `INVALID_FILTER_FIELD` (400). `IS_EMPTY` and
+ * `IS_NOT_EMPTY` conditions compile and reject as in {@link buildQuery}, and add no lookup.
  */
 export function buildFilterGroupMatch(
   filterGroup: FilterGroupInput,