@simtlix/simfinity-core 3.9.0 → 3.10.0

package/types/index.d.ts

@@ -21,10 +21,22 @@ 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. 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';
+  | '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
@@ -279,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;
   /**
@@ -312,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`
@@ -326,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;
   /**
@@ -350,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;
@@ -366,7 +401,9 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    * 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; 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;
@@ -486,7 +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. */
+/**
+ * `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;
@@ -502,6 +544,18 @@ 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`.
  */
 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[];