@simtlix/simfinity-core 3.5.5 → 3.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.5.5",
+  "version": "3.5.7",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",

package/src/runtime.js

@@ -4,7 +4,7 @@ import {
   GraphQLObjectType, GraphQLString, GraphQLID, GraphQLSchema, GraphQLList,
   GraphQLNonNull, GraphQLInputObjectType, GraphQLScalarType,
   GraphQLInt, GraphQLEnumType, GraphQLBoolean, GraphQLError, GraphQLInterfaceType, GraphQLUnionType,
-  Kind, defaultFieldResolver, getNamedType,
+  Kind, getNamedType,
 } from 'graphql';
 
 import SimfinityError from './errors/simfinity.error.js';
@@ -24,6 +24,26 @@ import './introspection.js';
 // created is application code, such as a masking resolver, recorded once per type so later
 // in-place wrapping (for example by the auth plugin) does not change the snapshot.
 const generatedResolvers = new WeakSet();
+// A caller that runs one operation per call, such as simfinity-mcp, can collect the pagination
+// count through the root value instead of the shared context: a function stored under this key
+// receives the count. The key is not exported; simfinity-mcp defines the same Symbol.for key.
+const COUNT_SINK = Symbol.for('simfinity.countSink');
+const countSinkOf = (value) => {
+  if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return undefined;
+  const sink = value[COUNT_SINK];
+  return typeof sink === 'function' ? sink : undefined;
+};
+// The root value arrives as parent, which resolver wrappers that forward only (parent, args,
+// context) still pass on; info.rootValue is the fallback. Without a sink the count goes to
+// context.count, where Envelop/Apollo/Yoga count plugins read it.
+const reportCount = (parent, info, context, count) => {
+  const sink = countSinkOf(parent) || (info ? countSinkOf(info.rootValue) : undefined);
+  if (sink) {
+    sink(count);
+    return;
+  }
+  context.count = count;
+};
 const applicationResolvedFields = new WeakMap();
 const markGenerated = (resolve) => {
   generatedResolvers.add(resolve);
@@ -264,6 +284,29 @@ export const buildErrorFormatter = (callback) => (error) => {
 
 export { SimfinityError, InternalServerError };
 
+// A field named like an Object.prototype member (`constructor`, `toString`, ...) that reads as that
+// very member holds no value: graphql input objects and stored records without the field inherit
+// it, and MongoDB nested paths return it from their own accessors. Other values, overriding members
+// such as class methods and getters, and every other name read as usual. The property is read once,
+// so a getter runs once, as with a plain read.
+const isObjectMember = (key, read) => key in Object.prototype && read === Object.prototype[key];
+const ownValue = (value, key) => {
+  if (value == null) return undefined;
+  const read = value[key];
+  return isObjectMember(key, read) ? undefined : read;
+};
+
+// Output fields with such names read through this resolver instead of graphql's default one, which
+// would call the inherited member. Otherwise it resolves as the default one does, calling a method
+// with the parent as receiver, but reads the property only once. It reads no data, so installing it
+// binds no type to a runtime.
+const readOwnField = markGenerated((parent, args, context, info) => {
+  if (parent === null || (typeof parent !== 'object' && typeof parent !== 'function')) return undefined;
+  const property = parent[info.fieldName];
+  if (isObjectMember(info.fieldName, property)) return null;
+  return typeof property === 'function' ? property.call(parent, args, context, info) : property;
+});
+
 const cloneInput = (value, type) => {
   if (value === null || value === undefined || !type) return value;
   if (type instanceof GraphQLNonNull) return cloneInput(value, type.ofType);
@@ -791,28 +834,29 @@ const materializeModel = async (args, gqltype, linkToParent, operation, session)
   const collectionFields = {};
 
   for (const [fieldEntryName, fieldEntry] of Object.entries(argTypes)) {
+    const fieldValue = ownValue(args, fieldEntryName);
     if (fieldEntry.extensions && fieldEntry.extensions.validations
       && fieldEntry.extensions.validations[operation]) {
       for (const validator of fieldEntry.extensions.validations[operation]) {
-        await validator.validate(gqltype.name, fieldEntryName, args[fieldEntryName], session);
+        await validator.validate(gqltype.name, fieldEntryName, fieldValue, session);
       }
     }
 
-    if (args[fieldEntryName] !== undefined && args[fieldEntryName] !== null) {
+    if (fieldValue !== undefined && fieldValue !== null) {
       if (fieldEntry.type instanceof GraphQLScalarType
         || fieldEntry.type instanceof GraphQLEnumType
         || isNonNullOfType(fieldEntry.type, GraphQLScalarType)
         || isNonNullOfType(fieldEntry.type, GraphQLEnumType)) {
-        modelArgs[fieldEntryName] = args[fieldEntryName];
+        modelArgs[fieldEntryName] = fieldValue;
       } else if (fieldEntry.type instanceof GraphQLObjectType
         || isNonNullOfType(fieldEntry.type, GraphQLObjectType)) {
         if (fieldEntry.extensions && fieldEntry.extensions.relation) {
           if (!fieldEntry.extensions.relation.embedded) {
-            modelArgs[getFieldStorageName(fieldEntryName, fieldEntry)] = adapter.castId(args[fieldEntryName].id);
+            modelArgs[getFieldStorageName(fieldEntryName, fieldEntry)] = adapter.castId(fieldValue.id);
           } else {
             const fieldType = fieldEntry.type instanceof GraphQLNonNull
               ? fieldEntry.type.ofType : fieldEntry.type;
-            modelArgs[fieldEntryName] = (await materializeModel(args[fieldEntryName], fieldType,
+            modelArgs[fieldEntryName] = (await materializeModel(fieldValue, fieldType,
               null, operation, session)).modelArgs;
           }
         } else {
@@ -827,11 +871,11 @@ const materializeModel = async (args, gqltype, linkToParent, operation, session)
         if (itemType instanceof GraphQLObjectType && fieldEntry.extensions
           && fieldEntry.extensions.relation) {
           if (!fieldEntry.extensions.relation.embedded) {
-            collectionFields[fieldEntryName] = args[fieldEntryName];
+            collectionFields[fieldEntryName] = fieldValue;
           } else if (fieldEntry.extensions.relation.embedded) {
             const collectionEntries = [];
 
-            for (const element of args[fieldEntryName]) {
+            for (const element of fieldValue) {
               if (element === null) {
                 collectionEntries.push(null);
               } else {
@@ -843,9 +887,15 @@ const materializeModel = async (args, gqltype, linkToParent, operation, session)
             modelArgs[fieldEntryName] = collectionEntries;
           }
         } else if (itemType instanceof GraphQLScalarType || itemType instanceof GraphQLEnumType) {
-          modelArgs[fieldEntryName] = args[fieldEntryName];
+          modelArgs[fieldEntryName] = fieldValue;
         }
       }
+    } else if (operation === 'CREATE' && fieldEntryName in Object.prototype && getListShape(fieldEntry.type)
+      && !(fieldEntry.extensions?.relation && !fieldEntry.extensions.relation.embedded)) {
+      // A create without a value stores [] for a list: SQL backends store it for every list, and
+      // Mongoose defaults to it, except for a list named like an Object.prototype member, where it
+      // finds the inherited member. Collections are not stored on the record.
+      modelArgs[fieldEntryName] = [];
     }
   }
 
@@ -931,9 +981,9 @@ const completeEmbeddedValue = (fieldName, fieldEntry, value, patch = null) => {
       const memberList = getListShape(member.type);
       if (relation && !relation.embedded && memberList) continue;
       const storageName = getFieldStorageName(memberName, member);
-      if (item[storageName] === undefined && memberList) item[storageName] = [];
+      if (ownValue(item, storageName) === undefined && memberList) item[storageName] = [];
       if (memberName === 'id' || member.extensions?.readOnly) continue;
-      const memberValue = item[storageName];
+      const memberValue = ownValue(item, storageName);
       if (memberValue === null || memberValue === undefined) {
         if (member.type instanceof GraphQLNonNull) {
           throw new SimfinityError(`Required value ${memberName} is missing`, 'REQUIRED_VALUE', 400);
@@ -979,8 +1029,8 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
     });
     if (currentObject) {
       for (const fieldEntryName of embeddedFieldNames) {
-        const oldObjectData = currentObject[fieldEntryName];
-        const newObjectData = materializedModel.modelArgs[fieldEntryName];
+        const oldObjectData = ownValue(currentObject, fieldEntryName);
+        const newObjectData = ownValue(materializedModel.modelArgs, fieldEntryName);
         if (newObjectData) {
           if (Array.isArray(newObjectData)) {
             materializedModel.modelArgs[fieldEntryName] = newObjectData;
@@ -988,7 +1038,7 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
           } else {
             materializedModel.modelArgs[fieldEntryName] = { ...oldObjectData, ...newObjectData };
             clearNullEmbeddedMembers(materializedModel.modelArgs[fieldEntryName],
-              argTypes[fieldEntryName], args[fieldEntryName]);
+              argTypes[fieldEntryName], ownValue(args, fieldEntryName));
             completeEmbeddedValue(fieldEntryName, argTypes[fieldEntryName],
               materializedModel.modelArgs[fieldEntryName], newObjectData);
           }
@@ -1478,6 +1528,9 @@ const resolveById = async (type, args, context, requiredId) => {
   return results[0] || null;
 };
 
+// Every generated mutation field carries extensions.simfinityMutation with its operation (and, for
+// a state-machine action, the action and its from/to states), so tools such as the MCP package can
+// classify it without guessing from its name. Extensions do not appear in SDL or introspection.
 const buildMutation = (name, includedMutationTypes, includedCustomMutations) => {
   const rootQueryArgs = {};
   rootQueryArgs.name = name;
@@ -1494,6 +1547,7 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
           type: type.gqltype,
           description: 'add',
           args: argsObject,
+          extensions: { simfinityMutation: { typeName: type.gqltype.name, operation: operations.SAVE } },
           async resolve(parent, args, context) {
             const params = {
               type,
@@ -1511,6 +1565,7 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
           type: type.gqltype,
           description: 'delete',
           args: { id: { type: new GraphQLNonNull(GraphQLID) } },
+          extensions: { simfinityMutation: { typeName: type.gqltype.name, operation: operations.DELETE } },
           async resolve(parent, args, context) {
             const params = {
               type,
@@ -1536,6 +1591,7 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
           type: type.gqltype,
           description: 'update',
           args: argsObject,
+          extensions: { simfinityMutation: { typeName: type.gqltype.name, operation: operations.UPDATE } },
           async resolve(parent, args, context) {
             const params = {
               type,
@@ -1556,6 +1612,15 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
                 type: type.gqltype,
                 description: actionField.description,
                 args: argsObject,
+                extensions: {
+                  simfinityMutation: {
+                    typeName: type.gqltype.name,
+                    operation: operations.STATE_CHANGED,
+                    action: actionName,
+                    from: actionField.from && actionField.from.name,
+                    to: actionField.to && actionField.to.name,
+                  },
+                },
                 async resolve(parent, args, context) {
                   const params = {
                     type,
@@ -1587,6 +1652,7 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
         type: registeredMutation.outputModel,
         description: registeredMutation.description,
         args: argsObject,
+        extensions: { simfinityMutation: { operation: operations.CUSTOM_MUTATION } },
         async resolve(parent, args, context) {
           const params = {
             args,
@@ -1627,8 +1693,10 @@ const buildRootQuery = (name, includedTypes) => {
         rootQueryArgs.fields[type.listEntitiesEndpointName] = {
           type: new GraphQLList(type.gqltype),
           args: argsObject,
-          extensions: { simfinityQuery: { typeName: type.gqltype.name, operation: 'find' } },
-          async resolve(parent, args, context) {
+          // countSink: this resolver reports pagination counts through reportCount, so a caller
+          // that supplies a root-value sink can pass its context unchanged.
+          extensions: { simfinityQuery: { typeName: type.gqltype.name, operation: 'find', countSink: true } },
+          async resolve(parent, args, context, info) {
             const joinedScopes = inspectClientPaths(type.gqltype, args, 'find');
             const params = {
               type,
@@ -1649,7 +1717,7 @@ const buildRootQuery = (name, includedTypes) => {
 
             const [result, resultCount] = await Promise.all([dataPromise, countPromise]);
             if (wantsCount) {
-              context.count = resultCount;
+              reportCount(parent, info, context, resultCount);
             }
             return result;
           },
@@ -1724,8 +1792,9 @@ const installIdResolver = (gqltype) => {
 // this runtime: another runtime that reaches a shared type reads the same value through it.
 // The value is read as graphql's default resolver reads it, so a method on the parent, such as one a
 // custom mutation result supplies, is still called; a promise it returns is read once it settles.
+// Only a field named like an Object.prototype member that reads as that member reads as null.
 const readEmbeddedField = markGenerated((parent, args, context, info) => {
-  const value = defaultFieldResolver(parent, args, context, info);
+  const value = readOwnField(parent, args, context, info);
   return isThenable(value)
     ? value.then((resolved) => adapter.readEmbeddedValue(resolved))
     : adapter.readEmbeddedValue(value);
@@ -1744,6 +1813,20 @@ const installEmbeddedValueResolvers = (gqltype, visited) => {
   }
 };
 
+// Fields named like Object.prototype members, of registered types and the embedded types they reach,
+// read through readOwnField when they have no resolver yet; references and collections keep the ones
+// autoGenerateResolvers gives them.
+const installObjectMemberResolvers = (gqltype, visited) => {
+  if (!(gqltype instanceof GraphQLObjectType) || visited.has(gqltype)) return;
+  visited.add(gqltype);
+  for (const [fieldName, fieldEntry] of Object.entries(gqltype.getFields())) {
+    const relation = fieldEntry.extensions?.relation;
+    if (relation && !relation.embedded) continue;
+    if (fieldName in Object.prototype && !fieldEntry.resolve) fieldEntry.resolve = readOwnField;
+    if (relation) installObjectMemberResolvers(unwrapListAndNonNull(fieldEntry.type), visited);
+  }
+};
+
 // Configuration issues this runtime already reported, per type, so a repeated createSchema call or a
 // type reached from several places logs each one once.
 const reportedIssues = new WeakMap();
@@ -1827,6 +1910,9 @@ const createSchema = (includedQueryTypes, includedMutationTypes, includedCustomM
       }
     }
   });
+  // After every type has its relation and embedded value resolvers, which these fields keep.
+  const objectMemberTypes = new Set();
+  Object.values(typesDict.types).forEach(({ gqltype }) => installObjectMemberResolvers(gqltype, objectMemberTypes));
 
   const query = buildRootQuery('RootQueryType', includedQueryTypes);
   Object.values(typesDict.types).forEach(({ gqltype }) => {
@@ -1939,8 +2025,15 @@ const autoGenerateResolvers = (gqltype) => {
         if (!relatedTypeInfo || !relatedTypeInfo.model) {
           throw new Error(`Related type ${relatedType.name} not found or not connected. Make sure it's connected with simfinity.connect() or simfinity.addNoEndpointType().`);
         }
-        // Any stored identifier except null or an empty string, so numeric IDs such as 0 resolve.
-        const relatedId = parent[connectionField] ?? parent[fieldName];
+        // Any stored identifier except null or an empty string, so numeric IDs such as 0 resolve. A
+        // function under the field name is a member, such as the class a MongoDB document inherits
+        // `constructor` from, not an identifier.
+        // The field name is read only when the stored identifier is missing.
+        let relatedId = ownValue(parent, connectionField);
+        if (relatedId == null) {
+          const linked = ownValue(parent, fieldName);
+          relatedId = typeof linked === 'function' ? undefined : linked;
+        }
         const id = relatedId?._id ?? relatedId;
         if (id == null || id === '') return null;
         try {

package/src/scalars/factory.js

@@ -3,6 +3,11 @@ import { GraphQLScalarType, GraphQLString, GraphQLInt, GraphQLFloat, GraphQLBool
 // The base each validated scalar delegates parsing to. A base exists before its scalar, so these links cannot cycle.
 const validatedBases = new WeakMap();
 
+// The same link as a non-enumerable property, so MCP (packages/mcp/src/index.js, VALIDATED_SCALAR_BASE) can tell a
+// validated scalar, whose output is its base's, from a hand-set `baseScalarType` storage hint, whose own `serialize`
+// decides the output. Not exported; Symbol.for gives both packages the same key.
+const VALIDATED_SCALAR_BASE = Symbol.for('simfinity.validatedScalarBase');
+
 // Follow validated-scalar chains to the scalar that defines the literal syntax. Any other scalar is the root, even
 // with a hand-set `baseScalarType` storage hint, because its own parseLiteral decides which literals it takes.
 const findRootScalar = (scalarType) => {
@@ -68,5 +73,6 @@ export function createValidatedScalar(name, description, baseScalarType, validat
 
   scalar.baseScalarType = baseScalarType;
   validatedBases.set(scalar, baseScalarType);
+  Object.defineProperty(scalar, VALIDATED_SCALAR_BASE, { value: baseScalarType });
   return scalar;
 }

package/types/index.d.ts

@@ -66,9 +66,12 @@ export class SimfinityError extends Error {
   getCode(): string | undefined;
   getStatus(): number | undefined;
   getTimestamp(): string;
-  /** Set on errors that wrap a driver error, such as MongoDB's TRANSACTION_RETRY_EXCEEDED. */
+  /**
+   * Set on errors that wrap a driver error, such as TRANSACTION_RETRY_EXCEEDED, and on the PostgreSQL database errors
+   * that a SQL runtime maps or reports as DATABASE_ERROR; on those PostgreSQL errors it is not enumerable.
+   */
   cause?: unknown;
-  /** Set on errors that wrap a driver error, such as MongoDB's TRANSACTION_RETRY_EXCEEDED; returns `cause`. */
+  /** Set on errors that wrap a driver error, such as TRANSACTION_RETRY_EXCEEDED, and on PostgreSQL database errors; returns `cause`. */
   getCause?(): unknown;
 }