@simtlix/simfinity-core 3.8.0 → 3.10.0

package/README.md

@@ -8,11 +8,12 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 
 ## Runtime
 
-`createRuntime(adapter)` creates a Simfinity runtime. Each instance owns its registrations, generated input types, middleware, scopes, hooks, custom mutations, and state machines; the GraphQL type objects it builds resolvers for are bound to it, and query and mutation limits are process-wide. It exposes:
+`createRuntime(adapter)` creates a Simfinity runtime. Each instance owns its registrations, generated input types, middleware, scopes, hooks, custom queries and mutations, and state machines; the GraphQL type objects it builds resolvers for are bound to it, and query and mutation limits are process-wide. It exposes:
 
 - `connect`, `addNoEndpointType`, and `createSchema` for registration and schema creation;
 - `getModel`, `getType`, `getInputType`, and `getRegistrations` for runtime inspection;
 - `use`, `registerMutation`, and `saveObject` for middleware and write orchestration;
+- `registerCustomQuery` for reads whose results are not stored records, such as previews, other sources or permission evaluations;
 - `preventCreatingCollection` to pass validation-only storage setup to an adapter;
 - `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size and nested-operation limits.
 
@@ -20,13 +21,15 @@ 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`, or an emptiness operator, `IS_EMPTY` or `IS_NOT_EMPTY`, 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`. An adapter that declares `IS_EMPTY` and `IS_NOT_EMPTY` must compile their semantics on the queried record's own fields, where `IS_NOT_EMPTY` is the exact complement of `IS_EMPTY`: a `String` is empty when missing, `null` or `""`, any other scalar or enum when missing or `null`, a list when missing, `null` or `[]`, and an embedded object when missing, `null` or every stored member is empty. The runtime rejects a value other than `null`, a path inside a list, and emptiness through references and collections before it calls the adapter, so the adapter receives conditions whose `value` may be absent and whose term or group `path` may be omitted, `null` or `""` to name the field itself; `createQueryPlan` plans them as `{ kind: 'predicate', path, operator, value: null }`, whose `path` may end at a scalar list, an embedded list or an embedded object. See [empty values](https://simtlix.github.io/simfinity.js/guide/queries.html#empty-values).
+
 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.
 
 Registration and `createSchema()` validate `extensions.scope` (`INVALID_SCOPE`) and reject list or embedded relations to unregistered types (`UNREGISTERED_RELATION_TARGET`); `use()` rejects non-functions (`INVALID_MIDDLEWARE`). Before `adapter.prepare()`, `createSchema()` rejects a writable non-embedded list relation without a non-empty child `connectionField` whose resolver it would generate (`INVALID_MODEL`, 400). A collection without `connectionField` that has an application resolver, or is `readOnly`, only logs a `Configuration issue` warning, unless it is both, and nested writes through it fail with `INVALID_MODEL` (500) before anything is written; adapters that describe the whole model, such as PostgreSQL and transactional MongoDB, still reject it in `prepare()`. Fields named like generated query arguments (`sort`, `pagination`, `AND`, `OR`, and `aggregation` on aggregate endpoints) also log a warning once per runtime. Virtual fields (`extensions: { virtual: true }` or `{ virtual: { mcp: 'tool' | 'select' | false } }`, with the field's own `resolve`) are never stored, get no generated input and no filter argument, and resolve wherever their type appears; `createSchema()` rejects an invalid declaration, a virtual field without its own resolver or with `relation`, `unique: true`, `validations`, `queryable: true` or `readOnly: false`, and a virtual identity, index, state-machine `state` or `connectionField` field (`INVALID_MODEL`, 400). A client filter, sort, `groupId` or fact path through a virtual field fails with `FORBIDDEN_FILTER_PATH` (403), and one that middleware or a scope adds fails with `INVALID_MODEL` (500). A `readOnly` field with arguments and its own resolver that is not virtual, a reference or a collection logs a `Configuration issue` warning once per runtime. Generated inputs that would have no fields are left out with a `Configuration issue` warning, with the collection operations, embedded fields and mutations that would take them; a non-null embedded field whose embedded type has no writable fields throws `INVALID_MODEL` (400) when generated mutations reach its owner. An application type named `FieldExtensionsType` or `RelationType` makes Simfinity rename its introspection metadata types to `SimfinityFieldExtensionsType` and `SimfinityRelationType` 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 `adapter.prepare()` when it is an included endpoint type, a registered mutation's input or output type, an output type they reach or a field argument's type, and when the schema is constructed otherwise, such as for a type inside an input object's fields.
 
-Generated and custom mutations run through `adapter.withTransaction`. Retried attempts receive fresh clones of GraphQL input objects, lists, and dates while enum values keep their identity. An adapter can define `stateValue` when its persisted enum representation differs from GraphQL enum names.
+Generated and custom mutations run through `adapter.withTransaction`. Retried attempts receive fresh clones of GraphQL input objects, lists, and dates while enum values keep their identity. Custom queries run without a transaction: their callback receives `(input, context)` and opens one through the engine's API when it needs it. `createSchema()` takes an optional fourth argument, an options object whose only key, `includedCustomQueries`, selects custom queries by name; any other value or key throws `INVALID_SCHEMA_OPTIONS` (500) before `adapter.prepare()`. A schema without mutation fields has no `Mutation` root. An adapter can define `stateValue` when its persisted enum representation differs from GraphQL enum names.
 
 Importing the runtime installs Simfinity's `__Field.extensions` introspection field once per GraphQL module instance; its `readOnly` flag reads `true` for virtual fields. Multiple runtimes and driver packages can be imported together without cloning schemas or duplicating introspection types.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.8.0",
+  "version": "3.10.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/auth/index.js

@@ -45,7 +45,7 @@ import {
 import SimfinityError from '../errors/simfinity.error.js';
 import { UnauthenticatedError, ForbiddenError, createAuthError } from './errors.js';
 import { isPolicyExpression, createRuleFromExpression, evaluateExpression } from './expressions.js';
-import { collectQueryPaths, walkQueryPath } from '../query-plan.js';
+import { collectQueryPathEntries, walkQueryPath } from '../query-plan.js';
 import { relationFieldOwners } from '../relation-owners.js';
 import { isThenable } from './thenable.js';
 import {
@@ -246,13 +246,15 @@ const executeRule = async (rule, parent, args, ctx, info) => {
  * field's filter, sort and aggregation arguments. Each segment needs its own `Type.field` rule
  * (exact, wildcard, then default policy). Rules run without a parent, with empty args and the
  * path field's identity in info, so parent-dependent rules such as isOwner deny query paths. A rule that
- * throws anything other than a Simfinity or GraphQL error denies the path.
+ * throws anything other than a Simfinity or GraphQL error denies the path. An IS_EMPTY or IS_NOT_EMPTY
+ * condition on an embedded object reads its stored members, so each member path is authorized as a
+ * named path is, after it, with the same answer for a field that is both.
  */
 const authorizeQueryPaths = async (permissions, defaultPolicy, schema, query, args, ctx, info) => {
   const queriedType = query && schema?.getType?.(query.typeName);
   if (!queriedType) return;
   const checked = new Set();
-  for (const segments of collectQueryPaths(args, query.operation)) {
+  for (const { segments } of collectQueryPathEntries(args, query.operation, { gqltype: queriedType, expandMembers: true })) {
     const steps = [];
     walkQueryPath(queriedType, segments, (step) => steps.push(step));
     for (const { type, fieldName, field } of steps) {

package/src/const/QLOperator.js

@@ -13,6 +13,14 @@ 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' },
+    IS_EMPTY: { value: 'IS_EMPTY' },
+    IS_NOT_EMPTY: { value: 'IS_NOT_EMPTY' },
   },
 });
 

package/src/metadata.js

@@ -22,6 +22,26 @@ const unwrap = (type) => {
   return { named, required, list, itemRequired };
 };
 
+// Follows a validated scalar's baseScalarType chain to the scalar it is stored as, stopping where the
+// chain repeats, as MongoDB's resolveStorageScalar does.
+const rootScalar = (type) => {
+  let base = type;
+  const visited = new Set();
+  while (base?.baseScalarType && !visited.has(base)) {
+    visited.add(base);
+    base = base.baseScalarType;
+  }
+  return base;
+};
+
+/**
+ * Internal: the name of the scalar a field type is stored as: the end of its baseScalarType chain, by
+ * its own name (`Date` stays `Date`). An enum or a scalar without a base gives its own name, and a
+ * chain that repeats stops where it repeats. Never throws; describeModels rejects cyclic chains and
+ * unsupported scalars on top of it.
+ */
+export const effectiveScalarName = (type) => rootScalar(type)?.name;
+
 const scalarDescription = (type) => {
   if (isEnumType(type)) {
     const storedValues = new Map();
@@ -32,14 +52,10 @@ const scalarDescription = (type) => {
     }
     return { scalar: 'Enum', values: [...storedValues.keys()], enumValues: type.getValues().map(({ name, value }) => ({ name, value })) };
   }
-  let base = type;
-  const visited = new Set();
-  while (base.baseScalarType) {
-    if (visited.has(base)) invalid(`Cyclic base scalar ${type.name}`);
-    visited.add(base);
-    base = base.baseScalarType;
-  }
-  const scalar = ['DateTime', 'Date', 'Time'].includes(base.name) ? 'DateTime' : base.name;
+  // The walk stops on a type that still has a base only where the chain repeats.
+  if (rootScalar(type).baseScalarType) invalid(`Cyclic base scalar ${type.name}`);
+  const name = effectiveScalarName(type);
+  const scalar = ['DateTime', 'Date', 'Time'].includes(name) ? 'DateTime' : name;
   if (!['String', 'ID', 'Int', 'Float', 'Boolean', 'DateTime'].includes(scalar)) {
     invalid(`Unsupported scalar ${type.name}: declare a supported baseScalarType`);
   }

package/src/query-emptiness.js

@@ -0,0 +1,222 @@
+import {
+  getNamedType, isInterfaceType, isObjectType, isScalarType, isUnionType,
+} from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+import { effectiveScalarName } from './metadata.js';
+import { getListShape, isVirtualField } from './relation-storage.js';
+
+// Internal: what the emptiness operators IS_EMPTY and IS_NOT_EMPTY (#108, part 2a) mean for a path,
+// shared by the runtime gate, the query plan and the MongoDB compiler through the
+// `./internal/query-operators` subpath, which re-exports it and is not public API. Each backend
+// compiles the shape described here to its own forms.
+
+/** The emptiness operators, in QLOperator order. IS_NOT_EMPTY is the two-valued complement of IS_EMPTY. */
+export const EMPTINESS_QUERY_OPERATORS = Object.freeze(['IS_EMPTY', 'IS_NOT_EMPTY']);
+
+/** Whether `operator` is IS_EMPTY or IS_NOT_EMPTY. */
+export const isEmptinessOperator = (operator) => EMPTINESS_QUERY_OPERATORS.includes(operator);
+
+const fail = (message, code) => { throw new SimfinityError(message, code, 400); };
+const pathName = (path) => (Array.isArray(path) ? path.join('.') : path);
+
+/**
+ * Validates the value of an emptiness condition: it must be omitted (undefined) or null. Anything
+ * else, `""`, `[]`, `{}`, `false` and `0` included, fails with INVALID_FILTER_VALUE (400). `path`
+ * names the condition in the message. Returns null, the value the plan carries.
+ */
+export const validateEmptinessValue = (operator, value, path) => {
+  if (value !== undefined && value !== null) {
+    fail(`${operator} takes no value${path == null ? '' : ` on ${pathName(path)}`}: omit it or pass null`, 'INVALID_FILTER_VALUE');
+  }
+  return null;
+};
+
+const PATH_SEGMENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// The record identity, the queried entity's own `id` or `_id`, is never empty in practice: PostgreSQL
+// stores it as a uuid primary key even when it is declared String.
+const IDENTITY = ['id', '_id'];
+const LISTS = { embeddedList: 'an embedded list', collection: 'a collection' };
+
+// A path step or a member, classified as MongoDB reads paths: interface and union types first, then an
+// object field without a relation or with `embedded: true` is embedded, and any other object field is
+// a collection when it is a list and a reference otherwise. `node` is what members are read from (an
+// object type, or a description's `fields`), and `string` tells a String scalar.
+const graphqlStep = (name, field) => {
+  const type = getNamedType(field.type);
+  const list = !!getListShape(field.type);
+  if (isInterfaceType(type) || isUnionType(type)) return { name, kind: 'abstract' };
+  if (isObjectType(type)) {
+    const relation = field.extensions?.relation;
+    const embedded = !relation || relation.embedded;
+    return {
+      name, typeName: type.name, node: type, kind: embedded ? (list ? 'embeddedList' : 'embedded') : (list ? 'collection' : 'reference'),
+    };
+  }
+  return { name, kind: list ? 'scalarList' : 'scalar', string: isScalarType(type) && effectiveScalarName(type) === 'String' };
+};
+// Virtual members store nothing and are never read.
+const graphqlMembers = (type) => Object.entries(type.getFields())
+  .filter(([, field]) => !isVirtualField(field)).map(([name, field]) => graphqlStep(name, field));
+
+// The same classification of a describeModels field description: inferred inverse references are ID
+// scalars, as GraphQL exposes them. Descriptions hold no interface or union fields.
+const modelStep = (field) => {
+  if (field.kind === 'embedded') return { name: field.name, kind: field.list ? 'embeddedList' : 'embedded', node: field.fields ?? [] };
+  if (field.kind === 'collection') return { name: field.name, kind: 'collection' };
+  if (field.kind === 'reference' && !field.inferred) return { name: field.name, kind: 'reference' };
+  return { name: field.name, kind: field.list ? 'scalarList' : 'scalar', string: field.scalar === 'String' };
+};
+const modelMembers = (fields) => fields.filter((field) => !field.private).map(modelStep);
+
+const leafShape = (step, atRoot) => {
+  if (step.kind === 'scalarList' || step.kind === 'embeddedList') return { rule: 'list' };
+  if (atRoot && IDENTITY.includes(step.name)) return { rule: 'null' };
+  return { rule: step.string ? 'string' : 'null' };
+};
+
+// Rules 3 to 6 of the order of checks, on a path whose fields resolved (rule 1): rule 3 throws as
+// soon as it is found; a cycle (rule 4) and a reference or collection (rule 6) are recorded, are not
+// entered, and throw only once the whole path and its members passed rule 3, with the value (rule 5)
+// checked between them.
+const describeSteps = (steps, { operator, value, label, membersOf }) => {
+  const segments = steps.map((step) => step.name);
+  const prefix = (index) => segments.slice(0, index + 1).join('.');
+  let cycle = null;
+  let unsupported = null;
+  const abstract = (path) => fail(`${operator} cannot test ${label}: ${path} is an interface or union field, whose emptiness is not defined`, 'INVALID_FILTER_PATH');
+  for (const [index, step] of steps.entries()) {
+    const list = index > 0 ? LISTS[steps[index - 1].kind] : null;
+    if (list) {
+      fail(`${operator} cannot test ${label}: emptiness of a value inside a list is not defined, and ${prefix(index - 1)} is ${list}`, 'INVALID_FILTER_PATH');
+    }
+    if (step.kind === 'abstract') abstract(prefix(index));
+    if (!unsupported && (step.kind === 'reference' || step.kind === 'collection')) {
+      unsupported = `${operator} on ${label} ${index === steps.length - 1 ? 'ends at' : 'crosses'} the ${step.kind} ${prefix(index)}`;
+    }
+  }
+  // The member rule: each stored member by its own rule, single embedded members recursively, lists
+  // by the list rule without looking inside their items.
+  const expand = (node, base, ancestors) => {
+    const members = [];
+    for (const member of membersOf(node)) {
+      const memberPath = [...base, member.name].join('.');
+      if (member.kind === 'abstract') abstract(memberPath);
+      if (member.kind === 'reference' || member.kind === 'collection') {
+        unsupported ??= `${operator} on ${label} reads the ${member.kind} member ${memberPath}`;
+      } else if (member.kind !== 'embedded') {
+        members.push({ name: member.name, shape: leafShape(member, false) });
+      } else if (ancestors.includes(member.node)) {
+        cycle ??= `${operator} cannot test ${label}: the embedded type ${member.typeName ?? `of ${memberPath}`} reaches itself through the single embedded member ${memberPath}`;
+      } else {
+        members.push({ name: member.name, shape: { rule: 'object', members: expand(member.node, [...base, member.name], [...ancestors, member.node]) } });
+      }
+    }
+    return members;
+  };
+  const last = steps.at(-1);
+  const shape = last.kind === 'embedded'
+    ? { rule: 'object', members: expand(last.node, segments, [last.node]) }
+    : leafShape(last, steps.length === 1);
+  if (cycle) fail(cycle, 'INVALID_FILTER_OPERATOR');
+  validateEmptinessValue(operator, value, label);
+  if (unsupported) {
+    fail(`${unsupported}: emptiness through references and collections arrives with reference emptiness (#108)`, 'UNSUPPORTED_QUERY');
+  }
+  return shape;
+};
+
+// Rule 1 on GraphQL types: segment syntax and declared, stored fields, with resolveModelPath's codes
+// and messages; nothing is traversed after a field that is not an object.
+const graphqlSteps = (gqltype, segments, path) => {
+  const parts = typeof segments === 'string' ? segments.split('.') : segments;
+  if (!Array.isArray(parts) || !parts.length || parts.some((part) => typeof part !== 'string' || !PATH_SEGMENT.test(part))) {
+    fail('Invalid filter path', 'INVALID_FILTER_PATH');
+  }
+  const label = path == null ? parts.join('.') : pathName(path);
+  const steps = [];
+  let type = gqltype;
+  for (const [index, name] of parts.entries()) {
+    const fields = isObjectType(type) ? type.getFields() : null;
+    if (!fields || !Object.hasOwn(fields, name)) fail(`Unknown field ${parts.slice(0, index + 1).join('.')}`, 'INVALID_FILTER_FIELD');
+    if (isVirtualField(fields[name])) {
+      fail(`Query path ${label} uses the virtual field ${type.name}.${name}, which is not stored`, 'INVALID_FILTER_FIELD');
+    }
+    const step = graphqlStep(name, fields[name]);
+    if (index < parts.length - 1 && !step.node) fail(`Field ${name} cannot be traversed`, 'INVALID_FILTER_PATH');
+    steps.push(step);
+    type = step.node;
+  }
+  return { steps, label };
+};
+
+/**
+ * Describes what an emptiness condition tests on a path of `gqltype`, the queried type, and applies
+ * the checks of #108 part 2a in their order: rule 1 (segment syntax and declared, stored fields, with
+ * resolveModelPath's codes and messages; nothing is traversed after a field that is not an object),
+ * then rule 3 (INVALID_FILTER_PATH for a segment after an embedded list or a collection, and for an
+ * interface or union field on the path or among the members), rule 4 (INVALID_FILTER_OPERATOR when
+ * the members re-enter an embedded type through single embedded members), rule 5 (the value, as
+ * validateEmptinessValue checks it) and rule 6 (UNSUPPORTED_QUERY when the path crosses or ends at a
+ * reference or a collection, or a member is one). Form, depth and the adapter's operators are the
+ * caller's checks. `segments` is an array or a dotted string; `path` names the condition in messages.
+ *
+ * Returns the shape: `{ rule: 'string' }` (missing, null or ""), `{ rule: 'null' }` (missing or
+ * null; the record identity always), `{ rule: 'list' }` (missing, null or []), or
+ * `{ rule: 'object', members: [{ name, shape }] }` (missing, null, or every stored member empty).
+ */
+export const describeEmptiness = (gqltype, segments, { operator = 'IS_EMPTY', value, path } = {}) => {
+  const { steps, label } = graphqlSteps(gqltype, segments, path);
+  return describeSteps(steps, { operator, value, label, membersOf: graphqlMembers });
+};
+
+/**
+ * Rule 1 of {@link describeEmptiness} alone, with its codes and messages, for a caller that applies a
+ * check of its own between rule 1 and rules 3 to 6, as the runtime gate applies the adapter's
+ * operators (rule 2). Throws for a path that does not fully resolve on `gqltype`; returns nothing.
+ */
+export const assertEmptinessPath = (gqltype, segments, { path } = {}) => {
+  graphqlSteps(gqltype, segments, path);
+};
+
+/**
+ * The same description from model metadata, for a description whose entities carry no GraphQL type:
+ * `steps` are the field descriptions resolveModelPath returns for the path, so rule 1 is already
+ * done. Gives the shapes, codes and messages of {@link describeEmptiness} for the same types.
+ */
+export const describeModelEmptiness = (steps, { operator = 'IS_EMPTY', value, path } = {}) => {
+  if (!Array.isArray(steps) || !steps.length) fail('Invalid filter path', 'INVALID_FILTER_PATH');
+  const classified = steps.map(modelStep);
+  const label = path == null ? classified.map((step) => step.name).join('.') : pathName(path);
+  return describeSteps(classified, { operator, value, label, membersOf: modelMembers });
+};
+
+/**
+ * The stored member paths an emptiness condition reads when its path, on `gqltype`, ends at a single
+ * embedded object: absolute segment arrays, depth first in field order, entering single embedded
+ * members and nothing else. Virtual members are left out. A list, reference, collection, interface or
+ * union member is listed and not entered, and so is a single embedded member whose type is already on
+ * the chain being listed. A path that does not resolve to a single embedded object lists nothing. The
+ * path is followed as walkQueryPath follows it. Never throws; every code comes from the checks.
+ */
+export const emptinessMemberPaths = (gqltype, segments) => {
+  const paths = [];
+  if (!Array.isArray(segments) || !segments.length) return paths;
+  let type = gqltype;
+  let last = null;
+  for (const name of segments) {
+    const fields = typeof type?.getFields === 'function' ? type.getFields() : null;
+    if (!fields || typeof name !== 'string' || !Object.hasOwn(fields, name) || isVirtualField(fields[name])) return paths;
+    last = graphqlStep(name, fields[name]);
+    type = getNamedType(fields[name].type);
+  }
+  if (last.kind !== 'embedded') return paths;
+  const visit = (node, base, ancestors) => {
+    for (const member of graphqlMembers(node)) {
+      const memberPath = [...base, member.name];
+      paths.push(memberPath);
+      if (member.kind === 'embedded' && !ancestors.includes(member.node)) visit(member.node, memberPath, [...ancestors, member.node]);
+    }
+  };
+  visit(last.node, segments, [last.node]);
+  return paths;
+};

package/src/query-operators.js

@@ -0,0 +1,87 @@
+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. The emptiness operators live in
+// query-emptiness.js and are re-exported here, so the subpath stays the only one.
+
+export {
+  EMPTINESS_QUERY_OPERATORS, describeEmptiness, describeModelEmptiness, emptinessMemberPaths, isEmptinessOperator,
+  validateEmptinessValue,
+} from './query-emptiness.js';
+export { effectiveScalarName } from './metadata.js';
+
+/** 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)) };
+};