@simtlix/simfinity-js 3.14.0 → 3.15.0

package/README.md

@@ -95,3 +95,24 @@ For tooling that locates the package, use `require.resolve('@simtlix/simfinity-j
 - [MCP integration](https://simtlix.github.io/simfinity.js/guide/mcp.html)
 - [Complete library documentation](https://github.com/simtlix/simfinity.js#readme)
 - [Aggregation examples](./AGGREGATION_EXAMPLE.md)
+
+Controller `onSaveCommitted`, `onUpdateCommitted`, `onDeleteCommitted` and `onTransitionCommitted` callbacks run serially after the owning transaction confirms commit and attempts cleanup. `configureAfterCommit({ onError })` configures reporting per runtime; callback failures do not fail the committed write. Borrowed lifecycle writes join an adapter-owned attempt; externally owned native sessions do not provide observed commit notifications. Existing hooks remain transactional. See [the contract, payloads and outbox requirements](https://simtlix.github.io/simfinity.js/guide/controllers.html#after-commit-callbacks).
+
+## Client metadata
+
+Since 3.15.0, install the optional `@simtlix/simfinity-descriptor` package,
+aligned with your Simfinity version. It exports `buildClientDescriptor(schema)`
+and `createClientDescriptorHandler(schema, { authorize: 'public' })`. The builder
+describes the exact `createSchema()` result; the explicitly mounted handler can
+instead use an application access function. These functions are not facade/core
+exports. The descriptor does not evaluate dynamic permissions or serialize
+arbitrary validators.
+
+Legacy introspection stays enabled by default in 3.x. To opt out, import
+`configureIntrospection` from `@simtlix/simfinity-core/introspection` in a separate
+bootstrap module and call it with `{ fieldExtensions: false }` **before importing
+the runtime or facades**. That direct import requires core as a direct dependency
+pinned to the facade's exact version, including under pnpm or Yarn PnP. A late
+call fails without deleting installed metadata. Migrate clients selecting
+`__Field.extensions` before opting out. See the [descriptor reference](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html)
+for the format, protected HTTP access and composition limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "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.14.0",
-    "@simtlix/simfinity-mcp": "3.14.0"
+    "@simtlix/simfinity-core": "3.15.0",
+    "@simtlix/simfinity-mcp": "3.15.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -15,6 +15,7 @@ const runtime = createRuntime(mongoAdapter);
 
 export const configureQueryLimits = runtime.configureQueryLimits;
 export const configureMutationLimits = runtime.configureMutationLimits;
+export const configureAfterCommit = runtime.configureAfterCommit;
 export const connect = runtime.connect;
 export const addNoEndpointType = runtime.addNoEndpointType;
 export const createSchema = runtime.createSchema;

package/src/mongo/adapter.js

@@ -2,6 +2,7 @@ import mongoose from 'mongoose';
 import { SimfinityError } from '@simtlix/simfinity-core';
 import { MAX_RECORD_VERSION, isProtectedType, isVersionField, readStoredVersion, retainStoredVersion } from '@simtlix/simfinity-core/internal/record-version';
 import { getListShape, normalizeConnectionField } from '@simtlix/simfinity-core/internal/relation-storage';
+import { createTransactionCallbacks } from '@simtlix/simfinity-core/internal/transaction-callbacks';
 
 import { createMongoModel } from './models.js';
 import { MONGO_QUERY_OPERATORS, createMongoQueries } from './queries.js';
@@ -255,7 +256,8 @@ const nestedPathOf = (nested) => {
 };
 
 export const createMongoAdapter = (options) => {
-  const integrity = createMongoIntegrity(options);
+  const callbacks = createTransactionCallbacks();
+  const integrity = createMongoIntegrity(options, callbacks);
   const collectionBatching = readCollectionBatching(options);
   let queries;
   let getRegistrations = () => [];
@@ -303,8 +305,8 @@ export const createMongoAdapter = (options) => {
 
   // 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 withOwnedTransaction = (session, body, Model, transactionOptions) => withMongoTransaction(
+    session, body, (Model || session) ? Model : sessionModel(), transactionOptions, callbacks,
   );
 
   const versionedRead = (Model, query, many = false) => getRegistrations().some(
@@ -364,6 +366,7 @@ export const createMongoAdapter = (options) => {
     castId: castObjectId,
     initialize: integrity.initialize,
     withTransaction: integrity.enabled ? integrity.withTransaction : withOwnedTransaction,
+    enqueueAfterCommit: callbacks.enqueue,
     newRecord(Model, data, session) {
       const record = new Model(data);
       record.$session(session);

package/src/mongo/integrity.js

@@ -59,7 +59,7 @@ const valuesAt = (value, path) => {
 // createMongoAdapter's options: the adapter reads the collection batching ones.
 const ADAPTER_OPTIONS = ['referentialIntegrity', 'batchedCollections', 'collectionBatchSize'];
 
-export const createMongoIntegrity = (options = {}) => {
+export const createMongoIntegrity = (options = {}, callbacks) => {
   if (!options || typeof options !== 'object' || Array.isArray(options)
     || Object.keys(options).some((key) => !ADAPTER_OPTIONS.includes(key))) {
     throw invalid('Expected Mongo adapter options among referentialIntegrity, batchedCollections and collectionBatchSize');
@@ -316,7 +316,7 @@ export const createMongoIntegrity = (options = {}) => {
     withTransaction(session, body, Model) {
       assertReady();
       if (session) assertSession(session);
-      return withMongoTransaction(session, body, Model || models.values().next().value, transactionOptions);
+      return withMongoTransaction(session, body, Model || models.values().next().value, transactionOptions, callbacks);
     },
     async saveRecord(Model, record, session) {
       assertWrite(Model, session);

package/src/mongo/transactions.js

@@ -46,7 +46,7 @@ const endOwnedSession = async (session, failed) => {
   }
 };
 
-export const withMongoTransaction = async (session, body, model, transactionOptions) => {
+export const withMongoTransaction = async (session, body, model, transactionOptions, callbacks) => {
   const connection = model?.db || mongoose.connection;
   if (session) {
     if (!session.inTransaction()) {
@@ -61,15 +61,21 @@ export const withMongoTransaction = async (session, body, model, transactionOpti
   const mySession = connection === mongoose.connection
     ? await mongoose.startSession() : await connection.startSession();
   let failed = false;
+  let confirmed;
   try {
     for (let attempt = 0; ; attempt++) {
       if (transactionOptions) await mySession.startTransaction(transactionOptions);
       else await mySession.startTransaction();
+      const effects = callbacks?.begin(mySession);
       try {
         const result = await body(mySession);
+        effects?.seal();
         await commitWithRetry(mySession);
+        effects?.confirm();
+        confirmed = effects;
         return result;
       } catch (error) {
+        effects?.discard();
         if (error?.errorLabels?.includes('UnknownTransactionCommitResult')) {
           throw error;
         }
@@ -96,6 +102,7 @@ export const withMongoTransaction = async (session, body, model, transactionOpti
     failed = true;
     throw error;
   } finally {
-    await endOwnedSession(mySession, failed);
+    // Cleanup can reject after commit. The confirmed effects still run, outside every retry catch.
+    try { await endOwnedSession(mySession, failed); } finally { await confirmed?.drain(); }
   }
 };

package/types/index.d.ts

@@ -13,6 +13,8 @@ import type {
   GraphQLOutputType,
 } from 'graphql';
 import type {
+  AfterCommitOptions,
+  CommittedControllerCallbacks,
   CreateSchemaOptions,
   DatabaseAdapter,
   MutationLimitsOptions,
@@ -36,6 +38,9 @@ export {
   validators,
 } from '@simtlix/simfinity-core';
 export type {
+  AfterCommitErrorDetails,
+  AfterCommitOptions,
+  CommittedControllerCallbacks,
   AuthPluginOptions,
   AuthRule,
   AuthRuleFunction,
@@ -155,8 +160,8 @@ export function getRegistrations(): RuntimeRegistration[];
  * Core schema-building API (src/index.js)
  * ========================================================================== */
 
-/** Lifecycle hooks run before commit and may repeat on a transient transaction retry. */
-export interface EntityController {
+/** Lifecycle hooks run before commit; the inherited committed callbacks run after confirmed commit. */
+export interface EntityController extends CommittedControllerCallbacks {
   onSaving?(doc: any, args: any, session: any, context: any): void | Promise<void>;
   onSaved?(result: any, args: any, session: any, context: any): void | Promise<void>;
   onUpdating?(id: any, args: any, session: any, context: any): void | Promise<void>;
@@ -298,6 +303,9 @@ export function preventCreatingCollection(prevent: boolean): void;
  */
 export function configureQueryLimits(options?: QueryLimitsOptions): void;
 
+/** Configure the singleton runtime's best-effort reporting of after-commit callback failures. */
+export function configureAfterCommit(options?: AfterCommitOptions): void;
+
 /**
  * Process-wide limit on nested added/updated/deleted entries per generated add, update or
  * state-action mutation; unlimited by default, restored by calling it without options.