@simtlix/simfinity-core 3.9.0 → 3.11.0

package/types/index.d.ts

@@ -21,10 +21,26 @@ export const QLValue: GraphQLScalarType<unknown, unknown>;
  * and `IENDS_WITH` as a suffix, respecting or ignoring case, and `IEQ` as the whole value ignoring
  * case. An empty value matches every non-null string, except for `IEQ`, where it matches only the
  * empty string. On a list, some element must match.
+ *
+ * `IS_EMPTY` and `IS_NOT_EMPTY` take no value (omitted or null; any other value fails with
+ * `INVALID_FILTER_VALUE`), and every record matches exactly one of them. `IS_EMPTY` holds for a
+ * 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. 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';
+  | 'ILIKE' | 'STARTS_WITH' | 'ISTARTS_WITH' | 'ENDS_WITH' | 'IENDS_WITH' | 'IEQ'
+  | 'IS_EMPTY' | 'IS_NOT_EMPTY';
 
 /**
  * The query language features a {@link DatabaseAdapter} compiles. Declare it so that the runtime
@@ -36,6 +52,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 {
@@ -279,8 +304,32 @@ export interface MutationLimitsOptions {
   maxNestedOperations?: number | null;
 }
 
+/**
+ * The fourth `createSchema()` argument. Any other key, or a value that is not a plain object,
+ * throws `INVALID_SCHEMA_OPTIONS` (500) before models are prepared.
+ */
+export interface CreateSchemaOptions {
+  /**
+   * Custom queries to include, by name. `null` or omission includes every registered custom query,
+   * `[]` includes none, and names that are not registered are ignored.
+   */
+  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;
+}
+
 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
@@ -312,7 +361,7 @@ export interface Runtime<Model = any, Session = any> {
    * not virtual, and is not a reference or collection, logs a `Configuration issue` warning once. The
    * first schema binds the types whose relation resolvers it generates to this runtime and
    * reserves reachable types that still have a
-   * non-embedded relation field without a resolver, such as an unregistered custom mutation result.
+   * non-embedded relation field without a resolver, such as an unregistered custom operation result.
    * Every entity type resolves `id` to `_id ?? id`, whatever the allowlists include.
    *
    * A generated input that would have no fields is left out, with a `Configuration issue`
@@ -326,12 +375,16 @@ export interface Runtime<Model = any, Session = any> {
    * metadata types `SimfinityFieldExtensionsType` and `SimfinityRelationType` (numbered when
    * taken) for every later schema and logs a warning; once those names are fixed, a type with one
    * of them throws `RESERVED_TYPE_NAME` (500), before `adapter.prepare()` when it is an included
-   * endpoint type, a registered mutation's input or output type, an output type they reach or a
+   * endpoint type, a registered custom operation's input or output type, an output type they reach or a
    * field argument's type, and when the schema is constructed otherwise, such as for a type inside
    * an input object's fields. The check before `adapter.prepare()` never reads an input object's
    * fields, so a registered input's `fields` function may call `getInputType()`.
+   *
+   * `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.
    */
-  createSchema(includedQueryTypes?: GraphQLObjectType[] | null, includedMutationTypes?: GraphQLObjectType[] | null, includedCustomMutations?: string[] | null): GraphQLSchema;
+  createSchema(includedQueryTypes?: GraphQLObjectType[] | null, includedMutationTypes?: GraphQLObjectType[] | null, includedCustomMutations?: string[] | null, options?: CreateSchemaOptions): GraphQLSchema;
   getModel(type: GraphQLObjectType | { name: string }): Model | null | undefined;
   getType(name: string | { name: string }): GraphQLObjectType | null | undefined;
   /**
@@ -350,6 +403,13 @@ export interface Runtime<Model = any, Session = any> {
    */
   use(middleware: (params: MiddlewareContext, next: () => Promise<void>) => void | Promise<void>): void;
   registerMutation(name: string, description: string, input: GraphQLInputObjectType | null | undefined, output: GraphQLOutputType, callback: (args: any, session: Session, context: any) => any): void;
+  /**
+   * Register a custom query on `RootQueryType`, for a result that is not a stored record. The
+   * callback receives the input and the request context; no transaction or session wraps it.
+   * Throws `INVALID_QUERY_REGISTRATION` (500) for invalid arguments and `QUERY_NAME_CONFLICT`
+   * (500) for a name already registered.
+   */
+  registerCustomQuery(name: string, description: string, input: GraphQLInputObjectType | null | undefined, output: GraphQLOutputType, callback: (input: any, context: any) => any): 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;
@@ -360,13 +420,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.
+   * 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.
    */
   queryFeatures?: QueryFeatures | null | undefined;
   bind?(runtime: Pick<Runtime<Model, Session>, 'getModel' | 'getType' | 'getRegistrations'>): void;
@@ -486,8 +549,25 @@ export interface DatabaseAdapter<Model = any, Session = any> {
 }
 export function createRuntime<Model = any, Session = any>(adapter: DatabaseAdapter<Model, Session>): Runtime<Model, Session>;
 
-/** `operator` is a {@link QueryOperator}; the value of a text operator is a validated string. */
-export type QueryPredicate = { kind: 'predicate'; path: string[]; operator: string; value: any } | { kind: 'and' | 'or'; terms: QueryPredicate[] };
+/**
+ * `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. 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; scopes?: Record<string, QueryPredicate | null> }
+  | { kind: 'and' | 'or'; terms: QueryPredicate[] };
 export interface QueryPlan {
   entity: string;
   where: QueryPredicate | null;
@@ -502,11 +582,38 @@ export interface QueryPlan {
  * a string or contains U+0000. With `operators`, the names the caller compiles, any other
  * `QLOperator` value fails with `UNSUPPORTED_QUERY` (400); unknown operators fail with
  * `INVALID_FILTER_OPERATOR` (400) either way.
+ *
+ * An emptiness condition is checked in this order: its form, path and group depth
+ * (`MISSING_FILTER_PATH` for `IS_EMPTY` or `IS_NOT_EMPTY` on an object filter without terms or beside
+ * terms, `AMBIGUOUS_FILTER_FIELD`, `INVALID_FILTER_PATH`, `INVALID_FILTER_FIELD`,
+ * `FILTER_DEPTH_EXCEEDED`), then `operators` (`UNSUPPORTED_QUERY`), then `INVALID_FILTER_PATH` for a
+ * value inside an embedded list or a collection, `INVALID_FILTER_OPERATOR` for an embedded type that
+ * reaches itself through single embedded members, `INVALID_FILTER_VALUE` for a value that is not
+ * omitted or null, and `UNSUPPORTED_QUERY` for a reference or collection on the path or among the
+ * members. A term without a path (omitted, null or `""`) and a group condition without a path test
+ * 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.