@simtlix/simfinity-core 3.14.0 → 3.16.0

package/types/index.d.ts

@@ -56,11 +56,18 @@ export const MAX_RECORD_VERSION: number;
  * missing; constructs that middleware and scopes add read stored data. With any other adapter they
  * fail with `UNSUPPORTED_QUERY`. A term or group condition without a path tests the field itself, except that every term
  * of a quantified relation filter needs a non-empty element-relative path.
+ *
+ * `IIN` is `IN` ignoring case: an array of non-null strings without U+0000, possibly empty, on a `String` field or
+ * `String` list by its effective scalar; it matches where `IEQ` matches one of them, and `[]` matches nothing.
+ * `CONTAINS_ALL` takes a non-empty array of non-null scalars, cast like `IN` elements; it applies to a scalar list or a
+ * field reached through embedded lists, where it holds when every value is among the values of all items, and fails
+ * with `INVALID_FILTER_OPERATOR` on other leaves and with `INVALID_FILTER_PATH` through a collection or a reference
+ * inside an embedded list. Neither has a negated form.
  */
 export type QueryOperator =
   | 'EQ' | 'NE' | 'LT' | 'LTE' | 'GT' | 'GTE' | 'BTW' | 'IN' | 'NIN' | 'LIKE'
   | 'ILIKE' | 'STARTS_WITH' | 'ISTARTS_WITH' | 'ENDS_WITH' | 'IENDS_WITH' | 'IEQ'
-  | 'IS_EMPTY' | 'IS_NOT_EMPTY';
+  | 'IS_EMPTY' | 'IS_NOT_EMPTY' | 'CONTAINS_ALL' | 'IIN';
 
 /** The quantifier applied to the elements visible in a collection or reference frame. */
 export type QueryQuantifier = 'ANY' | 'ALL' | 'NONE';
@@ -333,7 +340,27 @@ export class InternalServerError extends SimfinityError {
  */
 export function buildErrorFormatter(callback?: (error: SimfinityError) => Error | void): (error: unknown) => GraphQLError;
 
-export interface EntityController<Session = any> {
+export interface AfterCommitErrorDetails {
+  committed: true;
+  typeName: string;
+  operation: 'save' | 'update' | 'delete' | 'state_changed';
+  callbackName: 'onSaveCommitted' | 'onUpdateCommitted' | 'onDeleteCommitted' | 'onTransitionCommitted';
+  context: any;
+}
+export interface AfterCommitOptions {
+  /** Operational reporting only. Rejections are caught and never fail the committed write. */
+  onError?: (error: unknown, details: AfterCommitErrorDetails) => void | Promise<void>;
+}
+export interface CommittedControllerCallbacks {
+  /** After the owning transaction commits; a detached result and the successful attempt's input. */
+  onSaveCommitted?(record: any, args: any, context: any): void | Promise<void>;
+  onUpdateCommitted?(record: any, context: any): void | Promise<void>;
+  /** Called only when a record was actually deleted. */
+  onDeleteCommitted?(record: any, context: any): void | Promise<void>;
+  /** Exclusive notification for a state action; action is its registered name. */
+  onTransitionCommitted?(record: any, action: string, context: any): void | Promise<void>;
+}
+export interface EntityController<Session = any> extends CommittedControllerCallbacks {
   onSaving?(record: any, args: any, session: Session | undefined, context: any): void | Promise<void>;
   onSaved?(record: any, args: any, session: Session | undefined, context: any): void | Promise<void>;
   onUpdating?(id: any, update: any, session: Session | undefined, context: any): void | Promise<void>;
@@ -407,16 +434,24 @@ export interface ConcurrencyDeclaration {
 }
 
 /**
- * Process-wide limits for generated add, update and state-action mutations. Any other option,
- * such as a misspelled `maxNestedOperation`, throws `INVALID_MUTATION_LIMITS` (400).
+ * Process-wide limits for generated mutations. Each call replaces both values: an omitted or
+ * `undefined` option restores its default. Any other option, such as a misspelled
+ * `maxNestedOperation`, throws `INVALID_MUTATION_LIMITS` (400) and keeps the current limits.
  */
 export interface MutationLimitsOptions {
   /**
    * Maximum number of `added`, `updated` and `deleted` entries across every nested level of
    * non-embedded collection fields in one generated mutation. A non-negative safe integer;
-   * `null` or omitted means unlimited (the default).
+   * `null` or omitted means unlimited (the default). The helpers `updateObject` and
+   * `transitionObject` apply it to their `input` as the generated mutations do.
    */
   maxNestedOperations?: number | null;
+  /**
+   * Maximum number of operations in one generated transaction mutation. A positive safe integer;
+   * omitted means 100 (the default). `null`, `0`, a negative number or a non-integer throws
+   * `INVALID_MUTATION_LIMITS` (400).
+   */
+  maxTransactionOperations?: number;
 }
 
 /**
@@ -429,6 +464,21 @@ export interface CreateSchemaOptions {
    * `[]` includes none, and names that are not registered are ignored.
    */
   includedCustomQueries?: string[] | null;
+  /**
+   * Adds one mutation field that runs a list of generated mutations in order in one database
+   * transaction. `null` or omission adds none. `name` defaults to `transaction` and must be a GraphQL
+   * name that does not start with `__`; it names the field and its types (for `transaction`:
+   * `TransactionOperation`, a `@oneOf` input keyed by operation, `TransactionResult` and, for deletes
+   * of types without optimistic concurrency, `TransactionDeleteInput`). The operations are the
+   * generated add, update, delete and state machine action mutations of `types` that this schema
+   * includes; registered mutations never are. `types` is a non-empty array of distinct types registered
+   * in this runtime. An invalid option throws `INVALID_SCHEMA_OPTIONS` (500) before models are prepared,
+   * or once the generated mutations are built when the field name or a derived type name is taken or
+   * no operation remains; a type bound to another runtime throws `TYPE_BOUND_TO_OTHER_RUNTIME` (409),
+   * and an adapter without `assertTransactionModels` throws `TRANSACTION_UNSUPPORTED` (500). A failed
+   * `createSchema()` keeps no transaction field or type.
+   */
+  transaction?: { name?: string; types: GraphQLObjectType[] } | null;
 }
 
 export interface QueryLimitsOptions {
@@ -485,13 +535,17 @@ export interface ViewOptions {
 }
 
 export interface Runtime<Model = any, Session = any> {
+  /** Per runtime. No arguments resets to safe default logging; invalid options leave it unchanged. */
+  configureAfterCommit(options?: AfterCommitOptions): void;
   /** The same process-wide setting as the root `configureQueryLimits`. */
   configureQueryLimits(options?: QueryLimitsOptions): void;
   /**
-   * Process-wide; calling it without options restores the unlimited default. Invalid options,
-   * including unknown or misspelled option keys, throw `INVALID_MUTATION_LIMITS` (400) and keep
-   * the current limit. A generated mutation over the limit fails with
-   * `NESTED_OPERATIONS_EXCEEDED` (400) before its transaction starts.
+   * Process-wide; calling it without options restores both defaults (`maxNestedOperations`
+   * unlimited, `maxTransactionOperations` 100). Invalid options, including unknown or misspelled
+   * option keys, throw `INVALID_MUTATION_LIMITS` (400) and keep the current limits. A generated
+   * mutation over the nested limit fails with `NESTED_OPERATIONS_EXCEEDED` (400) before its
+   * transaction starts. `updateObject` and `transitionObject` apply `maxNestedOperations` to their
+   * `input` in the same way (`null` = no limit).
    */
   configureMutationLimits(options?: MutationLimitsOptions): void;
   /**
@@ -539,7 +593,8 @@ export interface Runtime<Model = any, Session = any> {
    *
    * `options.includedCustomQueries` selects custom queries by name (see {@link CreateSchemaOptions});
    * an included custom query named like an included generated query throws `QUERY_NAME_CONFLICT`
-   * (500). A schema without mutation fields has no `Mutation` root.
+   * (500). `options.transaction` adds the generated transaction field (see {@link CreateSchemaOptions}).
+   * A schema without mutation fields has no `Mutation` root.
    */
   createSchema(includedQueryTypes?: GraphQLObjectType[] | null, includedMutationTypes?: GraphQLObjectType[] | null, includedCustomMutations?: string[] | null, options?: CreateSchemaOptions): GraphQLSchema;
   getModel(type: GraphQLObjectType | { name: string }): Model | null | undefined;
@@ -580,6 +635,64 @@ export interface Runtime<Model = any, Session = any> {
   registerView(name: string, options: ViewOptions): void;
   /** Owns the full workflow transaction unless an active caller session is supplied. */
   saveObject(typeName: string, args: Record<string, any>, session?: Session, context?: any): Promise<any>;
+  /**
+   * Runs the lifecycle of the generated update mutation from code: validators, controller hooks,
+   * optimistic concurrency and the nested `added`, `updated` and `deleted` entries, in one transaction.
+   * `typeName` names a type registered in this runtime that stores records and has its update input
+   * prepared by `createSchema()`, with an `id` field. Whether a schema exposes the mutation does not
+   * matter: the helper is not an authorization boundary. Any other `typeName` rejects with
+   * `INVALID_OPERATION_TARGET` (500), before the input is read.
+   *
+   * `input` has the shape of the type's generated update input, `version` included on a type with
+   * optimistic concurrency. It is checked structurally and copied before anything runs, and the
+   * caller's object is never written to. It is not coerced like a GraphQL input: enum fields take
+   * their internal values, scalars are not parsed, a reference is its record key as a string, such as
+   * `{ id: String(record._id) }`, and the `state` of a type with a state machine changes only through
+   * `transitionObject`. A scalar field takes a primitive, a `Date` or plain data (objects and arrays,
+   * copied deeply, at most 256 levels deep); class instances such as `ObjectId`, `Buffer` or `Map` are
+   * rejected with `INVALID_INPUT`. An own `undefined` counts as omitted, and a bare value is never
+   * wrapped into a list. A missing `input`, `id` or value for a non-null field rejects with
+   * `REQUIRED_VALUE` (400); any other violation, such as an unknown field, an object that is not plain
+   * or a list that is not dense, rejects with `INVALID_INPUT` (400). The message names the path, such
+   * as `input.lines.added[1].price`, and never a value. More nested entries than `maxNestedOperations`
+   * from `configureMutationLimits()` (`null` = no limit) reject with `NESTED_OPERATIONS_EXCEEDED` (400)
+   * before the transaction starts.
+   *
+   * Without `session`, the adapter owns the transaction and its retries. A supplied `session` must have
+   * an active transaction, and the helper itself never commits, retries, aborts or cleans up a supplied
+   * session; an adapter may still abort it on a write error (for example MongoDB with transactional
+   * reference integrity). Like `saveObject`, it skips the global middleware of the record itself; nested entries keep theirs and
+   * receive `context`, which may be `undefined`.
+   *
+   * Resolves to the updated record, as the generated mutation returns it. An `id` that has no record
+   * rejects with `NOT_VALID_ID` (404), and a stale `version` with `VERSION_CONFLICT` (409).
+   */
+  updateObject(typeName: string, input: Record<string, any>, session?: Session, context?: any): Promise<any>;
+  /**
+   * Runs the lifecycle of the generated delete mutation from code. `target` is `{ id }`, the record key
+   * as a string, plus `version`, the version read, on a type with optimistic concurrency; on any other
+   * type `version` is an unknown field. The type is checked as in {@link Runtime.updateObject}, except
+   * that it needs no update input of its own; the type must still be a stored record type, which only
+   * `createSchema()` establishes. The target is checked before anything runs: a missing
+   * target, `id` or required `version` rejects with `REQUIRED_VALUE` (400), and any other violation
+   * with `INVALID_INPUT` (400). A stale `version` rejects with `VERSION_CONFLICT` (409). Sessions,
+   * `context` and middleware work as in `updateObject`.
+   *
+   * Resolves to the deleted record, or to `null` when no record has that ID.
+   */
+  deleteObject(typeName: string, target: { id: string; version?: number }, session?: Session, context?: any): Promise<any>;
+  /**
+   * Runs the state machine action `actionName` of `typeName` from code, with the lifecycle of the
+   * generated action mutation: the check of the current state, the action's callback, the update and the
+   * controller hooks, in one transaction. An `actionName` that is not an own action of the type's state
+   * machine, or a type without one, rejects with `UNKNOWN_ACTION` (500). The type, the checks of `input`,
+   * the session, `context`, the middleware and the errors are as in {@link Runtime.updateObject}. `input` has
+   * the shape of the update input and does not carry `state`. An action that does not start from the
+   * record's state rejects with `BAD_REQUEST` (400).
+   *
+   * Resolves to the updated record, with `state` set to the action's target state.
+   */
+  transitionObject(typeName: string, actionName: string, input: Record<string, any>, session?: Session, context?: any): Promise<any>;
   preventCreatingCollection(prevent: boolean): void;
 }
 
@@ -594,10 +707,17 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    * by-ID read through a `get_by_id` scope, whose arguments use a `QLOperator` value the adapter
    * does not support fails with `UNSUPPORTED_QUERY` (400), before middleware runs for the client's
    * arguments and before `find`, `count`, `aggregate`, `findChildren` or `findChildrenBatch` for
-   * conditions that middleware, scopes and joined scopes added. Operators outside `QLOperator` still
-   * reach the adapter, which reports them as before. Declaring `IS_EMPTY` and `IS_NOT_EMPTY` means
-   * compiling their semantics on the record's own fields; emptiness through references and
-   * collections also needs `referenceEmptiness: true`, and fails with `UNSUPPORTED_QUERY` without it.
+   * conditions that middleware, scopes and joined scopes added. Operators outside `QLOperator`, which
+   * only trusted code can write, fail with `INVALID_FILTER_OPERATOR` (400) before the adapter is
+   * called, except in the forms the compilers ignore: an operator beside the `terms` of an object
+   * filter, and the `terms` of a scalar, scalar-list, interface or union field's filter. Those reach
+   * the adapter, which ignores them. Declaring `IS_EMPTY` and `IS_NOT_EMPTY` means compiling their
+   * semantics on the record's own fields; emptiness through references and collections also needs
+   * `referenceEmptiness: true`, and fails with `UNSUPPORTED_QUERY` without it.
+   * Declaring `CONTAINS_ALL` means compiling set containment over the leaf's values, including the
+   * values of every item of embedded lists, two-valued under negation; declaring `IIN` means
+   * compiling case-insensitive membership under the case-folding contract of the text operators.
+   * Names that an older version ignored are honored once this version knows them.
    */
   queryFeatures?: QueryFeatures | null | undefined;
   /**
@@ -609,6 +729,16 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    * contract of `update` and `delete` and to the requirements on `find` below.
    */
   writeFeatures?: { optimisticConcurrency?: boolean } | null | undefined;
+  /**
+   * Optional, and required to enable the generated transaction field (see
+   * `CreateSchemaOptions.transaction`). Receives the models one transaction of that field may
+   * write: those of the types that own its operations and of the referenced collection items their
+   * inputs declare, at any depth, without duplicates. Core calls it before each transaction of the
+   * field opens, never in `createSchema()`, so a schema can be created before the connection opens.
+   * It must be synchronous and never write, and it throws when the models cannot share one session; a
+   * returned promise fails the transaction with `TRANSACTION_UNSUPPORTED` (500).
+   */
+  assertTransactionModels?(models: Model[]): void;
   bind?(runtime: Pick<Runtime<Model, Session>, 'getModel' | 'getType' | 'getRegistrations'>): void;
   validateRegistration?(registration: RuntimeRegistration<Model, Session>): void;
   /**
@@ -638,6 +768,15 @@ export interface DatabaseAdapter<Model = any, Session = any> {
   castId(value: any): any;
   stateValue?(state: { name: string; value: any }): any;
   withTransaction<T>(session: Session | null | undefined, callback: (session: Session) => Promise<T> | T, model?: Model): Promise<T>;
+  /**
+   * Optional capability for controller callbacks. Accept only into an active attempt owned by this
+   * adapter; false means the supplied session has no owned attempt. A new queue is required per
+   * retry, including retries on the same native session. Seal before commit, discard on abort or
+   * unresolved uncertainty, and drain once, serially, after confirmed commit and cleanup attempt.
+   * Callback failures must never enter transaction retry/rollback paths or fail a committed write.
+   * Borrowed operations join the owning attempt; this method does not observe external commits.
+   */
+  enqueueAfterCommit?(session: Session, run: () => void | Promise<void>): boolean;
   newRecord(model: Model, data: any, session?: Session): any;
   saveRecord(model: Model, record: any, session?: Session): any;
   toObject(record: any): any;
@@ -760,6 +899,8 @@ export type QueryJoins = Record<string, QueryPredicate | null>;
 
 /**
  * `operator` is a {@link QueryOperator}; the value of a text operator is a validated string. For
+ * `CONTAINS_ALL` the value is a non-empty array of non-null scalars, validated and not cast; the
+ * compiler casts each element as for `IN`. For `IIN` it is an array of strings, possibly empty. For
  * `IS_EMPTY` and `IS_NOT_EMPTY` the value is null, and `path` may end at an embedded object, an
  * embedded list or a scalar list as well as at a scalar; `IS_NOT_EMPTY` is the exact complement,
  * which the compiler builds. With `referenceEmptiness: true`, their `path` may also cross single
@@ -818,6 +959,22 @@ export interface QueryPlan {
  * object fails with `INVALID_FILTER_PATH`, as on MongoDB; a bare object field keeps
  * `MISSING_FILTER_PATH`.
  *
+ * `CONTAINS_ALL` and `IIN` are checked in this order: the path (`AMBIGUOUS_FILTER_FIELD`,
+ * `INVALID_FILTER_PATH`, `INVALID_FILTER_FIELD`) and the object-end rule above, then an unknown name
+ * (`INVALID_FILTER_OPERATOR`) and `operators` (`UNSUPPORTED_QUERY`), then, for `CONTAINS_ALL` only,
+ * `INVALID_FILTER_PATH` through a collection, aggregate join prefixes included
+ * (`The shorthand excludes them; use an explicit group`), `INVALID_FILTER_PATH` through a reference
+ * inside an embedded list, and `INVALID_FILTER_OPERATOR` on a leaf that is neither a scalar list nor
+ * a scalar reached through an embedded list, and the values last, with `INVALID_FILTER_VALUE`.
+ * `CONTAINS_ALL` takes a non-empty array of non-null scalars, none of them an array or a plain
+ * object; `IIN` takes an array of strings without U+0000, possibly empty, on a `String` field or list
+ * by its effective scalar. A hole of a sparse array fails for both, while `IN`, `NIN` and `BTW` keep
+ * skipping holes.
+ * Both plan `{ kind: 'predicate', path, operator, value }` with the array as validated, neither cast
+ * nor deduplicated. `IIN` through a collection plans as `IN` does: an implicit `ANY` frame with
+ * `quantifiers`, a row filter on an aggregate's join prefix, a legacy join otherwise. `CONTAINS_ALL`
+ * is never cut into a frame.
+ *
  * `referenceEmptiness` defaults to true when `operators` is omitted and to false when it is given.
  * When it is false, an emptiness condition that crosses or ends at a reference or a collection, or
  * reads a reference or collection member, fails with `UNSUPPORTED_QUERY` where the order above has
@@ -826,8 +983,17 @@ export interface QueryPlan {
  * becomes the predicate's `scopes`. `quantifiers` has the same default rule and requires reference
  * emptiness; enabled collection filters emit quantified nodes, with per-group/prefix correlation,
  * element-relative scopes/joins and aggregate anchors beyond legacy J joins. `__scope`, `__implicit`
- * and `__anchor` are reserved internal input metadata. A marker not filled for every path fails
- * with `DETACHED_CLIENT_FILTER` (500).
+ * and `__anchor` are reserved internal input metadata. A group that trusted code writes with
+ * `__implicit: true` must, after its `__anchor`, end at a collection, or at a reference without
+ * crossing a list, and its `__anchor`, when present, must have exactly the shape the collection
+ * shorthand writes: in an aggregate, on a group at the root, a non-empty array of field names without
+ * dots that crosses at least one collection, each a join prefix, followed by a `path` of one
+ * collection. Otherwise the group fails with `INVALID_FILTER_PATH` (400), whatever operators it holds
+ * and before its conditions are checked, with the message
+ * `An implicit quantified path must end at a collection, or at a reference without crossing a list` or
+ * `An implicit quantified anchor must name the aggregate's join prefixes`; the anchor's form is
+ * checked before the path rule, the rest after it.
+ * A marker not filled for every path fails with `DETACHED_CLIENT_FILTER` (500).
  */
 export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string>; referenceEmptiness?: boolean; quantifiers?: boolean }): QueryPlan;
 export function resolveModelPath(models: ModelDescription, entityName: string, path: string | string[]): FieldDescription[];
@@ -843,7 +1009,7 @@ export function resolveModelPath(models: ModelDescription, entityName: string, p
 export function configureQueryLimits(options?: QueryLimitsOptions): void;
 /**
  * Same process-wide setting as `Runtime.configureMutationLimits`. Unknown or misspelled options
- * throw `INVALID_MUTATION_LIMITS` (400) and keep the current limit.
+ * throw `INVALID_MUTATION_LIMITS` (400) and keep the current limits.
  */
 export function configureMutationLimits(options?: MutationLimitsOptions): void;
 export function paginationStages(pagination: { page: number; size: number } | null | undefined, withDefault: boolean): Array<{ $skip: number } | { $limit: number }>;
@@ -1093,3 +1259,6 @@ export const plugins: {
     };
   };
 };
+
+/** Early opt-out. Import its function from /introspection before loading the runtime. */
+export interface IntrospectionOptions { fieldExtensions: false; }

package/types/introspection.d.ts

@@ -0,0 +1,4 @@
+import type { IntrospectionOptions } from './index.js';
+export type { IntrospectionOptions } from './index.js';
+/** Must run before importing the runtime/facades. Never removes installed metadata. */
+export function configureIntrospection(options: IntrospectionOptions): void;