@simtlix/simfinity-core 3.15.0 → 3.16.0

package/src/operation-input.js

@@ -0,0 +1,345 @@
+import {
+  GraphQLID, getNamedType, isEnumType, isInputObjectType, isListType, isNonNullType,
+} from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+import { RecordVersionRef } from './record-version.js';
+
+// Internal, and never exported from the package. The typed walk that validates the inputs of the
+// lifecycle helpers and of the generated transaction (#151) and builds the snapshots they work on.
+// It is pure: it reads the value and its GraphQL input type, calls no scalar function and no hook,
+// and never changes what it is given. Every container, list and plain-data scalar of the result is
+// new, so no two positions of a snapshot share an object and a hook that rewrites one cannot change
+// another, a retry or the caller's input.
+
+// Programmatic callers get the whole check; a transaction's operations arrive already coerced by
+// GraphQL, so they only get the scalar and record-key rules; a copy of a snapshot gets no check.
+const MODES = ['programmatic', 'coerced', 'copy'];
+
+const UNKNOWN_FIELD = 'unknown field';
+const STATE_FIELD = 'state changes only through transitionObject';
+const EXPECTED_OBJECT = 'expected a plain object';
+const EXPECTED_LIST = 'expected a list';
+const EXPECTED_DENSE_LIST = 'expected a dense list';
+const ACCESSOR = 'accessor property';
+const HIDDEN_PROPERTY = 'non-enumerable or symbol-keyed property';
+const CYCLE = 'cycle';
+const UNSUPPORTED_SCALAR = 'unsupported scalar value';
+const STRING_KEY = 'pass the ID as a string, for example String(record._id)';
+const PRIMITIVE_KEY = 'pass the ID as a primitive value';
+const NESTED_TOO_DEEPLY = 'input is nested too deeply';
+
+const requiredValueError = (path) => new SimfinityError(`Required value ${path} is missing`, 'REQUIRED_VALUE', 400);
+
+// The message names the path and the rule, never a value.
+const invalidInputError = (path, reason) => new SimfinityError(`Invalid input at ${path}: ${reason}`,
+  'INVALID_INPUT', 400);
+
+// How many containers one scalar value may nest. Past it the copy would recurse without a bound: a JSON
+// value of a few thousand nested arrays is a client's to send, and it must be refused as input, not
+// crash with a stack overflow.
+const MAX_SCALAR_DEPTH = 256;
+
+// How many input objects and lists an input may nest, the top-level input object included. Past it the walk
+// would recurse without a bound and end in a stack overflow, a 500 where GraphQL's own roots give a 400.
+// Scalar values inside count on their own, against MAX_SCALAR_DEPTH.
+const MAX_INPUT_DEPTH = 256;
+
+const intrinsicGetTime = Date.prototype.getTime;
+
+// The time of a real Date, read with the intrinsic so that nothing the caller put on the value runs, or
+// undefined when the value is not one (an object that only has the Date prototype, a Proxy of a Date).
+const dateTime = (value) => {
+  try {
+    return intrinsicGetTime.call(value);
+  } catch {
+    return undefined;
+  }
+};
+
+const isPrimitive = (value) => ['string', 'number', 'boolean', 'bigint'].includes(typeof value);
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+// Every copied property is an own data property, even `__proto__`, which assignment would turn into a
+// change of prototype.
+const defineData = (target, key, value) => Object.defineProperty(target, key,
+  { value, writable: true, enumerable: true, configurable: true });
+
+// The keys the walk visits: with checks, every own key, so that a symbol key is seen and rejected;
+// without them, the enumerable string keys.
+const ownKeysOf = (source, checked) => (checked ? Reflect.ownKeys(source) : Object.keys(source));
+
+// The value of an own property, read from its descriptor so that a getter is never run. Only an
+// enumerable data property qualifies. The caller has already refused symbol keys.
+const dataProperty = (source, key, path) => {
+  const descriptor = Object.getOwnPropertyDescriptor(source, key);
+  // A key that was reported and then has no descriptor (a Proxy, or a property that caller code removed
+  // while the walk was running) is as hidden as one that is not enumerable.
+  if (descriptor === undefined) throw invalidInputError(path, HIDDEN_PROPERTY);
+  if (!('value' in descriptor)) throw invalidInputError(path, ACCESSOR);
+  if (!descriptor.enumerable) throw invalidInputError(path, HIDDEN_PROPERTY);
+  return descriptor.value;
+};
+
+// The items of a list, in order. With checks the list must be dense and made of enumerable data
+// properties; without them it is read as it is.
+const listItems = (list, path, checked) => {
+  const items = [];
+  for (let index = 0; index < list.length; index += 1) {
+    if (!checked) {
+      items.push(list[index]);
+    } else if (Object.hasOwn(list, index)) {
+      items.push(dataProperty(list, index, `${path}[${index}]`));
+    } else {
+      throw invalidInputError(path, EXPECTED_DENSE_LIST);
+    }
+  }
+  return items;
+};
+
+// Cycles are looked for along the path from the root to the value being copied, so an object that two
+// positions share without containing itself is not one. `state.depth` counts the input objects and lists
+// entered, and the one past MAX_INPUT_DEPTH is refused at its own path.
+const enter = (source, path, state) => {
+  if (state.ancestors.has(source)) throw invalidInputError(path, CYCLE);
+  if (state.depth >= MAX_INPUT_DEPTH) throw invalidInputError(path, NESTED_TOO_DEEPLY);
+  state.ancestors.add(source);
+  state.depth += 1;
+};
+
+const leave = (source, state) => {
+  state.ancestors.delete(source);
+  state.depth -= 1;
+};
+
+// A scalar value as plain data: primitives as they are, `Date` by time, and arrays and objects with
+// the Object or a null prototype deeply. `shared` maps the objects already copied within this one
+// value, so a reference it repeats stays shared in the copy; a position never shares with another.
+// Each copied object keeps its source's prototype and is never frozen. Anything else (a function, a
+// symbol, an instance of another class such as ObjectId, Buffer or Map) is unsupported, and so is a
+// value nested in more than MAX_SCALAR_DEPTH containers. `depth` counts the containers above the value.
+const copyData = (value, path, state, shared, depth = 0) => {
+  if (typeof value === 'function' || typeof value === 'symbol') {
+    if (state.checkValues) throw invalidInputError(path, UNSUPPORTED_SCALAR);
+    return value;
+  }
+  if (value === null || typeof value !== 'object') return value;
+  const isList = Array.isArray(value);
+  const time = !isList && Object.getPrototypeOf(value) === Date.prototype ? dateTime(value) : undefined;
+  const isDate = time !== undefined;
+  if (!isList && !isDate && !isPlainObject(value)) {
+    if (state.checkValues) throw invalidInputError(path, UNSUPPORTED_SCALAR);
+    return value;
+  }
+  if (state.ancestors.has(value)) throw invalidInputError(path, CYCLE);
+  if (shared.has(value)) return shared.get(value);
+  let copy;
+  if (isDate) {
+    copy = new Date(time);
+  } else {
+    if (depth >= MAX_SCALAR_DEPTH) throw invalidInputError(path, UNSUPPORTED_SCALAR);
+    state.ancestors.add(value);
+    if (isList) {
+      copy = listItems(value, path, state.checkValues)
+        .map((item, index) => copyData(item, `${path}[${index}]`, state, shared, depth + 1));
+    } else {
+      copy = Object.create(Object.getPrototypeOf(value));
+      for (const key of ownKeysOf(value, state.checkValues)) {
+        if (typeof key === 'symbol') throw invalidInputError(path, HIDDEN_PROPERTY);
+        const keyPath = `${path}.${key}`;
+        const item = state.checkValues ? dataProperty(value, key, keyPath) : value[key];
+        defineData(copy, key, copyData(item, keyPath, state, shared, depth + 1));
+      }
+    }
+    state.ancestors.delete(value);
+  }
+  shared.set(value, copy);
+  return copy;
+};
+
+// A record key: where the declared type is ID, and for IdInputType.id, only a string; where it is
+// another scalar, any primitive. Plain objects, arrays, dates and class instances such as ObjectId are
+// refused, because on a database that casts nothing an `id` of { $ne: null } would select a record (D1).
+const assertRecordKey = (value, kind, path) => {
+  const accepted = kind === 'string' ? typeof value === 'string' : isPrimitive(value);
+  if (!accepted) throw invalidInputError(path, kind === 'string' ? STRING_KEY : PRIMITIVE_KEY);
+};
+
+const keyKind = (declaredType, isIdInput = false) => (
+  isIdInput || getNamedType(declaredType) === GraphQLID ? 'string' : 'primitive'
+);
+
+const walkScalar = (value, path, state, position) => {
+  if (state.checkValues && position.key !== undefined) assertRecordKey(value, position.key, path);
+  return copyData(value, path, state, new Map());
+};
+
+// The matched internal value is kept by identity. The test is membership under SameValueZero, which is
+// what `includes` uses; it is not parseValue, and only programmatic input needs it, as GraphQL has
+// already checked a transaction's.
+const walkEnum = (value, type, path, state) => {
+  if (state.checkShape && !type.getValues().map((entry) => entry.value).includes(value)) {
+    throw invalidInputError(path, `not a value of enum ${type.name}`);
+  }
+  return value;
+};
+
+const walkList = (value, type, path, state, position) => {
+  if (!Array.isArray(value)) {
+    if (state.checkShape) throw invalidInputError(path, EXPECTED_LIST);
+    return walkValue(value, type.ofType, path, state, position);
+  }
+  enter(value, path, state);
+  // walkValue turns an `undefined` item into `null`, which executeItemFunction skips.
+  const items = listItems(value, path, state.checkShape)
+    .map((item, index) => walkValue(item, type.ofType, `${path}[${index}]`, state, position));
+  leave(value, state);
+  return items;
+};
+
+const walkObject = (value, type, path, state, position) => {
+  if (state.checkShape && !isPlainObject(value)) throw invalidInputError(path, EXPECTED_OBJECT);
+  // Only a coerced or copied value can get here without being an object, and GraphQL does not
+  // produce one: it is copied as plain data.
+  if (typeof value !== 'object' || Array.isArray(value)) return copyData(value, path, state, new Map());
+  enter(value, path, state);
+  const fields = type.getFields();
+  const isCollection = state.collectionInputTypes?.has(type) === true;
+  // The top-level id of an update, a transition or a delete is required whatever its declared type,
+  // and it is a record key.
+  const isTopLevelId = (key) => key === 'id' && position.topLevel === true && state.requireId;
+  const copy = {};
+  for (const key of ownKeysOf(value, state.checkShape)) {
+    if (typeof key === 'symbol') throw invalidInputError(path, HIDDEN_PROPERTY);
+    const fieldPath = `${path}.${key}`;
+    const item = state.checkShape ? dataProperty(value, key, fieldPath) : value[key];
+    // An own `undefined` is an omitted field, as GraphQL never delivers one.
+    if (item === undefined) continue;
+    const field = Object.hasOwn(fields, key) ? fields[key] : undefined;
+    if (field === undefined) {
+      if (state.checkShape) {
+        const managedState = position.topLevel && state.stateManaged && key === 'state';
+        throw invalidInputError(fieldPath, managedState ? STATE_FIELD : UNKNOWN_FIELD);
+      }
+      // GraphQL leaves no undeclared field in a coerced input, so there is no rule to apply: the
+      // value is kept as plain data.
+      defineData(copy, key, walkScalar(item, fieldPath, state, {}));
+      continue;
+    }
+    const fieldPosition = {};
+    if (key === 'id' && (isTopLevelId(key) || position.idIsKey || type === state.idInputType
+      || type === state.recordVersionRef)) {
+      fieldPosition.key = keyKind(field.type, type === state.idInputType);
+    }
+    if (isCollection && key === 'updated') fieldPosition.idIsKey = true;
+    if (isCollection && key === 'deleted') fieldPosition.key = keyKind(field.type);
+    if (item === null && isTopLevelId(key)) throw requiredValueError(fieldPath);
+    defineData(copy, key, walkValue(item, field.type, fieldPath, state, fieldPosition));
+  }
+  leave(value, state);
+  for (const [name, field] of Object.entries(fields)) {
+    const required = (state.checkShape && isNonNullType(field.type)) || isTopLevelId(name);
+    if (required && !Object.hasOwn(copy, name)) throw requiredValueError(`${path}.${name}`);
+  }
+  return copy;
+};
+
+const walkValue = (value, type, path, state, position) => {
+  if (isNonNullType(type)) {
+    if (state.checkShape && (value === null || value === undefined)) throw requiredValueError(path);
+    return walkValue(value, type.ofType, path, state, position);
+  }
+  if (value === null || value === undefined) return null;
+  if (isListType(type)) return walkList(value, type, path, state, position);
+  if (isInputObjectType(type)) return walkObject(value, type, path, state, position);
+  if (isEnumType(type)) return walkEnum(value, type, path, state);
+  return walkScalar(value, path, state, position);
+};
+
+const createWalkState = ({
+  mode = 'programmatic', topLevelId = false, stateManaged = false, collectionInputTypes, idInputType,
+  recordVersionRef = RecordVersionRef,
+}) => {
+  if (!MODES.includes(mode)) throw new TypeError(`Unknown input walk mode: ${typeof mode === 'string' ? mode : typeof mode}`);
+  return {
+    // Containers, lists, fields, nullability and enums.
+    checkShape: mode === 'programmatic',
+    // Scalars and record keys.
+    checkValues: mode !== 'copy',
+    requireId: topLevelId === true && mode !== 'copy',
+    stateManaged: stateManaged === true,
+    collectionInputTypes,
+    idInputType,
+    recordVersionRef,
+    ancestors: new Set(),
+    depth: 0,
+  };
+};
+
+/**
+ * Validates `value` against an input object type and returns a snapshot of it.
+ *
+ * `options.mode` is 'programmatic' (the default: the structure rules and the scalar rules, for the
+ * lifecycle helpers), 'coerced' (the scalar rules and the record keys only, for the operations of a
+ * transaction, which GraphQL has already coerced) or 'copy' (no check, a type-directed copy of an
+ * existing snapshot for one attempt). `path` names the root in errors (default `input`). `topLevelId`
+ * makes the top-level `id` required and a record key. `collectionInputTypes` is the set of generated
+ * collection inputs (`added`, `updated`, `deleted`), `idInputType` the input of a single reference and
+ * `recordVersionRef` the input of a versioned delete (default: Simfinity's own), which the walk knows
+ * by identity to find their record keys. With `stateManaged`, an undeclared top-level `state` says that
+ * state changes only through transitionObject; elsewhere it is an unknown field.
+ *
+ * Input objects and lists may nest 256 levels, the top-level input included, in every mode; the next one
+ * is refused with `input is nested too deeply`.
+ *
+ * A missing or null value throws REQUIRED_VALUE (400) and any other violation INVALID_INPUT (400), both
+ * naming a path such as `input.lines.added[1].price` and never a value. The value is never changed.
+ * The result has new, extensible, plain containers; dates and plain data are copied and enum values
+ * are kept by identity.
+ */
+export const snapshotOperationInput = (value, inputType, options = {}) => {
+  const state = createWalkState(options);
+  const path = options.path ?? 'input';
+  if (!isInputObjectType(isNonNullType(inputType) ? inputType.ofType : inputType)) {
+    throw new TypeError('snapshotOperationInput needs an input object type');
+  }
+  if (value === undefined || value === null) {
+    if (state.checkValues) throw requiredValueError(path);
+    return value;
+  }
+  return walkValue(value, inputType, path, state, { topLevel: true });
+};
+
+/**
+ * The target of `deleteObject`: a plain object with `id` and, on a protected type only, `version`. The
+ * id is a record key and must be a string, as the `ID` of the delete root is (D1). Any other key,
+ * including `version` on a type that is not protected, is an unknown field. A missing id, or a missing
+ * version on a protected type, throws REQUIRED_VALUE; a version that is present but invalid is left for
+ * the OCC check inside the attempt. Returns `{ id }` or `{ id, version }`, which are new objects.
+ */
+export const readDeleteTarget = (value, { protectedType, path = 'input' } = {}) => {
+  if (value === undefined || value === null) throw requiredValueError(path);
+  if (!isPlainObject(value)) throw invalidInputError(path, EXPECTED_OBJECT);
+  const state = createWalkState({});
+  let id;
+  let version;
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key === 'symbol') throw invalidInputError(path, HIDDEN_PROPERTY);
+    const keyPath = `${path}.${key}`;
+    const item = dataProperty(value, key, keyPath);
+    if (item === undefined) continue;
+    if (key !== 'id' && !(key === 'version' && protectedType)) throw invalidInputError(keyPath, UNKNOWN_FIELD);
+    if (item === null) throw requiredValueError(keyPath);
+    if (key === 'id') {
+      assertRecordKey(item, 'string', keyPath);
+      id = item;
+    } else {
+      version = copyData(item, keyPath, state, new Map());
+    }
+  }
+  if (id === undefined) throw requiredValueError(`${path}.id`);
+  if (!protectedType) return { id };
+  if (version === undefined) throw requiredValueError(`${path}.version`);
+  return { id, version };
+};

package/src/query-frames.js

@@ -6,7 +6,10 @@ import { isVirtualField } from './relation-storage.js';
 import {
   describeEmptiness, describeModelEmptiness, emptinessScopePaths, graphqlStep, isEmptinessOperator, modelStep,
 } from './query-emptiness.js';
-import { isQueryOperator, textQueryOperator, validateTextFilterValue } from './query-operators.js';
+import {
+  assertContainsAllPath, isQueryOperator, takesListValue, textQueryOperator, validateContainsAllValue, validateTextFilterValue,
+  validateTextListFilterValue,
+} from './query-operators.js';
 import { collectQueryOperators, validateQueryGroupKeys } from './query-plan.js';
 import { getQueryMaxFrameNesting } from './query-limits.js';
 
@@ -281,18 +284,25 @@ const validateShapes = (args) => {
 };
 const validateValue = (entry, resolved, ctx) => {
   const { operator, value } = entry;
+  const scalar = resolved.steps.at(-1).scalar;
   // GraphQL compilers historically report the text operator's own type/value diagnostic.
   // Model planning retains its generic scalar-shape checks before text validation.
   if (ctx.gqltype && textQueryOperator(operator)) {
-    validateTextFilterValue(operator, value, resolved.steps.at(-1).scalar, entry.path);
+    validateTextFilterValue(operator, value, scalar, entry.path);
+    return;
+  }
+  if (ctx.gqltype && operator === 'IIN') {
+    validateTextListFilterValue(operator, value, scalar, entry.path);
     return;
   }
-  const array = ['IN', 'NIN', 'BTW'].includes(operator);
+  const array = takesListValue(operator);
   if (value === undefined || (!array && Array.isArray(value)) || (value === null && !['EQ', 'NE'].includes(operator))) fail('Expected a scalar filter value');
   if (array && Array.isArray(value) && value.some((item) => item == null || Array.isArray(item))) fail('Filter lists require non-null scalar elements');
   if (array && !Array.isArray(value)) fail(`${operator} requires an array value`);
   if (operator === 'BTW' && value.length !== 2) fail('BTW requires two values');
-  if (textQueryOperator(operator)) validateTextFilterValue(operator, value, resolved.steps.at(-1).scalar, entry.path);
+  if (operator === 'CONTAINS_ALL') validateContainsAllValue(value);
+  if (textQueryOperator(operator)) validateTextFilterValue(operator, value, scalar, entry.path);
+  if (operator === 'IIN') validateTextListFilterValue(operator, value, scalar, entry.path);
 };
 /** Internal: check sort shape and path syntax without resolving or authorizing model fields. */
 export const assertSortSyntax = (sort) => {
@@ -407,6 +417,32 @@ export const validateQuantifiedGroups = (args, ctx) => {
     if (entry.form === 'quantified') {
       if (!implicit && (steps.slice(0, -1).some((step) => ['collection', 'embeddedList'].includes(step.kind))
         || !['reference', 'collection', 'embeddedList'].includes(last.kind))) fail('A quantified path must end at a relation without crossing a list', 'INVALID_FILTER_PATH');
+      // A hand-built anchor (#108 part 4) is first a non-empty array of single path segments, before the path rule,
+      // which counts the anchor's steps by its elements; list() reads any other present value as [].
+      const anchored = implicit && entry.construct.__anchor != null;
+      if (anchored && (!anchor.length || anchor.some((name) => typeof name !== 'string' || name.includes('.')))) {
+        fail('An implicit quantified anchor must name the aggregate\'s join prefixes', 'INVALID_FILTER_PATH');
+      }
+      // A hand-built implicit group, whatever its operators (#108 part 4): after any anchor, its path ends at a collection,
+      // whatever it crosses first, or at a reference without crossing a list, the explicit groups' rule for references.
+      if (implicit && last.kind !== 'collection' && (last.kind !== 'reference'
+        || steps.slice(anchor.length, -1).some((step) => ['collection', 'embeddedList'].includes(step.kind)))) {
+        fail('An implicit quantified path must end at a collection, or at a reference without crossing a list', 'INVALID_FILTER_PATH');
+      }
+      // Then the shape the rewrite writes (cutAt): in an aggregate, on a group at the root, an anchor that crosses at
+      // least one collection, every one a J prefix, with any embedded lists, embedded objects and references between,
+      // and after it one step, a collection.
+      if (anchored) {
+        const prefixes = ctx.J ?? new Set();
+        const crossed = steps.slice(0, anchor.length);
+        const prefix = (index) => crossed.slice(0, index + 1).map(({ name }) => name).join('.');
+        if (ctx.operation !== 'aggregate' || entry.frames.length
+          || !crossed.some((step) => step.kind === 'collection')
+          || crossed.some((step, index) => step.kind === 'collection' && !prefixes.has(prefix(index)))
+          || partsOf(entry.construct.path).length !== 1 || last.kind !== 'collection') {
+          fail('An implicit quantified anchor must name the aggregate\'s join prefixes', 'INVALID_FILTER_PATH');
+        }
+      }
       if (!implicit && !QUANTIFIERS.has(entry.quantifier)) fail('Unknown quantifier', 'INVALID_FILTER_VALUE');
       if (!implicit) gates.push(() => {
         if (ctx.quantifiers !== true || last.kind === 'embeddedList') fail('Quantified groups are not supported by this query compiler', 'UNSUPPORTED_QUERY');
@@ -420,11 +456,10 @@ export const validateQuantifiedGroups = (args, ctx) => {
         if (!valueLeaf(last, current)) fail(ordinaryCondition && steps.length === 1
           ? `Filter on object field "${last.name}" requires a path` : 'Filter on object field requires a scalar path',
         steps.length > 1 ? 'INVALID_FILTER_PATH' : 'MISSING_FILTER_PATH');
-        // CONTAINS_ALL has no semantics in this release; its excluded shorthand form has
-        // the permanent path error specified for it, while every other use stays unknown.
-        if (entry.operator === 'CONTAINS_ALL' && steps.slice(0, -1).some((step) => step.kind === 'collection')) fail('The shorthand excludes them; use an explicit group', 'INVALID_FILTER_PATH');
         if (!isQueryOperator(entry.operator)) fail(`Unknown filter operator: ${entry.operator}`, 'INVALID_FILTER_OPERATOR');
         if (ctx.operators && !ctx.operators.has(entry.operator)) fail(`The ${entry.operator} filter operator is not supported by this query compiler`, 'UNSUPPORTED_QUERY');
+        // CONTAINS_ALL's permanent path rules, then its leaf rule (#108 section 3.3), on the frame-relative path.
+        if (entry.operator === 'CONTAINS_ALL') assertContainsAllPath(steps);
         if (current.gqltype && last.kind === 'abstract' && entry.value === undefined) fail(`Expected a scalar value for ${entry.path}`);
         validateValue(entry, resolved, current);
       }

package/src/query-operators.js

@@ -1,10 +1,11 @@
 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.
+// Internal: the filter operators and the value rules every backend applies to them, and the path
+// and leaf rules of the list operator CONTAINS_ALL (#108, part 4). They are shared by the core
+// runtime, the query plan and the backend compilers 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, emptinessScopePaths,
@@ -28,7 +29,9 @@ export const LEGACY_QUERY_OPERATORS = Object.freeze(['EQ', 'NE', 'LT', 'LTE', 'G
  * 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.
+ * substring of 3.7.0, keeps its own validation and compilation and is not listed here. Neither is
+ * `IIN` (#108, part 4), `IN` ignoring case: it takes a list of such values, which
+ * {@link validateTextListFilterValue} checks.
  */
 export const TEXT_QUERY_OPERATORS = Object.freeze({
   ILIKE: Object.freeze({ match: 'contains', ignoreCase: true }),
@@ -66,6 +69,85 @@ export const validateTextFilterValue = (operator, value, scalar, path) => {
   return value;
 };
 
+/** The operators whose value is an array: IN, NIN and BTW (3.7.0), CONTAINS_ALL and IIN (#108 part 4). */
+export const LIST_VALUE_OPERATORS = Object.freeze(['IN', 'NIN', 'BTW', 'CONTAINS_ALL', 'IIN']);
+
+/** Whether `operator` takes an array value. */
+export const takesListValue = (operator) => LIST_VALUE_OPERATORS.includes(operator);
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+/**
+ * Validates the value of CONTAINS_ALL (#108 section 3.3) before any backend compiles it: a non-empty array of
+ * non-null scalars, none of them an array or a plain object. Anything else fails with INVALID_FILTER_VALUE (400).
+ * Returns the value unchanged: the compilers cast each element as they cast IN elements, and keep duplicates.
+ */
+export const validateContainsAllValue = (value) => {
+  if (value === undefined || value === null) invalidValue('Expected a scalar filter value');
+  // Array.from reads a hole of a sparse array as undefined; `some` would skip it.
+  if (Array.isArray(value) && Array.from(value).some((item) => item == null || Array.isArray(item) || isPlainObject(item))) {
+    invalidValue('Filter lists require non-null scalar elements');
+  }
+  if (!Array.isArray(value)) invalidValue('CONTAINS_ALL requires an array value');
+  if (!value.length) invalidValue('CONTAINS_ALL requires a non-empty list');
+  return value;
+};
+
+/**
+ * Validates the value of IIN, IN ignoring case, before any backend compiles it: the field must be a `String` field
+ * or a `String` list by its effective scalar, as for IEQ, and the value an array of strings without U+0000; the
+ * empty array is valid and matches nothing. Anything else fails with INVALID_FILTER_VALUE (400). Returns the value
+ * unchanged: it is neither folded nor deduplicated.
+ */
+export const validateTextListFilterValue = (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 (!Array.isArray(value)) invalidValue(`${operator} requires an array value${where}`);
+  // Array.from reads a hole of a sparse array as undefined; `some` would skip it.
+  const items = Array.from(value);
+  if (items.some((item) => typeof item !== 'string')) invalidValue(`${operator} requires non-null string elements${where}`);
+  if (items.some((item) => item.includes('\u0000'))) invalidValue(`${operator} values cannot contain U+0000${where}`);
+  return value;
+};
+
+const failPath = (message, code) => { throw new SimfinityError(message, code, 400); };
+// The validator's steps (graphqlStep, modelStep) and resolveModelPath's field descriptions, read alike.
+const stepKind = (step) => {
+  if (step.kind === 'embedded') return step.list ? 'embeddedList' : 'embedded';
+  if (step.kind === 'scalar') return step.list ? 'scalarList' : 'scalar';
+  if (step.kind === 'reference' && step.inferred) return 'scalar';
+  return step.kind;
+};
+
+/**
+ * The permanent path and leaf rules of CONTAINS_ALL (#108 section 3.3), on the steps of a path relative to its
+ * frame: the path ends at a value, as for every operator (MISSING_FILTER_PATH for one segment, INVALID_FILTER_PATH
+ * otherwise; the validator has applied this rule already, and PostgreSQL's hand-built plans get core's codes from
+ * it), no collection is crossed (INVALID_FILTER_PATH, which the shorthand's exclusion states), no reference follows
+ * an embedded list (INVALID_FILTER_PATH: that join yields one referenced record per row), and the leaf is a list: a
+ * scalar list, or a scalar reached through an embedded list (INVALID_FILTER_OPERATOR otherwise).
+ */
+export const assertContainsAllPath = (steps) => {
+  const kinds = steps.map(stepKind);
+  const names = steps.map(({ name }) => name);
+  // Core's object-end rule first (query-frames.js:420-422), so that every caller gets core's codes in core's order.
+  if (['embedded', 'embeddedList', 'reference', 'collection'].includes(kinds.at(-1))) {
+    failPath('Filter on object field requires a scalar path', steps.length > 1 ? 'INVALID_FILTER_PATH' : 'MISSING_FILTER_PATH');
+  }
+  const crossed = kinds.slice(0, -1);
+  if (crossed.includes('collection')) failPath('The shorthand excludes them; use an explicit group', 'INVALID_FILTER_PATH');
+  const list = crossed.indexOf('embeddedList');
+  const reference = list === -1 ? -1 : crossed.findIndex((kind, index) => index > list && kind === 'reference');
+  if (reference !== -1) {
+    failPath(`CONTAINS_ALL cannot cross the reference ${names.slice(0, reference + 1).join('.')} inside an embedded list, which joins one referenced record per row; combine EQ conditions on the path instead`, 'INVALID_FILTER_PATH');
+  }
+  const leaf = kinds.at(-1);
+  if (leaf !== 'scalarList' && !(leaf === 'scalar' && list !== -1)) {
+    failPath(`CONTAINS_ALL requires a list field, or a field reached through an embedded list; ${names.join('.')} is not one`, 'INVALID_FILTER_OPERATOR');
+  }
+};
+
 const invalidFeatures = (message) => {
   throw new SimfinityError(`DatabaseAdapter queryFeatures ${message}`, 'INVALID_QUERY_FEATURES', 500);
 };
@@ -76,7 +158,9 @@ const invalidFeatures = (message) => {
  * Without a declaration (undefined or null) the adapter supports {@link LEGACY_QUERY_OPERATORS}
  * and neither feature. 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` and `quantifiers` are booleans, undefined or null (false).
+ * optional `referenceEmptiness` and `quantifiers` are booleans, undefined or null (false). A name
+ * counts once this version knows it: a declaration that listed `CONTAINS_ALL` or `IIN` before
+ * #108 part 4 added them receives them on upgrade.
  * Quantifiers require reference emptiness for scoped joins. Other members are left for later
  * features. Anything else throws `INVALID_QUERY_FEATURES` (500).
  */

package/src/query-plan.js

@@ -4,7 +4,7 @@ import { paginationStages } from './query-limits.js';
 import SimfinityError from './errors/simfinity.error.js';
 import {
   describeEmptiness, describeModelEmptiness, emptinessMemberPaths, emptinessScopeTargets, isEmptinessOperator, isQueryOperator,
-  textQueryOperator, validateTextFilterValue,
+  takesListValue, textQueryOperator, validateContainsAllValue, validateTextFilterValue, validateTextListFilterValue,
 } from './query-operators.js';
 
 const fail = (message, code = 'INVALID_FILTER_VALUE') => { throw new SimfinityError(message, code, 400); };
@@ -256,10 +256,19 @@ export const resolveModelPath = (models, entityName, path) => {
 
 /**
  * Typed paths and logical groups; neither SQL nor Mongo pipeline objects are stored here. Operators
- * and values are validated here, text operators through validateTextFilterValue. With `operators`,
+ * and values are validated here, text operators through validateTextFilterValue, CONTAINS_ALL
+ * through validateContainsAllValue and IIN through validateTextListFilterValue. With `operators`,
  * the names a compiler supports, any other QLOperator value fails with UNSUPPORTED_QUERY (400);
  * without it every QLOperator value is planned.
  *
+ * The list operators (#108 part 4) plan `{ kind: 'predicate', path, operator, value }` with the
+ * array as validated, neither cast nor deduplicated: CONTAINS_ALL's is a non-empty array of
+ * non-null scalars, on a scalar list or a scalar reached through embedded lists; IIN's is an array
+ * of strings, possibly empty, on a String field or list. CONTAINS_ALL's path and leaf rules are the
+ * shared validator's, which runs first: through a collection or a reference inside an embedded
+ * list it fails with INVALID_FILTER_PATH, on any other leaf with INVALID_FILTER_OPERATOR. IIN
+ * through a collection becomes a correlated ANY frame like IN, and CONTAINS_ALL is never cut.
+ *
  * 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
@@ -339,12 +348,14 @@ export const createQueryPlan = (models, entityName, source = {}, {
     }
     if (!isQueryOperator(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);
+    const collection = takesListValue(op);
     if (value === undefined || (!collection && Array.isArray(value)) || (value === null && !['EQ', 'NE'].includes(op))) fail('Expected a scalar filter value');
     if (collection && Array.isArray(value) && value.some((item) => item == null || Array.isArray(item))) fail('Filter lists require non-null scalar elements');
-    if (['IN', 'NIN', 'BTW'].includes(op) && !Array.isArray(value)) fail(`${op} requires an array value`);
+    if (collection && !Array.isArray(value)) fail(`${op} requires an array value`);
     if (op === 'BTW' && value.length !== 2) fail('BTW requires two values');
     if (textQueryOperator(op)) validateTextFilterValue(op, value, field.scalar, path);
+    if (op === 'CONTAINS_ALL') validateContainsAllValue(value);
+    if (op === 'IIN') validateTextListFilterValue(op, value, field.scalar, path);
     const node = { kind: 'predicate', path: Array.isArray(path) ? path : path.split('.'), operator: op, value: value === undefined ? null : value };
     if (hasMarker(construct)) {
       if (!inFrame) detached(`${op} on ${node.path.join('.')} carries a client scope marker, but is not an emptiness condition`);