@simtlix/simfinity-core 3.5.9 → 3.6.0

package/README.md

@@ -16,7 +16,7 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 - `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 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` (500), since the client did not send the value. `update()` resolves to the updated record as stored, or null; nested collection children of that record are linked to and checked against its `_id`, else `id`, else the requested ID. An adapter that hydrates records can define `readEmbeddedValue(value)`: every nullable, singular embedded object field without a resolver then passes its value through it, so an explicitly stored `null` reads as `null`. The field is read as graphql's default resolver reads it, so a method on the parent is called and a promise it returns is awaited before the hook receives the value. Simfinity then reads as `null` an object that holds no data when a required member would read as `null`, not counting `id`, `readOnly`, interface and union members, members with an application resolver and referenced collections; runtimes that share the type read the same. It reads the stored members, never calling a getter, and counts a stored `_id` as `id`; it reads nothing from objects whose type has no member that counts, and an error while reading returns the object unchanged. An adapter whose hydrated records render members through getters can also define `rawEmbeddedValue(value)`, which returns a record's stored data as a plain object, or the record unchanged when that data does not show what it renders; a value that is not a plain object counts as data. The MongoDB adapter defines both.
+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. An adapter can define `readByIdIsInert(model)`, returning `true` when a `getById` of that model has no side effects and `update()` and `delete()` reject the same malformed IDs with `NOT_VALID_ID` (400) and return null for a missing record; the runtime then skips the reads before deletes without an `onDelete` hook and before updates that merge no embedded value and have neither `onUpdating` nor nested collection items. The SQL adapter always reports it, and the MongoDB adapter does for models without `find`, `findOne`, `findOneAndUpdate` or `findOneAndDelete` middleware and without application `_id` setters or overrides of the statics those reads and writes call. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError` (500), since the client did not send the value. `update()` resolves to the updated record as stored, or null; nested collection children of that record are linked to and checked against its `_id`, else `id`, else the requested ID. An adapter that hydrates records can define `readEmbeddedValue(value)`: every nullable, singular embedded object field without a resolver then passes its value through it, so an explicitly stored `null` reads as `null`. The field is read as graphql's default resolver reads it, so a method on the parent is called and a promise it returns is awaited before the hook receives the value. Simfinity then reads as `null` an object that holds no data when a required member would read as `null`, not counting `id`, `readOnly`, interface and union members, members with an application resolver and referenced collections; runtimes that share the type read the same. It reads the stored members, never calling a getter, and counts a stored `_id` as `id`; it reads nothing from objects whose type has no member that counts, and an error while reading returns the object unchanged. An adapter whose hydrated records render members through getters can also define `rawEmbeddedValue(value)`, which returns a record's stored data as a plain object, or the record unchanged when that data does not show what it renders; a value that is not a plain object counts as data. The MongoDB adapter defines both.
 
 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()`.
 

package/package.json

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

package/src/runtime.js

@@ -427,6 +427,21 @@ const cloneInput = (value, type) => {
   return value;
 };
 
+// Each transaction attempt works on its own copy of the request input, since hooks, validators and
+// state actions may change it. The first copy is taken now, before the transaction starts, and is
+// handed out once; a retry copies the request input again, which no attempt receives or changes.
+const attemptInputs = (input, type) => {
+  let first = cloneInput(input, type);
+  let taken = false;
+  return () => {
+    if (taken) return cloneInput(input, type);
+    taken = true;
+    const value = first;
+    first = undefined;
+    return value;
+  };
+};
+
 export const createRuntime = (adapter) => {
   if (!adapter) {
     throw new SimfinityError('A database adapter is required', 'ADAPTER_REQUIRED', 500);
@@ -1246,10 +1261,10 @@ const materializeModel = async (args, gqltype, linkToParent, operation, session)
 };
 
 const executeRegisteredMutation = (args, callback, context, session, inputModel) => {
-  const inputSnapshot = cloneInput(args, inputModel);
+  const nextInput = attemptInputs(args, inputModel);
   return adapter.withTransaction(
     session,
-    (mySession) => callback(cloneInput(inputSnapshot, inputModel), mySession, context),
+    (mySession) => callback(nextInput(), mySession, context),
   );
 };
 
@@ -1270,10 +1285,23 @@ const iterateOnCollectionFields = async (materializedModel, gqltype, objectId, s
   }
 };
 
-const onDelete = async (Model, controller, id, session, context) => {
-  const currentObject = await adapter.getById(Model, id, session, { plain: true });
+// Whether the runtime may skip a read by ID whose result it does not use: the adapter reports that
+// such a read of the model has no side effects, such as query middleware, and fails only where the
+// update or delete by that ID fails too. Without the report, those reads run as before.
+const readByIdIsInert = (Model) => typeof adapter.readByIdIsInert === 'function'
+  && adapter.readByIdIsInert(Model) === true;
+
+// The record is read for the onDelete hook; adapter.delete casts the ID, deletes and returns the
+// record itself. Without a hook, the read is skipped when it is inert. A nested delete passes the
+// child it has already read as `current`.
+const onDelete = async (Model, controller, id, session, context, current) => {
+  const hasHook = !!(controller && controller.onDelete);
+  let currentObject = current;
+  if (currentObject === undefined && (hasHook || !readByIdIsInert(Model))) {
+    currentObject = await adapter.getById(Model, id, session, { plain: true });
+  }
 
-  if (controller && controller.onDelete) {
+  if (hasHook) {
     await controller.onDelete(currentObject, session, context);
   }
 
@@ -1346,13 +1374,35 @@ const clearNullEmbeddedMembers = (merged, fieldEntry, patch) => {
   }
 };
 
-const onUpdateSubject = async (Model, gqltype, controller, args, session, linkToParent, context) => {
+// Whether an update reads the stored embedded values of a type with embedded fields. They are used
+// to merge a singular embedded object, and a non-empty embedded list is completed only for an
+// existing record; empty lists and nulls use nothing. A top-level update also keeps the read before
+// onUpdating, so that a malformed ID fails before the hook, and before nested collection items, so
+// that the SQL adapter locks the parent row before child writes; otherwise it skips the read only
+// when it is inert. A state action or a nested update has already read and checked the record
+// (`recordChecked`).
+const readsStoredEmbedded = (Model, controller, materializedModel, embeddedFieldNames, recordChecked) => {
+  const usesStored = embeddedFieldNames.some((name) => {
+    const value = ownValue(materializedModel.modelArgs, name);
+    return value && (!Array.isArray(value) || value.length > 0);
+  });
+  if (usesStored) return true;
+  if (recordChecked) return false;
+  return !!(controller && controller.onUpdating)
+    || Object.values(materializedModel.collectionFields).some((field) => field
+      && ['added', 'updated', 'deleted'].some((key) => field[key] && hasNestedItems(field[key])))
+    || !readByIdIsInert(Model);
+};
+
+const onUpdateSubject = async (Model, gqltype, controller, args, session, linkToParent, context,
+  recordChecked = false) => {
   const materializedModel = await materializeModel(args, gqltype, linkToParent, 'UPDATE', session);
   const objectId = args.id;
   const argTypes = gqltype.getFields();
   const embeddedFieldNames = getEmbeddedFieldNames(gqltype);
 
-  if (embeddedFieldNames.length > 0) {
+  if (embeddedFieldNames.length > 0
+    && readsStoredEmbedded(Model, controller, materializedModel, embeddedFieldNames, recordChecked)) {
     const projection = Object.fromEntries(embeddedFieldNames.map((name) => [name, 1]));
     const currentObject = await adapter.getById(Model, objectId, session, {
       projection,
@@ -1365,7 +1415,6 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
         const newObjectData = ownValue(materializedModel.modelArgs, fieldEntryName);
         if (newObjectData) {
           if (Array.isArray(newObjectData)) {
-            materializedModel.modelArgs[fieldEntryName] = newObjectData;
             completeEmbeddedValue(fieldEntryName, argTypes[fieldEntryName], newObjectData);
           } else {
             materializedModel.modelArgs[fieldEntryName] = { ...oldObjectData, ...newObjectData };
@@ -1427,7 +1476,7 @@ const onStateChanged = async (Model, gqltype, controller, args, session, actionF
     }
 
     args.state = stateValue(actionField.to);
-    let result = await onUpdateSubject(Model, gqltype, controller, args, session, null, context);
+    let result = await onUpdateSubject(Model, gqltype, controller, args, session, null, context, true);
     result = adapter.toObject(result);
     result.state = actionField.to.value;
     return result;
@@ -1543,13 +1592,11 @@ const executeOperation = (Model, gqltype, controller, args, operation, actionFie
   const limit = getMaxNestedOperations();
   if (limit !== null && operation !== operations.DELETE) assertNestedOperations(gqltype, args, limit);
   if (operation !== operations.DELETE) assertCollectionWrites(gqltype, args);
-  const inputSnapshot = operation === operations.DELETE ? args : cloneInput(args, inputType);
+  const nextInput = operation === operations.DELETE ? () => args : attemptInputs(args, inputType);
   return adapter.withTransaction(
     session,
     async (mySession) => {
-      const attemptArgs = operation === operations.DELETE
-        ? inputSnapshot
-        : cloneInput(inputSnapshot, inputType);
+      const attemptArgs = nextInput();
       switch (operation) {
         case operations.SAVE:
           return onSaveObject(Model, gqltype, controller, attemptArgs, mySession, null, context);
@@ -1594,9 +1641,12 @@ const executeItemFunction = async (gqltype, collectionField, parentKey, session,
     const args = operationType === operations.DELETE ? { id: element } : { input: element };
     await executeMiddleware({ type, args, operation: operationType, context });
 
+    // The ownership check reads the child (the SQL adapter locks its row). onDelete receives this
+    // record, and an update reads the child again only to merge embedded values.
+    let child;
     if (operationType === operations.UPDATE || operationType === operations.DELETE) {
       const id = operationType === operations.DELETE ? args.id : args.input.id;
-      const child = await adapter.getById(type.model, id, session, { plain: true, lock: true });
+      child = await adapter.getById(type.model, id, session, { plain: true, lock: true });
       if (!child) {
         throw new SimfinityError(`${collectionGQLType.name} ${id} is not valid`, 'NOT_VALID_ID', 404);
       }
@@ -1612,10 +1662,10 @@ const executeItemFunction = async (gqltype, collectionField, parentKey, session,
         break;
       case operations.UPDATE:
         await onUpdateSubject(type.model, collectionGQLType, type.controller,
-          args.input, session, linkToParent, context);
+          args.input, session, linkToParent, context, true);
         break;
       case operations.DELETE:
-        await onDelete(type.model, type.controller, args.id, session, context);
+        await onDelete(type.model, type.controller, args.id, session, context, child);
     }
   }
 };

package/types/index.d.ts

@@ -323,6 +323,16 @@ export interface DatabaseAdapter<Model = any, Session = any> {
   getById(model: Model, id: any, session?: Session | null, options?: { projection?: Record<string, number>; plain?: boolean; lock?: boolean; requiredId?: any; context?: any }): any;
   /** Optional batch read: the records found for `ids`, in getById shape and any order. After a failure, the runtime reads each ID with getById. */
   getByIds?(model: Model, ids: any[], options?: { context?: any }): any;
+  /**
+   * Optional. Return true when a `getById` of `model` has no side effects (no query middleware or
+   * hooks that guard, count or change reads) and cannot fail where `update` or `delete` by the same
+   * ID would succeed: both reject a malformed ID with `NOT_VALID_ID` (400) as the read does, and
+   * return null for a missing record. The runtime may then skip a read whose result it does not use:
+   * the read before a delete without an `onDelete` hook, and, for a type with embedded fields, the
+   * read before an update that merges no embedded value and has neither `onUpdating` nor nested
+   * collection items. When it is absent or returns false, those reads run.
+   */
+  readByIdIsInert?(model: Model): boolean;
   prepareUpdate(set: Record<string, any>, unset: Record<string, string>): any;
   update(model: Model, id: any, changes: any, session?: Session): any;
   delete(model: Model, id: any, session?: Session): any;