@simtlix/simfinity-js 3.5.7 → 3.5.9

package/README.md

@@ -22,9 +22,9 @@ Use a MongoDB replica set or sharded cluster for transactional mutations. The li
 
 Generated single-reference reads can be batched within a request. Models with any `find` or `findOne` pre/post query hook retain individual `findOne` reads, including hooks shared by both operations, to preserve access restrictions and other middleware behavior. See the [relationship contract](https://simtlix.github.io/simfinity.js/guide/relationships.html).
 
-Generated models store enum internal values with their own type (numbers, booleans or strings; other combinations as given) and support embedded fields named `type`. Range filters, sorts and aggregates on numeric and boolean enums follow that type; PostgreSQL uses their text form. Earlier versions stored numeric and boolean enum values as strings; convert existing documents once as described in the [schema guide](https://simtlix.github.io/simfinity.js/guide/schema.html#what-gets-generated).
+Generated models store enum internal values with their own type (numbers, booleans or strings; other combinations as given) and support embedded fields named `type`. Embedded types that contain each other are rejected with `INVALID_MODEL` (`Embedded cycle at …`) when a generated model reaches them, and always in transactional mode; in the default mode, a cycle that only supplied models reach is not checked. Range filters, sorts and aggregates on numeric and boolean enums follow that type; PostgreSQL uses their text form. Earlier versions stored numeric and boolean enum values as strings; convert existing documents once as described in the [schema guide](https://simtlix.github.io/simfinity.js/guide/schema.html#what-gets-generated).
 
-The facade registers generated models on your application's default Mongoose instance and does not change global Mongoose options such as `strictQuery`. `createMongoAdapter().castId` accepts only an ObjectId or its 24-character hexadecimal string and throws `NOT_VALID_ID` (400) otherwise; create new identifiers with `new mongoose.Types.ObjectId()`. Owned transactions retry transient failures after a short random delay, and a write conflict that outlasts the retries fails with `TRANSACTION_RETRY_EXCEEDED` (409).
+The facade registers generated models on your application's default Mongoose instance and does not change global Mongoose options such as `strictQuery`. Supplied models may use another connection, such as one from `mongoose.createConnection()`: generated mutations and `saveObject()` use the model's connection, and, in the default `referentialIntegrity: 'off'` mode, custom mutations use the default connection unless it is unused, never opened and without compiled models, also on its `useDb()` descendants, and the registered models share one MongoDB client; with transactional reference integrity they use the first protected model's connection. `createMongoAdapter().castId` accepts only an ObjectId or its 24-character hexadecimal string and throws `NOT_VALID_ID` (400) otherwise; create new identifiers with `new mongoose.Types.ObjectId()`. Owned transactions retry transient failures after a short random delay, and a write conflict that outlasts the retries fails with `TRANSACTION_RETRY_EXCEEDED` (409).
 
 Mongoose 8.24.2 or later within version 8 is required to exclude the update-casting prototype-pollution vulnerability. Existing applications should update Mongoose and their dependency lockfile, then run `npm audit`; upgrading Simfinity does not refresh every transitive dependency already locked by the application.
 
@@ -50,6 +50,8 @@ Owned transactions use snapshot reads and majority commits. Supplied sessions ne
 
 The source now lives in `packages/mongodb` in the monorepo. Its public npm name remains `@simtlix/simfinity-js`; existing imports, including paths under `@simtlix/simfinity-js/src/`, retain their layout. Shared helpers, error identities and MCP compatibility exports are preserved. Internal Simfinity dependencies use the same exact release version.
 
+Its legacy `src/` modules that re-export public API (`src/index.js`, `src/auth/index.js`, `src/auth/errors.js`, `src/auth/expressions.js`, `src/auth/rules.js`, `src/plugins.js`, `src/scalars.js`, `src/validators.js`, `src/mcp.js`, `src/const/*.js`, `src/errors/*.js`, and their extensionless aliases) ship TypeScript declarations with the types of the package root and the matching `@simtlix/simfinity-core` subpaths; `src/mongo/*` is internal and undeclared. New code should still import `auth`, `plugins`, `scalars` and `validators` from the package root. Importing the typed `@simtlix/simfinity-core` subpaths, such as `@simtlix/simfinity-core/auth`, instead needs `@simtlix/simfinity-core` as a direct dependency pinned to this package's exact version.
+
 For tooling that locates the package, use `require.resolve('@simtlix/simfinity-js/package.json')` or the package root without a trailing slash. Directory specifiers ending in `/` were not valid ESM imports and are not supported by the export map, including in `require.resolve`; use explicit filenames such as `src/auth/index.js`.
 
 - [MongoDB quick start](https://simtlix.github.io/simfinity.js/guide/getting-started.html)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "3.5.7",
+  "version": "3.5.9",
   "description": "MongoDB/Mongoose adapter and compatibility facade for Simfinity GraphQL APIs",
   "main": "src/index.js",
   "types": "./types/index.d.ts",
@@ -29,8 +29,8 @@
     "owner": "simtlix"
   },
   "dependencies": {
-    "@simtlix/simfinity-core": "3.5.7",
-    "@simtlix/simfinity-mcp": "3.5.7"
+    "@simtlix/simfinity-core": "3.5.9",
+    "@simtlix/simfinity-mcp": "3.5.9"
   },
   "files": [
     "src",

package/src/auth/errors.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/auth/errors';
+export { default } from '@simtlix/simfinity-core/auth/errors';

package/src/auth/expressions.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/auth/expressions';
+export { default } from '@simtlix/simfinity-core/auth/expressions';

package/src/auth/index.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/auth';
+export { default } from '@simtlix/simfinity-core/auth';

package/src/auth/rules.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/auth/rules';
+export { default } from '@simtlix/simfinity-core/auth/rules';

package/src/const/QLOperator.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/const/QLOperator.js` deep import: core's `QLOperator`. */
+export { QLOperator as default } from '@simtlix/simfinity-core';

package/src/const/QLSort.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/const/QLSort.js` deep import: core's `QLSort`. */
+export { QLSort as default } from '@simtlix/simfinity-core';

package/src/const/QLValue.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/const/QLValue.js` deep import: core's `QLValue`. */
+export { QLValue as default } from '@simtlix/simfinity-core';

package/src/errors/internal-server.error.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/errors/internal-server.error.js` deep import: core's `InternalServerError`. */
+export { InternalServerError as default } from '@simtlix/simfinity-core';

package/src/errors/simfinity.error.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/errors/simfinity.error.js` deep import: core's `SimfinityError`. */
+export { SimfinityError as default } from '@simtlix/simfinity-core';

package/src/index.d.ts

@@ -0,0 +1,2 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/index.js` (and `src`) deep import: the package root. */
+export * from '../types/index.js';

package/src/mcp.d.ts

@@ -0,0 +1,3 @@
+/** Declarations for the legacy `@simtlix/simfinity-js/src/mcp.js` deep import, which re-exports `@simtlix/simfinity-mcp`. */
+export * from '@simtlix/simfinity-mcp';
+export { default } from '@simtlix/simfinity-mcp';

package/src/mongo/adapter.js

@@ -50,11 +50,116 @@ const hasNoFindHooks = (hooks) => {
 const batchesFindOne = (Model) => hasNoFindHooks(Model.schema?.s?.hooks)
   && (Model.Query?.prototype?._queryMiddleware == null || hasNoFindHooks(Model.Query.prototype._queryMiddleware));
 
+// `useDb()` connections share their parent's MongoClient, and a session belongs to a client.
+const clientOf = (connection) => connection.getClient?.() || connection;
+
+// Whether a schema lets Mongoose render a member inside an embedded object from something other
+// than its stored value: a getter on a path, a virtual, an alias or, on a subdocument, a method
+// (GraphQL's default resolver calls one named like a member), at any depth (nested paths,
+// subdocuments, document arrays, map values). Core cannot tell such an object's data without
+// running them, so rawEmbeddedValue leaves it unconverted and core keeps it. Read from schema
+// metadata only. The `id` virtual that Mongoose adds to a schema with an `_id` renders that `_id`,
+// which core reads itself, so it does not count; one the application declares does: it has another
+// getter, or the schema disables the automatic one.
+const isAutomaticIdVirtual = (schema, name, virtual) => name === 'id' && virtual?.getters?.length === 1
+  && schema.options?.id !== false && schema.paths._id !== undefined && schema.paths.id === undefined;
+const schemaTypeComputes = (schemaType, seen) => {
+  if (!(schemaType instanceof mongoose.SchemaType) || seen.has(schemaType)) return false;
+  seen.add(schemaType);
+  if (schemaType.getters?.length > 0) return true;
+  // schemaComputes is defined below: schemas and their paths contain each other.
+  if (schemaType.schema && schemaComputes(schemaType.schema, '', seen)) return true;
+  // Map values, array items and document array elements.
+  return [schemaType.$__schemaType, schemaType.$embeddedSchemaType, schemaType.caster]
+    .some((inner) => schemaTypeComputes(inner, seen));
+};
+// `prefix` is a nested path of the schema; '' is the whole schema, as a subdocument's own.
+const schemaComputes = (schema, prefix, seen) => {
+  if (prefix === '') {
+    if (seen.has(schema)) return false;
+    seen.add(schema);
+    // Nested paths get no schema methods; a subdocument's own schema can.
+    if (Object.keys(schema.methods ?? {}).length > 0) return true;
+  }
+  const inside = (path) => prefix === '' || path.startsWith(`${prefix}.`);
+  return Object.entries(schema.paths ?? {}).some(([path, schemaType]) => inside(path) && schemaTypeComputes(schemaType, seen))
+    || Object.entries(schema.virtuals ?? {}).some(([name, virtual]) => inside(name)
+      && !(prefix === '' && isAutomaticIdVirtual(schema, name, virtual)))
+    // An alias stores its value under another path, and may be declared outside a nested path.
+    || Object.entries(schema.aliases ?? {}).some(([alias, path]) => inside(alias) || inside(path));
+};
+// Schemas do not change once their models are compiled, so each answer is computed once.
+const computesCache = new WeakMap();
+const cachedComputes = (key, prefix, compute) => {
+  let byPrefix = computesCache.get(key);
+  if (!byPrefix) {
+    byPrefix = new Map();
+    computesCache.set(key, byPrefix);
+  }
+  if (!byPrefix.has(prefix)) byPrefix.set(prefix, compute());
+  return byPrefix.get(prefix);
+};
+const declaresComputedMembers = (schema, prefix) => cachedComputes(schema, prefix, () => schemaComputes(schema, prefix, new Set()));
+const declaresComputedValues = (schemaType) => cachedComputes(schemaType, '', () => schemaTypeComputes(schemaType, new Set()));
+// A hydrated nested path is cached by its full path in its document's internal getters cache, which
+// it shares; '' (the whole schema) if it is not found there.
+const nestedPathOf = (nested) => {
+  const cache = nested.$__?.getters;
+  return (cache && Object.keys(cache).find((path) => cache[path] === nested)) ?? '';
+};
+
 export const createMongoAdapter = (options) => {
   const integrity = createMongoIntegrity(options);
   let queries;
+  let getRegistrations = () => [];
   const privateConnectionFields = new Map();
 
+  // A registered custom mutation passes no model, so its owned session stays on the default
+  // mongoose.connection, as before. While that connection has never been opened (no client), a
+  // session there can only wait and time out. Use the one MongoDB client of the registered models
+  // instead, but only when nothing can need the default connection:
+  // - any model compiled on it, generated or the application's, registered or not, means the
+  //   application opens it, maybe after the request arrived, and the callback may write that
+  //   model with the session, which must then come from the default connection's client. The
+  //   same holds for a model compiled on any useDb() descendant of it, such as
+  //   mongoose.connection.useDb('tenant').useDb('audit'), which shares its client. A connection's
+  //   otherDbs lists its direct useDb() children, not theirs, so the walk follows otherDbs at any
+  //   depth.
+  //   useDb(name, { noListener: true }) leaves a connection out of its parent's otherDbs, so neither
+  //   it nor its descendants are seen, and native collection writes
+  //   (mongoose.connection.collection()) compile no model;
+  // - registered models on several clients have no single client to choose.
+  // Once the default connection has a client, nothing changes.
+  const hasModels = (connection) => Object.keys(connection.models).length > 0;
+  // A child's otherDbs also lists its parent, so the walk visits each connection once, cycles
+  // included: a Set iteration also visits the entries added while it runs.
+  const defaultClientHasModels = () => {
+    const seen = new Set([mongoose.connection]);
+    for (const connection of seen) {
+      if (hasModels(connection)) return true;
+      for (const other of connection.otherDbs) seen.add(other);
+    }
+    return false;
+  };
+  const sessionModel = () => {
+    if (mongoose.connection.getClient() || defaultClientHasModels()) return undefined;
+    let found;
+    for (const { model } of getRegistrations()) {
+      const connection = model?.db;
+      if (!connection) continue;
+      if (connection === mongoose.connection) return undefined;
+      if (!found) found = model;
+      else if (clientOf(found.db) !== clientOf(connection)) return undefined;
+    }
+    return found;
+  };
+
+  // A supplied session or model is used as is; only an owned session without a model looks up
+  // the registrations.
+  const withOwnedTransaction = (session, body, Model, ...rest) => withMongoTransaction(
+    session, body, (Model || session) ? Model : sessionModel(), ...rest,
+  );
+
   const addPrivateConnectionField = (typeName, fieldName) => {
     if (!privateConnectionFields.has(typeName)) privateConnectionFields.set(typeName, new Set());
     privateConnectionFields.get(typeName).add(fieldName);
@@ -63,6 +168,7 @@ export const createMongoAdapter = (options) => {
   const adapter = {
     bind(binding) {
       integrity.bind(binding);
+      getRegistrations = binding.getRegistrations;
       queries = createMongoQueries(binding);
       adapter.buildQuery = queries.buildQuery;
       adapter.buildFilterGroupMatch = queries.buildFilterGroupMatch;
@@ -103,7 +209,7 @@ export const createMongoAdapter = (options) => {
     // Relation inputs and batch keys: only an ObjectId or its hex form, never a newly minted one.
     castId: castObjectId,
     initialize: integrity.initialize,
-    withTransaction: integrity.enabled ? integrity.withTransaction : withMongoTransaction,
+    withTransaction: integrity.enabled ? integrity.withTransaction : withOwnedTransaction,
     newRecord(Model, data, session) {
       const record = new Model(data);
       record.$session(session);
@@ -118,7 +224,8 @@ export const createMongoAdapter = (options) => {
     },
     // A hydrated document renders a singular embedded path as an object even when the stored value
     // is an explicit null. Only that stored null reads as null; an absent value keeps Mongoose's
-    // materialized object, as legacy documents rely on.
+    // materialized object; core then reads it as null when its stored members (rawEmbeddedValue)
+    // hold no data and miss a required member (runtime.js readEmbeddedObject).
     readEmbeddedValue(value) {
       // The nested accessor's toJSON is called without a receiver on purpose. It reads the schema's
       // toJSON virtuals option from `this` (guarded by `this &&`), and with that option set a stored
@@ -126,6 +233,30 @@ export const createMongoAdapter = (options) => {
       return value?.$__isNested === true && typeof value.toJSON === 'function' && value.toJSON.call(null) === null
         ? null : value;
     },
+    // The stored data of a hydrated embedded value, which core reads to tell whether it holds data
+    // without running schema getters or virtuals: a nested path's raw value (its toJSON without a
+    // receiver, as above), a subdocument's _doc or a Mongoose map's entries. The first two hold an
+    // absent nested path as {}, as Mongoose renders it, and keep subdocuments and maps hydrated,
+    // which core passes back here. A subdocument's automatic `id` virtual is not in _doc; core reads
+    // `_id` for `id`. A value whose schema declares a getter, a virtual, an alias or a subdocument
+    // method on a member at any depth inside it (declaresComputedMembers) is returned unchanged, so core counts it as data
+    // and keeps it, as 3.5.8 rendered it; no getter runs. Generated models declare none. Any other
+    // value is returned unchanged too.
+    rawEmbeddedValue(value) {
+      if (value?.$__isNested === true) {
+        // A schema from another Mongoose copy cannot be inspected; keep the value as 3.5.8 did.
+        if (typeof value.toJSON !== 'function' || !(value.$__schema instanceof mongoose.Schema)
+          || declaresComputedMembers(value.$__schema, nestedPathOf(value))) return value;
+        return value.toJSON.call(null);
+      }
+      // Iterating a map reads its stored values; its get() would run the value getters.
+      if (value instanceof mongoose.Types.Map) {
+        return declaresComputedValues(value.$__schemaType) ? value : Object.fromEntries(value);
+      }
+      if (!(value instanceof mongoose.Document) || !value._doc) return value;
+      const schema = value.$__schema ?? value.schema;
+      return !schema || declaresComputedMembers(schema, '') ? value : value._doc;
+    },
     getById(Model, id, session, { projection, plain, requiredId } = {}) {
       integrity.assertReady();
       let query = withSession(requiredId == null ? Model.findById(id, projection)

package/src/mongo/models.js

@@ -87,7 +87,17 @@ const assertEmbeddedFieldName = (gqlType, fieldEntryName) => {
   }
 };
 
-const generateSchemaDefinition = (gqlType, nested = false) => {
+// An embedded field whose type is the type being generated, or a type that embeds it on this path,
+// would nest without end. The path starts at the type whose model is generated. Sibling and nested
+// fields may still embed the same type.
+const assertNoEmbeddedCycle = (gqlType, entryType, ancestors, fieldPath) => {
+  if (entryType === gqlType) {
+    throw new SimfinityError('A type cannot have a field of its same type and embedded', 'INVALID_MODEL', 400);
+  }
+  if (ancestors.includes(entryType)) throw new SimfinityError(`Embedded cycle at ${fieldPath}`, 'INVALID_MODEL', 400);
+};
+
+const generateSchemaDefinition = (gqlType, nested = false, ancestors = [], path = gqlType.name) => {
   const argTypes = gqlType.getFields();
   const schemaArg = {};
 
@@ -111,10 +121,9 @@ const generateSchemaDefinition = (gqlType, nested = false) => {
         } else {
           assertEmbeddedFieldName(gqlType, fieldEntryName);
           const entryType = unwrapNonNull(type);
-          if (entryType === gqlType) {
-            throw new Error('A type cannot have a field of its same type and embedded');
-          }
-          const definition = generateSchemaDefinition(entryType, true);
+          const fieldPath = `${path}.${fieldEntryName}`;
+          assertNoEmbeddedCycle(gqlType, entryType, ancestors, fieldPath);
+          const definition = generateSchemaDefinition(entryType, true, [...ancestors, gqlType], fieldPath);
           // A nested object under a `type` key can only be a subdocument; like other embedded objects, it has no _id.
           schemaArg[fieldEntryName] = nested && fieldEntryName === 'type'
             ? new mongoose.Schema(definition, { _id: false })
@@ -126,10 +135,9 @@ const generateSchemaDefinition = (gqlType, nested = false) => {
       if (fieldEntry.extensions && fieldEntry.extensions.relation) {
         if (fieldEntry.extensions.relation.embedded) {
           assertEmbeddedFieldName(gqlType, fieldEntryName);
-          if (itemType === gqlType) {
-            throw new Error('A type cannot have a field of its same type and embedded');
-          }
-          schemaArg[fieldEntryName] = [generateSchemaDefinition(itemType, true)];
+          const fieldPath = `${path}.${fieldEntryName}`;
+          assertNoEmbeddedCycle(gqlType, itemType, ancestors, fieldPath);
+          schemaArg[fieldEntryName] = [generateSchemaDefinition(itemType, true, [...ancestors, gqlType], fieldPath)];
         }
       } else if (listItemMatchesScalar(type, GraphQLID)) {
         schemaArg[fieldEntryName] = [mongoose.Schema.Types.ObjectId];

package/src/mongo/queries.js

@@ -1,10 +1,9 @@
 import {
   GraphQLEnumType,
   GraphQLID,
-  GraphQLList,
-  GraphQLNonNull,
   GraphQLObjectType,
   GraphQLScalarType,
+  getNamedType,
 } from 'graphql';
 import mongoose from 'mongoose';
 
@@ -16,18 +15,6 @@ import {
 import { castObjectId } from './ids.js';
 import { resolveStorageScalar } from './models.js';
 
-const isNonNullOfType = (fieldEntryType, graphQLType) => (
-  fieldEntryType instanceof GraphQLNonNull && fieldEntryType.ofType instanceof graphQLType
-);
-
-const unwrapListAndNonNull = (type) => {
-  let unwrapped = type;
-  while (unwrapped instanceof GraphQLList || unwrapped instanceof GraphQLNonNull) {
-    unwrapped = unwrapped.ofType;
-  }
-  return unwrapped;
-};
-
 const getEffectiveTypeName = (type) => (
   type instanceof GraphQLScalarType ? resolveStorageScalar(type).name : type.name
 );
@@ -127,12 +114,6 @@ const AGG_OP_TO_MONGO = {
 
 const filterError = (message, code = 'INVALID_FILTER_VALUE') => new SimfinityError(message, code, 400);
 
-const queryNamedType = (type) => {
-  let result = type;
-  while (result instanceof GraphQLList || result instanceof GraphQLNonNull) result = result.ofType;
-  return result;
-};
-
 // `id` is the record key `_id` at an entity boundary: the root or a joined document. Inside an
 // embedded object it follows what reads return. Entity types read the stored subdocument `_id`
 // through the generated id resolver; that resolver lives on the type object, so any runtime that
@@ -159,7 +140,7 @@ const resolveQueryPath = (gqltype, path, aggregationsIncluded) => {
   for (const [index, part] of parts.entries()) {
     const field = Object.hasOwn(currentType.getFields(), part) ? currentType.getFields()[part] : null;
     if (!field) throw filterError(`Unknown query field: ${path}`, 'INVALID_FILTER_FIELD');
-    const fieldType = queryNamedType(field.type);
+    const fieldType = getNamedType(field.type);
     const relation = field.extensions?.relation;
     if (fieldType instanceof GraphQLObjectType) {
       if (index === parts.length - 1) throw filterError(`Query path must end in a scalar field: ${path}`, 'INVALID_FILTER_PATH');
@@ -267,7 +248,7 @@ const buildQueryTerms = async (filterField, qlField, fieldName, gqltype, aggrega
   if (!qlField) throw filterError(`Unknown filter field: ${fieldName}`, 'INVALID_FILTER_FIELD');
   if (filterField == null) return { aggregateClauses, matchesClauses };
   if (typeof filterField !== 'object' || Array.isArray(filterField)) throw filterError(`Invalid filter for ${fieldName}`);
-  const isObject = queryNamedType(qlField.type) instanceof GraphQLObjectType;
+  const isObject = getNamedType(qlField.type) instanceof GraphQLObjectType;
   if (isObject && (!Array.isArray(filterField.terms) || filterField.terms.length === 0)) {
     throw filterError(`Filter on ${fieldName} requires non-empty terms`, 'MISSING_FILTER_PATH');
   }
@@ -309,8 +290,7 @@ const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, agg
         throw new SimfinityError(`Unknown filter field: ${condition.field}`, 'INVALID_FILTER_FIELD', 400);
       }
 
-      const fieldType = unwrapListAndNonNull(qlField.type);
-      const isObject = fieldType instanceof GraphQLObjectType || isNonNullOfType(fieldType, GraphQLObjectType);
+      const isObject = getNamedType(qlField.type) instanceof GraphQLObjectType;
 
       let filterInput;
       if (isObject) {
@@ -326,8 +306,6 @@ const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, agg
       }
 
       const result = await buildQueryTerms(filterInput, qlField, condition.field, gqltype, aggregationsIncluded);
-      if (!result) continue;
-
       appendLookups(aggregateClauses, aggregationsIncluded, result.aggregateClauses);
       for (const matchClause of Object.values(result.matchesClauses)) {
         for (const [matchKey, match] of Object.entries(matchClause)) {
@@ -379,8 +357,6 @@ const collectFiltersAndLookups = async (input, gqltype, aggregateClauses, aggreg
     if (controlKeys.has(key)) continue;
     const qlField = fields[key];
     const result = await buildQueryTerms(filterField, qlField, key, gqltype, aggregationsIncluded);
-    if (!result) continue;
-
     appendLookups(aggregateClauses, aggregationsIncluded, result.aggregateClauses);
     for (const matchClause of Object.values(result.matchesClauses)) {
       for (const [matchKey, match] of Object.entries(matchClause)) {

package/src/plugins.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/plugins';
+export { default } from '@simtlix/simfinity-core/plugins';

package/src/scalars.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/scalars';
+export { default } from '@simtlix/simfinity-core/scalars';

package/src/validators.d.ts

@@ -0,0 +1,2 @@
+export * from '@simtlix/simfinity-core/validators';
+export { default } from '@simtlix/simfinity-core/validators';

package/types/index.d.ts

@@ -36,6 +36,7 @@ export type {
   EnvelopSchemaPlugin,
   FieldValidations,
   FieldValidator,
+  ItemValidators,
   MutationLimitsOptions,
   PermissionSchema,
   PolicyExpression,
@@ -51,6 +52,14 @@ export interface MongoAdapterOptions {
   /** Fixed at adapter creation. Defaults to off; transactional mode requires initialize(). */
   referentialIntegrity?: 'off' | 'transactional';
 }
+/**
+ * In the default 'off' mode, withTransaction(null, callback) without a model, as custom mutations
+ * call it, opens its session on the default mongoose.connection, unless that connection has no
+ * client, no model is compiled on it or on its useDb() descendants, and every model of the bound
+ * runtime's registrations uses one MongoDB client: then it opens it on that client. A supplied
+ * session or model is used as is. In transactional mode it uses the first protected model's
+ * connection.
+ */
 export interface MongoAdapter extends DatabaseAdapter {
   readonly referentialIntegrity: 'off' | 'transactional';
   /**
@@ -61,6 +70,14 @@ export interface MongoAdapter extends DatabaseAdapter {
   castId(value: any): any;
   /** Returns null for a hydrated nested path whose stored value is an explicit null; otherwise the value. */
   readEmbeddedValue(value: any): any;
+  /**
+   * Returns the raw stored data of a hydrated nested path or subdocument, or a Mongoose map's
+   * entries as a plain object, without running schema getters or virtuals. Returns the value
+   * unchanged when its schema declares a getter, a virtual other than Mongoose's automatic `id`, an
+   * alias or a subdocument method on a member at any depth inside it, so Simfinity keeps the object
+   * as stored, and for any other value.
+   */
+  rawEmbeddedValue(value: any): any;
   /** After connecting MongoDB and createSchema(), await the transaction capability and existing-reference audit. */
   initialize(): Promise<void>;
 }
@@ -119,6 +136,20 @@ export function addNoEndpointType(gqltype: GraphQLObjectType): void;
  * connectionField, whose resolver Simfinity would generate, throws INVALID_MODEL (400). In default
  * mode, one with its own resolver or readOnly only logs a warning and rejects nested writes
  * (INVALID_MODEL, 500); referentialIntegrity 'transactional' rejects every such collection.
+ * Embedded types that contain each other throw INVALID_MODEL (400, `Embedded cycle at …`) when a
+ * generated model's embedded fields reach them, and always in transactional mode; in default mode a
+ * cycle that only supplied models reach is not checked.
+ * A generated input that would have no fields is left out with a warning, together with the
+ * collection operation, embedded field or add/update/state-action mutation that would take it; a
+ * non-null embedded field whose embedded type has no writable fields throws INVALID_MODEL (400)
+ * when the generated mutations reach its owner. An application type named FieldExtensionsType or
+ * RelationType renames Simfinity's introspection metadata types (SimfinityFieldExtensionsType,
+ * SimfinityRelationType) with a warning 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 models are created 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.
  */
 export function createSchema(
   includedQueryTypes?: GraphQLObjectType[] | null,
@@ -186,7 +217,8 @@ export function configureMutationLimits(options?: MutationLimitsOptions): void;
  * Get the generated create input type, preserving field and list-item non-null
  * wrappers. Update inputs remove only the outer wrapper (except entity id).
  * References use IdInputType; embedded lists use nested inputs; referenced
- * collections use added/updated/deleted operation inputs.
+ * collections use added/updated/deleted operation inputs. It has no fields for a type without
+ * writable fields; such inputs are not part of generated schemas.
  */
 export function getInputType(type: GraphQLObjectType | { name: string }): GraphQLInputObjectType;