@simtlix/simfinity-postgres 3.14.0 → 3.15.0

package/README.md

@@ -31,7 +31,7 @@ import { postgresPlugin } from '@simtlix/simfinity-postgres';
 const simfinity = createSQL({ plugin: postgresPlugin({ pool, schema: 'library' }) });
 ```
 
-Install `@simtlix/simfinity-sql@3.14.0` as a direct dependency when importing its factory. PostgreSQL 15 or later is the only supported SQL plugin. The [SQL package guide](https://github.com/simtlix/simfinity.js/tree/master/packages/sql) documents relational planning and the versioned plugin contract.
+Install `@simtlix/simfinity-sql@3.15.0` as a direct dependency when importing its factory. PostgreSQL 15 or later is the only supported SQL plugin. The [SQL package guide](https://github.com/simtlix/simfinity.js/tree/master/packages/sql) documents relational planning and the versioned plugin contract.
 
 Both factories permanently bind one pool and schema, and five optional settings: `multiRowInserts: false` keeps one `INSERT` per owned row instead of multi-row statements; `explicitNullsOrder: true` keeps the `NULLS` clause on sorts of `id` and required fields, as 3.5.9 did, instead of letting indexes serve them; `batchedCollections: true` reads the generated collection fields of the parents that share their arguments with one statement per 100 parents, in a transaction that turns JIT off for that transaction only, instead of one statement per field as 3.6.0 did and as the default still does, and can return unsorted and tied rows in another order; the opt-in `refreshTriggers: 'perRoot'` refreshes each changed root's owned shape and unique keys once per transaction, while its guard trigger stays deferred, instead of once per changed row; and the opt-in `ownerIndexes: 'minimal'` leaves out the `(__owner_id)` indexes that the primary key or a unique index covers on new owned and guard tables. An unknown `refreshTriggers` or `ownerIndexes` value throws `INVALID_DATABASE_SCHEMA` (400). Read the [upgrade notes](https://simtlix.github.io/simfinity.js/resources/compatibility.html#upgrade-to-3-6-0) before enabling the opt-ins: versions up to 3.5.9 cannot validate databases created with them. The returned runtime supports registration, generated queries and mutations, middleware and scopes, controllers and validators, custom queries and mutations, named views, state machines, nested relationship writes, embedded reconstruction, and native PostgreSQL model handles. Native handles expose `findById`, `find`, `create`, `update`, and `delete`; they are not Mongoose models. `find(args, { session })` accepts the generated GraphQL list query arguments. Existing `pg.Pool` configuration and `pg.PoolClient` query interfaces remain compatible across both factories. A custom pool or client wrapper should pass `pg`'s `command` through in query results: the plugin reads it from the `COMMIT` result to detect a transaction that PostgreSQL rolled back because one of its statements failed, and without it such a transaction reports success with nothing stored.
 
@@ -62,7 +62,7 @@ The module and every `createPostgres` instance expose the shared `auth`, `valida
 MCP integration is an independent opt-in and does not add MCP dependencies to PostgreSQL applications:
 
 ```sh
-npm install @simtlix/simfinity-mcp@3.14.0 @modelcontextprotocol/sdk@^1.31.0
+npm install @simtlix/simfinity-mcp@3.15.0 @modelcontextprotocol/sdk@^1.31.0
 ```
 
 ```javascript
@@ -122,3 +122,24 @@ await initializeDatabase(pool, description, { mode: 'validate' });
 ```
 
 Low-level `describeDatabase(registrations, { schema, refreshTriggers, ownerIndexes })` uses the `public` schema when `schema` is omitted, not the schema of a configured runtime; pass the schema given to `configure()` or `createPostgres()`, or call `describeDatabase()` and `compileDatabaseSchema()` without arguments for the default instance. `compileDatabaseSchema` returns reviewable SQL. Low-level `initializeDatabase(pool, description, { mode })` creates or validates storage transactionally and never closes the pool. Create mode adds missing objects and rejects incompatible definitions; validate mode performs no DDL. Neither mode performs destructive schema synchronization or data migration.
+
+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, such as those inside a registered mutation or `withTransaction(null, callback)`, join that owner's queue; a session this runtime did not create is rejected with `INVALID_SESSION`, as before. 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-postgres",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "description": "PostgreSQL GraphQL runtime and schema generation with foreign keys for Simfinity",
   "type": "module",
   "main": "./src/index.js",
@@ -27,8 +27,8 @@
     "directory": "packages/postgres"
   },
   "dependencies": {
-    "@simtlix/simfinity-core": "3.14.0",
-    "@simtlix/simfinity-sql": "3.14.0",
+    "@simtlix/simfinity-core": "3.15.0",
+    "@simtlix/simfinity-sql": "3.15.0",
     "pg": "^8.16.3"
   },
   "peerDependencies": {

package/src/index.js

@@ -22,7 +22,7 @@ export {
 /** Each instance permanently binds one pool/schema; getModel exposes PostgreSQL native helpers. */
 export const createPostgres = (options) => createSQL({ plugin: postgresPlugin(options) });
 const defaultInstance = createPostgres();
-export const { configureQueryLimits, configureMutationLimits, configure, connect, addNoEndpointType, createSchema, getModel, getType, getInputType, getRegistrations, use, registerMutation, registerCustomQuery, registerView, saveObject, preventCreatingCollection, withTransaction } = defaultInstance;
+export const { configureQueryLimits, configureMutationLimits, configureAfterCommit, configure, connect, addNoEndpointType, createSchema, getModel, getType, getInputType, getRegistrations, use, registerMutation, registerCustomQuery, registerView, saveObject, preventCreatingCollection, withTransaction } = defaultInstance;
 
 /** Preserve the foundation low-level API while allowing initialization of the configured default instance. */
 export const initializeDatabase = (poolOrOptions, description, options) => description

package/types/index.d.ts

@@ -15,6 +15,9 @@ export {
   validators,
 } from '@simtlix/simfinity-core';
 export type {
+  AfterCommitErrorDetails,
+  AfterCommitOptions,
+  CommittedControllerCallbacks,
   AuthPluginOptions,
   AuthRule,
   AuthRuleFunction,
@@ -300,6 +303,7 @@ export function createPostgres(options?: PostgresConfiguration): PostgresRuntime
  * anything other than a non-empty string.
  */
 export function caseFoldExpression(sqlExpression: string): string;
+export const configureAfterCommit: PostgresRuntime['configureAfterCommit'];
 export const configure: PostgresRuntime['configure'];
 export const connect: PostgresRuntime['connect'];
 export const addNoEndpointType: PostgresRuntime['addNoEndpointType'];