@simtlix/simfinity-postgres 3.11.0 → 3.13.0

package/README.md

@@ -31,9 +31,9 @@ import { postgresPlugin } from '@simtlix/simfinity-postgres';
 const simfinity = createSQL({ plugin: postgresPlugin({ pool, schema: 'library' }) });
 ```
 
-Install `@simtlix/simfinity-sql@3.11.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.13.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, 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.
+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.
 
 Operations attempted before successful initialization fail with `DATABASE_NOT_INITIALIZED`. Call `createSchema` before `initializeDatabase`. Configuration and registrations become immutable once schema preparation begins. `preventCreatingCollection(true)` makes instance initialization validate existing storage without issuing creation DDL. A rejected initialization request leaves readiness as it was; a ready instance keeps serving while it is initialized again, and becomes unavailable if that initialization fails. `create` mode reads the catalog without table locks and locks nothing when nothing is missing. When it creates objects, writers of the tables that it changes, of existing tables that a new foreign key references, or of roots whose keys it rebuilds wait until it commits, so use `mode: 'validate'` to check a live instance. `simfinity.compileDatabaseSchema()` returns the instance's DDL for review or export.
 
@@ -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.11.0 @modelcontextprotocol/sdk@^1.31.0
+npm install @simtlix/simfinity-mcp@3.13.0 @modelcontextprotocol/sdk@^1.31.0
 ```
 
 ```javascript
@@ -93,6 +93,16 @@ Scalar-list leaves inside nested embedded lists support filters, sorts, ragged g
 
 The following mappings remain unsupported and fail explicitly: implicit many-to-many reciprocal lists, non-embedded collections inside embedded objects, embedded cycles, nested list wrappers, whole embedded-object uniqueness, conflicting relationship metadata, enum values that collide after text conversion, and stored custom scalars without a recognized base scalar. Query paths cannot sort or group whole embedded objects. Arbitrary MongoDB pipelines and Mongoose-native methods are outside the PostgreSQL contract.
 
+## Optimistic concurrency
+
+Declare `extensions: { concurrency: { mode: 'optimistic' } }` on an entity before building its schema to receive the managed `version` field. PostgreSQL stores it as `bigint NOT NULL DEFAULT 1`; migrating an existing table requires an explicit migration, such as `ALTER TABLE "library"."Book" ADD COLUMN "version" bigint NOT NULL DEFAULT 1;`. Updates atomically match the ID and expected version and advance it, including version-only updates. Those updates fire the touch and refresh triggers of maintained roots. Stale writes fail with `VERSION_CONFLICT` (409); an update at `MAX_RECORD_VERSION` fails with `VERSION_EXHAUSTED` (409), while a delete at that version remains valid. Valid bigint values from `pg`, including a custom BigInt parser, are decoded to numbers; unsafe stored values remain invalid rather than being rounded into valid versions. `RecordVersion` and `MAX_RECORD_VERSION` are shared core exports.
+
+Initialization in both `create` and `validate` modes rejects a missing or differently defined version column with `SCHEMA_MISMATCH`, explaining the required definition and, when absent, the qualified `ALTER TABLE ... ADD COLUMN` statement. An instance without the concurrency declaration also cannot initialize while its table retains the bigint version column: deploy the declaration on that instance, or stop every protected instance before dropping the column for a rollback. Run the adding migration immediately before the first protected instance starts; instances already running without the declaration can still write without advancing versions. Initialization never migrates the column automatically.
+
+Protected native handles initialize `model.create(data)` at version 1. Use `model.update(id, { ...changes, version: record.version }, { session })` and `model.delete(id, { session, version: record.version })`. The update captures the version once before transaction retries without mutating your changes. Missing versions fail with `REQUIRED_VALUE` (400) and a message explaining the handle protocol. For a derived value that a hook maintains in the same transaction, `model.update(id, changes, { session, version: false })` writes without checking or advancing the version and ignores `changes.version`; delete also accepts `version: false`. Handles still bypass validators, hooks, scopes and authorization. Unprotected handles keep their existing behavior and ignore the option. Native SQL writers must follow the same conditional-write protocol to participate; writes that bypass it are not detected.
+
+The plugin declares `optimisticConcurrency`. Copies overriding `compileRecord` must honor `operation.version` or delegate versioned updates and deletes to the original compiler. Versioned deletes use `RETURNING id`, including after the SQL runtime's locked read. Record-result checks report `DATABASE_ERROR` for inconsistent update versions or a missing delete result; they are defensive diagnostics and cannot prove that arbitrary overrides preserved the atomic condition.
+
 ## Low-level schema API
 
 The foundation API remains available independently of a runtime:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-postgres",
-  "version": "3.11.0",
+  "version": "3.13.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.11.0",
-    "@simtlix/simfinity-sql": "3.11.0",
+    "@simtlix/simfinity-core": "3.13.0",
+    "@simtlix/simfinity-sql": "3.13.0",
     "pg": "^8.16.3"
   },
   "peerDependencies": {

package/src/codecs.js

@@ -2,7 +2,7 @@ import { getNamedType, isEnumType } from 'graphql';
 import { SimfinityError } from '@simtlix/simfinity-core';
 import { isCaseFoldUnsupported } from './query/case-fold.js';
 
-export const storageTypes = { ID: 'uuid', String: 'text', Enum: 'text', Int: 'integer', Float: 'double precision', Boolean: 'boolean', DateTime: 'timestamp with time zone' };
+export const storageTypes = { ID: 'uuid', Version: 'bigint', String: 'text', Enum: 'text', Int: 'integer', Float: 'double precision', Boolean: 'boolean', DateTime: 'timestamp with time zone' };
 export const invalidValue = (message) => { throw new SimfinityError(message, 'INVALID_FILTER_VALUE', 400); };
 export const castId = (value) => {
   const id = typeof value === 'object' && value ? value._id || value.id : value;
@@ -23,6 +23,7 @@ export const encodeScalar = (field, value) => {
     }
     case 'String': if (typeof value !== 'string') invalidValue(`Expected a string for ${field.name}`); break;
     case 'Boolean': if (typeof value !== 'boolean') invalidValue(`Expected a boolean for ${field.name}`); break;
+    case 'Version': if (!Number.isSafeInteger(value) || value < 1) invalidValue(`Expected a safe positive integer for ${field.name}`); break;
     case 'Int': if (!Number.isInteger(value) || value < -2147483648 || value > 2147483647) invalidValue(`Expected a 32-bit integer for ${field.name}`); break;
     case 'Float': if (typeof value !== 'number' || !Number.isFinite(value)) invalidValue(`Expected a finite number for ${field.name}`); break;
     case 'DateTime': {
@@ -37,6 +38,10 @@ export const encodeScalar = (field, value) => {
 
 export const decodeScalar = (field, value, gqlField) => {
   if (value == null) return value;
+  if (field.scalar === 'Version' && ['string', 'number', 'bigint'].includes(typeof value)) {
+    const version = Number(value);
+    return Number.isSafeInteger(version) && version >= 1 ? version : value;
+  }
   if (field.scalar === 'Enum' && gqlField) {
     const type = getNamedType(gqlField.type);
     if (isEnumType(type)) return type.getValues().find((item) => String(item.value) === value)?.value ?? value;

package/src/index.js

@@ -11,7 +11,9 @@ export {
   buildErrorFormatter,
   createValidatedScalar,
   InternalServerError,
+  MAX_RECORD_VERSION,
   plugins,
+  RecordVersion,
   scalars,
   SimfinityError,
   validators,
@@ -20,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, saveObject, preventCreatingCollection, withTransaction } = defaultInstance;
+export const { configureQueryLimits, configureMutationLimits, 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/src/plugin.js

@@ -17,7 +17,7 @@ export const postgresPlugin = (options) => ({
   options: options || null,
   // singleStatementReads: one statement reads one snapshot at any isolation level, so a read without owned
   // tables needs no repeatable-read transaction.
-  capabilities: ['transactions', 'foreignKeys', 'deferredForeignKeys', 'embeddedValues', 'ownedRecords', 'scalarLists', 'uniqueValues', 'nullableUnique', 'singleStatementReads'],
+  capabilities: ['transactions', 'optimisticConcurrency', 'foreignKeys', 'deferredForeignKeys', 'embeddedValues', 'ownedRecords', 'scalarLists', 'uniqueValues', 'nullableUnique', 'singleStatementReads'],
   // Every filter operator compileQuery and compileChildrenQuery compile, listed one by one so that a later
   // QLOperator value is rejected until the compiler supports it, and emptiness through references and collections
   // (#108 part 2b): the scoped joins and frames of client constructs, and stored semantics for the others. The

package/src/record-statements.js

@@ -7,6 +7,7 @@ export const compileRecord = (database, operation) => {
   const target = qualified(database.schema, storage.name);
   if (kind === 'selectById') return { text: `SELECT * FROM ${target} WHERE id = $1::uuid${operation.lock ? ' FOR UPDATE' : ''}`, values: [id] };
   if (kind === 'selectOwned') return { text: `SELECT * FROM ${target} WHERE "__owner_id" = ANY ($1::uuid[])${operation.ordered ? ' ORDER BY "__position"' : ''}`, values: [operation.ids] };
+  if (kind === 'deleteById' && operation.version) return { text: `DELETE FROM ${target} WHERE id = $1::uuid AND ${q(operation.version.column)} = $2::bigint RETURNING id`, values: [id, operation.version.expected] };
   if (kind === 'deleteById') return { text: `DELETE FROM ${target} WHERE id = $1::uuid`, values: [id] };
   if (kind === 'deleteOwned') return { text: `DELETE FROM ${target} WHERE "__owner_id" = $1::uuid`, values: [operation.ownerId] };
   if (kind === 'insert') {
@@ -16,6 +17,12 @@ export const compileRecord = (database, operation) => {
   }
   if (kind === 'update') {
     const entries = Object.entries(data);
+    if (operation.version) {
+      const column = q(operation.version.column);
+      const assignments = entries.map(([key], index) => `${q(key)} = $${index + 2}::${storage.columns.find((column) => column.name === key).type}`);
+      assignments.push(`${column} = ${column} + 1`);
+      return { text: `UPDATE ${target} SET ${assignments.join(', ')} WHERE id = $1::uuid AND ${column} = $${entries.length + 2}::bigint RETURNING *`, values: [id, ...entries.map(([, value]) => value), operation.version.expected] };
+    }
     return { text: `UPDATE ${target} SET ${entries.map(([key], index) => `${q(key)} = $${index + 2}::${storage.columns.find((column) => column.name === key).type}`).join(', ')} WHERE id = $1::uuid RETURNING *`, values: [id, ...entries.map(([, value]) => value)] };
   }
   throw new SimfinityError(`Unknown record operation ${kind}`, 'INVALID_RECORD_OPERATION', 400);

package/src/schema/describe.js

@@ -4,7 +4,7 @@ import { queryFunctions } from '../query/functions.js';
 import { constraintBuilder, withLayouts } from './constraints.js';
 import { identifier, literal, generatedName, invalid } from './sql.js';
 
-const scalarTypes = { ID: 'uuid', String: 'text', Enum: 'text', Int: 'integer', Float: 'double precision', Boolean: 'boolean', DateTime: 'timestamp with time zone', Embedded: 'jsonb' };
+const scalarTypes = { ID: 'uuid', Version: 'bigint', String: 'text', Enum: 'text', Int: 'integer', Float: 'double precision', Boolean: 'boolean', DateTime: 'timestamp with time zone', Embedded: 'jsonb' };
 const physicalType = (column) => `${scalarTypes[column.scalar]}${column.list ? '[]' : ''}`;
 const physicalDefault = (value) => value.kind === 'identity' ? 'gen_random_uuid()' : typeof value.value === 'string' ? `${literal(value.value)}::text` : String(value.value);
 // The first value is the default, which keeps the 3.5.9 description.

package/src/schema/initialize.js

@@ -560,14 +560,45 @@ const virtualLeftovers = (description, catalog, virtualFields) => {
   return `${series(fields)} ${many ? 'are' : 'is'} virtual (extensions.virtual), so ${many ? 'they are' : 'it is'} never stored, but this database still holds ${many ? 'their' : 'its'} `
     + `earlier storage. Once nothing reads that storage, migrate it: ${statements.join(' ')} See the upgrade notes at ${UPGRADE_NOTES}`;
 };
-// A SCHEMA_MISMATCH of a database that still holds storage of fields that are now virtual also names them.
+// Explain version-column drift from catalog contents, including when equal column counts hide a missing
+// or leftover version in the original mismatch. Private owned and auxiliary tables have no record version.
+const versionColumns = (description, catalog) => {
+  const explanations = [];
+  for (const table of description.tables) {
+    if (table.ownership || table.auxiliary) continue;
+    const actual = catalog.tables.get(table.name);
+    if (!actual) continue;
+    const column = table.columns.find((item) => item.name === 'version');
+    const stored = actual.columns.find((item) => item.name === 'version');
+    const target = qualified(description.schema, table.name);
+    if (column?.type === 'bigint') {
+      const declaration = `${table.name} declares optimistic concurrency (extensions.concurrency), so its table needs the version column`;
+      if (!stored) explanations.push(`${declaration}. Migrate it: ALTER TABLE ${target} ADD COLUMN "version" bigint NOT NULL DEFAULT 1;`);
+      else if (stored.type !== column.type || stored.nullable !== column.nullable
+        || (column.collation && (stored.collation !== column.collation || stored.collation_schema !== 'pg_catalog'))
+        || normalizeExpression(stored.default) !== normalizeExpression(column.default || null) || stored.attidentity || stored.attgenerated) {
+        explanations.push(`${declaration} defined as bigint NOT NULL DEFAULT 1.`);
+      }
+    } else if (!column && stored?.type === 'bigint') {
+      explanations.push(`${table.name} does not declare optimistic concurrency, but its table has the version column. `
+        + 'If other instances of this application declare it, deploy the declaration here: while the column exists, instances without it cannot start. '
+        + `Otherwise, once no instance declares it: ALTER TABLE ${target} DROP COLUMN "version";`);
+    }
+  }
+  return explanations.length ? explanations.join(' ') : null;
+};
+
+// A SCHEMA_MISMATCH also explains optimistic-concurrency columns and earlier storage of virtual fields.
 const explainMismatch = (error, description, catalog, layouts, virtualFields) => {
-  if (!virtualFields.length || !catalog || !(error instanceof SimfinityError) || error.extensions?.code !== 'SCHEMA_MISMATCH') return error;
+  if (!catalog || !(error instanceof SimfinityError) || error.extensions?.code !== 'SCHEMA_MISMATCH') return error;
   let resolved = description;
   // Refresh-trigger objects of two layouts in one root are themselves the mismatch; compare with the description.
   try { resolved = resolveLayouts(description, catalog, layouts); } catch { /* keep the description */ }
   try {
-    const explanation = virtualLeftovers(resolved, catalog, virtualFields);
+    const explanation = [
+      versionColumns(resolved, catalog),
+      virtualFields.length ? virtualLeftovers(resolved, catalog, virtualFields) : null,
+    ].filter(Boolean).join(' ');
     return explanation ? new SimfinityError(`${error.message} ${explanation}`, 'SCHEMA_MISMATCH', 409) : error;
   } catch {
     // An explanation never replaces the mismatch it explains.

package/types/index.d.ts

@@ -7,7 +7,9 @@ export {
   buildErrorFormatter,
   createValidatedScalar,
   InternalServerError,
+  MAX_RECORD_VERSION,
   plugins,
+  RecordVersion,
   scalars,
   SimfinityError,
   validators,
@@ -17,11 +19,14 @@ export type {
   AuthRule,
   AuthRuleFunction,
   AuthSchemaPlugin,
+  ConcurrencyDeclaration,
   CreateSchemaOptions,
   EntityController,
   EnvelopSchemaPlugin,
   FieldValidations,
   FieldValidator,
+  FilterCondition,
+  FilterGroup,
   ItemValidators,
   MiddlewareContext,
   MutationLimitsOptions,
@@ -33,6 +38,9 @@ export type {
   StateMachine,
   TypePermissions,
   TypeScopes,
+  ViewOptions,
+  ViewParam,
+  ViewParamType,
   VirtualFieldDeclaration,
   VirtualFieldOptions,
 } from '@simtlix/simfinity-core';
@@ -169,8 +177,10 @@ export interface PostgresModel {
   find(args?: Record<string, any>, options?: { session?: PostgresSession }): Promise<PostgresRecord[]>;
   /** Native helpers bypass GraphQL validators/controllers; references use storage column names. */
   create(data: Record<string, any>, options?: { session?: PostgresSession }): Promise<PostgresRecord>;
-  update(id: string, changes: Record<string, any>, options?: { session?: PostgresSession }): Promise<PostgresRecord | null>;
-  delete(id: string, options?: { session?: PostgresSession }): Promise<PostgresRecord | null>;
+  /** Protected entities require changes.version; version:false ignores that field and does not advance it. */
+  update(id: string, changes: Record<string, any>, options?: { session?: PostgresSession; version?: false }): Promise<PostgresRecord | null>;
+  /** Protected entities require the version read, or false to bypass the version precondition. */
+  delete(id: string, options?: { session?: PostgresSession; version?: number | false }): Promise<PostgresRecord | null>;
 }
 export interface PostgresConfiguration {
   pool: PostgresPool;
@@ -292,6 +302,7 @@ export const getRegistrations: PostgresRuntime['getRegistrations'];
 export const use: PostgresRuntime['use'];
 export const registerMutation: PostgresRuntime['registerMutation'];
 export const registerCustomQuery: PostgresRuntime['registerCustomQuery'];
+export const registerView: PostgresRuntime['registerView'];
 export const saveObject: PostgresRuntime['saveObject'];
 export const preventCreatingCollection: PostgresRuntime['preventCreatingCollection'];
 export const withTransaction: PostgresRuntime['withTransaction'];