@simtlix/simfinity-core 3.11.0 → 3.13.0

package/README.md

@@ -8,12 +8,13 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 
 ## Runtime
 
-`createRuntime(adapter)` creates a Simfinity runtime. Each instance owns its registrations, generated input types, middleware, scopes, hooks, custom queries and mutations, and state machines; the GraphQL type objects it builds resolvers for are bound to it, and query and mutation limits are process-wide. It exposes:
+`createRuntime(adapter)` creates a Simfinity runtime. Each instance owns its registrations, generated input types, middleware, scopes, hooks, custom queries and mutations, views, and state machines; the GraphQL type objects it builds resolvers for are bound to it, and query and mutation limits are process-wide. It exposes:
 
 - `connect`, `addNoEndpointType`, and `createSchema` for registration and schema creation;
 - `getModel`, `getType`, `getInputType`, and `getRegistrations` for runtime inspection;
 - `use`, `registerMutation`, and `saveObject` for middleware and write orchestration;
 - `registerCustomQuery` for reads whose results are not stored records, such as previews, other sources or permission evaluations;
+- `registerView` for a named list read of one registered type, with params and a fixed predicate, run through the type's scope;
 - `preventCreatingCollection` to pass validation-only storage setup to an adapter;
 - `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size, reference-frame and nested-operation limits.
 
@@ -44,3 +45,11 @@ Importing the runtime installs Simfinity's `__Field.extensions` introspection fi
 The package also exports the `auth`, `validators`, `scalars`, and `plugins` helper namespaces alongside `createValidatedScalar`, `SimfinityError`, `InternalServerError`, `UnauthenticatedError` and `ForbiddenError` (the same classes as `auth.UnauthenticatedError` and `auth.ForbiddenError`), `buildErrorFormatter`, `configureQueryLimits`, `configureMutationLimits`, `QLOperator`, `QLSort`, and `QLValue`. `buildErrorFormatter` returns a `GraphQLError` whose `originalError` is the classified Simfinity error. Database packages reuse these exports so helpers, errors, and globally named GraphQL types retain one identity.
 
 The same helpers are available from the `@simtlix/simfinity-core/auth`, `/auth/errors`, `/auth/expressions`, `/auth/rules`, `/plugins`, `/scalars` and `/validators` subpaths, each with TypeScript declarations whose types match the root namespaces. `moduleResolution` `node16`, `nodenext` and `bundler` read them through the export map, and `node10` through `typesVersions`. The `internal/*` subpaths are not public API and have no declarations.
+
+## Optimistic concurrency
+
+`extensions: { concurrency: { mode: 'optimistic' } }` opts an entity into the managed `version: RecordVersion!` field. Core exports `RecordVersion` and `MAX_RECORD_VERSION` (`9007199254740991`); import from the application's facade to share their identity. See the [concurrency guide](https://simtlix.github.io/simfinity.js/guide/concurrency.html).
+
+An adapter advertises `writeFeatures: { optimisticConcurrency: true }`; `createRuntime()` snapshots/freezes this declaration and rejects invalid shapes with `INVALID_WRITE_FEATURES` (500). A protected schema rejects an adapter without support. `update(model, id, changes, session, { expectedVersion })` must atomically match ID/version, apply changes and set `expectedVersion + 1`, returning the updated record; `delete(model, id, session, { expectedVersion })` must atomically match both and return the deleted record. An update at the maximum skips the write. After no match, read the same cast key in the same session: return `null` if absent, report `VERSION_CONFLICT` if stale or `VERSION_EXHAUSTED` for an equal maximum on update, otherwise return `null`. MongoDB missing/null versions count as 1. Without `expectedVersion`, existing writes and call paths remain unchanged.
+
+Support also requires `find(model, type, args, session, { requiredId, context })` to honor the session, required key and context for scoped visibility checks. Wrappers must forward every argument, including options. Core's update result diagnostic requires `expected + 1` and advancement beyond its immutable pre-read version; delete results must carry the expected version. These diagnostics raise `DATABASE_ERROR` for inconsistent results but cannot prove arbitrary wrappers kept the atomic predicate. They retain supplied-session ownership; adapters must preserve their own guarded-write abort semantics. The `get_by_id` scope defers stale/exhausted errors for hidden callers until write hooks authorize the operation, but malformed stored versions can fail before hooks. Protected writes always perform their required pre-read, regardless of `readByIdIsInert`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",
@@ -53,6 +53,7 @@
     },
     "./internal/object-id": "./src/auth/object-id.js",
     "./internal/query-operators": "./src/query-operators.js",
+    "./internal/record-version": "./src/record-version.js",
     "./internal/relation-storage": "./src/relation-storage.js",
     "./plugins": {
       "types": "./types/plugins.d.ts",

package/src/index.js

@@ -1,5 +1,6 @@
 export { describeModels } from './metadata.js';
 export { isVirtualField, virtualFieldOptions } from './relation-storage.js';
+export { MAX_RECORD_VERSION, RecordVersion } from './record-version.js';
 export { default as SimfinityError } from './errors/simfinity.error.js';
 export { createValidatedScalar } from './scalars/factory.js';
 export {

package/src/metadata.js

@@ -6,6 +6,10 @@ import {
   assertVirtualConnection, assertVirtualDeclaration, assertVirtualIndexes, assertVirtualStateField,
 } from './virtual-fields.js';
 import { assertPlainConnectionField } from './relation-storage.js';
+import {
+  isProtectedType, isVersionField, recordVersionFieldMisuse, versionConnectionCollision, versionEmbeddedMisuse,
+  versionFieldCollision,
+} from './record-version.js';
 
 const invalid = (message) => {
   throw new SimfinityError(message, 'INVALID_MODEL', 400);
@@ -62,10 +66,20 @@ const scalarDescription = (type) => {
   return { scalar };
 };
 
+// The version field of a protected entity, described the same way whether the type carries Simfinity's
+// injected field or only declares the extension and createSchema() has not injected it yet.
+const versionDescription = () => ({
+  name: 'version', storageName: 'version', kind: 'scalar', scalar: 'Version', required: true,
+  list: false, itemRequired: false, unique: false, readOnly: true, version: true,
+});
+
 /**
  * Describe persistent entities without importing a database driver or mutating GraphQL types.
  * Virtual fields (`extensions.virtual`) store nothing, so they are left out of every entity and
  * embedded type, and their result types are neither described nor required to declare a relation.
+ * An entity that declares optimistic concurrency (`extensions.concurrency`), or already carries its
+ * injected field, ends with the version field. A field that would collide with it, any other field
+ * typed RecordVersion, and a protected type used as an embedded value throw INVALID_MODEL.
  */
 export const describeModels = (registrations) => {
   if (!Array.isArray(registrations)) invalid('registrations must be an array');
@@ -91,10 +105,17 @@ export const describeModels = (registrations) => {
   const fieldsOf = (type, ancestors, path, embedded = false) => {
     if (ancestors.includes(type)) invalid(`Embedded cycle at ${path}`);
     registerType(type);
+    const isProtected = isProtectedType(type);
+    if (isProtected && embedded) invalid(versionEmbeddedMisuse(type.name, path));
+    const collision = isProtected ? versionFieldCollision(type) : null;
+    if (collision) invalid(collision);
+    const misuse = recordVersionFieldMisuse(type);
+    if (misuse) invalid(misuse);
     const stored = Object.values(type.getFields()).filter((field) => !assertVirtualDeclaration(
       type.name, field.name, field, () => typeof field.resolve === 'function',
     ));
     const fields = stored.map((field) => {
+      if (isVersionField(field)) return versionDescription();
       const { named, ...wrappers } = unwrap(field.type);
       const extensions = field.extensions || {};
       const descriptor = {
@@ -117,12 +138,15 @@ export const describeModels = (registrations) => {
       assertPlainConnectionField(type.name, field.name, field);
       addEntity(named);
       if (wrappers.list) {
+        const connectionCollision = versionConnectionCollision(type, field.name, field);
+        if (connectionCollision) invalid(connectionCollision);
         if (!relation.connectionField) invalid(`${path}.${field.name} requires a child connectionField`);
         if (embedded) invalid(`Non-embedded collections inside embedded objects are not supported: ${path}.${field.name}`);
         return { ...descriptor, kind: 'collection', target: named.name, connectionField: relation.connectionField };
       }
       return { ...descriptor, kind: 'reference', target: named.name, storageName: relation.connectionField || field.name };
     });
+    if (isProtected && !fields.some((item) => item.version)) fields.push(versionDescription());
     const storage = new Set();
     for (const field of fields.filter((item) => item.kind !== 'collection')) {
       if (storage.has(field.storageName)) invalid(`Storage collision at ${path}.${field.storageName}`);

package/src/record-version.js

@@ -0,0 +1,235 @@
+import {
+  GraphQLError, GraphQLID, GraphQLInputObjectType, GraphQLNonNull, GraphQLScalarType, Kind, getNamedType, isObjectType,
+} from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+import { getFieldStorageName, getListShape } from './relation-storage.js';
+
+// Everything about declarative optimistic concurrency (`extensions.concurrency`) that does not depend
+// on a runtime: the RecordVersion scalar, the version field Simfinity injects into a protected type,
+// how version values are read and checked, the errors that report them and the collision rules that
+// createSchema() and describeModels() share. The scalar and its maximum are public root exports of the
+// core package; the rest reaches the adapters through the `./internal/record-version` subpath, which
+// is not public API.
+
+/** The highest version. A record at it cannot be updated again, because its version cannot advance. */
+export const MAX_RECORD_VERSION = Number.MAX_SAFE_INTEGER;
+
+const RANGE = `an integer from 1 to ${MAX_RECORD_VERSION}`;
+
+const isVersionNumber = (value) => Number.isSafeInteger(value) && value >= 1;
+
+// A stored or serialized version as a number: a safe integer from 1 to MAX_RECORD_VERSION, given as a
+// number or as a bigint (a PostgreSQL driver may return one for a bigint column). Null for anything else.
+const asVersion = (value) => {
+  if (typeof value === 'bigint') return value >= 1n && value <= BigInt(MAX_RECORD_VERSION) ? Number(value) : null;
+  return isVersionNumber(value) ? value : null;
+};
+
+// The value as an error message shows it. A string is quoted; a value that cannot be converted to
+// text, such as an object without a prototype, shows its type.
+const show = (value) => {
+  try {
+    return typeof value === 'string' ? JSON.stringify(value) : String(value);
+  } catch {
+    return typeof value;
+  }
+};
+
+export const RecordVersion = new GraphQLScalarType({
+  name: 'RecordVersion',
+  description: 'Revision of a record with optimistic concurrency. Send it back unchanged in updates and deletes; Simfinity advances it.',
+  serialize(value) {
+    const version = asVersion(value);
+    if (version === null) throw new GraphQLError(`RecordVersion cannot represent ${show(value)}`);
+    return version;
+  },
+  // Input is a JSON number only: a string, a float or a bigint is never a version a client read.
+  parseValue(value) {
+    if (!isVersionNumber(value)) throw new TypeError(`RecordVersion must be ${RANGE}`);
+    return value;
+  },
+  parseLiteral(ast) {
+    // An IntValue beyond the safe integers rounds to an unsafe number, so the same check rejects it.
+    const version = ast.kind === Kind.INT ? Number(ast.value) : Number.NaN;
+    if (!isVersionNumber(version)) throw new GraphQLError(`RecordVersion must be ${RANGE}`, { nodes: ast });
+    return version;
+  },
+});
+
+/** A record of a protected collection, named by its ID and the version the client read. */
+export const RecordVersionRef = new GraphQLInputObjectType({
+  name: 'RecordVersionRef',
+  fields: {
+    id: { type: new GraphQLNonNull(GraphQLID) },
+    version: { type: new GraphQLNonNull(RecordVersion) },
+  },
+});
+
+// The marker of the injected field. Symbol.for gives every copy of the core code the same key, and a
+// null-prototype extensions object keeps it through toConfig() copies and extensions spreads.
+export const RECORD_VERSION_FIELD = Symbol.for('simfinity.recordVersionField');
+// Invalid raw storage values survive native hydration without mutating returned records.
+// Weak keys also support frozen documents and do not keep query results alive.
+const retainedVersions = new WeakMap();
+// Undefined clears metadata when a later query reuses the same result object.
+export const retainStoredVersion = (record, value) => {
+  if (value === undefined) retainedVersions.delete(record);
+  else retainedVersions.set(record, value);
+};
+export const retainedStoredVersion = (record) => retainedVersions.get(record);
+
+/** Whether a field is the version field that Simfinity injected into a protected type. */
+export const isVersionField = (field) => field?.extensions?.[RECORD_VERSION_FIELD] === true;
+
+const VERSION_FIELD_TYPE = new GraphQLNonNull(RecordVersion);
+
+/**
+ * The graphql-js field object that createSchema() puts into a protected type's `getFields()` map, with
+ * `resolve` as its resolver. `readOnly: true` keeps it out of the create input and `queryable: false`
+ * out of filters, sorts and aggregations; the marker tells it from an application field.
+ */
+export const createVersionFieldConfig = (resolve) => ({
+  name: 'version',
+  description: 'Revision of this record. Send it back unchanged in updates and deletes; Simfinity advances it.',
+  type: VERSION_FIELD_TYPE,
+  args: [],
+  resolve,
+  deprecationReason: undefined,
+  extensions: Object.assign(Object.create(null), { readOnly: true, queryable: false, [RECORD_VERSION_FIELD]: true }),
+  astNode: undefined,
+});
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+/**
+ * Whether the type declares optimistic concurrency. `extensions.concurrency` is either absent or a plain
+ * object whose only key is `mode`, with the value 'optimistic'; any other value throws INVALID_MODEL
+ * (400), whatever the key (own, hidden or a symbol) that makes it so.
+ */
+export const concurrencyDeclared = (gqltype) => {
+  const declaration = gqltype.extensions?.concurrency;
+  if (declaration === undefined) return false;
+  const keys = isPlainObject(declaration) ? Reflect.ownKeys(declaration) : [];
+  if (keys.length !== 1 || keys[0] !== 'mode' || declaration.mode !== 'optimistic') {
+    throw new SimfinityError(`${gqltype.name} extensions.concurrency must be { mode: 'optimistic' }`, 'INVALID_MODEL', 400);
+  }
+  return true;
+};
+
+/**
+ * A stored version as a number. A missing or null one is 1 (a MongoDB document written before the type
+ * was protected); anything but a safe integer from 1 to MAX_RECORD_VERSION, given as a number or a
+ * bigint, throws DATABASE_ERROR (500): the stored data is wrong, not the request.
+ */
+export const readStoredVersion = (value, { typeName, id } = {}) => {
+  if (value === undefined || value === null) return 1;
+  const version = asVersion(value);
+  if (version === null) {
+    const record = [typeName ?? 'Record', id].filter((part) => part !== undefined && part !== null).join(' ');
+    throw new SimfinityError(`${record} stores an invalid version`, 'DATABASE_ERROR', 500);
+  }
+  return version;
+};
+
+/**
+ * Checks a version that did not come through GraphQL coercion (middleware, saveObject(), a programmatic
+ * caller): a missing or null one throws REQUIRED_VALUE and one that is not a number from 1 to
+ * MAX_RECORD_VERSION throws INVALID_VERSION, both 400. Returns the version.
+ */
+export const assertVersionInput = (value) => {
+  if (value === undefined || value === null) throw new SimfinityError('Required value version is missing', 'REQUIRED_VALUE', 400);
+  if (!isVersionNumber(value)) throw new SimfinityError(`Invalid value for version: expected ${RANGE}`, 'INVALID_VERSION', 400);
+  return value;
+};
+
+// None of these messages carries the stored version or other data of the record.
+export const versionConflictError = (typeName, id) => new SimfinityError(
+  `${typeName} ${id} was modified by another operation`, 'VERSION_CONFLICT', 409,
+);
+
+export const versionExhaustedError = (typeName, id) => new SimfinityError(
+  `${typeName} ${id} has reached the maximum version`, 'VERSION_EXHAUSTED', 409,
+);
+
+/** `hook` is the name of the hook that set the managed field, such as 'onUpdating'. */
+export const versionManagedError = (typeName, hook) => new SimfinityError(
+  `${typeName}.version is managed by Simfinity; ${hook} cannot set it`, 'VERSION_MANAGED', 500,
+);
+
+export const unadvancedVersionError = (typeName, id) => new SimfinityError(
+  `${typeName} ${id} was written without advancing its version`, 'DATABASE_ERROR', 500,
+);
+
+export const unexpectedDeleteError = (typeName, id) => new SimfinityError(
+  `${typeName} ${id} was deleted at another version`, 'DATABASE_ERROR', 500,
+);
+
+/**
+ * Whether the type is protected: it declares the extension, whose shape this checks (INVALID_MODEL), or
+ * already carries the injected field. describeModels() and the checks of createSchema() ask this, since
+ * they run before the field is injected.
+ */
+export const isProtectedType = (gqltype) => concurrencyDeclared(gqltype) || Object.values(gqltype.getFields()).some(isVersionField);
+
+/**
+ * The INVALID_MODEL message for a protected type used as an embedded value at `path`, such as
+ * `Pedido.items`: an embedded value's changes belong to the revision of the record that embeds it.
+ */
+export const versionEmbeddedMisuse = (typeName, path) => `${typeName} declares optimistic concurrency, so it cannot be embedded (${path})`;
+
+const collisionPrefix = (typeName) => `${typeName} declares optimistic concurrency, so Simfinity adds its version field, but`;
+
+/**
+ * For a type that declares optimistic concurrency: the INVALID_MODEL message for the first field that
+ * would collide with the version field, or null. That is a field named `version` that Simfinity did not
+ * add, or a reference stored under `version` (`connectionField: 'version'`). The injected field itself
+ * is never a collision. A field named `version` typed RecordVersion is almost always the injected field
+ * copied without its marker, as a spread of its extensions passed to a graphql-js constructor does, so
+ * the message says how to keep it.
+ */
+export const versionFieldCollision = (gqltype) => {
+  for (const [name, field] of Object.entries(gqltype.getFields())) {
+    if (isVersionField(field)) continue;
+    if (name === 'version') {
+      const copied = getNamedType(field.type) === RecordVersion
+        ? '. It is typed RecordVersion, so it was probably copied from a protected type without its marker: keep '
+          + 'the field\'s extensions object as it is, for example with toConfig()'
+        : '';
+      return `${collisionPrefix(gqltype.name)} ${gqltype.name} already has a field named version; rename that field${copied}`;
+    }
+    if (getFieldStorageName(name, field) === 'version') {
+      return `${collisionPrefix(gqltype.name)} ${gqltype.name}.${name} uses version as its connectionField; choose another one`;
+    }
+  }
+  return null;
+};
+
+/**
+ * For a collection (a list relation that is not embedded) of `ownerType.fieldName` whose item type
+ * declares optimistic concurrency: the INVALID_MODEL message when the collection links its items through
+ * `version`, by its connectionField or, without one, by its own field name; otherwise null. The link
+ * would resolve to the injected version field instead of a field of the application.
+ */
+export const versionConnectionCollision = (ownerType, fieldName, field) => {
+  const relation = field.extensions?.relation;
+  const itemType = getListShape(field.type)?.itemType;
+  if (!relation || relation.embedded || !isObjectType(itemType)) return null;
+  if ((relation.connectionField || fieldName) !== 'version' || !isProtectedType(itemType)) return null;
+  return `${collisionPrefix(itemType.name)} ${ownerType.name}.${fieldName} links its items through version; use another connectionField`;
+};
+
+/**
+ * The INVALID_MODEL message for the first field of the type that is typed RecordVersion (the instance
+ * this module exports, single or list, required or not) without being the injected version field, or
+ * null. Only the managed field may use the scalar in a type; a registered mutation or custom query may
+ * still use it in its own input and output types.
+ */
+export const recordVersionFieldMisuse = (gqltype) => {
+  for (const [name, field] of Object.entries(gqltype.getFields())) {
+    if (getNamedType(field.type) === RecordVersion && !isVersionField(field)) {
+      return `${gqltype.name}.${name} uses RecordVersion, which only the managed version field may use`;
+    }
+  }
+  return null;
+};