@simtlix/simfinity-core 3.10.0 → 3.12.0

package/types/index.d.ts

@@ -2,6 +2,8 @@ import type {
   GraphQLEnumType,
   GraphQLError,
   GraphQLInputObjectType,
+  GraphQLList,
+  GraphQLNonNull,
   GraphQLObjectType,
   GraphQLOutputType,
   GraphQLScalarType,
@@ -27,17 +29,41 @@ export const QLValue: GraphQLScalarType<unknown, unknown>;
  * missing, null or `""` String (`" "` is not empty), a missing or null value of any other scalar or
  * enum, a missing, null or `[]` list (`[null]` and `[""]` are not empty), and a missing or null
  * embedded object or one whose stored members are all empty by these rules; the record identity is
- * never empty. They apply to the queried record's own fields: a path that continues inside an
- * embedded list or a collection fails with `INVALID_FILTER_PATH`, and a path that crosses or ends
- * at a reference, a path that ends at a collection, and an embedded object with a reference or
- * collection member fail with `UNSUPPORTED_QUERY` until reference emptiness arrives. A term or
- * group condition without a path tests the field itself.
+ * never empty. The target's `id` right after a reference is empty exactly when the reference is,
+ * including when the target is missing or hidden by its `find` scope. A path that continues inside an
+ * embedded list or a collection fails with `INVALID_FILTER_PATH`. With an adapter that declares
+ * `queryFeatures.referenceEmptiness: true`, a path may also cross single references and end at a
+ * reference or a collection, and an embedded object may have reference and collection members: a
+ * reference is empty when no record it points to exists that the target's `find` scope admits for
+ * the caller, a collection when no such child exists, and a hidden record on the way reads as
+ * 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.
  */
 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';
 
+/**
+ * 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.
@@ -48,6 +74,15 @@ export interface QueryFeatures {
    * version of Simfinity does not know are ignored.
    */
   operators: readonly (QueryOperator | (string & {}))[];
+  /**
+   * Whether the adapter compiles `IS_EMPTY` and `IS_NOT_EMPTY` through single references and at
+   * references and collections, including reference and collection members of embedded objects.
+   * Undefined or null means false; any other value that is not a boolean fails `createRuntime` with
+   * `INVALID_QUERY_FEATURES` (500). An adapter that declares it receives client constructs that carry
+   * a filled client scope marker, `__scope: { id, scopes }`, on their term or group condition, and
+   * must apply each target scope in `scopes`; constructs without a marker read stored data.
+   */
+  referenceEmptiness?: boolean | null | undefined;
 }
 
 export interface ModelRegistration {
@@ -303,8 +338,56 @@ export interface CreateSchemaOptions {
   includedCustomQueries?: string[] | null;
 }
 
+export interface QueryLimitsOptions {
+  /** Positive safe integer; defaults to 1000. Unpaged lists use min(100, maxPageSize). */
+  maxPageSize?: number;
+  /**
+   * Positive safe integer; defaults to 10. The most distinct scoped joins and frames that the
+   * client's reference and collection emptiness may need in one list, aggregate or collection-field
+   * call; more fail with `FILTER_DEPTH_EXCEEDED` (400).
+   */
+  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> {
-  configureQueryLimits(options?: { maxPageSize?: number }): 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
@@ -385,6 +468,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;
@@ -395,15 +489,16 @@ export interface DatabaseAdapter<Model = any, Session = any> {
   /**
    * Optional. The filter operators this adapter compiles. `createRuntime` reads it once and throws
    * `INVALID_QUERY_FEATURES` (500) unless it is undefined, null or an object whose `operators` is an
-   * array of strings. Without it the adapter supports the operators of 3.7.0 (`EQ`, `NE`, `LT`,
-   * `LTE`, `GT`, `GTE`, `BTW`, `IN`, `NIN` and `LIKE`). A list, aggregate or collection read, or a
+   * array of strings and whose `referenceEmptiness`, if present, is a boolean or null. Without it the
+   * adapter supports the operators of 3.7.0 (`EQ`, `NE`, `LT`, `LTE`, `GT`, `GTE`, `BTW`, `IN`, `NIN`
+   * and `LIKE`) and no reference emptiness. A list, aggregate or collection read, or a
    * 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; it does not lift the `UNSUPPORTED_QUERY`
-   * that emptiness through references and collections gets in this release.
+   * 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.
    */
   queryFeatures?: QueryFeatures | null | undefined;
   bind?(runtime: Pick<Runtime<Model, Session>, 'getModel' | 'getType' | 'getRegistrations'>): void;
@@ -527,9 +622,21 @@ export function createRuntime<Model = any, Session = any>(adapter: DatabaseAdapt
  * `operator` is a {@link QueryOperator}; the value of a text operator is a validated string. 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.
+ * which the compiler builds. With `referenceEmptiness: true`, their `path` may also cross single
+ * references and end at a reference or a collection.
+ *
+ * `scopes` exists only on such an emptiness predicate from a client, and only for a compiler that
+ * declares `referenceEmptiness: true`. It has one key per dotted path from the queried record: each
+ * single reference the path crosses (a scoped join, which admits the target only where the scope
+ * admits it), the end when it is a reference or a collection, and each reference and collection
+ * member of an embedded object (frames, which keep only the records the scope admits). Each value is
+ * the target's `find` scope as a predicate in the target's own frame, or null when the scope added
+ * nothing; after a scoped crossing, a null hop still correlates through that scoped join. Without
+ * `scopes` the predicate reads stored data, through plain joins.
  */
-export type QueryPredicate = { kind: 'predicate'; path: string[]; operator: string; value: any } | { kind: 'and' | 'or'; terms: QueryPredicate[] };
+export type QueryPredicate =
+  | { kind: 'predicate'; path: string[]; operator: string; value: any; scopes?: Record<string, QueryPredicate | null> }
+  | { kind: 'and' | 'or'; terms: QueryPredicate[] };
 export interface QueryPlan {
   entity: string;
   where: QueryPredicate | null;
@@ -556,11 +663,26 @@ export interface QueryPlan {
  * the field itself. For other operators, a filter path of more than one segment that ends at an
  * object fails with `INVALID_FILTER_PATH`, as on MongoDB; a bare object field keeps
  * `MISSING_FILTER_PATH`.
+ *
+ * `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
+ * `UNSUPPORTED_QUERY` for references; when it is true, such a condition plans with stored semantics,
+ * unless its term or group condition carries a client scope marker that the runtime filled, which
+ * becomes the predicate's `scopes`. A marker that is not filled for every path of the condition fails
+ * with `DETACHED_CLIENT_FILTER` (500).
  */
-export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string> }): QueryPlan;
+export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string>; referenceEmptiness?: boolean }): QueryPlan;
 export function resolveModelPath(models: ModelDescription, entityName: string, path: string | string[]): FieldDescription[];
 
-export function configureQueryLimits(options?: { maxPageSize?: number }): void;
+/**
+ * Process-wide. `maxPageSize` (default 1000) caps page sizes. `maxReferenceFrames` (default 10) caps,
+ * per list, aggregate or collection-field call, the distinct scoped joins and frames that a client's
+ * reference and collection emptiness needs; more fail with `FILTER_DEPTH_EXCEEDED` (400). Each must be
+ * a positive safe integer, or the call throws `INVALID_QUERY_LIMITS` (400) and keeps both limits; an
+ * omitted option takes its default again.
+ */
+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.