@simtlix/simfinity-core 3.11.0 → 3.13.0

package/types/index.d.ts

@@ -2,6 +2,8 @@ import type {
   GraphQLEnumType,
   GraphQLError,
   GraphQLInputObjectType,
+  GraphQLList,
+  GraphQLNonNull,
   GraphQLObjectType,
   GraphQLOutputType,
   GraphQLScalarType,
@@ -13,6 +15,20 @@ export const QLOperator: GraphQLEnumType;
 export const QLSort: GraphQLInputObjectType;
 export const QLValue: GraphQLScalarType<unknown, unknown>;
 
+/**
+ * The scalar of the `version` field that Simfinity adds to a type that declares optimistic
+ * concurrency (see {@link ConcurrencyDeclaration}). It holds safe integers from 1 to
+ * {@link MAX_RECORD_VERSION}, a JSON number on the wire: a string, a float, 0, a negative number and an
+ * unsafe integer fail GraphQL coercion. A client sends the version it read back unchanged in updates
+ * and deletes, and Simfinity advances it. Only the managed field may use it in a type, which
+ * `createSchema()` and `describeModels()` enforce with `INVALID_MODEL` (400); a registered mutation or
+ * custom query may use it in its own input and output types. Import it from the facade the application
+ * uses: the protection depends on one copy of core per process.
+ */
+export const RecordVersion: GraphQLScalarType;
+/** The highest version, `Number.MAX_SAFE_INTEGER`. The version of a record never goes past it. */
+export const MAX_RECORD_VERSION: number;
+
 /**
  * A `QLOperator` value. The operators of 3.7.0 are `EQ`, `NE`, `LT`, `LTE`, `GT`, `GTE`, `BTW`, `IN`,
  * `NIN` and `LIKE`. The literal text operators take a non-null string without U+0000 on a `String`
@@ -42,6 +58,26 @@ export type QueryOperator =
   | 'ILIKE' | 'STARTS_WITH' | 'ISTARTS_WITH' | 'ENDS_WITH' | 'IENDS_WITH' | 'IEQ'
   | 'IS_EMPTY' | 'IS_NOT_EMPTY';
 
+/**
+ * A condition of a {@link FilterGroup}, as the `QLFilterCondition` input takes it: the field it
+ * tests, its {@link QueryOperator} (`EQ` when omitted) and its value. On an object field, `path`
+ * names the member it tests; `IS_EMPTY` and `IS_NOT_EMPTY` take no value and may omit `path` to test
+ * the field itself.
+ */
+export interface FilterCondition {
+  field: string;
+  operator?: QueryOperator | (string & {});
+  value?: any;
+  path?: string;
+}
+
+/** A `QLFilterGroup` value: flat conditions plus nested `AND` and `OR` groups. */
+export interface FilterGroup {
+  AND?: FilterGroup[];
+  OR?: FilterGroup[];
+  conditions?: FilterCondition[];
+}
+
 /**
  * The query language features a {@link DatabaseAdapter} compiles. Declare it so that the runtime
  * sends the adapter only conditions it compiles; later releases add members for later features.
@@ -77,7 +113,8 @@ export interface FieldDescription {
   itemRequired: boolean;
   unique: boolean;
   readOnly: boolean;
-  scalar?: 'ID' | 'String' | 'Int' | 'Float' | 'Boolean' | 'DateTime' | 'Enum';
+  /** `'Version'` is the managed version field of a type that declares optimistic concurrency (`version: true`). */
+  scalar?: 'ID' | 'String' | 'Int' | 'Float' | 'Boolean' | 'DateTime' | 'Enum' | 'Version';
   values?: string[];
   enumValues?: { name: string; value: unknown }[];
   target?: string;
@@ -85,6 +122,12 @@ export interface FieldDescription {
   fields?: FieldDescription[];
   private?: boolean;
   inferred?: boolean;
+  /**
+   * Set on the managed version field of a type that declares optimistic concurrency, which
+   * `describeModels()` appends after the type's own fields: `{ name: 'version', scalar: 'Version',
+   * required: true, readOnly: true, version: true }`.
+   */
+  version?: true;
 }
 export interface ModelDescription {
   entities: Array<{
@@ -99,6 +142,13 @@ export interface ModelDescription {
  * fields are left out of every entity and embedded type, and the types only they reach are not
  * described. Throws `INVALID_MODEL` (400) for an invalid `extensions.virtual` declaration, as
  * `createSchema()` does (see {@link VirtualFieldOptions}).
+ *
+ * A type that declares optimistic concurrency (see {@link ConcurrencyDeclaration}) is described with
+ * its version field last, before `createSchema()` has added it and after, and the call throws
+ * `INVALID_MODEL` (400) for an invalid declaration, for a field named `version` that Simfinity did not
+ * add, for a reference stored under `version` (`connectionField: 'version'`), for a collection of
+ * such items that links through `version`, for such a type used as an embedded value, and for any
+ * other field typed {@link RecordVersion}.
  */
 export function describeModels(registrations: ModelRegistration[]): ModelDescription;
 /**
@@ -290,6 +340,19 @@ export type ScopeFunction<Model = any, Session = any> = (params: ScopeParams<Mod
  * was changed.
  */
 export type TypeScopes<Model = any, Session = any> = Partial<Record<ScopeOperation, ScopeFunction<Model, Session>>>;
+/**
+ * Value of a type's `extensions.concurrency`: the entity is protected by optimistic concurrency.
+ * Simfinity adds a read-only `version: RecordVersion!` field to the type, which starts at 1 and grows
+ * by 1 with each accepted write; a client sends the version it read back in updates and deletes, and a
+ * write at another version fails with `VERSION_CONFLICT` (409). The only valid value is
+ * `{ mode: 'optimistic' }`: `null`, an array, another mode or an extra key throws `INVALID_MODEL`
+ * (400). So does a type that is not an entity, one used as an embedded value, one that already has a
+ * field named `version` (or a field stored under that name), and an adapter that does not declare
+ * `writeFeatures.optimisticConcurrency`.
+ */
+export interface ConcurrencyDeclaration {
+  mode: 'optimistic';
+}
 
 /**
  * Process-wide limits for generated add, update and state-action mutations. Any other option,
@@ -327,6 +390,42 @@ export interface QueryLimitsOptions {
   maxReferenceFrames?: number;
 }
 
+/**
+ * The type of a view parameter: a value the client sends as a variable or a literal, so a scalar,
+ * an enum or a list of them, each possibly non-null, never an input object.
+ */
+export type ViewParamType =
+  | GraphQLScalarType
+  | GraphQLEnumType
+  | GraphQLList<ViewParamType>
+  | GraphQLNonNull<GraphQLScalarType | GraphQLEnumType | GraphQLList<ViewParamType>>;
+
+/** A view parameter: an argument of the view's root field that only its `where` reads. */
+export interface ViewParam {
+  type: ViewParamType;
+  description?: string;
+  defaultValue?: unknown;
+}
+
+/** The declaration of a named view (see {@link Runtime.registerView}). */
+export interface ViewOptions {
+  /** The connected endpoint type whose list the view returns. */
+  type: GraphQLObjectType;
+  /** Non-empty; the root field's description. */
+  description: string;
+  /**
+   * Arguments of the root field besides the generated list arguments, named unlike them and unlike
+   * the fields of `type`. They never reach the adapter: only `where` receives them.
+   */
+  params?: Record<string, ViewParam>;
+  /**
+   * Called on every read with the param values and the request context. The groups it returns are
+   * appended to the client's filters after middleware, so neither the client nor middleware can drop
+   * them; their paths may name fields that are not queryable.
+   */
+  where: (input: { params: Record<string, any>; context: any }) => FilterGroup[] | Promise<FilterGroup[]>;
+}
+
 export interface Runtime<Model = any, Session = any> {
   /** The same process-wide setting as the root `configureQueryLimits`. */
   configureQueryLimits(options?: QueryLimitsOptions): void;
@@ -410,6 +509,17 @@ export interface Runtime<Model = any, Session = any> {
    * (500) for a name already registered.
    */
   registerCustomQuery(name: string, description: string, input: GraphQLInputObjectType | null | undefined, output: GraphQLOutputType, callback: (input: any, context: any) => any): void;
+  /**
+   * Register a named view: a root query field that returns the list of `options.type` with the
+   * generated list arguments plus `options.params`, and appends the groups of `options.where` after
+   * middleware. A schema includes the view exactly when it includes the type. Throws `INVALID_VIEW`
+   * (500) for an invalid declaration and `QUERY_NAME_CONFLICT` (500) for a name already registered as
+   * a view, keeping the first registration. `createSchema` throws `INVALID_VIEW` when the type is not
+   * connected in this runtime or a param is named like one of its fields or a generated list
+   * argument, and `QUERY_NAME_CONFLICT` when an included view is named like an included generated or
+   * custom query.
+   */
+  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>;
   preventCreatingCollection(prevent: boolean): void;
@@ -432,6 +542,15 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    * collections also needs `referenceEmptiness: true`, and fails with `UNSUPPORTED_QUERY` without it.
    */
   queryFeatures?: QueryFeatures | null | undefined;
+  /**
+   * Optional. Declares the write features this adapter implements. `createRuntime` reads it once and
+   * throws `INVALID_WRITE_FEATURES` (500) unless it is undefined, null or an object whose
+   * `optimisticConcurrency`, if present, is a boolean. A schema with a type that declares
+   * `extensions.concurrency` (see {@link ConcurrencyDeclaration}) throws `INVALID_MODEL` (400) unless
+   * the adapter declares `optimisticConcurrency: true`, which commits it to the `options.expectedVersion`
+   * contract of `update` and `delete` and to the requirements on `find` below.
+   */
+  writeFeatures?: { optimisticConcurrency?: boolean } | null | undefined;
   bind?(runtime: Pick<Runtime<Model, Session>, 'getModel' | 'getType' | 'getRegistrations'>): void;
   validateRegistration?(registration: RuntimeRegistration<Model, Session>): void;
   /**
@@ -440,10 +559,16 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    * must never be stored: an adapter that builds storage from a type's fields skips each field for
    * which {@link isVirtualField} returns true, on the types its embedded fields reach as well, or
    * builds it from `describeModels(registrations)`, which leaves them out. Generated writes, filters,
-   * sorts and aggregations never name a virtual field; a controller hook can still assign one.
+   * sorts and aggregations never name a virtual field; a controller hook can still assign one. The
+   * version field of a type that declares optimistic concurrency is injected after `prepare()`, so a
+   * type here may not have it yet; `describeModels(registrations)` describes it either way.
    */
   prepare?(registrations: RuntimeRegistration<Model, Session>[], options: { createCollection: boolean }): void;
-  /** Creates the model of a registered type. Its fields include virtual fields; see `prepare()`. */
+  /**
+   * Creates the model of a registered type. Its fields include virtual fields; see `prepare()`. A type
+   * that declares optimistic concurrency already has its injected version field here, which
+   * `describeModels(registrations)` describes as well.
+   */
   createModel(type: GraphQLObjectType, callback: ((model: Model) => void) | null | undefined, options: { createCollection: boolean }): Model;
   /**
    * Casts a reference or batch key to the stored identifier type. Throw a `SimfinityError` with
@@ -505,8 +630,31 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    */
   readByIdIsInert?(model: Model): boolean;
   prepareUpdate(set: Record<string, any>, unset: Record<string, string>): any;
-  update(model: Model, id: any, changes: any, session?: Session): any;
-  delete(model: Model, id: any, session?: Session): any;
+  /**
+   * With `options.expectedVersion`, one atomic write that matches the ID and a stored version equal to
+   * it (on MongoDB a missing or null stored version counts as 1), applies `changes`, sets the version
+   * to `expectedVersion + 1` and returns the updated record. When nothing matches, or when
+   * `expectedVersion >= MAX_RECORD_VERSION` and the write is skipped, it reads the record by ID in the
+   * same session: it returns null for a missing one, throws `VERSION_CONFLICT` (409) when the stored
+   * version differs, `VERSION_EXHAUSTED` (409) when stored and expected are `MAX_RECORD_VERSION`, and
+   * returns null otherwise. Without `options.expectedVersion` it behaves as before. A wrapper must
+   * forward every argument, `options` included.
+   */
+  update(model: Model, id: any, changes: any, session?: Session, options?: { expectedVersion?: number }): any;
+  /**
+   * With `options.expectedVersion`, one atomic delete that matches the ID and the version, and returns
+   * the deleted record. When nothing matches, it decides as `update` does, without the exhausted case:
+   * a delete does not advance the version, so a record at `MAX_RECORD_VERSION` is deleted like any
+   * other. Without it, it behaves as before. A wrapper must forward every argument, `options`
+   * included.
+   */
+  delete(model: Model, id: any, session?: Session, options?: { expectedVersion?: number }): any;
+  /**
+   * An adapter that declares `writeFeatures.optimisticConcurrency` must run `find` inside the given
+   * `session`, honor `options.requiredId` and accept `options.context`: the runtime reads through
+   * `find` with the caller's session to check, before a hook runs, whether the caller can read a
+   * record whose version is stale.
+   */
   find(model: Model, type: GraphQLObjectType, args: any, session?: Session | null, options?: { requiredId?: any; context?: any }): any;
   count(model: Model, type: GraphQLObjectType, args: any, session?: Session | null): Promise<number> | number;
   aggregate(model: Model, type: GraphQLObjectType, args: any, session?: Session | null): any;