@simtlix/simfinity-core 3.15.0 → 3.17.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';
@@ -70,6 +77,8 @@ export interface QLFilterCondition {
   field: string;
   operator?: QueryOperator | null;
   value?: any;
+  /** A stored field path, mutually exclusive with a supplied value; null preserves literal behavior. */
+  valuePath?: string | null;
   path?: string | null;
 }
 
@@ -94,6 +103,8 @@ export interface QLTypeFilterExpression {
   terms?: Array<{
     operator?: QueryOperator | null;
     value?: any;
+    /** A stored field path, mutually exclusive with a supplied value; null preserves literal behavior. */
+    valuePath?: string | null;
     path?: string | null;
   } | null> | null;
 }
@@ -108,6 +119,8 @@ export interface FilterCondition {
   field: string;
   operator?: QueryOperator | (string & {});
   value?: any;
+  /** A stored field path, mutually exclusive with a supplied value; null preserves literal behavior. */
+  valuePath?: string | null;
   path?: string;
 }
 
@@ -149,6 +162,8 @@ export interface QueryFeatures {
    * legacy joins. All adapters reject list sorts through collections, including count mode.
    */
   quantifiers?: boolean | null | undefined;
+  /** Field operands, including scoped references. Requires referenceEmptiness: true. */
+  valuePath?: boolean | null | undefined;
 }
 
 export interface ModelRegistration {
@@ -169,6 +184,10 @@ export interface FieldDescription {
   scalar?: 'ID' | 'String' | 'Int' | 'Float' | 'Boolean' | 'DateTime' | 'Enum' | 'Version';
   values?: string[];
   enumValues?: { name: string; value: unknown }[];
+  /** Logical GraphQL enum identity, required for field comparisons. */
+  enumName?: string;
+  /** Effective temporal base before storage normalizes Date and Time to DateTime. */
+  temporalName?: 'DateTime' | 'Date' | 'Time';
   target?: string;
   connectionField?: string;
   fields?: FieldDescription[];
@@ -427,16 +446,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;
 }
 
 /**
@@ -449,6 +476,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 {
@@ -510,10 +552,12 @@ export interface Runtime<Model = any, Session = any> {
   /** 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;
   /**
@@ -561,7 +605,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;
@@ -602,6 +647,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;
 }
 
@@ -616,10 +719,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;
   /**
@@ -631,6 +741,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;
   /**
@@ -789,8 +909,13 @@ export function createRuntime<Model = any, Session = any>(adapter: DatabaseAdapt
 /** Scoped single-reference joins, keyed by a dotted prefix relative to the containing frame. */
 export type QueryJoins = Record<string, QueryPredicate | null>;
 
+/** A field operand in the same frame (up: 0) or an enclosing shorthand frame. */
+export type QueryOperand = { up: number; path: string[]; joins?: QueryJoins };
+
 /**
  * `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
@@ -808,10 +933,11 @@ export type QueryJoins = Record<string, QueryPredicate | null>;
  * A `quantified` node selects elements with `ANY`, `ALL` or `NONE`, applying `scope` before `where`;
  * both predicates use paths relative to the element, and null means no restriction. Empty elements
  * give ANY false, ALL/NONE true; scope is never negated, and frames never multiply roots. `anchor` is
- * an aggregate's legacy join chain; when present, `path` is relative to it and `joins` is absent.
+ * an aggregate's legacy join chain; when present, `path` is relative to it. Comparison-bearing
+ * anchored frames may carry full-prefix joins as visibility guards, preserving the existing J row.
  */
 export type QueryPredicate =
-  | { kind: 'predicate'; path: string[]; operator: string; value: any; scopes?: Record<string, QueryPredicate | null>; joins?: QueryJoins }
+  | { kind: 'predicate'; path: string[]; operator: string; value: any; operand?: QueryOperand; scopes?: Record<string, QueryPredicate | null>; joins?: QueryJoins }
   | { kind: 'and' | 'or'; terms: QueryPredicate[] }
   | {
       kind: 'quantified';
@@ -849,6 +975,29 @@ 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.
+ *
+ * `valuePath` selects a compatible stored scalar operand instead of a literal value. It defaults
+ * like `quantifiers`; a comparison node has `value: null` and `operand: { up, path, joins? }`.
+ * Same-frame operands use the union of scoped paths in `joins`; internal shorthand outer bindings
+ * use positive `up` and their own operand joins. Public inputs do not accept outer-frame syntax.
+ * Null equality is two-valued, and a left scalar list uses null-safe EQ/NE membership.
+ * Embedded-list comparisons, right scalar lists and incompatible logical types fail explicitly.
+ *
  * `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
@@ -857,10 +1006,19 @@ 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 createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string>; referenceEmptiness?: boolean; quantifiers?: boolean; valuePath?: boolean }): QueryPlan;
 export function resolveModelPath(models: ModelDescription, entityName: string, path: string | string[]): FieldDescription[];
 
 /**
@@ -874,7 +1032,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 }>;