@simtlix/simfinity-core 3.5.2 → 3.5.5

package/README.md

@@ -8,14 +8,21 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 
 ## Runtime
 
-`createRuntime(adapter)` creates an isolated Simfinity runtime. Each instance owns its registrations, generated input types, middleware, scopes, hooks, custom mutations, and state machines. It exposes:
+`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:
 
 - `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;
-- `preventCreatingCollection` to pass validation-only storage setup to an adapter.
+- `preventCreatingCollection` to pass validation-only storage setup to an adapter;
+- `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size 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. 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 it.
+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. 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. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError`, since the client did not send the value. 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. The MongoDB adapter defines it.
+
+Entity types, those registered with `connect()` and the targets of non-embedded relations, resolve `id` to `_id`, falling back to `id`, whatever the `createSchema()` allowlists include; types used only as embedded values keep their declared `id`. Embedded copies of an entity type resolve the same way, so they return their declared `id` unless the adapter stores an `_id` for them, as MongoDB does for embedded list items. The resolver is set on the type object, so it applies in every runtime that shares the type. `createSchema()` marks these registrations with `storedIdentity: true` before calling `adapter.prepare()`.
+
+When a runtime first creates a schema, it binds each GraphQL object type whose non-embedded relation fields receive its generated resolvers. It also reserves each reachable object type that still has a non-embedded relation field without a resolver, such as an unregistered custom mutation result. Registering a bound or reserved type in another runtime, or building another runtime's schema that reaches it through fields, interfaces, union members or custom mutation results, throws `TYPE_BOUND_TO_OTHER_RUNTIME` (409). `createSchema()` also rejects a type with a relation field copied, by `toConfig()` or a field spread, after another runtime generated that field's resolver. Create type objects once per runtime, for example with a factory function. Types without non-embedded relation fields, and types whose relation fields all have application resolvers, can be shared, and another runtime can use a `toConfig()` copy made before the first runtime built its schema. A shared custom mutation result type with an unresolved relation field is rejected.
+
+Registration and `createSchema()` validate `extensions.scope` (`INVALID_SCOPE`) and reject list or embedded relations to unregistered types (`UNREGISTERED_RELATION_TARGET`); `use()` rejects non-functions (`INVALID_MIDDLEWARE`). Before `adapter.prepare()`, `createSchema()` rejects a writable non-embedded list relation without a non-empty child `connectionField` whose resolver it would generate (`INVALID_MODEL`, 400). A collection without `connectionField` that has an application resolver, or is `readOnly`, only logs a `Configuration issue` warning, unless it is both, and nested writes through it fail with `INVALID_MODEL` (500) before anything is written; adapters that describe the whole model, such as PostgreSQL and transactional MongoDB, still reject it in `prepare()`. Fields named like generated query arguments (`sort`, `pagination`, `AND`, `OR`, and `aggregation` on aggregate endpoints) also log a warning once per runtime.
 
 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.
 
@@ -27,4 +34,4 @@ Importing the runtime installs Simfinity's `__Field.extensions` introspection fi
 
 `createQueryPlan` and `resolveModelPath` turn Simfinity filter, sort, pagination, and aggregation inputs into a driver-neutral plan resolved against that metadata.
 
-The package also exports the `auth`, `validators`, `scalars`, and `plugins` helper namespaces alongside `createValidatedScalar`, `SimfinityError`, `InternalServerError`, `buildErrorFormatter`, `QLOperator`, `QLSort`, and `QLValue`. Database packages reuse these exports so helpers, errors, and globally named GraphQL types retain one identity.
+The package also exports the `auth`, `validators`, `scalars`, and `plugins` helper namespaces alongside `createValidatedScalar`, `SimfinityError`, `InternalServerError`, `buildErrorFormatter`, `configureQueryLimits`, `configureMutationLimits`, `QLOperator`, `QLSort`, and `QLValue`. `buildErrorFormatter` returns a `GraphQLError` whose `originalError` is the classified Simfinity error. Database packages reuse these exports so helpers, errors, and globally named GraphQL types retain one identity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.5.2",
+  "version": "3.5.5",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",
@@ -15,6 +15,7 @@
     "./auth/expressions": "./src/auth/expressions.js",
     "./auth/rules": "./src/auth/rules.js",
     "./internal/object-id": "./src/auth/object-id.js",
+    "./internal/relation-storage": "./src/relation-storage.js",
     "./plugins": "./src/plugins.js",
     "./scalars": "./src/scalars.js",
     "./validators": "./src/validators.js"

package/src/auth/expressions.js

@@ -5,6 +5,7 @@
  */
 
 import { normalizeObjectId } from './object-id.js';
+import { isThenable, discardThenable } from './thenable.js';
 
 const invalidResult = Symbol('invalid policy result');
 
@@ -21,7 +22,8 @@ const isValidValue = (value) => {
   if (isReference(value)) {
     return Object.keys(value).length === 1 && Object.hasOwn(value, 'ref') && isValidRef(value.ref);
   }
-  return value !== undefined && typeof value !== 'function' && typeof value !== 'symbol';
+  // NaN equals nothing, so a literal NaN is rejected, as in literal `in` lists.
+  return value !== undefined && typeof value !== 'function' && typeof value !== 'symbol' && !Number.isNaN(value);
 };
 
 const isDenseArray = value => Array.isArray(value)
@@ -105,38 +107,93 @@ const resolveValue = (value, context) => {
   return isReference(value) ? resolveRef(value.ref, context) : value;
 };
 
-// Registered ObjectIds compare by hexadecimal value; every other value compares strictly.
+/**
+ * The time value of a genuine Date from any realm (NaN when invalid), or undefined for other values.
+ * The tag skips other objects cheaply; getTime then rejects objects that only spoof the tag.
+ */
+const dateTime = (value) => {
+  if (value === null || typeof value !== 'object') return undefined;
+  try {
+    return Object.prototype.toString.call(value) === '[object Date]' ? Date.prototype.getTime.call(value) : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+// Registered ObjectIds compare by hexadecimal value; other values except Dates compare strictly.
 const comparable = value => normalizeObjectId(value) ?? value;
 
-// Strict equality never matches values of different types, such as a string and a number or a
-// primitive and a list. Such a comparison is invalid, so `not` cannot turn it into a grant.
-// null stays comparable with anything, as an explicit check for a missing value.
-const isMismatch = (left, right) => left !== null && right !== null && typeof left !== typeof right;
+/**
+ * Classify the left value of a comparison once: a promise, null, NaN, a Date by its time, or another
+ * value in its comparable form. A membership list then repeats only the checks on its items.
+ */
+const classifyOperand = (value) => {
+  if (isThenable(value)) return { kind: 'promise', value: undefined };
+  if (value === null) return { kind: 'null', value };
+  if (Number.isNaN(value)) return { kind: 'nan', value };
+  const time = dateTime(value);
+  if (time !== undefined) return { kind: 'date', value: time };
+  return { kind: 'value', value: comparable(value) };
+};
+
+/**
+ * Compare a classified value with a resolved value: true, false, or invalidResult when they cannot
+ * be compared reliably. A promise is not its eventual value, so it is never compared; a rejected
+ * native one is handled, so it cannot crash the process. null stays comparable with anything else,
+ * as an explicit check for a missing value. NaN equals nothing, and Dates compare by time, only with
+ * valid Dates. Otherwise strict equality never matches values of different types, such as a string
+ * and a number. Such comparisons are invalid, so `not` cannot turn them into a grant.
+ */
+const compareOperand = (left, right) => {
+  if (isThenable(right)) {
+    discardThenable(right);
+    return invalidResult;
+  }
+  if (left.kind === 'promise') return invalidResult;
+  if (left.kind === 'null' || right === null) return left.kind === 'null' && right === null;
+  if (left.kind === 'nan' || Number.isNaN(right)) return invalidResult;
+  const rightTime = dateTime(right);
+  if (left.kind === 'date' || rightTime !== undefined) {
+    if (left.kind !== 'date' || rightTime === undefined || Number.isNaN(left.value) || Number.isNaN(rightTime)) {
+      return invalidResult;
+    }
+    return left.value === rightTime;
+  }
+  const other = comparable(right);
+  return typeof left.value !== typeof other ? invalidResult : left.value === other;
+};
 
 const evaluateMembership = (target, list) => {
   // A list or plain object is not a member value.
   if (!Array.isArray(list) || isPlainValue(target)) return invalidResult;
+  const operand = classifyOperand(target);
   // Never call the list's own includes: Mongoose arrays cast and compare loosely.
   let mismatched = false;
   for (let index = 0; index < list.length; index++) {
-    const item = comparable(list[index]);
-    if (item === target) return true;
-    if (isMismatch(target, item)) mismatched = true;
+    const result = compareOperand(operand, list[index]);
+    if (result === true) return true;
+    if (result === invalidResult) mismatched = true;
   }
-  // Without a match, an item of another type means the list could not be checked reliably.
+  // Without a match, an item that could not be compared means the list was not checked reliably.
   return mismatched ? invalidResult : false;
 };
 
 const evaluateComparison = (operator, operands, context) => {
   const left = resolveValue(operands[0], context);
   const right = resolveValue(operands[1], context);
-  if (left === undefined || right === undefined || typeof left === 'function' || typeof right === 'function') {
+  // A promise is not its eventual value, so it cannot be compared, even with an empty list. A rejected
+  // native promise a ref yields, such as a lazy relation that failed to load, is handled so it cannot
+  // crash the process.
+  const leftThenable = isThenable(left);
+  const rightThenable = isThenable(right);
+  if (leftThenable) discardThenable(left);
+  if (rightThenable) discardThenable(right);
+  if (left === undefined || right === undefined || typeof left === 'function' || typeof right === 'function'
+    || leftThenable || rightThenable) {
     return invalidResult;
   }
-  const target = comparable(left);
-  if (operator === 'in') return evaluateMembership(target, right);
-  const other = comparable(right);
-  return isMismatch(target, other) ? invalidResult : target === other;
+  if (operator === 'in') return evaluateMembership(left, right);
+  return compareOperand(classifyOperand(left), right);
 };
 
 const evaluateAllOf = (expressions, context) => {
@@ -209,6 +266,9 @@ const compileOperand = (operator, value, index) => {
   if (isReference(value)) return new CompiledOperand(true, value.ref);
   // A literal membership list is copied, so only its validated items are compared.
   if (operator === 'in' && index === 1) return new CompiledOperand(false, Object.freeze(copyArray(value)));
+  // A literal Date compares by time, so a private copy keeps setTime on the configured one out.
+  const time = dateTime(value);
+  if (time !== undefined) return new CompiledOperand(false, new Date(time));
   // Other literals keep their identity, which equality compares.
   return new CompiledOperand(false, value);
 };
@@ -219,7 +279,8 @@ const snapshotOperands = (operator, operand) => Object.freeze(
 
 /**
  * Copy the validated structure, so evaluation needs no revalidation and later changes to the
- * configured object cannot make it malformed. Other literal operands keep their identity.
+ * configured object cannot make it malformed. Date literals are copied; other literal operands keep
+ * their identity.
  */
 const snapshotExpression = (expression) => {
   if (typeof expression === 'boolean') return expression;

package/src/auth/index.js

@@ -31,11 +31,23 @@
  * const yoga = createYoga({ schema, plugins: [authPlugin] });
  */
 
-import { GraphQLError, GraphQLObjectType, defaultFieldResolver, __Field } from 'graphql';
+import {
+  GraphQLError,
+  GraphQLEnumType,
+  GraphQLInputObjectType,
+  GraphQLInterfaceType,
+  GraphQLObjectType,
+  GraphQLScalarType,
+  GraphQLUnionType,
+  defaultFieldResolver,
+  __Field,
+} from 'graphql';
 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 { relationFieldOwners } from '../relation-owners.js';
+import { isThenable } from './thenable.js';
 import {
   resolvePath,
   requireAuth,
@@ -145,8 +157,20 @@ const isExemptMetadataType = (permissions, type) => isSimfinityMetadataType(type
 // these schemas; in a schema no instance processed, every wrapper keeps enforcing its rules.
 const authorizedSchemas = new WeakSet();
 
-const isThenable = value => value !== null && (typeof value === 'object' || typeof value === 'function')
-  && typeof value.then === 'function';
+const namedTypeClasses = [
+  GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType,
+  GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType,
+];
+
+/**
+ * A type created by another copy of graphql (a second installed version, or its ESM and CommonJS
+ * builds loaded together) fails `instanceof`, so it cannot be classified and its fields could not be
+ * protected. graphql's own isObjectType only reports such copies outside production.
+ */
+const assertSameGraphQLModule = (typeName, type) => {
+  if (namedTypeClasses.some(NamedType => type instanceof NamedType)) return;
+  throw new TypeError(`Cannot authorize type ${typeName}: it was created by a different copy of the graphql module than the auth plugin uses. Install a single graphql version and load it through one entry point.`);
+};
 
 const validateConfiguration = (permissions, defaultPolicy) => {
   if (defaultPolicy !== 'ALLOW' && defaultPolicy !== 'DENY') {
@@ -348,6 +372,9 @@ export const createFieldMiddleware = (permissions, options = {}) => createAuthMi
  * and rebuilds the schema), this plugin mutates resolvers directly on the existing schema,
  * avoiding schema reconstruction and the duplicate-type errors it can cause.
  *
+ * `onSchemaChange` throws `TypeError` before wrapping any field when a schema type was created by
+ * another copy of the graphql module, instead of leaving that type's fields unprotected.
+ *
  * @param {PermissionSchema} permissions - The permission schema object
  * @param {AuthMiddlewareOptions} [options={}] - Plugin options
  * @returns {Object} An Envelop plugin with an `onSchemaChange` hook
@@ -441,7 +468,7 @@ export const createAuthPlugin = (permissions, options = {}) => {
       return denied();
     };
 
-    return (parent, args, ctx, info) => {
+    const resolver = (parent, args, ctx, info) => {
       // In a schema that only other auth plugin instances processed, their rules apply, not these.
       if (info?.schema && authorizedSchemas.has(info.schema) && !processedSchemas.has(info.schema)) {
         return originalResolve(parent, args, ctx, info);
@@ -454,6 +481,11 @@ export const createAuthPlugin = (permissions, options = {}) => {
       }
       return runRules(0, parent, args, ctx, info);
     };
+    // The wrapper still reads through the runtime that generated a relation resolver, so a field
+    // copied with it stays bound to that runtime.
+    const owner = relationFieldOwners.get(originalResolve);
+    if (owner !== undefined) relationFieldOwners.set(resolver, owner);
+    return resolver;
   };
 
   const wrapSchemaResolvers = (schema) => {
@@ -461,11 +493,15 @@ export const createAuthPlugin = (permissions, options = {}) => {
     validateConfiguration(permissions, defaultPolicy);
     warnAboutQueryRoot(schema);
 
-    const typeMap = schema.getTypeMap();
-
-    for (const [typeName, type] of Object.entries(typeMap)) {
-      if (!(type instanceof GraphQLObjectType) || typeName.startsWith('__') || isExemptMetadataType(permissions, type)) continue;
+    // Check every type before wrapping any field, so an unsupported schema is left unchanged.
+    const objectTypes = [];
+    for (const [typeName, type] of Object.entries(schema.getTypeMap())) {
+      if (typeName.startsWith('__')) continue;
+      assertSameGraphQLModule(typeName, type);
+      if (type instanceof GraphQLObjectType && !isExemptMetadataType(permissions, type)) objectTypes.push([typeName, type]);
+    }
 
+    for (const [typeName, type] of objectTypes) {
       const fields = type.getFields();
 
       for (const [fieldName, field] of Object.entries(fields)) {

package/src/auth/rules.js

@@ -1,8 +1,10 @@
 import { UnauthenticatedError, ForbiddenError } from './errors.js';
 import { normalizeObjectId } from './object-id.js';
+import { isThenable, discardThenable } from './thenable.js';
 
 /**
  * Resolves a value from an object using a dotted path string or function.
+ * A function's result is returned as is, including a promise; the built-in rules deny such results.
  * @param {Object} obj - The object to resolve from
  * @param {string|Function} pathOrFn - Dotted path (e.g., 'user.profile.id') or function to extract value
  * @returns {*} The resolved value or undefined if not found
@@ -44,6 +46,30 @@ const ruleFromCheck = (check) => {
 
 const unauthenticated = () => new UnauthenticatedError('You must be logged in to access this resource');
 
+// Built-in checks are synchronous, so they cannot wait for a path that yields a promise or another
+// thenable. Such a value is never truthy evidence of a user or claim: it denies with this error.
+const pendingValue = () => new TypeError(
+  'Authorization paths must return values synchronously; resolve asynchronous data in the GraphQL context or use an async rule',
+);
+const pending = Symbol('pending authorization value');
+
+const isAsyncFunction = value => ['[object AsyncFunction]', '[object AsyncGeneratorFunction]']
+  .includes(Object.prototype.toString.call(value));
+
+const validatePath = (name, pathOrFn) => {
+  if (isAsyncFunction(pathOrFn)) {
+    throw new TypeError(`${name} must be a dotted path or a synchronous extractor function`);
+  }
+};
+
+/** Resolve a path for a built-in check; a thenable result is discarded and reported as pending. */
+const readPath = (obj, pathOrFn) => {
+  const value = resolvePath(obj, pathOrFn);
+  if (!isThenable(value)) return value;
+  discardThenable(value);
+  return pending;
+};
+
 /**
  * Rule that requires the user to be authenticated
  * Checks for user existence at the specified path in context
@@ -55,9 +81,12 @@ const unauthenticated = () => new UnauthenticatedError('You must be logged in to
  * requireAuth('session.currentUser') // checks ctx.session.currentUser
  */
 export const requireAuth = (userPath = 'user') => {
+  validatePath('userPath', userPath);
   return ruleFromCheck((_parent, _args, ctx) => {
-    if (!ctx || !resolvePath(ctx, userPath)) return unauthenticated;
-    return true;
+    if (!ctx) return unauthenticated;
+    const user = readPath(ctx, userPath);
+    if (user === pending) return pendingValue;
+    return user ? true : unauthenticated;
   });
 };
 
@@ -80,14 +109,18 @@ export const requireRole = (role, options = {}) => {
     throw new TypeError('Required roles must be a nonempty string or array of nonempty strings');
   }
   const { userPath = 'user', rolePath = 'role' } = options;
+  validatePath('userPath', userPath);
+  validatePath('rolePath', rolePath);
   const forbidden = () => new ForbiddenError(`Requires role: ${roles.join(' or ')}`);
 
   return ruleFromCheck((_parent, _args, ctx) => {
     if (!ctx) return unauthenticated;
-    const user = resolvePath(ctx, userPath);
+    const user = readPath(ctx, userPath);
+    if (user === pending) return pendingValue;
     if (!user) return unauthenticated;
 
-    const userRole = resolvePath(user, rolePath);
+    const userRole = readPath(user, rolePath);
+    if (userRole === pending) return pendingValue;
     return roles.includes(userRole) ? true : forbidden;
   });
 };
@@ -130,13 +163,18 @@ export const requirePermission = (permission, options = {}) => {
     throw new TypeError('Required permissions must be a nonempty string or array of nonempty strings');
   }
   const { userPath = 'user', permissionsPath = 'permissions' } = options;
+  validatePath('userPath', userPath);
+  validatePath('permissionsPath', permissionsPath);
 
   return ruleFromCheck((_parent, _args, ctx) => {
     if (!ctx) return unauthenticated;
-    const user = resolvePath(ctx, userPath);
+    const user = readPath(ctx, userPath);
+    if (user === pending) return pendingValue;
     if (!user) return unauthenticated;
 
-    const held = findHeldPermissions(resolvePath(user, permissionsPath), requiredPermissions);
+    const claims = readPath(user, permissionsPath);
+    if (claims === pending) return pendingValue;
+    const held = findHeldPermissions(claims, requiredPermissions);
     if (held === null) {
       return () => new ForbiddenError('User permissions must be an array of nonempty strings');
     }
@@ -244,17 +282,23 @@ const normalizeOwnerId = (value) => {
  */
 export const isOwner = (ownerField = 'userId', userIdField = 'id', options = {}) => {
   const { userPath = 'user' } = options;
+  validatePath('ownerField', ownerField);
+  validatePath('userIdField', userIdField);
+  validatePath('userPath', userPath);
 
   return ruleFromCheck((parent, _args, ctx) => {
     if (!ctx) return unauthenticated;
-    const user = resolvePath(ctx, userPath);
+    const user = readPath(ctx, userPath);
+    if (user === pending) return pendingValue;
     if (!user) return unauthenticated;
 
     // Get ownerId from parent (using path or function)
-    const ownerId = normalizeOwnerId(resolvePath(parent, ownerField));
-
+    const owner = readPath(parent, ownerField);
     // Get userId from user object (using path or function)
-    const userId = normalizeOwnerId(resolvePath(user, userIdField));
+    const id = readPath(user, userIdField);
+    if (owner === pending || id === pending) return pendingValue;
+    const ownerId = normalizeOwnerId(owner);
+    const userId = normalizeOwnerId(id);
 
     if (ownerId === undefined || userId === undefined) {
       return false;

package/src/auth/thenable.js

@@ -0,0 +1,17 @@
+/** Internal: true for promises and other values that `await` would wait for. */
+export const isThenable = value => value !== null && (typeof value === 'object' || typeof value === 'function')
+  && typeof value.then === 'function';
+
+/**
+ * Internal: handle a native promise from any realm whose result is never used, so its rejection
+ * cannot crash the process. The built-in then() is called directly: it throws for anything that is
+ * not a native promise without running its code, and skips an overriding then(). Other thenables are
+ * left untouched, because calling their then() can start work, such as a lazy query builder.
+ */
+export const discardThenable = (value) => {
+  try {
+    Promise.prototype.then.call(value, undefined, () => {});
+  } catch {
+    // Not a native promise: there is no rejection to handle without running its own then().
+  }
+};

package/src/index.js

@@ -11,6 +11,7 @@ export { default as QLOperator } from './const/QLOperator.js';
 export { default as QLSort } from './const/QLSort.js';
 export { default as QLValue } from './const/QLValue.js';
 export { configureQueryLimits, paginationStages } from './query-limits.js';
+export { configureMutationLimits } from './mutation-limits.js';
 export { default as auth } from './auth/index.js';
 export { default as plugins } from './plugins.js';
 export { default as scalars } from './scalars.js';

package/src/mutation-limits.js

@@ -0,0 +1,24 @@
+import SimfinityError from './errors/simfinity.error.js';
+
+// Process-wide, like the query limits. null leaves nested collection operations unlimited.
+let maxNestedOperations = null;
+
+export const configureMutationLimits = (options = {}) => {
+  if (!options || typeof options !== 'object' || Array.isArray(options)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(options))) {
+    throw new SimfinityError('Mutation limit options must be a plain object', 'INVALID_MUTATION_LIMITS', 400);
+  }
+  // A misspelled option must not silently reset the limit to unlimited.
+  const unknown = Reflect.ownKeys(options).find((key) => key !== 'maxNestedOperations');
+  if (unknown !== undefined) {
+    throw new SimfinityError(`Unknown mutation limit option ${String(unknown)}; use maxNestedOperations`,
+      'INVALID_MUTATION_LIMITS', 400);
+  }
+  const { maxNestedOperations: value = null } = options;
+  if (value !== null && (!Number.isSafeInteger(value) || value < 0)) {
+    throw new SimfinityError('maxNestedOperations must be null or a non-negative safe integer', 'INVALID_MUTATION_LIMITS', 400);
+  }
+  maxNestedOperations = value;
+};
+
+export const getMaxNestedOperations = () => maxNestedOperations;

package/src/query-plan.js

@@ -4,12 +4,17 @@ import SimfinityError from './errors/simfinity.error.js';
 const fail = (message, code = 'INVALID_FILTER_VALUE') => { throw new SimfinityError(message, code, 400); };
 const operators = new Set(['EQ', 'NE', 'LT', 'LTE', 'GT', 'GTE', 'BTW', 'IN', 'NIN', 'LIKE']);
 const reserved = new Set(['AND', 'OR', 'sort', 'pagination', 'aggregation']);
+// `aggregation` is a generated argument only on aggregate endpoints; on find and count a field of
+// that name is filtered like any other.
+const listReserved = new Set(['AND', 'OR', 'sort', 'pagination']);
+const controlArgs = (operation) => (operation === 'aggregate' ? reserved : listReserved);
 const listOf = (value) => (Array.isArray(value) ? value : []);
 
 /**
  * Internal: the model paths named by generated query arguments, as `{ segments, group }` entries.
  * Covers filter keys and relation terms, AND/OR conditions, list sort terms, and aggregation
- * groupId and fact paths; aggregate sort terms name result keys. `group` is the AND/OR group
+ * 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.
  */
@@ -27,8 +32,9 @@ export const collectQueryPathEntries = (args, operation = 'find') => {
     }
     for (const item of [...listOf(group.AND), ...listOf(group.OR)]) visit(item);
   };
+  const controls = controlArgs(operation);
   for (const [name, value] of Object.entries(args)) {
-    if (reserved.has(name) || value == null) continue;
+    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);
@@ -100,9 +106,9 @@ export const createQueryPlan = (models, entityName, input = {}, { mode = 'find'
     if (op === 'BTW' && value.length !== 2) fail('BTW requires two values');
     return { kind: 'predicate', path: Array.isArray(path) ? path : path.split('.'), operator: op, value: value === undefined ? null : value };
   };
-  const validateGroup = (value) => {
+  const validateGroup = (value, keys = ['conditions', 'AND', 'OR']) => {
     if (!value || typeof value !== 'object' || Array.isArray(value)) fail('Expected a filter group object');
-    for (const key of ['conditions', 'AND', 'OR']) if (value[key] != null && !Array.isArray(value[key])) fail(`${key} requires an array`);
+    for (const key of keys) if (value[key] != null && !Array.isArray(value[key])) fail(`${key} requires an array`);
   };
   const group = (value, depth = 0) => {
     validateGroup(value);
@@ -117,10 +123,12 @@ export const createQueryPlan = (models, entityName, input = {}, { mode = 'find'
     terms.push(combine('or', (value.OR || []).map((item) => group(item, depth + 1))));
     return combine('and', terms);
   };
-  validateGroup(input);
+  // Top-level arguments are field filters plus AND/OR; `conditions` only lists conditions inside groups.
+  validateGroup(input, ['AND', 'OR']);
+  const controls = controlArgs(mode);
   const terms = [];
   for (const [name, value] of Object.entries(input)) {
-    if (reserved.has(name) || value == null) continue;
+    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');

package/src/relation-owners.js

@@ -0,0 +1,5 @@
+// Internal: generated relation resolvers, the extensions object given to each field that holds one,
+// and Simfinity's own wrappers of those resolvers, mapped to the runtime that generated them.
+// toConfig() copies and field spreads keep the resolver or the extensions object, so a field copied
+// from a bound type still shows whose adapter, registrations and middleware it reads through.
+export const relationFieldOwners = new WeakMap();

package/src/relation-storage.js

@@ -0,0 +1,58 @@
+import { GraphQLList, GraphQLNonNull } from 'graphql';
+
+// Internal helpers that decide where a relation stores its link and which types keep a stored
+// identity. They are shared by the core runtime and the MongoDB adapter through the
+// `./internal/relation-storage` subpath, which is not public API.
+
+const unwrapNonNull = (type) => (type instanceof GraphQLNonNull ? type.ofType : type);
+
+export const getListShape = (type) => {
+  const outerNonNull = type instanceof GraphQLNonNull;
+  const listType = unwrapNonNull(type);
+  if (!(listType instanceof GraphQLList)) return null;
+  const itemNonNull = listType.ofType instanceof GraphQLNonNull;
+  return {
+    outerNonNull,
+    itemNonNull,
+    itemType: unwrapNonNull(listType.ofType),
+  };
+};
+
+export const getFieldStorageName = (fieldName, field) => {
+  const relation = field.extensions?.relation;
+  return relation && !relation.embedded && !getListShape(field.type)
+    ? relation.connectionField || fieldName
+    : fieldName;
+};
+
+// Entity types, which keep their own stored identity. The generated id resolver lives on the type
+// object, which runtimes may share, so the identity rule is per type object, not per runtime
+// registration: a store path for `id` follows the resolver any runtime installed on the type.
+const storedIdentityTypes = new WeakSet();
+
+export const markStoredIdentity = (gqltype) => {
+  storedIdentityTypes.add(gqltype);
+};
+
+export const hasStoredIdentity = (gqltype) => storedIdentityTypes.has(gqltype);
+
+export const normalizeConnectionField = (childType, declaredFieldName) => {
+  if (!declaredFieldName) {
+    return { declaredFieldName, graphqlFieldName: null, storageFieldName: null };
+  }
+  const childFields = childType.getFields();
+  let graphqlFieldName = childFields[declaredFieldName] ? declaredFieldName : null;
+  if (!graphqlFieldName) {
+    const aliasedField = Object.entries(childFields).find(([fieldName, field]) => (
+      getFieldStorageName(fieldName, field) === declaredFieldName
+    ));
+    graphqlFieldName = aliasedField?.[0] || null;
+  }
+  return {
+    declaredFieldName,
+    graphqlFieldName,
+    storageFieldName: graphqlFieldName
+      ? getFieldStorageName(graphqlFieldName, childFields[graphqlFieldName])
+      : declaredFieldName,
+  };
+};