@loradb/lora-graphql 0.24.0 → 0.25.0

package/dist/lora-graphql.d.ts

@@ -7,6 +7,9 @@ import { Statistics } from './analyze/statistics.js';
 import { CompiledRead, ReadSet } from './compile/read/types.js';
 import { WriteChange } from './execute/changes.js';
 import { LoraTransaction } from './execute/transaction.js';
+import { Worker, WorkerOptions } from './events/worker.js';
+import { JsonSchema } from './analyze/input-schemas.js';
+import { StoredReport } from './analyze/stored.js';
 import { OperationManifest } from './codegen.js';
 import { envelopPlugin } from './guards.js';
 import { GraphModel } from './model/types.js';
@@ -72,9 +75,29 @@ export declare class LoraGraphQL {
      * of caller, from the same rules as `accessMatrix()`, plus the most
      * restrictive verdict per caller. Takes a document (source or parsed)
      * or the id of a persisted operation; `operationName` picks one of
-     * several operations.
+     * several operations. A mutation's inputs are read for the
+     * relationship writes they make (a nested connect, disconnect, create,
+     * update or delete), which count towards its root field's verdict.
+     * Pass `variables` for inputs the document takes as variables; a
+     * variable without a value is listed in the field's `unresolved`.
      */
-    operationAccess(document: string | DocumentNode, operationName?: string): OperationAccess;
+    operationAccess(document: string | DocumentNode, operationName?: string, variables?: Readonly<Record<string, unknown>>): OperationAccess;
+    /**
+     * The validation rules as JSON Schema (2020-12), one per generated
+     * create and update input type, for clients: introspection does not
+     * show directives. Build zod, yup or valibot schemas from it, or
+     * validate with any JSON Schema library.
+     */
+    inputSchemas(): Record<string, JsonSchema>;
+    /**
+     * Stored values that break a validation rule of their field: rules are
+     * checked on write through the API, so a rule added later, or a value
+     * written with raw Cypher, is only found by reading. Reads at most
+     * `limit` nodes per type (default 10 000).
+     */
+    storedViolations(options?: {
+        limit?: number;
+    }): Promise<StoredReport>;
     /**
      * The CI gate: @cypher statements plan, the database has what the API
      * needs, and each operation's statements seek where they should.
@@ -158,6 +181,16 @@ export declare class LoraGraphQL {
      * others, and no change event fires, until `tx.commit()`.
      */
     begin(): Promise<LoraTransaction>;
-    /** Stop the engine change feed (with `changeFeed: true`). */
+    /**
+     * Hand the nodes of an `@outbox` type to `options.handle`, after the
+     * commit that made them: for the side effects a transaction cannot
+     * hold (a push, an e-mail, a webhook). Delivery is at least once, with
+     * retries and backoff; work left by a restart is picked up when the
+     * worker starts. With `changeFeed: true` it also hears of nodes
+     * created outside this instance, otherwise it finds those on its next
+     * sweep. `close()` stops it.
+     */
+    worker(type: string, options: WorkerOptions): Worker;
+    /** Stop the workers, and the engine change feed (with `changeFeed: true`). */
     close(): void;
 }

package/dist/model/build/authorization.d.ts

@@ -1,4 +1,4 @@
-import { AuthOperation, Authorization, RelationshipField } from '../types.js';
+import { AuthOperation, Authorization, AuthorizationWhere, NodeType, RelationshipField } from '../types.js';
 export declare function authOps(args: Record<string, unknown> | undefined): Set<AuthOperation> | undefined;
 /**
  * Field-level rules on a relationship or @cypher field: READ validate rules
@@ -28,4 +28,14 @@ export declare function relationshipRuleOperations(f: RelationshipField): Set<Au
 export declare const isRelationshipRule: (rule: {
     operations: ReadonlySet<AuthOperation>;
 }) => boolean;
+/**
+ * The authorization of a field to an interface or union, per member: its
+ * relationship rules hold per member, each with that member as its
+ * target. Sugar expands differently per member (`target: { isViewer:
+ * true }` is only ever true of one), so each member gets its own copy of
+ * the rules, which `desugar` expands in place.
+ */
+export declare function memberAuthorization(f: RelationshipField, nodes: ReadonlyMap<string, NodeType>, desugar: (rules: ReadonlyArray<{
+    where: AuthorizationWhere;
+}>, target: NodeType) => void): Map<string, Authorization>;
 export declare const isRecord: (x: unknown) => x is Record<string, unknown>;

package/dist/model/build/constraints.d.ts

@@ -0,0 +1,22 @@
+import { GraphQLDirective, GraphQLScalarType } from 'graphql';
+import { FieldConstraints } from '../constraints.js';
+import { ScalarType } from '../types.js';
+/** The value rules of field `f`, with every problem reported through `at`. */
+export declare function readConstraints(d: (n: string) => GraphQLDirective, f: {
+    astNode?: unknown;
+    extensionASTNodes?: unknown;
+}, at: (message: string) => void, field: {
+    type: ScalarType;
+    list: boolean;
+    vector: boolean;
+    timestamp: boolean;
+    defaultValue: {
+        value: unknown;
+    } | undefined;
+    /** The field's custom scalar, whose rules it inherits. */
+    scalar?: GraphQLScalarType | undefined;
+    /** How a problem names the default: an argument's is not a directive. */
+    defaultLabel?: string | undefined;
+    /** Directives another reader handles (an argument's plain @size, @range). */
+    skip?: ReadonlySet<string> | undefined;
+}): FieldConstraints | undefined;

package/dist/model/build/rule-checks.d.ts

@@ -1,5 +1,5 @@
 import { ModelProblem } from '../../errors.js';
-import { AbstractType, NodeType, RelationshipPropertiesType } from '../types.js';
+import { AbstractType, NodeType, RelationshipField, RelationshipPropertiesType } from '../types.js';
 /** Check an `@authorization` where against the model, at startup. */
 export declare function checkAuthorizationWhere(nodes: ReadonlyMap<string, NodeType>, props: ReadonlyMap<string, RelationshipPropertiesType>, node: NodeType, where: unknown, problems: ModelProblem[], jwtShape?: ReadonlyMap<string, string>, viewerNode?: NodeType): void;
 /**
@@ -15,6 +15,11 @@ export interface RuleEnds {
     edge: RelationshipPropertiesType | undefined;
 }
 export declare function checkRuleWhere(nodes: ReadonlyMap<string, NodeType>, props: ReadonlyMap<string, RelationshipPropertiesType>, node: NodeType | undefined, type: string, field: string | undefined, where: unknown, problems: ModelProblem[], jwtShape?: ReadonlyMap<string, string>, viewerNode?: NodeType, ends?: RuleEnds, nodeless?: string): void;
+/**
+ * Check the relationship rules of a field to an interface or union: each
+ * member's copy, with that member as the target.
+ */
+export declare function checkMemberRules(nodes: ReadonlyMap<string, NodeType>, props: ReadonlyMap<string, RelationshipPropertiesType>, source: NodeType, f: RelationshipField, problems: ModelProblem[], jwtShape?: ReadonlyMap<string, string>, viewerNode?: NodeType): void;
 export declare function checkNodeWhere(nodes: ReadonlyMap<string, NodeType>, props: ReadonlyMap<string, RelationshipPropertiesType>, node: NodeType, where: unknown, path: string, at: (message: string) => void): void;
 /**
  * Interfaces and unions of a model being built, by its node map: the rule

package/dist/model/build/trigger.d.ts

@@ -0,0 +1,9 @@
+import { GraphQLDirective, GraphQLObjectType } from 'graphql';
+import { ModelProblem } from '../../errors.js';
+import { NodeType, Trigger } from '../types.js';
+/** What a trigger statement may read as a `$parameter`. */
+export declare const TRIGGER_PARAMS: readonly string[];
+/** Every `@trigger` of a node type, in the order written, checked. */
+export declare function readTriggers(t: GraphQLObjectType, node: NodeType, d: (name: string) => GraphQLDirective, problems: ModelProblem[], 
+/** Whether the @jwt type has a @viewer claim (enables `$viewer`). */
+viewer: boolean): Trigger[];

package/dist/model/constraints.d.ts

@@ -0,0 +1,112 @@
+/** The rules of one field. Arguments map onto JSON Schema keywords. */
+export interface FieldConstraints {
+    length?: {
+        min?: number;
+        max?: number;
+        message?: string;
+    };
+    pattern?: {
+        source: string;
+        regex: RegExp;
+        message?: string;
+    };
+    format?: {
+        name: string;
+        message?: string;
+    };
+    range?: {
+        min?: number;
+        max?: number;
+        exclusiveMin?: number;
+        exclusiveMax?: number;
+        message?: string;
+    };
+    multipleOf?: {
+        value: number;
+        message?: string;
+    };
+    size?: {
+        min?: number;
+        max?: number;
+        unique: boolean;
+        message?: string;
+    };
+    /** `@normalize`: applied before the rules, and to what is stored. */
+    normalize?: {
+        trim: boolean;
+        unicode?: "NFC" | "NFD" | "NFKC" | "NFKD";
+        case?: "LOWER" | "UPPER";
+        emptyToNull: boolean;
+    };
+}
+/** One rule a value breaks. `rule` is the JSON Schema keyword. */
+export interface RuleFailure {
+    rule: string;
+    /** The rule's own numbers and names, for clients that localise. */
+    params: Record<string, unknown>;
+    message: string;
+    /** The item of a list field the failure is about. */
+    index?: number;
+}
+interface Format {
+    test: (value: string) => boolean;
+    message: string;
+}
+/**
+ * The formats `@format(as:)` knows. Named after JSON Schema's where the
+ * meaning matches, and differently where it does not (`url` is the WHATWG
+ * parser with an http/https allow-list, not RFC 3986; `e164` is a shape,
+ * not proof a number exists).
+ */
+export declare const FORMATS: Readonly<Record<string, Format>>;
+/**
+ * `value` as `@normalize` stores it: trimmed, normalised and case-mapped,
+ * in that order, and null for an empty string under `emptyToNull`. Items
+ * of a list are normalised one by one. Anything but a string is returned
+ * as it is.
+ */
+export declare function normalizeValue(c: FieldConstraints, value: unknown): unknown;
+/** Unicode code points in `s`. */
+export declare function codePoints(s: string): number;
+/**
+ * The rules `value` breaks, in declaration order; empty when it is valid.
+ * A list is checked as a list (`@size`) and then item by item.
+ */
+export declare function checkValue(c: FieldConstraints, value: unknown): RuleFailure[];
+/**
+ * Why `regex` is not safe to run on client input of up to `maxLength`
+ * characters, or undefined. JavaScript's engine backtracks, so a pattern
+ * such as `(a+)+` takes seconds on thirty characters. This runs the
+ * compiled pattern on inputs built to make it backtrack (a character it
+ * accepts, repeated, then one it rejects) and refuses a pattern that
+ * overruns the budget. A probe, not a proof: it finds the repetition
+ * mistakes people make, and `@length(max:)` bounds everything else.
+ */
+export declare function probePattern(regex: RegExp, source: string, maxLength: number): string | undefined;
+/**
+ * The rules as JSON Schema 2020-12 keywords, for one value (`item`) and
+ * for the list holding it (`list`). A pattern is exported anchored, since
+ * here it must match the whole value and in JSON Schema it need not. When
+ * a format and a @pattern both give an expression, they are joined with
+ * `allOf`.
+ */
+export declare function jsonSchemaKeywords(c: FieldConstraints | undefined): {
+    item: Record<string, unknown>;
+    list: Record<string, unknown>;
+};
+/**
+ * The rules in a sentence or two, for the description of a generated
+ * input field: what a client reads in GraphiQL and in the printed schema.
+ */
+export declare function describeConstraints(c: FieldConstraints | undefined, list: boolean): string | undefined;
+/**
+ * What changed between two versions of a field's rules, in the terms a
+ * schema diff needs: `tightened` refuses input the old rules accepted,
+ * `changed` may, `loosened` only accepts more.
+ */
+export declare function compareConstraints(before: FieldConstraints | undefined, after: FieldConstraints | undefined): {
+    tightened: string[];
+    changed: string[];
+    loosened: string[];
+};
+export {};

package/dist/model/desugar.d.ts

@@ -27,6 +27,13 @@ export interface DesugarContext {
     rules?: NamedRules;
     /** Named rules being expanded, to report a cycle with its chain. */
     expanding?: string[];
+    /**
+     * The member of an interface or union a relationship rule is expanded
+     * for, as its `target`. `isViewer` on a member that is not the viewer
+     * type is then never true, where elsewhere it is a mistake: the rule is
+     * written once for every member.
+     */
+    member?: NodeType;
     at: (message: string) => void;
 }
 /**

package/dist/model/directives.d.ts

@@ -1,3 +1,3 @@
-export declare const directiveTypeDefs = "\n  \"A node label set. Defaults to the type name.\"\n  directive @node(labels: [String!], plural: String) on OBJECT\n\n  \"Natural key: required, unique and immutable; the tie-breaker of every sort and the anchor of cursors, global ids, updates and deletes. With generate: true, creates fill it with a UUID when the input leaves it out.\"\n  directive @key(\n    generate: Boolean = false\n    \"VIEWER: a created key must start with the caller's @viewer claim and the separator (lou:tomorrowland).\"\n    scope: KeyScope\n    separator: String = \":\"\n  ) on FIELD_DEFINITION\n\n  enum KeyScope {\n    VIEWER\n  }\n\n  \"On an interface field: every implementation declares this relationship (with @relationship, possibly of different types or directions), so clients can select it on the interface.\"\n  directive @declareRelationship on FIELD_DEFINITION\n\n  \"Offer this field as a grouping key of <plural>Grouped (needs @query(aggregate: true)).\"\n  directive @groupBy on FIELD_DEFINITION\n\n  \"A field computed in JavaScript by the resolver passed in the resolvers option. requires is a selection on this type (for example name capacity) fetched in the same statement, so the resolver reads it from its source.\"\n  directive @customResolver(requires: String) on FIELD_DEFINITION\n\n  \"On a custom scalar: how its values are stored. Filters, sorts and indexes follow the storage type; the scalar is passed through unless the scalars option supplies an implementation.\"\n  directive @storedAs(type: StorageType!) on SCALAR\n\n  enum StorageType {\n    STRING\n    INT\n    FLOAT\n    BOOLEAN\n    DATETIME\n    DATE\n  }\n\n  \"A uniqueness constraint.\"\n  directive @unique on FIELD_DEFINITION\n\n  \"No two nodes of this type (among those matching where) share the values of fields: scalar fields, single relationships (by the target's @key) and at most one list relationship (by the set of target keys). Enforced by every generated mutation, for every caller.\"\n  directive @uniqueTogether(\n    fields: [String!]!\n    where: NodeWhere\n  ) repeatable on OBJECT\n\n  \"An explicit index. Usually unnecessary: inferred from @filterable and @sortable.\"\n  directive @index(kind: IndexKind!) on FIELD_DEFINITION\n\n  \"An edge. The target type is the field's type.\"\n  directive @relationship(\n    type: String!\n    direction: RelationshipDirection!\n    properties: String\n    \"UNDIRECTED reads follow the relationship both ways; writes use direction.\"\n    queryDirection: QueryDirection = DIRECTED\n    \"What deleting this node does to nodes reached through the field.\"\n    onDelete: OnDelete = DETACH\n    \"Which nested writes mutation inputs offer for the field.\"\n    nestedOperations: [NestedOperation!] = [\n      CREATE\n      CONNECT\n      DISCONNECT\n      UPDATE\n      DELETE\n    ]\n    \"false: no aggregate on the field's connection and no aggregate filter.\"\n    aggregate: Boolean = true\n  ) on FIELD_DEFINITION\n\n  \"UPDATE changes a connected node and its relationship properties in place; UPDATE_EDGE only the properties.\"\n  enum NestedOperation {\n    CREATE\n    CONNECT\n    DISCONNECT\n    UPDATE\n    UPDATE_EDGE\n    DELETE\n  }\n\n  enum QueryDirection {\n    DIRECTED\n    UNDIRECTED\n  }\n\n  \"DETACH removes the relationships; CASCADE deletes the related nodes too; RESTRICT refuses while any exist.\"\n  enum OnDelete {\n    DETACH\n    CASCADE\n    RESTRICT\n  }\n\n  \"Which mutations may set the field. @readonly is onCreate: false, onUpdate: false.\"\n  directive @settable(\n    onCreate: Boolean = true\n    onUpdate: Boolean = true\n  ) on FIELD_DEFINITION\n\n  \"Whether the field can be read (onRead: false makes it write-only) or aggregated.\"\n  directive @selectable(\n    onRead: Boolean = true\n    onAggregate: Boolean = true\n  ) on FIELD_DEFINITION\n\n  \"Set by a callback passed to LoraGraphQL({ callbacks }) on these operations. Client-settable only with an explicit @settable(onCreate: true) or (onUpdate: true) and a field-level @authorization(validate:) rule for that operation.\"\n  directive @populatedBy(\n    callback: String!\n    operations: [TimestampOperation!]! = [CREATE, UPDATE]\n  ) on FIELD_DEFINITION\n\n  \"The shape of the request's claims. Rules may only test declared claims.\"\n  directive @jwt on OBJECT\n\n  \"Where a declared claim lives in the token, e.g. app_metadata.roles.\"\n  directive @jwtClaim(path: String!) on FIELD_DEFINITION\n\n  \"The claim that identifies the caller: the node of `type` whose `field` (a @key or @unique field) equals it. Enables isViewer and viewer in rules.\"\n  directive @viewer(type: String!, field: String!) on FIELD_DEFINITION\n\n  \"Properties carried by a relationship type.\"\n  directive @relationshipProperties on OBJECT\n\n  \"API name differs from the stored property.\"\n  directive @alias(property: String!) on FIELD_DEFINITION\n\n  \"Stored, never exposed.\"\n  directive @private on FIELD_DEFINITION\n\n  \"Declared upper bound on a relationship's fan-out, used by cost estimates.\"\n  directive @cardinality(max: Int!) on FIELD_DEFINITION\n\n  \"The most items a list argument of a @cypher field takes; more is BAD_USER_INPUT before the statement runs. Without it, maxListArgument applies.\"\n  directive @size(max: Int!) on ARGUMENT_DEFINITION\n\n  \"Bounds of an Int or Float argument of a @cypher field (each item, for a list); a value outside them is BAD_USER_INPUT before the statement runs.\"\n  directive @range(min: Float, max: Float) on ARGUMENT_DEFINITION\n\n  \"Generated read operations for a node type. Reads are on by default.\"\n  directive @query(\n    read: Boolean = true\n    aggregate: Boolean = false\n  ) on OBJECT | INTERFACE | UNION\n\n  \"The plural of an interface or union, for its root field.\"\n  directive @plural(value: String!) on INTERFACE | UNION\n\n  \"Filter operators for a field. Without arguments: EQ and IN. On a relationship field: enables relationship filters.\"\n  directive @filterable(byValue: [FilterOperator!]) on FIELD_DEFINITION\n\n  \"Sort and keyset-paginate on this field.\"\n  directive @sortable on FIELD_DEFINITION\n\n  \"Page size bounds for lists of this type.\"\n  directive @limit(\n    default: Int\n    max: Int\n  ) on OBJECT | INTERFACE | UNION | FIELD_DEFINITION\n\n  \"Expose an opaque global id derived from this @key field.\"\n  directive @relayId on FIELD_DEFINITION\n\n  \"Full-text search over String fields: a FULLTEXT index and a search root field per entry.\"\n  directive @fulltext(indexes: [FulltextIndex!]!) on OBJECT\n\n  \"A vector embedding ([Float!]): a VECTOR index and a similarity root field.\"\n  directive @vector(\n    dimensions: Int!\n    similarity: VectorSimilarity = COSINE\n    queryName: String\n  ) on FIELD_DEFINITION\n\n  input FulltextIndex {\n    \"Index name. Default: <label>_search for the first, required after.\"\n    name: String\n    fields: [String!]!\n    analyzer: FulltextAnalyzer = STANDARD\n    \"Root field name. Default: search<Plural>, or search<Plural>By<Name>.\"\n    queryName: String\n  }\n\n  enum FulltextAnalyzer {\n    STANDARD\n    SIMPLE\n  }\n\n  enum VectorSimilarity {\n    COSINE\n    EUCLIDEAN\n  }\n\n  \"Generated subscriptions to changes made through the library. None without this directive.\"\n  directive @subscription(\n    operations: [MutationOperation!]! = [CREATE, UPDATE, DELETE]\n    \"Also send CONNECT and DISCONNECT events for the type's relationships.\"\n    relationships: Boolean = false\n    \"Send the stored values before an update or delete (one extra read per write).\"\n    previousState: Boolean = false\n  ) on OBJECT\n\n  \"Generated mutations for a node type. None without this directive.\"\n  directive @mutation(\n    operations: [MutationOperation!]! = [CREATE, UPDATE, DELETE]\n  ) on OBJECT\n\n  \"Value stored on create when the input leaves the field out.\"\n  directive @default(value: DefaultValue!) on FIELD_DEFINITION\n\n  \"Set to the current time by the listed operations. Client-settable only with an explicit @settable(onCreate: true) or (onUpdate: true) and a field-level @authorization(validate:) rule for that operation.\"\n  directive @timestamp(\n    operations: [TimestampOperation!]! = [CREATE, UPDATE]\n  ) on FIELD_DEFINITION\n\n  \"Readable but never client-settable.\"\n  directive @readonly on FIELD_DEFINITION\n\n  \"A field backed by a Cypher statement. `this` is the parent node; arguments are $parameters, $jwt holds the request's claims, and $viewer the caller's @viewer node key.\"\n  directive @cypher(statement: String!, columnName: String) on FIELD_DEFINITION\n\n  \"Require an authenticated request (a jwt in the context) for these operations.\"\n  directive @authentication(\n    operations: [AuthOperation!]! = [\n      READ\n      CREATE\n      UPDATE\n      DELETE\n      CREATE_RELATIONSHIP\n      DELETE_RELATIONSHIP\n      SUBSCRIBE\n    ]\n    \"Claims the request must also satisfy, such as a role in roles.\"\n    jwt: AuthorizationWhere\n  ) on OBJECT | FIELD_DEFINITION\n\n  \"Row-level rules over the node and the request's claims, compiled into the statements.\"\n  directive @authorization(\n    filter: [AuthorizationFilterRule!]\n    validate: [AuthorizationValidateRule!]\n    \"On a type: false keeps the schema's bypass (see @authorizationDefaults) from skipping this type's rules; true lets it skip them, as without the argument, and tells check() that was meant.\"\n    bypass: Boolean\n    \"On a @mutation type: operations deliberately open to every caller, so check() does not report them as unguarded.\"\n    public: [AuthOperation!]\n    \"On a scalar field: a row failing unless reads the field as value (null when left out) instead of failing the request.\"\n    mask: [AuthorizationMask!]\n  ) on OBJECT | FIELD_DEFINITION\n\n  \"Named rules over claims, usable in any rule as { rule: name }, on `extend schema`.\"\n  directive @authorizationRules(\n    rules: [AuthorizationRuleDefinition!]!\n  ) on SCHEMA\n\n  input AuthorizationRuleDefinition {\n    name: String!\n    where: AuthorizationWhere!\n  }\n\n  \"A named rule of this type, usable in its rules as { rule: name } and through a relationship to it as { rel: { rule: name } }.\"\n  directive @authorizationRule(\n    name: String!\n    where: AuthorizationWhere!\n  ) repeatable on OBJECT\n\n  \"Schema-wide authorization settings, on `extend schema`.\"\n  directive @authorizationDefaults(\n    \"A claims-only test (jwt, AND, OR, NOT): a request passing it skips every filter and validate rule (not @authentication).\"\n    bypass: AuthorizationWhere\n    \"The write rule of every @mutation type that declares no CREATE, UPDATE or DELETE rule of its own.\"\n    mutations: AuthorizationWhere\n    \"Default true: without a token every rule denies. false: a rule with a branch that reads no claims decides that branch for anonymous requests too; a rule that needs claims still asks for a token.\"\n    requireAuthentication: Boolean\n  ) on SCHEMA\n\n  input AuthorizationMask {\n    unless: AuthorizationWhere!\n    value: DefaultValue\n  }\n\n  input AuthorizationFilterRule {\n    operations: [AuthOperation!]! = [READ, UPDATE, DELETE]\n    where: AuthorizationWhere!\n  }\n\n  input AuthorizationValidateRule {\n    operations: [AuthOperation!]! = [READ, CREATE, UPDATE, DELETE]\n    when: [AuthorizationWhen!]! = [BEFORE, AFTER]\n    where: AuthorizationWhere!\n  }\n\n  enum MutationOperation {\n    CREATE\n    UPDATE\n    DELETE\n  }\n\n  enum TimestampOperation {\n    CREATE\n    UPDATE\n  }\n\n  enum AuthOperation {\n    READ\n    CREATE\n    UPDATE\n    DELETE\n    CREATE_RELATIONSHIP\n    DELETE_RELATIONSHIP\n    SUBSCRIBE\n    \"On a relationship field: creating one of its relationships (connect, nested create).\"\n    CONNECT\n    \"On a relationship field: removing one of its relationships (disconnect).\"\n    DISCONNECT\n    \"On a relationship field: setting properties on an existing relationship (edge update, re-connect).\"\n    UPDATE_EDGE\n    \"On a relationship field: reading, filtering, sorting or aggregating its properties.\"\n    READ_EDGE\n  }\n\n  enum AuthorizationWhen {\n    BEFORE\n    AFTER\n  }\n\n  \"Any literal.\"\n  scalar DefaultValue\n\n  \"{ node: <Type>Where-shaped filter, jwt: claim filter, AND, OR, NOT }. String values starting with $jwt. are replaced by claims.\"\n  scalar AuthorizationWhere\n\n  \"A <Type>Where-shaped filter over the type the directive is on.\"\n  scalar NodeWhere\n\n  enum IndexKind {\n    RANGE\n    TEXT\n    POINT\n  }\n\n  enum RelationshipDirection {\n    IN\n    OUT\n  }\n\n  enum FilterOperator {\n    EQ\n    IN\n    LT\n    LTE\n    GT\n    GTE\n    CONTAINS\n    STARTS_WITH\n    ENDS_WITH\n    WITHIN_BBOX\n    DISTANCE\n    INCLUDES\n    IS_NULL\n    CASE_INSENSITIVE\n  }\n\n  scalar BigInt\n  scalar Date\n  scalar Time\n  scalar LocalTime\n  scalar DateTime\n  scalar LocalDateTime\n  scalar Duration\n\n  type Point {\n    longitude: Float!\n    latitude: Float!\n    height: Float\n    srid: Int!\n    crs: String!\n  }\n\n  type CartesianPoint {\n    x: Float!\n    y: Float!\n    z: Float\n    srid: Int!\n    crs: String!\n  }\n";
+export declare const directiveTypeDefs = "\n  \"A node label set. Defaults to the type name.\"\n  directive @node(labels: [String!], plural: String) on OBJECT\n\n  \"Natural key: required, unique and immutable; the tie-breaker of every sort and the anchor of cursors, global ids, updates and deletes. With generate: true, creates fill it with a UUID when the input leaves it out.\"\n  directive @key(\n    generate: Boolean = false\n    \"VIEWER: a created key must start with the caller's @viewer claim and the separator (lou:tomorrowland).\"\n    scope: KeyScope\n    separator: String = \":\"\n  ) on FIELD_DEFINITION\n\n  enum KeyScope {\n    VIEWER\n  }\n\n  \"On an interface field: every implementation declares this relationship (with @relationship, possibly of different types or directions), so clients can select it on the interface.\"\n  directive @declareRelationship on FIELD_DEFINITION\n\n  \"Offer this field as a grouping key of <plural>Grouped (needs @query(aggregate: true)).\"\n  directive @groupBy on FIELD_DEFINITION\n\n  \"A field computed in JavaScript by the resolver passed in the resolvers option. requires is a selection on this type (for example name capacity) fetched in the same statement, so the resolver reads it from its source.\"\n  directive @customResolver(requires: String) on FIELD_DEFINITION\n\n  \"On a custom scalar: how its values are stored. Filters, sorts and indexes follow the storage type; the scalar is passed through unless the scalars option supplies an implementation.\"\n  directive @storedAs(type: StorageType!) on SCALAR\n\n  enum StorageType {\n    STRING\n    INT\n    FLOAT\n    BOOLEAN\n    DATETIME\n    DATE\n  }\n\n  \"A uniqueness constraint.\"\n  directive @unique on FIELD_DEFINITION\n\n  \"No two nodes of this type (among those matching where) share the values of fields: scalar fields, single relationships (by the target's @key) and at most one list relationship (by the set of target keys). Enforced by every generated mutation, for every caller.\"\n  directive @uniqueTogether(\n    fields: [String!]!\n    where: NodeWhere\n  ) repeatable on OBJECT\n\n  \"An explicit index. Usually unnecessary: inferred from @filterable and @sortable.\"\n  directive @index(kind: IndexKind!) on FIELD_DEFINITION\n\n  \"An edge. The target type is the field's type.\"\n  directive @relationship(\n    type: String!\n    direction: RelationshipDirection!\n    properties: String\n    \"UNDIRECTED reads follow the relationship both ways; writes use direction.\"\n    queryDirection: QueryDirection = DIRECTED\n    \"What deleting this node does to nodes reached through the field.\"\n    onDelete: OnDelete = DETACH\n    \"Which nested writes mutation inputs offer for the field.\"\n    nestedOperations: [NestedOperation!] = [\n      CREATE\n      CONNECT\n      DISCONNECT\n      UPDATE\n      DELETE\n    ]\n    \"false: no aggregate on the field's connection and no aggregate filter.\"\n    aggregate: Boolean = true\n  ) on FIELD_DEFINITION\n\n  \"UPDATE changes a connected node and its relationship properties in place; UPDATE_EDGE only the properties.\"\n  enum NestedOperation {\n    CREATE\n    CONNECT\n    DISCONNECT\n    UPDATE\n    UPDATE_EDGE\n    DELETE\n  }\n\n  enum QueryDirection {\n    DIRECTED\n    UNDIRECTED\n  }\n\n  \"DETACH removes the relationships; CASCADE deletes the related nodes too; RESTRICT refuses while any exist.\"\n  enum OnDelete {\n    DETACH\n    CASCADE\n    RESTRICT\n  }\n\n  \"Which mutations may set the field. @readonly is onCreate: false, onUpdate: false.\"\n  directive @settable(\n    onCreate: Boolean = true\n    onUpdate: Boolean = true\n  ) on FIELD_DEFINITION\n\n  \"Whether the field can be read (onRead: false makes it write-only) or aggregated.\"\n  directive @selectable(\n    onRead: Boolean = true\n    onAggregate: Boolean = true\n  ) on FIELD_DEFINITION\n\n  \"Set by a callback passed to LoraGraphQL({ callbacks }) on these operations. Client-settable only with an explicit @settable(onCreate: true) or (onUpdate: true) and a field-level @authorization(validate:) rule for that operation.\"\n  directive @populatedBy(\n    callback: String!\n    operations: [TimestampOperation!]! = [CREATE, UPDATE]\n  ) on FIELD_DEFINITION\n\n  \"The shape of the request's claims. Rules may only test declared claims.\"\n  directive @jwt on OBJECT\n\n  \"Where a declared claim lives in the token, e.g. app_metadata.roles.\"\n  directive @jwtClaim(path: String!) on FIELD_DEFINITION\n\n  \"The claim that identifies the caller: the node of `type` whose `field` (a @key or @unique field) equals it. Enables isViewer and viewer in rules.\"\n  directive @viewer(type: String!, field: String!) on FIELD_DEFINITION\n\n  \"Properties carried by a relationship type.\"\n  directive @relationshipProperties on OBJECT\n\n  \"API name differs from the stored property.\"\n  directive @alias(property: String!) on FIELD_DEFINITION\n\n  \"Stored, never exposed.\"\n  directive @private on FIELD_DEFINITION\n\n  \"Declared upper bound on a relationship's fan-out, used by cost estimates.\"\n  directive @cardinality(max: Int!) on FIELD_DEFINITION\n\n  \"How many items a list holds, with unique refusing the same item twice. On a list field: checked on every write. On a list argument of a @cypher field: checked before the statement runs (without max, maxListArgument applies).\"\n  directive @size(\n    min: Int\n    max: Int\n    unique: Boolean\n    \"Replaces the default message of this rule.\"\n    message: String\n  ) on ARGUMENT_DEFINITION | FIELD_DEFINITION\n\n  \"Bounds of a number: min and max are inclusive, exclusiveMin and exclusiveMax are not. On an Int, Float or BigInt field (each item, for a list): checked on every write. On an argument of a @cypher field: checked before the statement runs.\"\n  directive @range(\n    min: Float\n    max: Float\n    exclusiveMin: Float\n    exclusiveMax: Float\n    \"Replaces the default message of this rule.\"\n    message: String\n  ) on ARGUMENT_DEFINITION | FIELD_DEFINITION | SCALAR\n\n  \"How long a String or ID is, in Unicode code points (each item, for a list). On a custom scalar: for every field of that type.\"\n  directive @length(\n    min: Int\n    max: Int\n    \"Replaces the default message of this rule.\"\n    message: String\n  ) on FIELD_DEFINITION | SCALAR | ARGUMENT_DEFINITION\n\n  \"An expression the whole value of a String or ID must match (each item, for a list). Needs @length(max:) on the same field.\"\n  directive @pattern(\n    regex: String!\n    \"Replaces the default message of this rule.\"\n    message: String\n  ) on FIELD_DEFINITION | SCALAR | ARGUMENT_DEFINITION\n\n  \"A named shape a String or ID must have: email, email-strict, url, uuid, hostname, ipv4, ipv6, slug, hex-color, ulid or e164.\"\n  directive @format(\n    as: String!\n    \"Replaces the default message of this rule.\"\n    message: String\n  ) on FIELD_DEFINITION | SCALAR | ARGUMENT_DEFINITION\n\n  \"Changes a String or ID before it is validated and stored (each item, for a list): trim removes surrounding whitespace, unicode normalises, case maps, in that order; emptyToNull then stores no value for an empty string. Opt in: nothing is changed without it.\"\n  directive @normalize(\n    trim: Boolean\n    case: TextCase\n    unicode: UnicodeForm\n    emptyToNull: Boolean\n  ) on FIELD_DEFINITION | SCALAR\n\n  enum TextCase {\n    LOWER\n    UPPER\n  }\n\n  enum UnicodeForm {\n    NFC\n    NFD\n    NFKC\n    NFKD\n  }\n\n  \"An Int or Float must be a whole multiple of value (each item, for a list).\"\n  directive @multipleOf(\n    value: Float!\n    \"Replaces the default message of this rule.\"\n    message: String\n  ) on FIELD_DEFINITION | SCALAR | ARGUMENT_DEFINITION\n\n  \"Generated read operations for a node type. Reads are on by default.\"\n  directive @query(\n    read: Boolean = true\n    aggregate: Boolean = false\n  ) on OBJECT | INTERFACE | UNION\n\n  \"The plural of an interface or union, for its root field.\"\n  directive @plural(value: String!) on INTERFACE | UNION\n\n  \"Filter operators for a field. Without arguments: EQ and IN. On a relationship field: enables relationship filters.\"\n  directive @filterable(byValue: [FilterOperator!]) on FIELD_DEFINITION\n\n  \"Sort and keyset-paginate on this field.\"\n  directive @sortable on FIELD_DEFINITION\n\n  \"Page size bounds for lists of this type.\"\n  directive @limit(\n    default: Int\n    max: Int\n  ) on OBJECT | INTERFACE | UNION | FIELD_DEFINITION\n\n  \"Expose an opaque global id derived from this @key field.\"\n  directive @relayId on FIELD_DEFINITION\n\n  \"Full-text search over String fields: a FULLTEXT index and a search root field per entry.\"\n  directive @fulltext(indexes: [FulltextIndex!]!) on OBJECT\n\n  \"A vector embedding ([Float!]): a VECTOR index and a similarity root field.\"\n  directive @vector(\n    dimensions: Int!\n    similarity: VectorSimilarity = COSINE\n    queryName: String\n  ) on FIELD_DEFINITION\n\n  input FulltextIndex {\n    \"Index name. Default: <label>_search for the first, required after.\"\n    name: String\n    fields: [String!]!\n    analyzer: FulltextAnalyzer = STANDARD\n    \"Root field name. Default: search<Plural>, or search<Plural>By<Name>.\"\n    queryName: String\n  }\n\n  enum FulltextAnalyzer {\n    STANDARD\n    SIMPLE\n  }\n\n  enum VectorSimilarity {\n    COSINE\n    EUCLIDEAN\n  }\n\n  \"Generated subscriptions to changes made through the library. None without this directive.\"\n  directive @subscription(\n    operations: [MutationOperation!]! = [CREATE, UPDATE, DELETE]\n    \"Also send CONNECT and DISCONNECT events for the type's relationships.\"\n    relationships: Boolean = false\n    \"Send the stored values before an update or delete (one extra read per write).\"\n    previousState: Boolean = false\n  ) on OBJECT\n\n  \"A Cypher statement run inside the transaction of every generated mutation that creates, updates or deletes nodes of this type, before the commit. this is each written node; $jwt, $viewer and $operation are bound. Nodes it returns as created or updated join the mutation's write-set. Raw Cypher and @cypher mutations fire no trigger.\"\n  directive @trigger(\n    on: [MutationOperation!]!\n    statement: String!\n    \"Fire an UPDATE trigger only for nodes whose update set one of these fields.\"\n    fields: [String!]\n  ) repeatable on OBJECT\n\n  \"Nodes of this type are work for lora.worker(): each one created by a generated mutation or returned as created by a @trigger is handed to the worker's handler after the commit, at least once, with retries. The delivery state is stored on the node, outside the API.\"\n  directive @outbox on OBJECT\n\n  \"Generated mutations for a node type. None without this directive.\"\n  directive @mutation(\n    operations: [MutationOperation!]! = [CREATE, UPDATE, DELETE]\n  ) on OBJECT\n\n  \"Value stored on create when the input leaves the field out.\"\n  directive @default(value: DefaultValue!) on FIELD_DEFINITION\n\n  \"Set to the current time by the listed operations. Client-settable only with an explicit @settable(onCreate: true) or (onUpdate: true) and a field-level @authorization(validate:) rule for that operation.\"\n  directive @timestamp(\n    operations: [TimestampOperation!]! = [CREATE, UPDATE]\n  ) on FIELD_DEFINITION\n\n  \"Readable but never client-settable.\"\n  directive @readonly on FIELD_DEFINITION\n\n  \"A field backed by a Cypher statement. `this` is the parent node; arguments are $parameters, $jwt holds the request's claims, and $viewer the caller's @viewer node key.\"\n  directive @cypher(\n    statement: String!\n    columnName: String\n    \"Rows the statement examines each time it runs, charged against maxCost: once for a root field, once per parent node for a field of a type. Without it only the rows the field returns are charged.\"\n    cost: Int\n  ) on FIELD_DEFINITION\n\n  \"Require an authenticated request (a jwt in the context) for these operations.\"\n  directive @authentication(\n    operations: [AuthOperation!]! = [\n      READ\n      CREATE\n      UPDATE\n      DELETE\n      CREATE_RELATIONSHIP\n      DELETE_RELATIONSHIP\n      SUBSCRIBE\n    ]\n    \"Claims the request must also satisfy, such as a role in roles.\"\n    jwt: AuthorizationWhere\n  ) on OBJECT | FIELD_DEFINITION\n\n  \"Row-level rules over the node and the request's claims, compiled into the statements.\"\n  directive @authorization(\n    filter: [AuthorizationFilterRule!]\n    validate: [AuthorizationValidateRule!]\n    \"On a type: false keeps the schema's bypass (see @authorizationDefaults) from skipping this type's rules; true lets it skip them, as without the argument, and tells check() that was meant.\"\n    bypass: Boolean\n    \"On a @mutation type: operations deliberately open to every caller, so check() does not report them as unguarded.\"\n    public: [AuthOperation!]\n    \"On a scalar field: a row failing unless reads the field as value (null when left out) instead of failing the request.\"\n    mask: [AuthorizationMask!]\n  ) on OBJECT | FIELD_DEFINITION\n\n  \"Named rules over claims, usable in any rule as { rule: name }, on `extend schema`.\"\n  directive @authorizationRules(\n    rules: [AuthorizationRuleDefinition!]!\n  ) on SCHEMA\n\n  input AuthorizationRuleDefinition {\n    name: String!\n    where: AuthorizationWhere!\n  }\n\n  \"A named rule of this type, usable in its rules as { rule: name } and through a relationship to it as { rel: { rule: name } }.\"\n  directive @authorizationRule(\n    name: String!\n    where: AuthorizationWhere!\n  ) repeatable on OBJECT\n\n  \"Schema-wide authorization settings, on `extend schema`.\"\n  directive @authorizationDefaults(\n    \"A claims-only test (jwt, AND, OR, NOT): a request passing it skips every filter and validate rule (not @authentication).\"\n    bypass: AuthorizationWhere\n    \"The write rule of every @mutation type that declares no CREATE, UPDATE or DELETE rule of its own.\"\n    mutations: AuthorizationWhere\n    \"Default true: without a token every rule denies. false: a rule with a branch that reads no claims decides that branch for anonymous requests too; a rule that needs claims still asks for a token.\"\n    requireAuthentication: Boolean\n  ) on SCHEMA\n\n  input AuthorizationMask {\n    unless: AuthorizationWhere!\n    value: DefaultValue\n  }\n\n  input AuthorizationFilterRule {\n    operations: [AuthOperation!]! = [READ, UPDATE, DELETE]\n    where: AuthorizationWhere!\n  }\n\n  input AuthorizationValidateRule {\n    operations: [AuthOperation!]! = [READ, CREATE, UPDATE, DELETE]\n    when: [AuthorizationWhen!]! = [BEFORE, AFTER]\n    where: AuthorizationWhere!\n  }\n\n  enum MutationOperation {\n    CREATE\n    UPDATE\n    DELETE\n  }\n\n  enum TimestampOperation {\n    CREATE\n    UPDATE\n  }\n\n  enum AuthOperation {\n    READ\n    CREATE\n    UPDATE\n    DELETE\n    CREATE_RELATIONSHIP\n    DELETE_RELATIONSHIP\n    SUBSCRIBE\n    \"On a relationship field: creating one of its relationships (connect, nested create).\"\n    CONNECT\n    \"On a relationship field: removing one of its relationships (disconnect).\"\n    DISCONNECT\n    \"On a relationship field: setting properties on an existing relationship (edge update, re-connect).\"\n    UPDATE_EDGE\n    \"On a relationship field: reading, filtering, sorting or aggregating its properties.\"\n    READ_EDGE\n  }\n\n  enum AuthorizationWhen {\n    BEFORE\n    AFTER\n  }\n\n  \"Any literal.\"\n  scalar DefaultValue\n\n  \"{ node: <Type>Where-shaped filter, jwt: claim filter, AND, OR, NOT }. String values starting with $jwt. are replaced by claims.\"\n  scalar AuthorizationWhere\n\n  \"A <Type>Where-shaped filter over the type the directive is on.\"\n  scalar NodeWhere\n\n  enum IndexKind {\n    RANGE\n    TEXT\n    POINT\n  }\n\n  enum RelationshipDirection {\n    IN\n    OUT\n  }\n\n  enum FilterOperator {\n    EQ\n    IN\n    LT\n    LTE\n    GT\n    GTE\n    CONTAINS\n    STARTS_WITH\n    ENDS_WITH\n    WITHIN_BBOX\n    DISTANCE\n    INCLUDES\n    IS_NULL\n    CASE_INSENSITIVE\n  }\n\n  scalar BigInt\n  scalar Date\n  scalar Time\n  scalar LocalTime\n  scalar DateTime\n  scalar LocalDateTime\n  scalar Duration\n\n  type Point {\n    longitude: Float!\n    latitude: Float!\n    height: Float\n    srid: Int!\n    crs: String!\n  }\n\n  type CartesianPoint {\n    x: Float!\n    y: Float!\n    z: Float\n    srid: Int!\n    crs: String!\n  }\n";
 /** Names defined by the prelude; never treated as user types. */
 export declare const PRELUDE_TYPES: Set<string>;

package/dist/model/types.d.ts

@@ -1,9 +1,26 @@
+import { FieldConstraints } from './constraints.js';
 export type ScalarType = "String" | "ID" | "Int" | "Float" | "Boolean" | "BigInt" | "Date" | "Time" | "LocalTime" | "DateTime" | "LocalDateTime" | "Duration" | "Point" | "CartesianPoint"
 /** A user-declared enum, stored as its value name. */
  | "Enum";
 export type FilterOperator = "EQ" | "IN" | "LT" | "LTE" | "GT" | "GTE" | "CONTAINS" | "STARTS_WITH" | "ENDS_WITH" | "WITHIN_BBOX" | "DISTANCE" | "INCLUDES" | "IS_NULL" | "CASE_INSENSITIVE";
 export type IndexKind = "RANGE" | "TEXT" | "POINT";
 export type MutationOperation = "CREATE" | "UPDATE" | "DELETE";
+/**
+ * `@trigger(on:, statement:, fields:)`: a statement run for the nodes of
+ * a type that a generated mutation wrote, inside its transaction.
+ */
+export interface Trigger {
+    operations: ReadonlySet<MutationOperation>;
+    statement: string;
+    /** `UPDATE` fires only for nodes whose update set one of these. */
+    fields: readonly string[] | undefined;
+    /** The `$parameters` the statement uses: `jwt`, `viewer`, `operation`. */
+    params: readonly string[];
+    /** Whether the statement has a write clause. */
+    writes: boolean;
+    /** Whether it returns a `created` or `updated` column. */
+    reports: boolean;
+}
 export type AuthOperation = "READ" | MutationOperation | "CREATE_RELATIONSHIP" | "DELETE_RELATIONSHIP" | "SUBSCRIBE" | RelationshipOperation;
 /** Operations of rules on a relationship field, over `source`, `target`, `edge`. */
 export type RelationshipOperation = "CONNECT" | "DISCONNECT" | "UPDATE_EDGE" | "READ_EDGE";
@@ -53,6 +70,8 @@ export interface ScalarField extends FieldBase {
     defaultValue: {
         value: unknown;
     } | undefined;
+    /** `@length`, `@pattern`, `@format`, `@range`, `@multipleOf`, `@size`. */
+    constraints?: FieldConstraints | undefined;
     /** `@timestamp`: set to the current time by these operations. */
     timestamp: ReadonlySet<"CREATE" | "UPDATE"> | undefined;
     /** Never client-settable (`@readonly`, `@timestamp`, `@private`). */
@@ -110,6 +129,13 @@ export interface RelationshipField extends FieldBase {
     members: readonly string[];
     /** For a member copy of a polymorphic field: the field it came from. */
     via?: RelationshipField | undefined;
+    /**
+     * For a field to an interface or union with relationship rules (CONNECT,
+     * DISCONNECT, UPDATE_EDGE, READ_EDGE): the field's authorization per
+     * member, its rules expanded and checked with that member as their
+     * `target`. A member copy carries its own.
+     */
+    memberAuthorization?: ReadonlyMap<string, Authorization> | undefined;
     filterable: boolean;
     /** UNDIRECTED: reads follow the relationship both ways. */
     queryDirection: "DIRECTED" | "UNDIRECTED";
@@ -151,6 +177,8 @@ export interface CypherArgument {
         min?: number | undefined;
         max?: number | undefined;
     } | undefined;
+    /** The other value rules of the argument, as on a field. */
+    constraints?: FieldConstraints | undefined;
 }
 export interface CypherField extends FieldBase {
     kind: "cypher";
@@ -160,6 +188,8 @@ export interface CypherField extends FieldBase {
     statement: string;
     /** The result column holding the field's value. */
     columnName: string;
+    /** `@cypher(cost:)`: rows the statement examines per run; 0 without. */
+    cost: number;
     /** The field's type; `node` names a @node type when it returns nodes. */
     type: TypeShape;
     node: string | undefined;
@@ -281,6 +311,10 @@ export interface NodeType {
     interfaces: readonly string[];
     /** `@uniqueTogether`: combinations no two nodes of the type may share. */
     uniqueTogether: readonly UniqueTogether[];
+    /** `@outbox`: nodes of the type are work for `lora.worker()`. */
+    outbox: boolean;
+    /** `@trigger`: statements run in the transaction of a mutation, in SDL order. */
+    triggers: readonly Trigger[];
     description: string | undefined;
 }
 /**

package/dist/options.d.ts

@@ -1,9 +1,10 @@
 import { DocumentNode, GraphQLFieldResolver, GraphQLScalarType } from 'graphql';
 import { LoraDriver, Statement } from './driver.js';
-import { PopulatedByCallback } from './execute/mutate/env.js';
+import { PopulatedByCallback, TriggerFunctions } from './execute/mutate/env.js';
 import { LoraTransaction } from './execute/transaction.js';
 import { DocumentGuards } from './guards.js';
 import { ModelOptions } from './model/build/limits.js';
+import { TypeValidator } from './standard-schema.js';
 import { ObservabilityOptions } from './observe.js';
 export interface LoraGraphQLOptions extends ModelOptions, ObservabilityOptions {
     /** Annotated SDL: the graph model and the API in one document. */
@@ -61,6 +62,13 @@ export interface LoraGraphQLOptions extends ModelOptions, ObservabilityOptions {
      * request. Also the default `limit` of bulk updates and deletes.
      */
     maxBatch?: number;
+    /**
+     * Write transactions that may wait for the writer lock at once. One
+     * more fails at once with OVERLOADED (answer it with HTTP 503 and let
+     * the client back off) instead of joining a queue whose wait only
+     * grows: one writer runs at a time. Default 512; `Infinity` disables.
+     */
+    maxQueuedWrites?: number;
     /**
      * Most items a list argument of a `@cypher` field takes, unless its
      * `@size(max:)` says otherwise. More is BAD_USER_INPUT before the
@@ -85,6 +93,15 @@ export interface LoraGraphQLOptions extends ModelOptions, ObservabilityOptions {
      * may hold. More is BAD_USER_INPUT before anything runs. Default 10 000.
      */
     maxStringFilter?: number;
+    /**
+     * Most matches the `totalCount` of a root or search connection counts.
+     * A count stops there, so `totalCount` equal to this means "this many
+     * or more": enough for "1000+ results", at a bounded cost on a label
+     * of any size. Aggregates, and the `totalCount` of a connection nested
+     * under a node (bounded by that node's relationships), are not capped.
+     * Default: no cap.
+     */
+    maxTotalCount?: number;
     /**
      * Changes a `changes()` consumer or subscriber may fall behind before it
      * is ended with an error. Default 1000.
@@ -113,6 +130,50 @@ export interface LoraGraphQLOptions extends ModelOptions, ObservabilityOptions {
     subscriptionTimeoutMs?: number;
     /** Named callbacks for `@populatedBy(callback:)`. */
     callbacks?: Record<string, PopulatedByCallback>;
+    /**
+     * Send a mutation whose statements are all known up front (today: a
+     * create with the nodes it creates and connects, or an update of one
+     * node by key that sets or adjusts scalar fields and connects or
+     * creates related nodes, on a schema without
+     * triggers) as
+     * one call that begins, runs and commits, with its rule checks as
+     * `assert()` statements: the writer lock is then never held across a
+     * hop to the JavaScript thread. Needs a LoraDB with `assert()`; asked
+     * once, and without it every mutation keeps its transaction. Default
+     * true; false keeps every mutation in a transaction.
+     */
+    singleCallMutations?: boolean;
+    /**
+     * Trigger functions per node type: `{ Comment: { create, update,
+     * delete } }`. Each is called inside the transaction of a generated
+     * mutation that wrote nodes of the type, after the type's `@trigger`
+     * statements and before the commit, with the keys written, the
+     * write-set so far and the transaction. Throwing rolls the mutation
+     * back: a `GraphQLError` reaches the client as thrown, anything else
+     * is reported like a database error. Mutations a trigger runs in its
+     * transaction fire no trigger. A trigger holds the database's writer
+     * lock: keep network calls out of it.
+     */
+    triggers?: Record<string, TriggerFunctions>;
+    /**
+     * Most time one trigger function may take, in milliseconds; past it
+     * the mutation fails with TIMEOUT and rolls back. Default 1000; 0
+     * disables.
+     */
+    triggerTimeoutMs?: number;
+    /**
+     * A validator per node type, for what the validation directives do not
+     * say (a rule across two fields, a check against your own data): any
+     * Standard Schema object, which zod, valibot, arktype and yup schemas
+     * are. It is given each input of that type (a create's, an update's, a
+     * nested one's) after `@normalize` and after the field rules hold, and
+     * its issues are reported like theirs, in `extensions.violations` with
+     * `rule: "custom"`. What it returns is what is written, so its
+     * transforms apply. One schema validates every input; `{ create,
+     * update, upsert }` gives each kind its own, which matters because an
+     * update's input holds only the fields it sets.
+     */
+    validators?: Record<string, TypeValidator>;
     /**
      * Implementations of custom scalars declared with `@storedAs`, e.g. one
      * that validates e-mail addresses. Without one a scalar passes through.
@@ -190,8 +251,11 @@ export interface DatabaseErrorEvent {
     /** Correlation id, also in the client error's `extensions.id`. */
     id: string;
     /**
-     * The root field that failed, or `changeFeed` for a failure of the
-     * change feed (it reopens from where it stopped after a backoff).
+     * The root field that failed, `changeFeed` for a failure of the
+     * change feed (it reopens from where it stopped after a backoff), or
+     * `worker:<Type>` for a worker: a node given up after `maxAttempts`
+     * (with the handler's last error), or a failed read or write of its
+     * own.
      */
     field: string;
     /** The engine's message, which may name labels, properties and Cypher. */
@@ -231,6 +295,15 @@ export interface CheckOptions {
      * the GraphQL context to compile them under (e.g. `{ jwt }`, so rules
      * compile as they do for a signed-in caller). Without one, an operation
      * compiles as an anonymous request would.
+     *
+     * A query is compiled, not run. A mutation is run, because what it
+     * does depends on what it finds, in a transaction that is always rolled
+     * back: nothing is written and no change is reported, but its
+     * `@populatedBy` callbacks and trigger functions are called. Each
+     * statement it ran, a `@trigger`'s included, must start from keys: one
+     * that expands from a full scan is a finding. A mutation that fails is
+     * an error of the check, so give it variables that succeed against the
+     * database being checked.
      */
     operations?: Array<{
         name?: string;

package/dist/results.d.ts

@@ -1,3 +1,4 @@
+import { StoredViolation } from './analyze/stored.js';
 import { ExecutionResult } from 'graphql';
 import { CypherFinding } from './analyze/cypher-check.js';
 import { SchemaRequirement } from './analyze/indexes.js';
@@ -8,7 +9,11 @@ import { ModelWarning } from './model/types.js';
 export interface ExecutionTiming {
     /** The whole `execute()` call: parse, validation, execution. */
     totalMs: number;
-    /** Time spent running statements in LoraDB. */
+    /**
+     * Time spent running statements in LoraDB, summed over the root fields.
+     * A query's root fields run concurrently, so this can exceed `totalMs`;
+     * within one field it never exceeds that field's `totalMs`.
+     */
     databaseMs: number;
     /** Per root field, by response key (alias or name). */
     fields: Record<string, {
@@ -67,4 +72,10 @@ export interface CheckReport {
         operation: string;
         message: string;
     }>;
+    /**
+     * Stored values that break a validation rule of their field (not a
+     * failure): a rule added or tightened after they were written, or a
+     * value written with raw Cypher. At most 10 000 nodes per type are read.
+     */
+    stored: StoredViolation[];
 }

package/dist/schema/scalars.d.ts

@@ -1,4 +1,11 @@
-import { GraphQLScalarType } from 'graphql';
+import { GraphQLError, GraphQLScalarType, ValueNode } from 'graphql';
+/**
+ * A value this scalar refuses. Coded here, so that it is BAD_USER_INPUT
+ * whichever way it arrived: as a variable, as a literal in the document
+ * (which fails GraphQL validation, before any resolver), through
+ * `execute()` or through another server on `getSchema()`.
+ */
+export declare function badInput(message: string, nodes?: ValueNode): GraphQLError;
 export declare const GraphQLDate: GraphQLScalarType<unknown, unknown>;
 export declare const GraphQLTime: GraphQLScalarType<unknown, unknown>;
 export declare const GraphQLLocalTime: GraphQLScalarType<unknown, unknown>;

package/dist/standard-schema.d.ts

@@ -0,0 +1,37 @@
+/** A validator from any library that implements Standard Schema v1. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+export type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardIssue>;
+};
+export interface StandardIssue {
+    readonly message: string;
+    /** Keys into the value; a segment is a key, or an object holding one. */
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+}
+/**
+ * The validator of one node type's mutation inputs: one schema for every
+ * input, or one per kind of input. An update's input holds only the
+ * fields it sets, and an upsert's only the key for certain, so a schema
+ * that requires fields belongs under `create`.
+ */
+export type TypeValidator = StandardSchemaV1 | {
+    create?: StandardSchemaV1;
+    update?: StandardSchemaV1;
+    upsert?: StandardSchemaV1;
+};
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { graphql as g } from "graphql";
-import { a as h, l as b } from "./driver-DSnytFsU.js";
+import { a as h, l as b } from "./lora-graphql-D11QFUkf.js";
 async function T(l) {
   let u;
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loradb/lora-graphql",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Schema-first GraphQL for LoraDB: one annotated SDL becomes an executable, index-aware GraphQL API that compiles every operation to a single Cypher statement.",
   "license": "BUSL-1.1",
   "packageManager": "yarn@4.5.1",
@@ -65,7 +65,7 @@
     "bench:load": "node bench/load/main.mjs"
   },
   "peerDependencies": {
-    "@loradb/lora-node": "^0.24.0",
+    "@loradb/lora-node": "^0.25.0",
     "graphql": "^16.8.0 || ^17.0.0"
   },
   "devDependencies": {