@simtlix/simfinity-core 3.8.0 → 3.10.0

package/types/index.d.ts

@@ -8,10 +8,48 @@ import type {
   GraphQLSchema,
 } from 'graphql';
 
+/** The filter operator enum; its values are the {@link QueryOperator} names. */
 export const QLOperator: GraphQLEnumType;
 export const QLSort: GraphQLInputObjectType;
 export const QLValue: GraphQLScalarType<unknown, unknown>;
 
+/**
+ * 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`
+ * field or `String` list (a validated scalar filters by its base scalar), and match it literally:
+ * `ILIKE` as a substring ignoring case, `STARTS_WITH` and `ISTARTS_WITH` as a prefix, `ENDS_WITH`
+ * 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. 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.
+ */
+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';
+
+/**
+ * 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.
+ */
+export interface QueryFeatures {
+  /**
+   * The `QLOperator` values the adapter compiles, including an omitted operator's `EQ`. Names this
+   * version of Simfinity does not know are ignored.
+   */
+  operators: readonly (QueryOperator | (string & {}))[];
+}
+
 export interface ModelRegistration {
   gqltype: GraphQLObjectType;
   /** Defaults to true. False excludes embedded-only types until referenced. */
@@ -253,6 +291,18 @@ 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 Runtime<Model = any, Session = any> {
   configureQueryLimits(options?: { maxPageSize?: number }): void;
   /**
@@ -286,7 +336,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`
@@ -300,12 +350,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;
   /**
@@ -324,6 +378,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;
@@ -331,6 +392,20 @@ export interface Runtime<Model = any, Session = any> {
 
 /** Driver adapter contract. GraphQL generation and lifecycle live in createRuntime. */
 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
+   * 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.
+   */
+  queryFeatures?: QueryFeatures | null | undefined;
   bind?(runtime: Pick<Runtime<Model, Session>, 'getModel' | 'getType' | 'getRegistrations'>): void;
   validateRegistration?(registration: RuntimeRegistration<Model, Session>): void;
   /**
@@ -448,6 +523,12 @@ 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. 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.
+ */
 export type QueryPredicate = { kind: 'predicate'; path: string[]; operator: string; value: any } | { kind: 'and' | 'or'; terms: QueryPredicate[] };
 export interface QueryPlan {
   entity: string;
@@ -457,7 +538,26 @@ export interface QueryPlan {
   pagination: { limit: number; offset: number } | null;
   aggregation?: { groupId: string[]; facts: Array<{ path: string[]; factName: string; operation: 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' }> };
 }
-export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode'] }): QueryPlan;
+/**
+ * Validates the arguments into a plan: paths, operators and values, with `INVALID_FILTER_VALUE` (400)
+ * for a text operator on a field that is not a `String` field or list, or with a value that is not
+ * 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`.
+ */
+export function createQueryPlan(models: ModelDescription, entityName: string, input?: Record<string, any>, options?: { mode?: QueryPlan['mode']; operators?: Iterable<string> }): QueryPlan;
 export function resolveModelPath(models: ModelDescription, entityName: string, path: string | string[]): FieldDescription[];
 
 export function configureQueryLimits(options?: { maxPageSize?: number }): void;