@simtlix/simfinity-core 3.9.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,7 +21,7 @@ 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`.
+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()`.
 
@@ -28,7 +29,7 @@ When a runtime first creates a schema, it binds each GraphQL object type whose n
 
 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.9.0",
+  "version": "3.10.0",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",

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

@@ -19,6 +19,8 @@ const QLOperator = new GraphQLEnumType({
     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

@@ -3,7 +3,14 @@ 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.
+// `./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));

package/src/query-plan.js

@@ -1,6 +1,9 @@
 import { paginationStages } from './query-limits.js';
 import SimfinityError from './errors/simfinity.error.js';
-import { QUERY_OPERATORS, textQueryOperator, validateTextFilterValue } from './query-operators.js';
+import {
+  QUERY_OPERATORS, describeEmptiness, describeModelEmptiness, emptinessMemberPaths, isEmptinessOperator, textQueryOperator,
+  validateTextFilterValue,
+} from './query-operators.js';
 
 const fail = (message, code = 'INVALID_FILTER_VALUE') => { throw new SimfinityError(message, code, 400); };
 const operators = new Set(QUERY_OPERATORS);
@@ -10,6 +13,10 @@ const reserved = new Set(['AND', 'OR', 'sort', 'pagination', 'aggregation']);
 const listReserved = new Set(['AND', 'OR', 'sort', 'pagination']);
 const controlArgs = (operation) => (operation === 'aggregate' ? reserved : listReserved);
 const listOf = (value) => (Array.isArray(value) ? value : []);
+const nestedGroups = (group) => [...listOf(group.AND), ...listOf(group.OR)];
+// A term or condition path that names nothing: for the emptiness operators only, the field itself.
+const isPathless = (path) => path == null || path === '';
+const hasTermPath = (term) => typeof term?.path === 'string' && term.path !== '';
 
 /**
  * Internal: the model paths named by generated query arguments, as `{ segments, group }` entries.
@@ -17,30 +24,59 @@ const listOf = (value) => (Array.isArray(value) ? value : []);
  * groupId and fact paths; aggregate sort terms name result keys. Outside aggregate mode a key
  * named `aggregation` is a field filter like any other. `group` is the AND/OR group
  * object whose `conditions` hold the path, or null for the other forms. Malformed entries are
- * left to the backends.
+ * left to the backends. An emptiness term without a path (omitted, null or "") names its field,
+ * also next to sibling terms that have paths.
+ *
+ * With `expandMembers` and the queried `gqltype`, the path of each emptiness condition is followed by
+ * the stored member paths that condition reads (emptinessMemberPaths), as `{ segments, group,
+ * member: true }` entries, so that the checks of client paths apply to them. Only client arguments
+ * are expanded.
  */
-export const collectQueryPathEntries = (args, operation = 'find') => {
+export const collectQueryPathEntries = (args, operation = 'find', { gqltype, expandMembers = false } = {}) => {
   const entries = [];
   const add = (path, group = null) => {
     if (typeof path === 'string' && path) entries.push({ segments: path.split('.'), group });
   };
+  const addEmptiness = (path, group = null) => {
+    add(path, group);
+    if (!expandMembers || typeof path !== 'string' || !path) return;
+    for (const segments of emptinessMemberPaths(gqltype, path.split('.'))) entries.push({ segments, group, member: true });
+  };
   if (!args || typeof args !== 'object') return entries;
   const visit = (group) => {
     if (!group || typeof group !== 'object') return;
     for (const condition of listOf(group.conditions)) {
       if (typeof condition?.field !== 'string') continue;
-      add(condition.path != null && condition.path !== '' ? `${condition.field}.${condition.path}` : condition.field, group);
+      const path = isPathless(condition.path) ? condition.field : `${condition.field}.${condition.path}`;
+      if (isEmptinessOperator(condition.operator)) addEmptiness(path, group);
+      else add(path, group);
     }
-    for (const item of [...listOf(group.AND), ...listOf(group.OR)]) visit(item);
+    for (const item of nestedGroups(group)) visit(item);
   };
   const controls = controlArgs(operation);
   for (const [name, value] of Object.entries(args)) {
     if (controls.has(name) || value == null) continue;
-    const terms = listOf(value.terms).filter((term) => typeof term?.path === 'string' && term.path);
-    if (terms.length) for (const term of terms) add(`${name}.${term.path}`);
-    else add(name);
+    const terms = listOf(value.terms);
+    const pathless = (term) => isEmptinessOperator(term?.operator) && isPathless(term.path);
+    if (!terms.some(hasTermPath)) {
+      if (isEmptinessOperator(value.operator) || terms.some(pathless)) addEmptiness(name);
+      else add(name);
+      continue;
+    }
+    let field = false;
+    for (const term of terms) {
+      if (hasTermPath(term)) {
+        if (isEmptinessOperator(term.operator)) addEmptiness(`${name}.${term.path}`);
+        else add(`${name}.${term.path}`);
+      } else if (!field && pathless(term)) {
+        addEmptiness(name);
+        field = true;
+      }
+    }
+    // An emptiness operator beside terms is rejected later; until then it reads the field too.
+    if (!field && isEmptinessOperator(value.operator)) addEmptiness(name);
   }
-  for (const item of [...listOf(args.AND), ...listOf(args.OR)]) visit(item);
+  for (const item of nestedGroups(args)) visit(item);
   if (operation === 'aggregate') {
     add(args.aggregation?.groupId);
     for (const fact of listOf(args.aggregation?.facts)) add(fact?.path);
@@ -49,36 +85,75 @@ export const collectQueryPathEntries = (args, operation = 'find') => {
 };
 
 /**
- * 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.
+ * Internal: every condition the arguments hold, as `{ operator, path, segments, form, field, rawPath,
+ * value, hasValue, ambiguous, depth }` entries: field filters, relation terms and AND/OR group
+ * conditions at any depth, with an omitted operator read as `EQ`.
+ * - `form` is 'filter' (an argument's own operator, without a terms array), 'beside-terms' (an
+ *   operator written next to a terms array, which the compilers read only to reject an emptiness
+ *   operator), 'term' or 'condition'.
+ * - `field` is the argument or condition field as written (a condition's may be dotted) and `rawPath`
+ *   the term or condition path as written. `path`, for messages, and `segments` join them; a path that
+ *   is omitted, null or "" names the field itself.
+ * - `value` is the condition's value, and `hasValue` whether it has an own `value` key.
+ * - `ambiguous` marks a condition with both a dotted field and a non-empty path.
+ * - `depth` is 0 for argument filters and for the groups listed in args.AND and args.OR, and one more
+ *   for each nested group; a group reached at several depths reports the deepest.
+ * 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 add = (item, form, field, rawPath, depth, ambiguous = false) => {
+    if (!isObject(item)) return;
+    const path = isPathless(rawPath) ? field : `${field}.${rawPath}`;
+    entries.push({
+      operator: item.operator ?? 'EQ',
+      path,
+      segments: typeof path === 'string' && path ? path.split('.') : [],
+      form,
+      field,
+      rawPath,
+      value: item.value,
+      hasValue: Object.hasOwn(item, 'value'),
+      ambiguous,
+      depth,
+    });
+  };
+  // The deepest level of each group, as the backends' depth limit counts it; a group inside itself is
+  // not entered again.
+  const depths = new Map();
+  const open = new Set();
+  const measure = (group, depth) => {
+    if (!isObject(group) || open.has(group) || depths.get(group) >= depth) return;
+    depths.set(group, depth);
+    open.add(group);
+    for (const item of nestedGroups(group)) measure(item, depth + 1);
+    open.delete(group);
   };
   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);
+      const field = condition?.field;
+      const rawPath = condition?.path;
+      add(condition, 'condition', field, rawPath, depths.get(group), typeof field === 'string' && field.includes('.') && !isPathless(rawPath));
     }
-    for (const item of [...listOf(group.AND), ...listOf(group.OR)]) visit(item);
+    for (const item of nestedGroups(group)) 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}`);
+    const terms = Array.isArray(value.terms);
+    if (!terms || value.operator !== undefined) add(value, terms ? 'beside-terms' : 'filter', name, undefined, 0);
+    if (terms) for (const term of value.terms) add(term, 'term', name, term?.path, 0);
   }
-  for (const item of [...listOf(args.AND), ...listOf(args.OR)]) visit(item);
+  for (const item of nestedGroups(args)) measure(item, 0);
+  for (const item of nestedGroups(args)) visit(item);
   return entries;
 };
 
@@ -127,6 +202,14 @@ export const resolveModelPath = (models, entityName, path) => {
  * 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.
+ *
+ * The emptiness operators plan `{ kind: 'predicate', path, operator, value: null }`, whose path may
+ * end at a scalar, a scalar list, an embedded list or an embedded object, after the checks of
+ * describeEmptiness in their order (on the entity's GraphQL type, or on the field descriptions when
+ * the description has none). A term or condition without a path tests the field itself; an emptiness
+ * operator on an object filter without terms, or beside terms, fails with MISSING_FILTER_PATH. A
+ * filter path of other operators that has more than one segment and ends at an object fails with
+ * INVALID_FILTER_PATH; a bare object field keeps MISSING_FILTER_PATH.
  */
 export const createQueryPlan = (models, entityName, input = {}, { mode = 'find', operators: supported } = {}) => {
   const allowed = supported == null ? null : new Set(supported);
@@ -134,11 +217,24 @@ export const createQueryPlan = (models, entityName, input = {}, { mode = 'find',
     const active = terms.filter(Boolean);
     return active.length > 1 ? { kind, terms: active } : active[0] || null;
   };
+  // Rule 1 has resolved the path; rule 2 is the compiler's operators, rules 3 to 6 describeEmptiness's.
+  const emptiness = (path, steps, operator, value) => {
+    if (allowed && !allowed.has(operator)) fail(`The ${operator} filter operator is not supported by this query compiler`, 'UNSUPPORTED_QUERY');
+    const segments = Array.isArray(path) ? path : path.split('.');
+    const options = { operator, value, path: segments.join('.') };
+    const gqltype = models.entities.find((item) => item.name === entityName)?.gqltype;
+    if (gqltype) describeEmptiness(gqltype, segments, options);
+    else describeModelEmptiness(steps, options);
+    return { kind: 'predicate', path: segments, operator, value: null };
+  };
   const predicate = (path, operator, value) => {
     const steps = resolveModelPath(models, entityName, path);
-    const field = steps.at(-1);
-    if (field.kind !== 'scalar' && !field.inferred) fail(`Filter on object field ${path} requires a scalar path`, 'MISSING_FILTER_PATH');
     const op = operator ?? 'EQ';
+    if (isEmptinessOperator(op)) return emptiness(path, steps, op, value);
+    const field = steps.at(-1);
+    if (field.kind !== 'scalar' && !field.inferred) {
+      fail(`Filter on object field ${path} requires a scalar path`, steps.length > 1 ? 'INVALID_FILTER_PATH' : 'MISSING_FILTER_PATH');
+    }
     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);
@@ -174,10 +270,21 @@ export const createQueryPlan = (models, entityName, input = {}, { mode = 'find',
     if (controls.has(name) || value == null) continue;
     const field = resolveModelPath(models, entityName, name).at(-1);
     if (typeof value !== 'object' || Array.isArray(value)) fail('Expected a filter object');
-    if (field.kind !== 'scalar' && !field.inferred && (!Array.isArray(value.terms) || !value.terms.length)) fail('Object filters require non-empty terms', 'MISSING_FILTER_PATH');
-    if (field.kind === 'scalar' || field.inferred) terms.push(predicate(name, value.operator, value.value));
+    const object = field.kind !== 'scalar' && !field.inferred;
+    // Only trusted code writes these forms, since QLTypeFilterExpression has no operator. Other
+    // operators beside terms are left out, as before.
+    if (object && isEmptinessOperator(value.operator)) {
+      fail(`Filter on ${name} takes ${value.operator} only in a term; to test the field itself, use a term without a path: `
+        + `${name}: { terms: [{ operator: ${value.operator} }] }`, 'MISSING_FILTER_PATH');
+    }
+    if (object && (!Array.isArray(value.terms) || !value.terms.length)) fail('Object filters require non-empty terms', 'MISSING_FILTER_PATH');
+    if (!object) terms.push(predicate(name, value.operator, value.value));
     else for (const term of value.terms) {
       if (!term || typeof term !== 'object' || Array.isArray(term)) fail('Expected a relationship filter term');
+      if (isEmptinessOperator(term.operator) && isPathless(term.path)) {
+        terms.push(predicate(name, term.operator, term.value));
+        continue;
+      }
       if (typeof term.path !== 'string' || !term.path) fail('Relationship terms require a path', 'INVALID_FILTER_PATH');
       terms.push(predicate(`${name}.${term.path}`, term.operator, term.value));
     }