@loradb/lora-graphql 0.24.1 → 0.25.0

package/dist/driver.d.ts

@@ -36,10 +36,22 @@ export interface RunOptions {
      * only stored properties. Cheap enough to run synchronously.
      */
     bounded?: boolean;
+    /**
+     * A mutation sent as one write batch: counted against
+     * `maxQueuedWrites`, as a transaction waiting for the lock is.
+     */
+    queued?: boolean;
 }
 /** An open interactive transaction: statements see earlier writes. */
 export interface DriverTransaction {
     execute(statement: Statement): Promise<QueryResult>;
+    /**
+     * Run several statements in one call, in order, each seeing the writes
+     * of those before it. The first failure rolls the transaction back and
+     * rejects with that statement's error. Optional: without it the
+     * statements run one `execute()` at a time.
+     */
+    executeMany?(statements: Statement[]): Promise<QueryResult[]>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
     /** False once committed, rolled back, or failed (a failure rolls back). */
@@ -75,6 +87,12 @@ export interface DriverChange {
     startId?: number;
     endId?: number;
     properties?: Record<string, unknown>;
+    /** For an update: the properties the transaction set and removed. */
+    setKeys?: string[];
+    removedKeys?: string[];
+    /** For a node update: the labels it added and removed. */
+    addedLabels?: string[];
+    removedLabels?: string[];
 }
 export interface DriverChangeBatch {
     lsn: number;
@@ -107,11 +125,21 @@ export interface LoraDatabaseLike {
     }): AsyncIterable<DriverChangeBatch> & {
         ready: Promise<void>;
     };
-    begin?(mode?: "read_write" | "read_only"): Promise<{
+    begin?(mode?: "read_write" | "read_only", options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<{
         execute(query: string, params?: never, options?: {
             timeoutMs?: number;
             signal?: AbortSignal;
         }): Promise<QueryResult>;
+        executeMany?(statements: Array<{
+            query: string;
+            params?: never;
+        }>, options?: {
+            timeoutMs?: number;
+            signal?: AbortSignal;
+        }): Promise<QueryResult[]>;
         commit(): Promise<void>;
         rollback(): Promise<void>;
         readonly isOpen: boolean;
@@ -126,3 +154,10 @@ export interface LoraDatabaseLike {
  * ```
  */
 export declare function loraDriver(db: LoraDatabaseLike): LoraDriver;
+/**
+ * `driver`, refusing a write transaction when `max` are already waiting
+ * for the writer lock: one writer runs at a time, so past saturation a
+ * queue only adds latency. `onFull` builds the error to throw. Reads are
+ * not counted: they do not wait for the lock.
+ */
+export declare function boundedWrites(driver: LoraDriver, max: number, onFull: (waiting: number) => Error): LoraDriver;

package/dist/errors.d.ts

@@ -20,7 +20,7 @@ export declare function formatProblem(p: ModelProblem): string;
  * a stable order. Use it to exhaustively map codes (HTTP status, client
  * copy) or to test membership at runtime.
  */
-export declare const LORA_GRAPHQL_ERROR_CODES: readonly ["BAD_USER_INPUT", "INVALID_CURSOR", "LIMIT_EXCEEDED", "COST_EXCEEDED", "TIMEOUT", "UNAUTHENTICATED", "FORBIDDEN", "NOT_FOUND", "CONSTRAINT_VIOLATION", "DATABASE_ERROR", "PERSISTED_QUERY_ONLY", "WRONG_OPERATION_TYPE"];
+export declare const LORA_GRAPHQL_ERROR_CODES: readonly ["BAD_USER_INPUT", "INVALID_CURSOR", "LIMIT_EXCEEDED", "COST_EXCEEDED", "OVERLOADED", "TIMEOUT", "UNAUTHENTICATED", "FORBIDDEN", "NOT_FOUND", "CONSTRAINT_VIOLATION", "DATABASE_ERROR", "PERSISTED_QUERY_ONLY", "WRONG_OPERATION_TYPE"];
 export type LoraGraphQLErrorCode = (typeof LORA_GRAPHQL_ERROR_CODES)[number];
 /**
  * Whether `err` is a request-time error raised by this library: a
@@ -37,6 +37,26 @@ export declare function isLoraGraphQLError(err: unknown): err is {
 };
 /** A request-time error with a stable `extensions.code`. */
 export declare function requestError(code: LoraGraphQLErrorCode, message: string, cause?: unknown, extensions?: Record<string, unknown>): GraphQLError;
+/** One value a mutation was given, or computed, that breaks a field's rule. */
+export interface Violation {
+    /** Where the value is in the mutation's arguments: keys and list indices. */
+    path: Array<string | number>;
+    /** The model field whose rule it is, as `Type.field`. */
+    coordinate: string;
+    /** The rule, named as its JSON Schema keyword (`maxLength`, `format`, ...). */
+    rule: string;
+    /** The rule's own numbers and names, enough to localise the message. */
+    params: Record<string, unknown>;
+    message: string;
+}
+/** The most violations one error lists; a batch can hold thousands. */
+export declare const MAX_VIOLATIONS = 100;
+/**
+ * Every value a mutation got wrong, in one error: `extensions.violations`
+ * lists each with its path, rule and parameters. The values themselves
+ * are never included: a rule is often on a password or an address.
+ */
+export declare function validationError(code: "BAD_USER_INPUT" | "CONSTRAINT_VIOLATION", violations: readonly Violation[], total?: number): GraphQLError;
 /**
  * One error per field path pattern: errors with the same message and code
  * at paths that differ only in list indices (a field every row of a list

package/dist/events/outbox.d.ts

@@ -0,0 +1,14 @@
+export declare const OUTBOX: {
+    /** `PENDING`, `CLAIMED`, `DONE` or `FAILED`. */
+    readonly state: "_outbox";
+    /** Handler calls that failed so far. */
+    readonly attempts: "_outboxAttempts";
+    /** Not before this time (epoch ms): the backoff after a failure. */
+    readonly at: "_outboxAt";
+    /** A claim is void past this time (epoch ms): its worker died. */
+    readonly lease: "_outboxLease";
+    /** The message of the last failure. */
+    readonly error: "_outboxError";
+};
+/** Whether `property` is one of the delivery-state properties. */
+export declare function isOutboxProperty(property: string): boolean;

package/dist/events/worker.d.ts

@@ -0,0 +1,67 @@
+import { LoraDriver } from '../driver.js';
+import { WriteChange } from '../execute/changes.js';
+import { NodeType } from '../model/types.js';
+import { DatabaseErrorEvent } from '../options.js';
+export interface WorkerOptions {
+    /**
+     * Called with the node's stored scalar fields, by field name, read
+     * without read rules. Resolving marks the node done; throwing (or
+     * rejecting) schedules it again, up to `maxAttempts`.
+     */
+    handle: (node: Record<string, unknown>, info: {
+        /** The node's @key value: the idempotency key of the work. */
+        key: unknown;
+        /** 1 for the first call, 2 for the first retry, ... */
+        attempt: number;
+        /** Aborted when the worker stops. */
+        signal: AbortSignal;
+    }) => unknown;
+    /** Handlers running at once. Default 4. */
+    concurrency?: number;
+    /**
+     * Calls before a node is given up as `FAILED` and reported to
+     * `onError`. A call that never returned (its worker died, or it
+     * outlived `leaseMs`) counts. Default 8.
+     */
+    maxAttempts?: number;
+    /**
+     * Milliseconds to wait before attempt `attempt + 1`. Default: one
+     * second doubling per attempt, at most five minutes.
+     */
+    backoffMs?: (attempt: number) => number;
+    /**
+     * How often the worker looks for pending nodes it was not told about:
+     * work left by a restart, retries that are due, claims whose worker
+     * died. Milliseconds, default 30 000.
+     */
+    sweepMs?: number;
+    /**
+     * How long a claim holds, in milliseconds. Past it another worker may
+     * take the node, and what the first handler then returns is ignored:
+     * give a handler a timeout shorter than this. Default 60 000.
+     */
+    leaseMs?: number;
+}
+export interface Worker {
+    /**
+     * Resolves once nothing is pending: after a look at the database, with
+     * no handler running and no node due. For tests and for shutdown.
+     */
+    idle(): Promise<void>;
+    /** Stop taking work; resolves when the running handlers have ended. */
+    stop(): Promise<void>;
+}
+export interface WorkerHost {
+    driver: LoraDriver;
+    node: NodeType;
+    timeoutMs: number;
+    /** Committed writes, from the change hub. */
+    listen: (listener: (change: WriteChange) => void) => () => unknown;
+    onError: ((event: DatabaseErrorEvent) => void) | undefined;
+}
+export declare class OutboxWorker implements Worker {
+    #private;
+    constructor(host: WorkerHost, options: WorkerOptions);
+    idle(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/execute/mutate/checks.d.ts

@@ -1,3 +1,4 @@
+import { NodeType } from '../../model/types.js';
 import { WritePlan } from './plan.js';
 import { Runner } from './runner.js';
 /**
@@ -5,6 +6,12 @@ import { Runner } from './runner.js';
  * the relationship was created from. Check every node that gained one.
  */
 export declare function checkCardinality(runner: Runner, plan: WritePlan): Promise<void>;
+/**
+ * {@link checkCardinality} for a single call: each check is a statement
+ * that fails on the first node holding more than one, naming the node and
+ * its counts in the message. Nothing is awaited.
+ */
+export declare function assertCardinality(runner: Runner, plan: WritePlan): void;
 /**
  * `@uniqueTogether`: after every write of the mutation, no two nodes of
  * a constrained type share a combination. Checks the nodes it created
@@ -14,6 +21,15 @@ export declare function checkCardinality(runner: Runner, plan: WritePlan): Promi
  * rule, so the bypass does not skip it.
  */
 export declare function checkUniqueTogether(runner: Runner): Promise<void>;
+/**
+ * `@uniqueTogether` for a single call, on the nodes with `keys` of each
+ * type: every check is issued before this first waits, as a statement
+ * that fails on the node sharing its combination.
+ */
+export declare function assertUniqueTogether(runner: Runner, touched: Array<{
+    node: NodeType;
+    keys: unknown[];
+}>): Promise<void>;
 /**
  * A required single relationship stays set: disconnecting from the other
  * side must not leave the owner without one.

package/dist/execute/mutate/env.d.ts

@@ -1,8 +1,10 @@
+import { TypeValidator } from '../../standard-schema.js';
 import { Statistics } from '../../analyze/statistics.js';
 import { SelectionContext } from '../../compile/selection.js';
 import { DriverTransaction, LoraDriver, QueryResult, Statement } from '../../driver.js';
 import { GraphModel, NodeType } from '../../model/types.js';
 import { WriteChange } from '../changes.js';
+import { LoraTransaction } from '../transaction.js';
 /** Computes a `@populatedBy` field. */
 export type PopulatedByCallback = (args: {
     operation: "CREATE" | "UPDATE";
@@ -15,6 +17,33 @@ export type PopulatedByCallback = (args: {
     /** The GraphQL context. */
     context: unknown;
 }) => unknown;
+/** What a JavaScript trigger is called with. */
+export interface TriggerEvent {
+    operation: "CREATE" | "UPDATE" | "DELETE";
+    /** The node type whose nodes were written. */
+    type: string;
+    /** Their @key values. For DELETE the nodes still exist. */
+    keys: unknown[];
+    /** The mutation's write-set so far. */
+    change: WriteChange;
+    /**
+     * The mutation's transaction: `execute()` runs Cypher in it, and
+     * `lora.execute({ context: { ...context, transaction } })` runs a
+     * generated mutation in it, whose writes join the write-set. The
+     * mutation commits it; throw to roll everything back.
+     */
+    transaction: LoraTransaction;
+    /** The GraphQL context of the request. */
+    context: unknown;
+}
+/** A trigger function; it may return a promise. Throwing vetoes the write. */
+export type TriggerFunction = (event: TriggerEvent) => unknown;
+/** The trigger functions of one node type. */
+export interface TriggerFunctions {
+    create?: TriggerFunction;
+    update?: TriggerFunction;
+    delete?: TriggerFunction;
+}
 export interface MutationEnv {
     model: GraphModel;
     driver: LoraDriver;
@@ -43,6 +72,27 @@ export interface MutationEnv {
     /** Statistics from `analyze()`, for filter costs. */
     statistics?: Statistics | undefined;
     callbacks: Readonly<Record<string, PopulatedByCallback>>;
+    /** The `singleCallMutations` option; false keeps every mutation in a transaction. */
+    singleCall?: boolean | undefined;
+    /** The `triggers` option: functions per node type and operation. */
+    triggers?: Readonly<Record<string, TriggerFunctions>> | undefined;
+    /** The `triggerTimeoutMs` option, defaulted. */
+    triggerTimeoutMs?: number | undefined;
+    /**
+     * The mutation runs inside a trigger's transaction: it fires no trigger
+     * itself, so what a trigger writes never cascades.
+     */
+    inTrigger?: boolean | undefined;
+    /**
+     * `@populatedBy` callbacks already started, by the input they compute
+     * for and the field's name: those of the mutation's own inputs start
+     * before the transaction opens, all at once, so they do not run under
+     * the writer lock one after another. Each is awaited where it would
+     * have been called, so a failure surfaces at the same point.
+     */
+    computed?: WeakMap<object, Map<string, Promise<unknown>>> | undefined;
+    /** The `validators` option: a Standard Schema per node type. */
+    validators?: Readonly<Record<string, TypeValidator>> | undefined;
     /**
      * A caller-owned transaction: run inside it and leave the commit to the
      * caller. A failed mutation rolls it back, so it is never half-applied.

package/dist/execute/mutate/errors.d.ts

@@ -1,5 +1,11 @@
 import { GraphModel, NodeType, RelationshipField } from '../../model/types.js';
 export declare function notConnected(owner: NodeType, rel: RelationshipField, target: NodeType, to: unknown): import('graphql').GraphQLError;
+/** The error of a connect whose targets are not there (or not visible). */
+export declare function noTarget(owner: NodeType, rel: RelationshipField, target: NodeType, missing: unknown[]): import('graphql').GraphQLError;
+/** The error of a relationship field's rules refusing `op`. */
+export declare function refusedRule(op: "CONNECT" | "DISCONNECT" | "UPDATE_EDGE", rel: RelationshipField): import('graphql').GraphQLError;
+/** The error of a single relationship field that would hold `count` nodes. */
+export declare function tooMany(field: RelationshipField, key: unknown, count: number, seen: number): import('graphql').GraphQLError;
 /** In place of the key of a node the caller cannot read, in messages. */
 export declare const HIDDEN: unique symbol;
 export declare function requiredMissing(owner: NodeType, field: RelationshipField, target: string, key: unknown): import('graphql').GraphQLError;

package/dist/execute/mutate/links.d.ts

@@ -0,0 +1,38 @@
+import { NodeType, RelationshipField } from '../../model/types.js';
+import { WritePlan } from './plan.js';
+import { Runner } from './runner.js';
+/**
+ * The links of a single call: what {@link applyLinks} does, with
+ * nothing awaited. The rules on both ends and on the relationship field
+ * are assertions, and so is every target being there: the link reports
+ * the rows it connected in the message of the assertion that fails
+ * when one is missing.
+ */
+export declare function linkInOne(runner: Runner, plan: WritePlan): void;
+/**
+ * Connect `plan`'s links in a transaction, a relationship field at a
+ * time: the rules on both ends, the MERGE, then the rules on what it
+ * created or found.
+ */
+export declare function applyLinks(runner: Runner, plan: WritePlan): Promise<void>;
+/**
+ * Rules on the relationship field (and on a field declaring the same
+ * relationship from the other side) for `op`, on each pair's
+ * relationship as it stands: after the write for CONNECT and
+ * UPDATE_EDGE, before it for DISCONNECT. FORBIDDEN when any fails; the
+ * mutation rolls back.
+ */
+export declare function checkRelationshipRules(runner: Runner, op: "CONNECT" | "DISCONNECT" | "UPDATE_EDGE", rel: RelationshipField, pairs: Array<{
+    from: unknown;
+    to: unknown;
+}>): Promise<void>;
+/** Whether either end has validate rules for `op` at `when`. */
+export declare function endRules(owner: NodeType, target: NodeType, op: "CREATE_RELATIONSHIP" | "DELETE_RELATIONSHIP", when: "BEFORE" | "AFTER"): boolean;
+/**
+ * Validate rules for connecting or disconnecting, on both ends of each
+ * pair: FORBIDDEN when either end fails them.
+ */
+export declare function checkEnds(runner: Runner, op: "CREATE_RELATIONSHIP" | "DELETE_RELATIONSHIP", owner: NodeType, target: NodeType, pairs: Array<{
+    from: unknown;
+    to: unknown;
+}>, when: "BEFORE" | "AFTER"): Promise<void>;

package/dist/execute/mutate/plan.d.ts

@@ -74,6 +74,11 @@ export declare class WritePlan {
     }>;
     /** `@populatedBy` callbacks for planned creates. */
     pending: Array<() => Promise<void>>;
+    /**
+     * The plan is an update's: a link may find its relationship there
+     * already, which a single call must then tell in the database.
+     */
+    reconnects: boolean;
     constructor(env: MutationEnv, ctx: CompileContext);
     get model(): GraphModel;
     /**

package/dist/execute/mutate/runner.d.ts

@@ -1,11 +1,13 @@
 import { SelectionSetNode } from 'graphql';
 import { CompileContext } from '../../compile/context.js';
-import { DriverTransaction } from '../../driver.js';
-import { NodeType, RelationshipField, ScalarField } from '../../model/types.js';
+import { DriverTransaction, QueryResult, Statement } from '../../driver.js';
+import { NodeType, ScalarField } from '../../model/types.js';
 import { RelationshipRef, WriteChange } from '../changes.js';
 import { MutationEnv, MutationInfo } from './env.js';
+import { Assertions } from './single-call.js';
 import { WritePlan, Input } from './plan.js';
 export declare class Runner {
+    #private;
     readonly env: MutationEnv;
     readonly tx: DriverTransaction;
     readonly change: WriteChange;
@@ -17,6 +19,12 @@ export declare class Runner {
         keys: unknown[];
         fields: Set<string>;
     }>;
+    /** Whether a trigger function was called: it may have closed the transaction. */
+    triggerFunctionRan: boolean;
+    /** Nodes a trigger added to the write-set: they fire no trigger. */
+    triggered: Set<string>;
+    /** The fields each update set, per type and key: `@trigger(fields:)`. */
+    updatedFields: Map<NodeType, Map<string, Set<string>>>;
     /**
      * A type this mutation creates under a key held by a node the caller
      * cannot read; see {@link Runner.moveHiddenKeys}.
@@ -30,12 +38,100 @@ export declare class Runner {
         node: NodeType;
         field: ScalarField;
     } | undefined;
+    /** What the assertions of a single call stand for. */
+    readonly assertions: Assertions;
     constructor(env: MutationEnv, tx: DriverTransaction, change: WriteChange);
+    /** Whether the mutation is one call that commits as it returns. */
+    get single(): boolean;
+    /** The mutation needs more than one round trip: open its transaction. */
+    open(): Promise<void>;
+    /**
+     * In a single call, what JavaScript would decide after the mutation's
+     * statements is their last statement instead: an assertion that no node
+     * sat under a key or a unique value this create moved aside. It is last,
+     * so any other error is still the one a free key gets.
+     */
+    assertNothingMoved(): void;
+    /**
+     * Put a statement together and issue it. A single call puts every
+     * statement together before the first is sent, where a transaction
+     * does so once the one before it answered. An error raised meanwhile (a
+     * rule the claims settle) must not outrank what an earlier statement
+     * raises in the database: it becomes a statement that fails with it, in
+     * its place. Before the links' first statement it is thrown, as a
+     * transaction throws it: nothing was sent yet there either.
+     */
+    inPlace(issue: () => void): void;
+    /**
+     * Run `statement` in the transaction. Statements issued in the same
+     * tick, without awaiting one before issuing the next, go to the
+     * database in one call (`executeMany`), in the order issued: one round
+     * trip under the writer lock instead of one each. When a statement of
+     * such a batch fails, every statement of the batch rejects with its
+     * error, so a batch holds writes whose results are not checked,
+     * followed by reads.
+     */
+    send(statement: Statement): Promise<QueryResult>;
+    /**
+     * Issue a write whose result nothing checks, and leave it for the next
+     * statements to share its round trip: it is sent with whatever is
+     * issued before the event loop turns. `settle()` awaits it.
+     */
+    later(statement: Statement): void;
+    /**
+     * Leave `pending` (a statement issued, with what follows from its
+     * rows) for `settle()` to await.
+     */
+    defer(pending: Promise<unknown>): void;
+    /** The links of a single call begin; see {@link Runner.inPlace}. */
+    linking(): void;
+    /** Wait for the writes issued with `later`; throws the first failure. */
+    settle(): Promise<void>;
+    /**
+     * `pending`, safe to leave unawaited, and the mutation abandoned the
+     * moment it fails: before a batch still waiting to be sent goes out.
+     */
+    watch<T>(pending: Promise<T>): Promise<T>;
+    /**
+     * The mutation failed: nothing queued is sent. A single call commits
+     * with its first batch, so a batch must not go out after the error that
+     * should have stopped it.
+     */
+    abandon(err: unknown): void;
     ctx(): CompileContext;
+    /**
+     * An update of one node by key as one statement, for a single call:
+     * the match under the caller's filter rules, the BEFORE rules, the
+     * write and the AFTER rules, each rule an assertion. Which nodes it
+     * touched is then decided in the database, not between two round
+     * trips. Returns nothing when the update is not that simple (it writes
+     * relationships, adjusts a field with a constraint, or cannot be
+     * prepared without knowing whether the node is there): the caller opens
+     * a transaction instead.
+     */
+    updateInOne(plan: WritePlan, node: NodeType, key: unknown, input: Input, adjust: Input | undefined, tail: () => void): Promise<{
+        done: Promise<unknown[]>;
+    } | undefined>;
+    /**
+     * The single call found no node to update and rolled back: nothing of
+     * what was planned happened.
+     */
+    nothingWritten(): void;
+    /**
+     * `send()` for a statement's rows. The promise is safe to leave
+     * unawaited: a batch fails as a whole, so when one statement of several
+     * issued together is refused, the others reject too, and whoever
+     * stopped at the first must not leave the rest unhandled.
+     */
     run(text: string, ctx: CompileContext): Promise<Array<Record<string, unknown>>>;
     plan(): WritePlan;
     /** Every planned write, in order, with the checks that follow them. */
-    apply(plan: WritePlan): Promise<void>;
+    /**
+     * `tail` is called once the plan's last statements are issued, without
+     * waiting for them: what it issues (the payload read, the caller's own
+     * checks) shares their round trip.
+     */
+    apply(plan: WritePlan, tail?: () => void): Promise<void>;
     /**
      * `maxBatch` over the whole mutation: nodes created and updated so far
      * plus those `plan` creates and updates (nested `update` entries
@@ -69,28 +165,6 @@ export declare class Runner {
     moveTakenUniques(plan: WritePlan): Promise<void>;
     applyCreates(plan: WritePlan): Promise<void>;
     applyDisconnects(plan: WritePlan): Promise<void>;
-    applyLinks(plan: WritePlan): Promise<void>;
-    /**
-     * Rules on the relationship field (and on a field declaring the same
-     * relationship from the other side) for `op`, on each pair's
-     * relationship as it stands: after the write for CONNECT and
-     * UPDATE_EDGE, before it for DISCONNECT. FORBIDDEN when any fails; the
-     * mutation rolls back.
-     */
-    checkRelationshipRules(op: "CONNECT" | "DISCONNECT" | "UPDATE_EDGE", rel: RelationshipField, pairs: Array<{
-        from: unknown;
-        to: unknown;
-    }>): Promise<void>;
-    /** Whether either end has validate rules for `op` at `when`. */
-    endRules(owner: NodeType, target: NodeType, op: "CREATE_RELATIONSHIP" | "DELETE_RELATIONSHIP", when: "BEFORE" | "AFTER"): boolean;
-    /**
-     * Validate rules for connecting or disconnecting, on both ends of each
-     * pair: FORBIDDEN when either end fails them.
-     */
-    checkEnds(op: "CREATE_RELATIONSHIP" | "DELETE_RELATIONSHIP", owner: NodeType, target: NodeType, pairs: Array<{
-        from: unknown;
-        to: unknown;
-    }>, when: "BEFORE" | "AFTER"): Promise<void>;
     /** `update: [{ key, edge }]`: properties of connected pairs, in place. */
     applyEdgeUpdates(plan: WritePlan): Promise<void>;
     /**
@@ -127,3 +201,5 @@ export declare class Runner {
      */
     resolveKeys(node: NodeType, where: Input, op: "UPDATE" | "DELETE", limit: number): Promise<unknown[]>;
 }
+/** `pending`, safe to leave unawaited when an earlier check throws. */
+export declare function held<T>(pending: Promise<T>): Promise<T>;

package/dist/execute/mutate/single-call.d.ts

@@ -0,0 +1,92 @@
+import { DriverTransaction, LoraDriver, QueryResult, RunOptions, Statement } from '../../driver.js';
+import { GraphModel } from '../../model/types.js';
+import { WritePlan } from './plan.js';
+/**
+ * A transaction that is one `driver.run()` call until `open()` makes it a
+ * real one. In its single form the first batch is the whole mutation: it
+ * is committed when the call returns, so `commit()` has nothing left to
+ * do, and a failure has already rolled everything back.
+ *
+ * With `single` false it is never one call, only late: the transaction
+ * begins with its first statement, so what a mutation works out before
+ * that (its plan, its `@populatedBy` callbacks) does not hold the lock.
+ */
+export declare class LazyTransaction implements DriverTransaction {
+    #private;
+    constructor(driver: LoraDriver, options: RunOptions, single?: boolean);
+    /**
+     * Whether the single call ran and committed: an error after that can
+     * no longer undo the write.
+     */
+    get committed(): boolean;
+    /** Whether the mutation is still one call. */
+    get single(): boolean;
+    /** The mutation needs more than one round trip: begin a transaction. */
+    open(): Promise<void>;
+    execute(statement: Statement): Promise<QueryResult>;
+    executeMany(statements: Statement[]): Promise<QueryResult[]>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    get isOpen(): boolean;
+}
+/**
+ * `err` without the position the binding appends to the error of a
+ * failing statement of a batch (`(statement 2 of 3)`): callers see the
+ * error a lone statement gives. An error whose message is read-only (the
+ * DOMException of an aborted request) is passed on as it is.
+ */
+export declare function withoutPosition(err: unknown): unknown;
+/**
+ * Whether the database has `assert()`: asked once per driver. Without it
+ * every mutation keeps its transaction and decides in JavaScript.
+ */
+export declare function supportsAssert(driver: LoraDriver): Promise<boolean>;
+/**
+ * Whether reading any node can be refused by a READ validate rule: a
+ * payload read would then need a decision after the write, which a single
+ * call cannot make.
+ */
+export declare function readCanBeRefused(model: GraphModel): boolean;
+/**
+ * What the guard of a single-call update that writes relationships stands
+ * for: the node is not there (or not the caller's to update), so the call
+ * rolled back and the mutation answers null, as a transaction would after
+ * finding nothing.
+ */
+export declare const NOT_THERE: unique symbol;
+/**
+ * Whether `plan`'s links can go out in a single call: when each is
+ * known to create its relationship. A transaction asks the database
+ * whether the pair was connected already, and applies other rules to a
+ * re-connect; here it must be certain beforehand. It is when one end is
+ * a node this plan creates (it has no relationships yet) and no two
+ * links name the same relationship (one from each side's field). An
+ * update's links ask the database instead (`plan.reconnects`). A
+ * property the rules refuse depends on what the link found, in
+ * JavaScript.
+ */
+export declare function linksInOne(plan: WritePlan): boolean;
+/** The message of an `assert()` that stands for a refused rule. */
+export declare function refusal(kind: "forbidden" | "hidden" | "taken", type: string, detail: string): string;
+/**
+ * The request error an assertion stood for, or `err` when it is not one
+ * of ours.
+ */
+export declare function refused(model: GraphModel, err: unknown): unknown;
+/**
+ * The assertions of one single call that stand for an error only this
+ * mutation can name (the row a check failed on, a target that is not
+ * there): each is numbered, and its number is its message.
+ */
+export declare class Assertions {
+    #private;
+    /**
+     * The message, a Cypher expression, of an assertion that stands for
+     * `error`: {@link Assertions.refusedBy} gives the error back. `detail`
+     * is an expression appended to it, for an error that names what the
+     * rows held.
+     */
+    failsAs(error: (detail: string) => unknown, detail?: string): string;
+    /** The error an assertion of {@link Assertions.failsAs} stood for, if `err` is one. */
+    refusedBy(err: unknown): unknown;
+}

package/dist/execute/mutate/triggers.d.ts

@@ -0,0 +1,21 @@
+import { CompileContext } from '../../compile/context.js';
+import { Statement } from '../../driver.js';
+import { MutationOperation, NodeType, Trigger } from '../../model/types.js';
+import { MutationEnv } from './env.js';
+import { Runner } from './runner.js';
+/** Whether the mutation may fire a trigger: a statement or a function. */
+export declare function hasTriggers(env: MutationEnv): boolean;
+/** Whether the mutation may call a trigger function. */
+export declare function hasTriggerFunctions(env: MutationEnv): boolean;
+/** The trigger statement for `keys`, with `this` bound to each node. */
+export declare function triggerStatement(ctx: CompileContext, node: NodeType, trigger: Trigger, operation: MutationOperation, keys: unknown[]): Statement;
+/**
+ * Run the CREATE and UPDATE triggers for what the mutation wrote so far.
+ * A node the mutation created and then updated fires CREATE only.
+ */
+export declare function runWriteTriggers(runner: Runner): Promise<void>;
+/** Run the DELETE triggers of `doomed`, while the nodes still exist. */
+export declare function runDeleteTriggers(runner: Runner, doomed: ReadonlyArray<{
+    node: NodeType;
+    keys: unknown[];
+}>): Promise<void>;

package/dist/execute/mutate/unique-together.d.ts

@@ -14,5 +14,9 @@ export declare function checkUniqueTogetherOf(env: MutationEnv, tx: DriverTransa
  * compares it with the nodes that share its first relationship end (or,
  * with scalars only, its first scalar's value) — never a scan of the type.
  * Without `keys`, every node of the type is compared (a scan).
+ *
+ * With `failing`, the statement fails instead of returning that node:
+ * `failing` gives the assertion's message, from an expression for the
+ * node's place in `keys`.
  */
-export declare function uniqueTogetherStatement(ctx: CompileContext, model: GraphModel, node: NodeType, u: UniqueTogether, keys: unknown[] | undefined): string;
+export declare function uniqueTogetherStatement(ctx: CompileContext, model: GraphModel, node: NodeType, u: UniqueTogether, keys: unknown[] | undefined, failing?: (index: string) => string): string;

package/dist/execute/mutate/validate.d.ts

@@ -0,0 +1,11 @@
+import { GraphModel, NodeType } from '../../model/types.js';
+import { MutationKind } from '../../schema/mutations.js';
+import { TypeValidator } from '../../standard-schema.js';
+export type Validators = Readonly<Record<string, TypeValidator>>;
+/**
+ * Refuse a mutation whose input breaks a field's rule or its type's
+ * validator, with every violation in one `BAD_USER_INPUT`. Values
+ * computed during the write (an `adjust`, a `@populatedBy` callback) are
+ * checked where they appear.
+ */
+export declare function validateInput(model: GraphModel, validators: Validators, op: MutationKind, node: NodeType, args: Record<string, unknown>): Promise<void>;