@simtlix/simfinity-core 3.9.0 → 3.11.0

package/README.md

@@ -8,19 +8,20 @@ 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.
+- `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size, reference-frame and nested-operation limits.
 
 The adapter supplies model creation, identifiers, transactions, record reads and writes, queries, counts, aggregations, and inverse collection reads. `DatabaseAdapter`, `Runtime`, controller, middleware, registration, and state-machine interfaces are exported in the TypeScript declarations. A runtime binds one adapter; create another runtime to use another database or configuration. The GraphQL types that `prepare()` and `createModel()` receive still contain virtual fields, which must never be stored: an adapter that builds storage from a type's fields skips each field for which `isVirtualField(field)`, exported by this package with `virtualFieldOptions(field)`, returns true, on entities and embedded types alike, or builds it from `describeModels()`, which leaves them out. Generated writes, filters, sorts and aggregations never name a virtual field, but a controller hook can still assign one. An adapter can also define `getByIds(model, ids, { context })`, which returns the records it finds in `getById` shape and any order; the runtime then batches generated single-reference reads per request and type, matching records by `castId`, splitting batches at `maxPageSize`, and reading an ID with `getById` when a batch read fails or when `castId` would normalize or reject it. `castId` should throw a `NOT_VALID_ID` (400) `SimfinityError` for a malformed value and must not create a new identifier. An adapter can define `readByIdIsInert(model)`, returning `true` when a `getById` of that model has no side effects and `update()` and `delete()` reject the same malformed IDs with `NOT_VALID_ID` (400) and return null for a missing record; the runtime then skips the reads before deletes without an `onDelete` hook and before updates that merge no embedded value and have neither `onUpdating` nor nested collection items. The SQL adapter always reports it, and the MongoDB adapter does for models without `find`, `findOne`, `findOneAndUpdate` or `findOneAndDelete` middleware and without application `_id` setters or overrides of the statics those reads and writes call. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError` (500), since the client did not send the value. `update()` resolves to the updated record as stored, or null; nested collection children of that record are linked to and checked against its `_id`, else `id`, else the requested ID. An adapter that hydrates records can define `readEmbeddedValue(value)`: every nullable, singular embedded object field without a resolver then passes its value through it, so an explicitly stored `null` reads as `null`. The field is read as graphql's default resolver reads it, so a method on the parent is called and a promise it returns is awaited before the hook receives the value. Simfinity then reads as `null` an object that holds no data when a required member would read as `null`, not counting `id`, `readOnly` and virtual members, interface and union members, members with an application resolver and referenced collections; runtimes that share the type read the same. It reads the stored members, never calling a getter, and counts a stored `_id` as `id`; it reads nothing from objects whose type has no member that counts, and an error while reading returns the object unchanged. An adapter whose hydrated records render members through getters can also define `rawEmbeddedValue(value)`, which returns a record's stored data as a plain object, or the record unchanged when that data does not show what it renders; a value that is not a plain object counts as data. The MongoDB adapter defines both.
 
 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 and whose optional `referenceEmptiness` is a boolean, `undefined` or `null`. 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` and a path inside a list before it calls the adapter, and also emptiness through references and collections unless the adapter declares `referenceEmptiness: true`, 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). An adapter that declares `referenceEmptiness: true` also receives emptiness conditions whose path crosses single references and ends at a reference or a collection, and embedded objects with reference and collection members. A client's such term or group condition carries the key `__scope: { id, scopes }`, where `scopes` holds, for each reference it crosses and each reference, collection or member it ends at or reads, keyed by the dotted path from the queried record, the arguments that the target type's `find` scope produced, or `null` when it added nothing. The adapter must join a crossed reference only where that scope admits the target, and count at an end or member only the records that the scope admits, so that a record the caller may not see reads as a missing one, also on a later hop with a `null` scope; a condition without `__scope` comes from middleware or a scope and reads stored data. `createQueryPlan(models, entity, args, { operators, referenceEmptiness: true })` lifts each filled `__scope` into the predicate's `scopes`, planning each scope on its target type, and throws `DETACHED_CLIENT_FILTER` (500) for a `__scope` that lacks a path; its `referenceEmptiness` option defaults to `true` when `operators` is omitted and to `false` otherwise. See [references and collections](https://simtlix.github.io/simfinity.js/guide/queries.html#references-and-collections).
 
 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.11.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,297 @@
+import {
+  getNamedType, isInterfaceType, isObjectType, isScalarType, isUnionType,
+} from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+import { effectiveScalarName } from './metadata.js';
+import { getListShape, isVirtualField, normalizeConnectionField } from './relation-storage.js';
+
+// Internal: what the emptiness operators IS_EMPTY and IS_NOT_EMPTY (#108, parts 2a and 2b) 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, an 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. It is the queried entity's at the root, and
+// the target's right after a single reference.
+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. A reference or a
+// collection names its `target` type, and a collection the child's storage column that links it,
+// `connectionField`, derived as MongoDB derives it; without a declared connectionField a collection
+// reads through its own field name.
+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;
+    const kind = embedded ? (list ? 'embeddedList' : 'embedded') : (list ? 'collection' : 'reference');
+    const step = { name, typeName: type.name, node: type, kind };
+    if (kind === 'reference') step.target = type.name;
+    if (kind === 'collection') {
+      Object.assign(step, { target: type.name, connectionField: normalizeConnectionField(type, relation.connectionField || name).storageFieldName });
+    }
+    return step;
+  }
+  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, and describeModels
+// has already normalized a collection's connectionField to the child's storage column.
+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', target: field.target, connectionField: field.connectionField };
+  if (field.kind === 'reference' && !field.inferred) return { name: field.name, kind: 'reference', target: field.target };
+  return { name: field.name, kind: field.list ? 'scalarList' : 'scalar', string: field.scalar === 'String' };
+};
+const modelMembers = (fields) => fields.filter((field) => !field.private).map(modelStep);
+
+const isRelation = (step) => step.kind === 'reference' || step.kind === 'collection';
+const leafShape = (step, identity) => {
+  if (step.kind === 'scalarList' || step.kind === 'embeddedList') return { rule: 'list' };
+  if (identity && IDENTITY.includes(step.name)) return { rule: 'null' };
+  return { rule: step.string ? 'string' : 'null' };
+};
+const relationShape = (step) => (step.kind === 'reference'
+  ? { rule: 'reference', target: step.target }
+  : { rule: 'collection', target: step.target, connectionField: step.connectionField });
+
+// 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. Rule 6 throws only when the caller does not support reference emptiness;
+// otherwise a reference or collection end or member gets its own shape, and each single reference the
+// path crosses is listed in `crossings`.
+const describeSteps = (steps, {
+  operator, value, label, membersOf, referenceEmptiness,
+}) => {
+  const segments = steps.map((step) => step.name);
+  const prefix = (index) => segments.slice(0, index + 1).join('.');
+  let cycle = null;
+  let unsupported = null;
+  const crossings = [];
+  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 && isRelation(step)) {
+      unsupported = `${operator} on ${label} ${index === steps.length - 1 ? 'ends at' : 'crosses'} the ${step.kind} ${prefix(index)}`;
+    }
+    // Only a single reference can be crossed: rule 3 rejects any step after a collection.
+    if (step.kind === 'reference' && index < steps.length - 1) crossings.push({ path: prefix(index), target: step.target });
+  }
+  // The member rule: each stored member by its own rule, single embedded members recursively, lists
+  // by the list rule without looking inside their items, references and collections by their own
+  // rules without entering them.
+  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 (isRelation(member)) {
+        unsupported ??= `${operator} on ${label} reads the ${member.kind} member ${memberPath}`;
+        members.push({ name: member.name, shape: relationShape(member) });
+      } 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);
+  let shape;
+  if (last.kind === 'embedded') shape = { rule: 'object', members: expand(last.node, segments, [last.node]) };
+  else if (isRelation(last)) shape = relationShape(last);
+  else shape = leafShape(last, steps.length === 1 || steps.at(-2).kind === 'reference');
+  if (cycle) fail(cycle, 'INVALID_FILTER_OPERATOR');
+  validateEmptinessValue(operator, value, label);
+  if (unsupported && !referenceEmptiness) {
+    fail(`${unsupported}: the database adapter does not support emptiness through references and collections`, 'UNSUPPORTED_QUERY');
+  }
+  return crossings.length ? { ...shape, crossings } : 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, with `referenceEmptiness: false`, rule 6 (UNSUPPORTED_QUERY
+ * when the path crosses or ends at a reference or a collection, or a member is one, for a caller whose
+ * database adapter does not support reference emptiness, #108 part 2b). 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, at the root or right after a single reference, always, whatever scalar
+ * it is declared with), `{ rule: 'list' }` (missing, null or []), `{ rule: 'object', members: [{
+ * name, shape }] }` (missing, null, or every stored member empty), `{ rule: 'reference', target }`
+ * (no record the reference points to) or `{ rule: 'collection', target, connectionField }` (no child
+ * record whose `connectionField`, the child's storage column, points to the record); `target` is the
+ * type name. The members of an object take these shapes too. When the path crosses single references,
+ * the shape also lists them in path order as `crossings: [{ path, target }]`, with `path` the dotted
+ * path of the reference from the queried type; emptinessScopePaths reads them.
+ */
+export const describeEmptiness = (gqltype, segments, {
+  operator = 'IS_EMPTY', value, path, referenceEmptiness = true,
+} = {}) => {
+  const { steps, label } = graphqlSteps(gqltype, segments, path);
+  return describeSteps(steps, {
+    operator, value, label, membersOf: graphqlMembers, referenceEmptiness,
+  });
+};
+
+/**
+ * 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, referenceEmptiness = true,
+} = {}) => {
+  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, referenceEmptiness,
+  });
+};
+
+// The scoped joins and frames of one emptiness construct, as `[{ path, kind, target }]`: each crossing
+// in path order, then the end and the reference and collection members, depth first in field order.
+const scopeEntries = (shape, path) => {
+  const entries = (shape?.crossings ?? []).map(({ path: crossing, target }) => ({ path: crossing, kind: 'join', target }));
+  const visit = (node, at) => {
+    if (node?.rule === 'reference' || node?.rule === 'collection') entries.push({ path: at, kind: 'frame', target: node.target });
+    else if (node?.rule === 'object') for (const member of node.members) visit(member.shape, `${at}.${member.name}`);
+  };
+  visit(shape, pathName(path));
+  return entries;
+};
+
+/**
+ * The reference and collection paths that one emptiness construct reads, from the shape that
+ * describeEmptiness or describeModelEmptiness gave for its `path` (an array or a dotted string):
+ * `joins` are the single references the path crosses (one scoped join each, for a client construct),
+ * and `frames` the end when it is a reference or a collection, then each reference and collection
+ * member (one frame each). Every path is dotted and starts at the queried type. A construct on the
+ * record's own fields gives two empty lists.
+ */
+export const emptinessScopePaths = (shape, path) => {
+  const entries = scopeEntries(shape, path);
+  return {
+    joins: entries.filter((entry) => entry.kind === 'join').map((entry) => entry.path),
+    frames: entries.filter((entry) => entry.kind === 'frame').map((entry) => entry.path),
+  };
+};
+
+/**
+ * The target type name of every path {@link emptinessScopePaths} lists, as `{ [path]: target }`,
+ * joins first: the type whose `find` scope restricts that join or frame.
+ */
+export const emptinessScopeTargets = (shape, path) => Object.fromEntries(
+  scopeEntries(shape, path).map((entry) => [entry.path, entry.target]),
+);
+
+/**
+ * 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-limits.js

@@ -1,21 +1,33 @@
 import SimfinityError from './errors/simfinity.error.js';
 
 let queryMaxPageSize = 1000;
+let queryMaxReferenceFrames = 10;
 
+const isPositiveSafeInteger = (value) => Number.isSafeInteger(value) && value >= 1;
+
+// Process-wide. Each omitted option takes its default again, and every option is checked before any
+// is assigned, so a call that fails keeps every current limit. `maxReferenceFrames` caps, per resolver
+// call, the distinct scoped joins and frames of a client's reference emptiness (#108 part 2b).
 export const configureQueryLimits = (options = {}) => {
   if (!options || typeof options !== 'object' || Array.isArray(options)
     || ![Object.prototype, null].includes(Object.getPrototypeOf(options))) {
     throw new SimfinityError('Query limit options must be a plain object', 'INVALID_QUERY_LIMITS', 400);
   }
-  const { maxPageSize = 1000 } = options;
-  if (!Number.isSafeInteger(maxPageSize) || maxPageSize < 1) {
+  const { maxPageSize = 1000, maxReferenceFrames = 10 } = options;
+  if (!isPositiveSafeInteger(maxPageSize)) {
     throw new SimfinityError('maxPageSize must be a positive safe integer', 'INVALID_QUERY_LIMITS', 400);
   }
+  if (!isPositiveSafeInteger(maxReferenceFrames)) {
+    throw new SimfinityError('maxReferenceFrames must be a positive safe integer', 'INVALID_QUERY_LIMITS', 400);
+  }
   queryMaxPageSize = maxPageSize;
+  queryMaxReferenceFrames = maxReferenceFrames;
 };
 
 export const getQueryMaxPageSize = () => queryMaxPageSize;
 
+export const getQueryMaxReferenceFrames = () => queryMaxReferenceFrames;
+
 export const paginationStages = (pagination, withDefault) => {
   if (pagination == null) return withDefault ? [{ $skip: 0 }, { $limit: Math.min(100, queryMaxPageSize) }] : [];
   const { page, size } = pagination;

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, emptinessScopePaths,
+  emptinessScopeTargets, 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));
@@ -61,20 +68,25 @@ const invalidFeatures = (message) => {
 };
 
 /**
- * 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).
+ * Reads an adapter's `queryFeatures` declaration into `{ operators, referenceEmptiness }`: the set of
+ * operators it compiles, and whether it compiles emptiness through references and collections (#108
+ * part 2b). Without a declaration (undefined or null) the adapter supports {@link
+ * LEGACY_QUERY_OPERATORS} and no reference emptiness. A declaration is an object whose `operators`
+ * is an array of operator names, whose names this version does not know are ignored, and whose
+ * optional `referenceEmptiness` is a boolean, undefined or null (false); 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 (queryFeatures == null) return { operators: new Set(LEGACY_QUERY_OPERATORS), referenceEmptiness: false };
   if (typeof queryFeatures !== 'object' || Array.isArray(queryFeatures)) {
     invalidFeatures('must be an object with an operators array');
   }
-  const { operators } = queryFeatures;
+  const { operators, referenceEmptiness } = 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)) };
+  if (referenceEmptiness != null && typeof referenceEmptiness !== 'boolean') {
+    invalidFeatures('referenceEmptiness must be a boolean');
+  }
+  return { operators: new Set(operators.filter(isQueryOperator)), referenceEmptiness: referenceEmptiness === true };
 };