@simtlix/simfinity-core 3.8.0 → 3.9.0

package/README.md

@@ -20,6 +20,8 @@ The adapter supplies model creation, identifiers, transactions, record reads and
 
 An adapter can also define `findChildrenBatch(model, type, connectionField, parentIds, args, { context })`, the batch form of `findChildren` for generated collection fields, and a synchronous `batchesChildren(model, type, connectionField)` predicate. The runtime calls both as adapter methods and checks them on every read. When the method is missing or the predicate returns `false`, each field calls `findChildren` at once with the arguments object it built, as before. Otherwise, within one request (a context object), the runtime groups the collection reads of one related type and connection storage field whose effective arguments (after middleware, the scope and joined scopes) hold the same plain data and are requested in the same tick, that is before the promise jobs queued so far have run. It calls the method with 2 to 100 distinct parent IDs, each a raw ID that `castId` accepts without changing its string form, and with a copy of the arguments that the method may change; a group with one distinct parent calls `findChildren`. Return one array per parent ID, in order, each holding exactly the records, order and page that `findChildren` returns for that parent; records should show their parent under the connection field, or not show one. Fields of one parent share its records, each with its own array. After a rejection, or a result of another shape or with records of another parent, each field reads alone with `findChildren`; failures other than a `SimfinityError`, and results of another shape, are logged once per type. Pairing rule: the batch must reproduce `this.findChildren`, so `batchesChildren` must return `false` when `this.findChildren` is not the adapter's own function, as with a spread copy or an `Object.assign` override that changes how children are read. The bundled adapters follow this rule: both define the two members only with `batchedCollections: true`: the SQL adapter when the schema is prepared and its plugin's `compileChildrenQuery` is paired with its `compileQuery`, and the MongoDB adapter at creation. To opt out on one adapter instance, set `adapter.findChildrenBatch = undefined` (deleting it does nothing for a class whose method is on the prototype), or make `batchesChildren` return `false`. A copy that overrides `getById` still inherits the base `getByIds`, as before.
 
+An adapter declares the filter operators it compiles as `queryFeatures: { operators }`, a list of `QLOperator` values that includes `EQ`, which a condition without an operator means; names this version does not know are ignored. `createRuntime()` reads it once and throws `INVALID_QUERY_FEATURES` (500) unless it is `undefined`, `null` or an object whose `operators` is an array of strings. Without a declaration the adapter supports the operators of 3.7.0, `EQ`, `NE`, `LT`, `LTE`, `GT`, `GTE`, `BTW`, `IN`, `NIN` and `LIKE`, so it never receives a text operator such as `ILIKE` that it would drop or misread. A list, count, aggregate or collection read, or a by-ID read through a `get_by_id` scope, that uses another `QLOperator` value fails with `UNSUPPORTED_QUERY` (400): the runtime checks the client's arguments before middleware runs and the final arguments, with what middleware, scopes and joined scopes added, before it calls the adapter. Operators that `QLOperator` does not list still reach the adapter. An adapter that receives the text operators must apply their rules: literal values, a `String` field or list, and `INVALID_FILTER_VALUE` (400) for a value that is not a string or contains U+0000. `createQueryPlan(models, entity, args, { operators })` validates them and rejects operators outside `operators` with `UNSUPPORTED_QUERY`.
+
 Entity types, those registered with `connect()` and the targets of non-embedded relations, resolve `id` to `_id`, falling back to `id`, whatever the `createSchema()` allowlists include; types used only as embedded values keep their declared `id`. Embedded copies of an entity type resolve the same way, so they return their declared `id` unless the adapter stores an `_id` for them, as MongoDB does for embedded list items. The resolver is set on the type object, so it applies in every runtime that shares the type. `createSchema()` marks these registrations with `storedIdentity: true` before calling `adapter.prepare()`.
 
 When a runtime first creates a schema, it binds each GraphQL object type whose non-embedded relation fields receive its generated resolvers. It also reserves each reachable object type that still has a non-embedded relation field without a resolver, such as an unregistered custom mutation result. Registering a bound or reserved type in another runtime, or building another runtime's schema that reaches it through fields, interfaces, union members or custom mutation results, throws `TYPE_BOUND_TO_OTHER_RUNTIME` (409). `createSchema()` also rejects a type with a relation field copied, by `toConfig()` or a field spread, after another runtime generated that field's resolver. Create type objects once per runtime, for example with a factory function. Types without non-embedded relation fields, and types whose relation fields all have application resolvers, can be shared, and another runtime can use a `toConfig()` copy made before the first runtime built its schema. A shared custom mutation result type with an unresolved relation field is rejected.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",
@@ -52,6 +52,7 @@
       "default": "./src/auth/rules.js"
     },
     "./internal/object-id": "./src/auth/object-id.js",
+    "./internal/query-operators": "./src/query-operators.js",
     "./internal/relation-storage": "./src/relation-storage.js",
     "./plugins": {
       "types": "./types/plugins.d.ts",

package/src/const/QLOperator.js

@@ -13,6 +13,12 @@ const QLOperator = new GraphQLEnumType({
     IN: { value: 'IN' },
     NIN: { value: 'NIN' },
     LIKE: { value: 'LIKE' },
+    ILIKE: { value: 'ILIKE' },
+    STARTS_WITH: { value: 'STARTS_WITH' },
+    ISTARTS_WITH: { value: 'ISTARTS_WITH' },
+    ENDS_WITH: { value: 'ENDS_WITH' },
+    IENDS_WITH: { value: 'IENDS_WITH' },
+    IEQ: { value: 'IEQ' },
   },
 });
 

package/src/query-operators.js

@@ -0,0 +1,80 @@
+import QLOperator from './const/QLOperator.js';
+import SimfinityError from './errors/simfinity.error.js';
+
+// Internal: the filter operators and the value rules every backend applies to them. They are shared
+// by the core runtime, the query plan and the MongoDB compiler through the
+// `./internal/query-operators` subpath, which is not public API.
+
+/** Every `QLOperator` value, in declaration order. QLOperator is the only list of operators. */
+export const QUERY_OPERATORS = Object.freeze(QLOperator.getValues().map((entry) => entry.value));
+
+/**
+ * The operators of 3.7.0. An adapter that declares no `queryFeatures` supports exactly these, so a
+ * custom adapter written for 3.7 never receives an operator it would drop or misread.
+ */
+export const LEGACY_QUERY_OPERATORS = Object.freeze(['EQ', 'NE', 'LT', 'LTE', 'GT', 'GTE', 'BTW', 'IN', 'NIN', 'LIKE']);
+
+/**
+ * The literal text operators (#108, part 1) and what each one matches: `contains`, `prefix`,
+ * `suffix` or `exact` (the whole value), respecting case or ignoring it (`ignoreCase`). Values are
+ * literal: `%`, `_`, `.`, `*`, `\`, `^`, `$` and `(` match themselves. `LIKE`, the case-sensitive
+ * substring of 3.7.0, keeps its own validation and compilation and is not listed here.
+ */
+export const TEXT_QUERY_OPERATORS = Object.freeze({
+  ILIKE: Object.freeze({ match: 'contains', ignoreCase: true }),
+  STARTS_WITH: Object.freeze({ match: 'prefix', ignoreCase: false }),
+  ISTARTS_WITH: Object.freeze({ match: 'prefix', ignoreCase: true }),
+  ENDS_WITH: Object.freeze({ match: 'suffix', ignoreCase: false }),
+  IENDS_WITH: Object.freeze({ match: 'suffix', ignoreCase: true }),
+  IEQ: Object.freeze({ match: 'exact', ignoreCase: true }),
+});
+
+/** Whether `operator` is a `QLOperator` value. */
+export const isQueryOperator = (operator) => QUERY_OPERATORS.includes(operator);
+
+/** The {@link TEXT_QUERY_OPERATORS} entry of `operator`, or null for any other operator. */
+export const textQueryOperator = (operator) => (
+  typeof operator === 'string' && Object.hasOwn(TEXT_QUERY_OPERATORS, operator) ? TEXT_QUERY_OPERATORS[operator] : null
+);
+
+const invalidValue = (message) => { throw new SimfinityError(message, 'INVALID_FILTER_VALUE', 400); };
+
+/**
+ * Validates the value of a text operator condition before any backend compiles it, so both backends
+ * reject the same input with the same code. `scalar` names the effective scalar of the path's last
+ * field: the base scalar of a validated scalar (`String` for an email scalar), `Enum` or the enum
+ * type's name for an enum, `ID` for identifiers and references. The field must be a `String` field
+ * or a `String` list, and the value a string without U+0000; the empty string is valid. Anything
+ * else fails with `INVALID_FILTER_VALUE` (400), as `LIKE` does. Returns the value unchanged: it is
+ * not passed through the field's scalar, since a validated scalar filters by its base scalar.
+ */
+export const validateTextFilterValue = (operator, value, scalar, path) => {
+  const where = path == null ? '' : ` on ${Array.isArray(path) ? path.join('.') : path}`;
+  if (scalar !== 'String') invalidValue(`${operator} requires a String field${where}`);
+  if (typeof value !== 'string') invalidValue(`${operator} requires a non-null string value${where}`);
+  if (value.includes('\u0000')) invalidValue(`${operator} values cannot contain U+0000${where}`);
+  return value;
+};
+
+const invalidFeatures = (message) => {
+  throw new SimfinityError(`DatabaseAdapter queryFeatures ${message}`, 'INVALID_QUERY_FEATURES', 500);
+};
+
+/**
+ * Reads an adapter's `queryFeatures` declaration into the set of operators it compiles. Without a
+ * declaration (undefined or null) the adapter supports {@link LEGACY_QUERY_OPERATORS}. A declaration
+ * is an object whose `operators` is an array of operator names; names this version does not
+ * know are ignored, and other members are left for later features. Anything else throws
+ * `INVALID_QUERY_FEATURES` (500).
+ */
+export const resolveQueryFeatures = (queryFeatures) => {
+  if (queryFeatures == null) return { operators: new Set(LEGACY_QUERY_OPERATORS) };
+  if (typeof queryFeatures !== 'object' || Array.isArray(queryFeatures)) {
+    invalidFeatures('must be an object with an operators array');
+  }
+  const { operators } = queryFeatures;
+  if (!Array.isArray(operators) || operators.some((operator) => typeof operator !== 'string')) {
+    invalidFeatures('operators must be an array of operator names');
+  }
+  return { operators: new Set(operators.filter(isQueryOperator)) };
+};

package/src/query-plan.js

@@ -1,8 +1,9 @@
 import { paginationStages } from './query-limits.js';
 import SimfinityError from './errors/simfinity.error.js';
+import { QUERY_OPERATORS, textQueryOperator, validateTextFilterValue } from './query-operators.js';
 
 const fail = (message, code = 'INVALID_FILTER_VALUE') => { throw new SimfinityError(message, code, 400); };
-const operators = new Set(['EQ', 'NE', 'LT', 'LTE', 'GT', 'GTE', 'BTW', 'IN', 'NIN', 'LIKE']);
+const operators = new Set(QUERY_OPERATORS);
 const reserved = new Set(['AND', 'OR', 'sort', 'pagination', 'aggregation']);
 // `aggregation` is a generated argument only on aggregate endpoints; on find and count a field of
 // that name is filtered like any other.
@@ -47,6 +48,40 @@ export const collectQueryPathEntries = (args, operation = 'find') => {
   return entries;
 };
 
+/**
+ * Internal: the operator of every condition the arguments hold, as `{ operator, path }` entries: field
+ * filters, relation terms and AND/OR group conditions at any depth, with an omitted operator read as
+ * `EQ`. `path` names the condition for messages. Sort, pagination and aggregation hold no operators.
+ * Malformed entries are skipped and left to the backends; a group reached twice is read once.
+ */
+export const collectQueryOperators = (args, operation = 'find') => {
+  const entries = [];
+  if (!args || typeof args !== 'object') return entries;
+  const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+  const add = (item, path) => {
+    if (isObject(item)) entries.push({ operator: item.operator ?? 'EQ', path });
+  };
+  const visited = new Set();
+  const visit = (group) => {
+    if (!isObject(group) || visited.has(group)) return;
+    visited.add(group);
+    for (const condition of listOf(group.conditions)) {
+      add(condition, condition?.path != null && condition.path !== '' ? `${condition.field}.${condition.path}` : condition?.field);
+    }
+    for (const item of [...listOf(group.AND), ...listOf(group.OR)]) visit(item);
+  };
+  const controls = controlArgs(operation);
+  for (const [name, value] of Object.entries(args)) {
+    if (controls.has(name) || !isObject(value)) continue;
+    // A relation filter's operators are in its terms; an operator beside them is read too, since a
+    // backend that reads the field as a scalar would compile it.
+    if (!Array.isArray(value.terms) || value.operator !== undefined) add(value, name);
+    if (Array.isArray(value.terms)) for (const term of value.terms) add(term, `${name}.${term?.path}`);
+  }
+  for (const item of [...listOf(args.AND), ...listOf(args.OR)]) visit(item);
+  return entries;
+};
+
 /** Internal: the segment arrays of {@link collectQueryPathEntries}. */
 export const collectQueryPaths = (args, operation = 'find') => (
   collectQueryPathEntries(args, operation).map((entry) => entry.segments)
@@ -87,8 +122,14 @@ export const resolveModelPath = (models, entityName, path) => {
   return steps;
 };
 
-/** Typed paths and logical groups; neither SQL nor Mongo pipeline objects are stored here. */
-export const createQueryPlan = (models, entityName, input = {}, { mode = 'find' } = {}) => {
+/**
+ * Typed paths and logical groups; neither SQL nor Mongo pipeline objects are stored here. Operators
+ * and values are validated here, text operators through validateTextFilterValue. With `operators`,
+ * the names a compiler supports, any other QLOperator value fails with UNSUPPORTED_QUERY (400);
+ * without it every QLOperator value is planned.
+ */
+export const createQueryPlan = (models, entityName, input = {}, { mode = 'find', operators: supported } = {}) => {
+  const allowed = supported == null ? null : new Set(supported);
   const combine = (kind, terms) => {
     const active = terms.filter(Boolean);
     return active.length > 1 ? { kind, terms: active } : active[0] || null;
@@ -99,11 +140,13 @@ export const createQueryPlan = (models, entityName, input = {}, { mode = 'find'
     if (field.kind !== 'scalar' && !field.inferred) fail(`Filter on object field ${path} requires a scalar path`, 'MISSING_FILTER_PATH');
     const op = operator ?? 'EQ';
     if (!operators.has(op)) fail(`Unknown filter operator: ${op}`, 'INVALID_FILTER_OPERATOR');
+    if (allowed && !allowed.has(op)) fail(`The ${op} filter operator is not supported by this query compiler`, 'UNSUPPORTED_QUERY');
     const collection = ['IN', 'NIN', 'BTW'].includes(op);
     if (value === undefined || (!collection && Array.isArray(value)) || (value === null && !['EQ', 'NE'].includes(op))) fail('Expected a scalar filter value');
     if (collection && Array.isArray(value) && value.some((item) => item == null || Array.isArray(item))) fail('Filter lists require non-null scalar elements');
     if (['IN', 'NIN', 'BTW'].includes(op) && !Array.isArray(value)) fail(`${op} requires an array value`);
     if (op === 'BTW' && value.length !== 2) fail('BTW requires two values');
+    if (textQueryOperator(op)) validateTextFilterValue(op, value, field.scalar, path);
     return { kind: 'predicate', path: Array.isArray(path) ? path : path.split('.'), operator: op, value: value === undefined ? null : value };
   };
   const validateGroup = (value, keys = ['conditions', 'AND', 'OR']) => {

package/src/runtime.js

@@ -13,7 +13,10 @@ import { ForbiddenError } from './auth/errors.js';
 import QLOperator from './const/QLOperator.js';
 import QLValue from './const/QLValue.js';
 import QLSort from './const/QLSort.js';
-import { collectQueryPathEntries, collectQueryPaths, walkQueryPath } from './query-plan.js';
+import {
+  collectQueryOperators, collectQueryPathEntries, collectQueryPaths, walkQueryPath,
+} from './query-plan.js';
+import { QUERY_OPERATORS, isQueryOperator, resolveQueryFeatures } from './query-operators.js';
 import { relationFieldOwners } from './relation-owners.js';
 import { isThenable } from './auth/thenable.js';
 import {
@@ -451,6 +454,10 @@ export const createRuntime = (adapter) => {
   if (!adapter) {
     throw new SimfinityError('A database adapter is required', 'ADAPTER_REQUIRED', 500);
   }
+  // The filter operators the adapter compiles, read once: its queryFeatures.operators, or the 3.7.0
+  // operators when it declares none.
+  const supportedOperators = resolveQueryFeatures(adapter.queryFeatures).operators;
+  const supportsEveryOperator = QUERY_OPERATORS.every((operator) => supportedOperators.has(operator));
 
   const stateValue = adapter.stateValue || ((state) => state.name);
   const runtimeIdentity = {};
@@ -1787,6 +1794,21 @@ const assertStoredQueryPaths = (gqltype, args, operation) => {
   }
 };
 
+// Rejects a QLOperator value that the adapter does not declare in queryFeatures, with
+// UNSUPPORTED_QUERY (400), so an adapter never drops or misreads a condition it does not compile.
+// Runs on the client's arguments before middleware and on the final arguments before the adapter
+// call, which covers what middleware, scopes and joined scopes added. Operators that QLOperator does
+// not list are left to the adapter, which reports them as before.
+const assertSupportedOperators = (gqltype, args, operation) => {
+  if (supportsEveryOperator) return;
+  for (const { operator, path } of collectQueryOperators(args, operation)) {
+    if (isQueryOperator(operator) && !supportedOperators.has(operator)) {
+      throw new SimfinityError(`The database adapter does not support the ${operator} filter operator, used on `
+        + `${gqltype.name}.${path}`, 'UNSUPPORTED_QUERY', 400);
+    }
+  }
+};
+
 // A joined scope must not repeat the rows it restricts: its paths may not cross a collection, nor
 // reach a non-embedded relation inside an embedded list, which is joined once per list item.
 const assertJoinedScopePaths = (groups, prefix, target) => {
@@ -1941,6 +1963,7 @@ const resolveById = async (type, args, context, requiredId) => {
   const queryArgs = { id: { operator: 'EQ', value: args.id } };
   await executeScope({ type, args: queryArgs, operation: 'get_by_id', context });
   assertStoredQueryPaths(type.gqltype, queryArgs, 'find');
+  assertSupportedOperators(type.gqltype, queryArgs, 'find');
   const results = await adapter.find(type.model, type.gqltype, queryArgs, null, { requiredId, context });
   return results[0] || null;
 };
@@ -2448,6 +2471,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
           extensions: { simfinityQuery: { typeName: type.gqltype.name, operation: 'find', countSink: true } },
           async resolve(parent, args, context, info) {
             const joinedScopes = inspectClientPaths(type.gqltype, args, 'find');
+            assertSupportedOperators(type.gqltype, args, 'find');
             const params = {
               type,
               args,
@@ -2458,6 +2482,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
             await executeScope(params);
             await applyJoinedScopes(joinedScopes, params);
             assertStoredQueryPaths(type.gqltype, params.args, 'find');
+            assertSupportedOperators(type.gqltype, params.args, 'find');
             const queryArgs = params.args;
             const wantsCount = !!(queryArgs.pagination && queryArgs.pagination.count)
               && canReportCount(parent, info, context);
@@ -2494,6 +2519,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
           extensions: { simfinityQuery: { typeName: type.gqltype.name, operation: 'aggregate' } },
           async resolve(parent, args, context) {
             const joinedScopes = inspectClientPaths(type.gqltype, args, 'aggregate');
+            assertSupportedOperators(type.gqltype, args, 'aggregate');
             const params = {
               type,
               args,
@@ -2504,6 +2530,7 @@ const buildRootQuery = (name, includedTypes, aggregationResultType = QLTypeAggre
             await executeScope(params);
             await applyJoinedScopes(joinedScopes, params);
             assertStoredQueryPaths(type.gqltype, params.args, 'aggregate');
+            assertSupportedOperators(type.gqltype, params.args, 'aggregate');
             return adapter.aggregate(type.model, type.gqltype, params.args, null);
           },
         };
@@ -2953,11 +2980,13 @@ const autoGenerateResolvers = (gqltype) => {
           throw new Error(`Related type ${relatedType.name} not found or not connected. Make sure it's connected with simfinity.connect() or simfinity.addNoEndpointType().`);
         }
         const joinedScopes = inspectClientPaths(relatedType, args, 'find');
+        assertSupportedOperators(relatedType, args, 'find');
         const params = { type: relatedTypeInfo, args, operation: 'find', context };
         await executeMiddleware(params);
         await executeScope(params);
         await applyJoinedScopes(joinedScopes, params);
         assertStoredQueryPaths(relatedType, params.args, 'find');
+        assertSupportedOperators(relatedType, params.args, 'find');
         return loadChildren(relatedTypeInfo, connection, parent._id ?? parent.id, params.args, context);
       }, { simfinityQuery: { typeName: relatedType.name, operation: 'find' } });
       runtimeBoundTypes.set(gqltype, runtimeIdentity);

package/types/index.d.ts

@@ -8,10 +8,36 @@ import type {
   GraphQLSchema,
 } from 'graphql';
 
+/** The filter operator enum; its values are the {@link QueryOperator} names. */
 export const QLOperator: GraphQLEnumType;
 export const QLSort: GraphQLInputObjectType;
 export const QLValue: GraphQLScalarType<unknown, unknown>;
 
+/**
+ * A `QLOperator` value. The operators of 3.7.0 are `EQ`, `NE`, `LT`, `LTE`, `GT`, `GTE`, `BTW`, `IN`,
+ * `NIN` and `LIKE`. The literal text operators take a non-null string without U+0000 on a `String`
+ * field or `String` list (a validated scalar filters by its base scalar), and match it literally:
+ * `ILIKE` as a substring ignoring case, `STARTS_WITH` and `ISTARTS_WITH` as a prefix, `ENDS_WITH`
+ * and `IENDS_WITH` as a suffix, respecting or ignoring case, and `IEQ` as the whole value ignoring
+ * case. An empty value matches every non-null string, except for `IEQ`, where it matches only the
+ * empty string. On a list, some element must match.
+ */
+export type QueryOperator =
+  | 'EQ' | 'NE' | 'LT' | 'LTE' | 'GT' | 'GTE' | 'BTW' | 'IN' | 'NIN' | 'LIKE'
+  | 'ILIKE' | 'STARTS_WITH' | 'ISTARTS_WITH' | 'ENDS_WITH' | 'IENDS_WITH' | 'IEQ';
+
+/**
+ * The query language features a {@link DatabaseAdapter} compiles. Declare it so that the runtime
+ * sends the adapter only conditions it compiles; later releases add members for later features.
+ */
+export interface QueryFeatures {
+  /**
+   * The `QLOperator` values the adapter compiles, including an omitted operator's `EQ`. Names this
+   * version of Simfinity does not know are ignored.
+   */
+  operators: readonly (QueryOperator | (string & {}))[];
+}
+
 export interface ModelRegistration {
   gqltype: GraphQLObjectType;
   /** Defaults to true. False excludes embedded-only types until referenced. */
@@ -331,6 +357,18 @@ export interface Runtime<Model = any, Session = any> {
 
 /** Driver adapter contract. GraphQL generation and lifecycle live in createRuntime. */
 export interface DatabaseAdapter<Model = any, Session = any> {
+  /**
+   * Optional. The filter operators this adapter compiles. `createRuntime` reads it once and throws
+   * `INVALID_QUERY_FEATURES` (500) unless it is undefined, null or an object whose `operators` is an
+   * array of strings. Without it the adapter supports the operators of 3.7.0 (`EQ`, `NE`, `LT`,
+   * `LTE`, `GT`, `GTE`, `BTW`, `IN`, `NIN` and `LIKE`). A list, aggregate or collection read, or a
+   * by-ID read through a `get_by_id` scope, whose arguments use a `QLOperator` value the adapter
+   * does not support fails with `UNSUPPORTED_QUERY` (400), before middleware runs for the client's
+   * arguments and before `find`, `count`, `aggregate`, `findChildren` or `findChildrenBatch` for
+   * conditions that middleware, scopes and joined scopes added. Operators outside `QLOperator` still
+   * reach the adapter, which reports them as before.
+   */
+  queryFeatures?: QueryFeatures | null | undefined;
   bind?(runtime: Pick<Runtime<Model, Session>, 'getModel' | 'getType' | 'getRegistrations'>): void;
   validateRegistration?(registration: RuntimeRegistration<Model, Session>): void;
   /**
@@ -448,6 +486,7 @@ export interface DatabaseAdapter<Model = any, Session = any> {
 }
 export function createRuntime<Model = any, Session = any>(adapter: DatabaseAdapter<Model, Session>): Runtime<Model, Session>;
 
+/** `operator` is a {@link QueryOperator}; the value of a text operator is a validated string. */
 export type QueryPredicate = { kind: 'predicate'; path: string[]; operator: string; value: any } | { kind: 'and' | 'or'; terms: QueryPredicate[] };
 export interface QueryPlan {
   entity: string;
@@ -457,7 +496,14 @@ export interface QueryPlan {
   pagination: { limit: number; offset: number } | null;
   aggregation?: { groupId: string[]; facts: Array<{ path: string[]; factName: string; operation: 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' }> };
 }
-export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode'] }): QueryPlan;
+/**
+ * Validates the arguments into a plan: paths, operators and values, with `INVALID_FILTER_VALUE` (400)
+ * for a text operator on a field that is not a `String` field or list, or with a value that is not
+ * a string or contains U+0000. With `operators`, the names the caller compiles, any other
+ * `QLOperator` value fails with `UNSUPPORTED_QUERY` (400); unknown operators fail with
+ * `INVALID_FILTER_OPERATOR` (400) either way.
+ */
+export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string> }): QueryPlan;
 export function resolveModelPath(models: ModelDescription, entityName: string, path: string | string[]): FieldDescription[];
 
 export function configureQueryLimits(options?: { maxPageSize?: number }): void;