@loradb/lora-graphql 0.24.0 → 0.25.0

package/README.md

@@ -65,6 +65,7 @@ const yoga = createYoga({
 - [The smart layer](#the-smart-layer)
 - [Change tracking](#change-tracking)
 - [Subscriptions](#subscriptions)
+- [Triggers and workers](#triggers-and-workers)
 - [Transactions](#transactions)
 - [CLI](#cli)
 - [Drivers, limits and errors](#drivers-limits-and-errors)
@@ -97,6 +98,13 @@ Relationship fields take `where`, `sort` and `limit`; list relationships
 also get `…Connection`, whose edges carry the relationship properties and
 filter on them (`where: { node, edge }`).
 
+`@query(aggregate: true)` on a type also gives every relationship
+connection that leads to it types of its own (`CityVenuesConnection` in
+place of `VenueConnection`), since its `aggregate` covers that
+relationship: turning it on renames types in the schema. A count does not
+need it: `{ venuesConnection { totalCount } }` selects no page and reads
+none.
+
 The surface is restrictive: a field is filterable only with `@filterable`,
 and only by the operators listed; sortable only with `@sortable`;
 `printPublicSchema()` prints exactly what clients see, with no directives.
@@ -157,8 +165,12 @@ API:
 | `@sortable`                                           | field                                        | Sort and paginate by this field (on a relationship property: `sort: [{ edge: { ... } }]`)                     |
 | `@groupBy`                                            | field                                        | A grouping key of `<plural>Grouped(by:)` (needs `@query(aggregate: true)`)                                    |
 | `@limit(default:, max:)`                              | type, interface, union, list relationship    | Page size bounds                                                                                              |
-| `@size(max:)`                                         | list argument of a `@cypher` field           | The most items it takes (default `maxListArgument`)                                                           |
-| `@range(min:, max:)`                                  | Int / Float argument of a `@cypher` field    | Bounds of its value (each item of a list); outside is `BAD_USER_INPUT`                                        |
+| `@length(min:, max:)`                                 | String / ID field                            | Its length in code points (each item of a list)                                                               |
+| `@pattern(regex:)`                                    | String / ID field                            | An expression the whole value must match; needs `@length(max:)`                                               |
+| `@format(as:)`                                        | String / ID field                            | `email`, `email-strict`, `url`, `uuid`, `hostname`, `ipv4`, `ipv6`, `slug`, `hex-color`, `ulid`, `e164`       |
+| `@range(min:, max:, exclusiveMin:, exclusiveMax:)`    | number field; argument of a `@cypher` field  | Bounds of its value (each item of a list); on an argument, `min` and `max`                                    |
+| `@multipleOf(value:)`                                 | Int / Float field                            | A whole multiple of `value`                                                                                   |
+| `@size(min:, max:, unique:)`                          | list field; list argument of `@cypher`       | How many items it holds; on an argument, `max` (default `maxListArgument`)                                    |
 | `@relayId`                                            | `@key` field                                 | Adds a global `id` and the `Node` interface                                                                   |
 | `@authentication(operations:, jwt:)`                  | type, field                                  | Needs an authenticated request, whose claims satisfy `jwt`                                                    |
 | `@authorization(filter:, validate:)`                  | type (filter and validate), field (validate) | Row-level rules, compiled into statements                                                                     |
@@ -178,6 +190,29 @@ string), `Date`, `Time`, `LocalTime`, `DateTime`, `LocalDateTime`,
 `Duration` (ISO-8601 strings), `Point` and `CartesianPoint` (objects; set with
 `PointInput` / `CartesianPointInput`), and non-null lists of these.
 
+The six rows from `@length` to `@size` are validation rules. On a field
+they are checked wherever the field is set (create, update, upsert, nested
+creates, relationship properties), in JavaScript before the transaction
+opens, and a mutation that breaks any is `BAD_USER_INPUT` with every
+violation in `extensions.violations` (`path`, `coordinate`, `rule`,
+`params`, `message`; never the value). `null` and absent values pass; a
+pattern must match the whole value; values computed during the write (an
+`adjust`, a `@populatedBy` result) are checked in the transaction and fail
+with `CONSTRAINT_VIOLATION`. Raw Cypher and `@cypher` mutations are not
+checked. Each takes `message:`. `@normalize(trim:, case:, unicode:,
+emptyToNull:)` changes a string before it is validated and stored (it is
+what makes a `@unique` email treat `Ada@X.com ` and `ada@x.com` as one
+value). The rules and `@normalize` may sit on a custom scalar (`scalar
+Email @storedAs(type: STRING) @format(as: "email")`), for every field of
+that type. For a rule across fields, the `validators` option takes a
+Standard Schema validator per node type (zod, valibot, arktype, yup),
+run on each input after the field rules. The same directives go on
+`@cypher` arguments. Each input field says its rules in its description,
+`lora.inputSchemas()` (CLI: `json-schema`) exports them as JSON Schema
+for clients, `diff` reports a tightened rule as breaking, and `check`
+lists stored values that no longer pass. See the
+[directive reference](https://loradb.com/docs/graphql/directives#validation).
+
 ## Queries
 
 ```graphql
@@ -809,12 +844,18 @@ type Post
 - **Anonymous callers.** Without a token every rule denies, unless the
   schema says `@authorizationDefaults(requireAuthentication: false)`. Then
   a rule with a branch that reads no claims decides that branch for
-  anonymous callers too (the published posts above), while a rule that
-  needs claims still asks for a token: `UNAUTHENTICATED`, not `FORBIDDEN`.
-  It is one setting for the schema; a rule has no such field. To keep a
-  claim-free branch for signed-in callers, test a claim beside it
+  anonymous callers too (the published posts above). A rule that needs
+  claims still denies them, and how depends on the kind of rule: a
+  validate rule asks for a token (`UNAUTHENTICATED`, not `FORBIDDEN`),
+  while a READ filter admits no row, so a signed-out caller reads an
+  empty list and the access matrix calls it `denied`.
+  It is one setting for the schema; a rule has no such field, and it
+  reaches every rule: a CREATE, UPDATE, DELETE or CONNECT rule that
+  reads no claims decides for signed-out callers as well. `check` names
+  each such write rule that no `@authentication` covers. To keep a
+  claim-free rule or branch for signed-in callers, test a claim beside it
   (`{ jwt: { sub: { exists: true } } }`, as the tenant rule above does),
-  or put `@authentication` on the type.
+  or put `@authentication` on the type or the relationship field.
 - **The caller's own node.** Mark the claim that identifies the caller
   with `@viewer(type: "Person", field: "subject")` (the field is `@key` or
   `@unique`), so the key can stay a slug while the subject is an identity
@@ -1363,6 +1404,85 @@ replay earlier writes. `onWrite` still reports
 this instance's mutations, and `previousState` needs them: the feed carries
 the state after the write. Call `lora.close()` to stop the feed.
 
+## Triggers and workers
+
+Three things react to a write, at three moments:
+
+- a **trigger** runs inside the mutation's transaction, before the
+  commit: derived data that must never be out of step, or a refusal;
+- an **event** (`onWrite`, `changes()`, a subscription) reports what
+  committed;
+- a **worker** delivers what a transaction cannot hold (a push, an
+  e-mail, a webhook) after the commit, with retries.
+
+```graphql
+type Comment
+  @node
+  @mutation
+  @authentication
+  @trigger(
+    on: [CREATE]
+    statement: """
+    MATCH (this)-[:ON]->(post:Post)<-[:WROTE]-(author:Person)
+    CREATE (author)<-[:FOR]-(n:Notification {
+      key: 'comment:' + this.key, text: 'New comment on ' + post.title
+    })
+    RETURN n AS created
+    """
+  ) {
+  key: String! @key
+  text: String!
+  post: Post! @relationship(type: "ON", direction: OUT)
+}
+
+type Notification @node @outbox @subscription(operations: [CREATE]) {
+  key: String! @key
+  text: String!
+}
+```
+
+```ts
+const lora = new LoraGraphQL({
+  typeDefs,
+  driver: loraDriver(db),
+  // What Cypher cannot say; throwing rolls the mutation back.
+  triggers: {
+    Comment: {
+      create: async ({ keys, transaction }) => {
+        /* transaction.execute(cypher, params) */
+      },
+    },
+  },
+});
+
+// After the commit, at least once, with retries: make it idempotent.
+lora.worker("Notification", {
+  handle: async (notification, { key, attempt, signal }) => {
+    await push.send(key, notification.text, { signal });
+  },
+});
+```
+
+- A `@trigger` statement runs once per mutation with `this` bound to
+  every node of the type the mutation wrote; `$jwt`, `$viewer` and
+  `$operation` are bound. `fields:` narrows an `UPDATE` trigger to
+  updates that named one of them.
+- Nodes a statement returns as `created` or `updated` join the
+  mutation's write-set, so `onWrite` and subscriptions see them without
+  `changeFeed`.
+- Triggers run only for a write every rule has passed, and what a
+  trigger writes fires no trigger.
+- **Only generated mutations fire triggers.** Raw Cypher and `@cypher`
+  mutations fire none.
+- A trigger function holds the writer lock, bounded by
+  `triggerTimeoutMs` (default 1000). Network calls belong in a worker.
+- `@outbox` makes each node of a type work for `lora.worker()`. The
+  delivery state lives on the node, outside the API, so the work is as
+  durable as the data and is found again after a restart.
+
+The full guide, with a tested example and every option, is on the
+[site](https://loradb.com/docs/graphql/triggers).
+
 ## Transactions
 
 ```ts
@@ -1445,18 +1565,29 @@ the rules test, such as `roles:admin`), with the verdict (`allowed`,
 rules that decide it. When rules name the caller's node (`isViewer`),
 `viewer` is the caller on nodes that are theirs: every rule part that
 only names them passes, so it shows the most a related caller gets,
-where `authenticated` shows what any signed-in caller gets. A
+where `authenticated` shows what any signed-in caller gets. A part under
+`NOT` stays as written and is decided per row, so `viewer` never reads
+below `authenticated`. A relationship field has a CONNECT row when a
+rule or `@authentication(operations: [CREATE_RELATIONSHIP])` guards it,
+and a DISCONNECT row for a rule or `DELETE_RELATIONSHIP`. A
 `@key(scope: VIEWER)` type's CREATE reads
 `unauthenticated` for anonymous callers and `validated` by `key scope`
 for the rest.
 
-`lora.operationAccess(document | persistedId, operationName?)` answers
-the same question for one operation: each root field (fragments
+`lora.operationAccess(document | persistedId, operationName?, variables?)`
+answers the same question for one operation: each root field (fragments
 followed) with its type, the operations it needs (an upsert needs
 `CREATE` and `UPDATE`) and the verdict per caller, plus the most
 restrictive verdict per caller over all root fields. A field over
 several types (`node`, a union) reports the most restrictive member.
-Root fields only: nested selections answer to their own types' rules.
+A mutation's inputs are read for what they write through relationship
+fields: a nested connect or create counts as that field's CONNECT (and
+the target's CREATE), a disconnect or nested delete as its DISCONNECT, an
+`update: { edge }` as UPDATE_EDGE, each named in `by`
+(`Room.chan CONNECT: @authentication`). Pass `variables` for inputs the
+document takes as variables; a variable without a value is not read and
+is listed in the field's `unresolved`. Selections below a root field
+answer to their own types' READ rules.
 To keep admin-only operations out of client bundles:
 
 ````ts
@@ -1470,9 +1601,15 @@ order is stable, so a snapshot in CI turns access changes into diffs.
 `check` lints authorization too:
 
 - a filter rule every signed-in caller passes;
-- a rule with a branch that needs no claims, in a schema that leaves
+- a rule that needs no claims, as a whole or in one `OR` branch, on a
+  type or a field, in a schema that leaves
   `@authorizationDefaults(requireAuthentication:)` unset: anonymous
-  callers are refused that branch by default, so say which was meant;
+  callers are refused it by default, so say which was meant;
+- once that setting is `false`, each write rule (CREATE, UPDATE, DELETE,
+  CONNECT, DISCONNECT, UPDATE_EDGE) a signed-out caller can pass and no
+  `@authentication` covers. READ rules and operations the type lists in
+  `public` are left alone: those are what the setting and the list are
+  for;
 - field rules the schema's bypass skips, on a type that says neither
   `@authorization(bypass: false)` nor `bypass: true`, and one line naming
   every type with rules the bypass reaches that way (plus relationship
@@ -1585,37 +1722,43 @@ transaction. Mutations need interactive transactions, which only the Node
 binding has, so the WASM binding serves reads.
 `explain()`, and so plan checks, need the Node binding too.
 
-| Option                       | Default       | Meaning                                             |
-| ---------------------------- | ------------- | --------------------------------------------------- |
-| `timeoutMs`                  | 10 000        | Per statement and lock wait; a `signal` cancels     |
-| `operationTimeoutMs`         | 2 × timeout   | All root fields of one query; then `TIMEOUT`        |
-| `maxConcurrentStatements`    | 2             | Statements one operation runs at once               |
-| `maxCost`                    | 50 000        | Estimated rows per operation                        |
-| `maxBatch`                   | 1000          | Nodes written per mutation; bulk `limit` by default |
-| `compileCacheBytes`          | 64 MiB        | Compile cache and document cache, each              |
-| `maxQueuedChanges`           | 1000          | How far a change consumer may fall behind           |
-| `maxSubscriptions`           | 100           | Live subscriptions per `subscriptionScope`          |
-| `subscriptionScope`          | the context   | What `maxSubscriptions` counts per                  |
-| `maxSubscriptionFilterDepth` | 1             | Relationship filter nesting in a subscription where |
-| `subscriptionTimeoutMs`      | 2000          | Per statement checking a change for a subscriber    |
-| `defaultLimit` / `maxLimit`  | 25 / 100      | Global page sizes; `@limit` may only lower `max`    |
-| `callbacks`                  |               | Named callbacks for `@populatedBy`                  |
-| `jwt`                        | `context.jwt` | Where the claims are                                |
-| `onStatement`                |               | Observe every statement                             |
-| `cursorSecret`               |               | Sign cursors; reject unsigned or forged ones        |
-| `maskErrors`                 | production    | Clients get `DATABASE_ERROR` and an `id` only       |
-| `onError`                    |               | Receives each database error's detail and `id`      |
-| `guards`                     | see below     | Document limits; `false` turns them off             |
-| `persistedOnly`              | false         | `execute()`, `subscribe()` run persisted ops only   |
-| `budget`                     |               | Cost limit per request, from the context            |
-| `onCost`                     |               | Each root field's estimate, total and limit         |
-| `onStatementEnd`             |               | Duration, rows and error of every statement call    |
-| `timing`                     | false         | `extensions.timing` in `execute()` results          |
-| `tracer` / `traceStatements` |               | OpenTelemetry-style spans; Cypher text on request   |
-| `metrics`                    |               | Counters and histograms (see below)                 |
+| Option                       | Default       | Meaning                                                  |
+| ---------------------------- | ------------- | -------------------------------------------------------- |
+| `timeoutMs`                  | 10 000        | Per statement and lock wait; a `signal` cancels          |
+| `operationTimeoutMs`         | 2 × timeout   | All root fields of one query; then `TIMEOUT`             |
+| `maxConcurrentStatements`    | 2             | Statements one operation runs at once                    |
+| `maxCost`                    | 50 000        | Estimated rows per operation                             |
+| `maxBatch`                   | 1000          | Nodes written per mutation; bulk `limit` by default      |
+| `compileCacheBytes`          | 64 MiB        | Compile cache and document cache, each                   |
+| `maxQueuedChanges`           | 1000          | How far a change consumer may fall behind                |
+| `maxSubscriptions`           | 100           | Live subscriptions per `subscriptionScope`               |
+| `maxQueuedWrites`            | 512           | Writes waiting for the writer lock; more is `OVERLOADED` |
+| `maxTotalCount`              | none          | Where a root connection's `totalCount` stops counting    |
+| `triggerTimeoutMs`           | 1000          | Per trigger function; past it the mutation fails         |
+| `singleCallMutations`        | true          | A create is one call that begins, runs, commits          |
+| `subscriptionScope`          | the context   | What `maxSubscriptions` counts per                       |
+| `maxSubscriptionFilterDepth` | 1             | Relationship filter nesting in a subscription where      |
+| `subscriptionTimeoutMs`      | 2000          | Per statement checking a change for a subscriber         |
+| `defaultLimit` / `maxLimit`  | 25 / 100      | Global page sizes; `@limit` may only lower `max`         |
+| `callbacks`                  |               | Named callbacks for `@populatedBy`                       |
+| `jwt`                        | `context.jwt` | Where the claims are                                     |
+| `onStatement`                |               | Observe every statement                                  |
+| `cursorSecret`               |               | Sign cursors; reject unsigned or forged ones             |
+| `maskErrors`                 | production    | Clients get `DATABASE_ERROR` and an `id` only            |
+| `onError`                    |               | Receives each database error's detail and `id`           |
+| `guards`                     | see below     | Document limits; `false` turns them off                  |
+| `persistedOnly`              | false         | `execute()`, `subscribe()` run persisted ops only        |
+| `budget`                     |               | Cost limit per request, from the context                 |
+| `onCost`                     |               | Each root field's estimate, total and limit              |
+| `onStatementEnd`             |               | Duration, rows and error of every statement call         |
+| `timing`                     | false         | `extensions.timing` in `execute()` results               |
+| `tracer` / `traceStatements` |               | OpenTelemetry-style spans; Cypher text on request        |
+| `metrics`                    |               | Counters and histograms (see below)                      |
 
 Errors carry `extensions.code`: `BAD_USER_INPUT`, `INVALID_CURSOR`,
-`LIMIT_EXCEEDED`, `COST_EXCEEDED`, `TIMEOUT` (with `operationTimeoutMs`),
+`LIMIT_EXCEEDED`, `COST_EXCEEDED`, `OVERLOADED` (more than
+`maxQueuedWrites` mutations are waiting for the database: answer 503 and
+let the client back off), `TIMEOUT` (with `operationTimeoutMs`),
 `UNAUTHENTICATED`, `FORBIDDEN`,
 `NOT_FOUND`, `CONSTRAINT_VIOLATION` (with `type` and `field`),
 `DATABASE_ERROR` (with an `id`, also given to `onError`),

package/dist/analyze/access.d.ts

@@ -23,6 +23,11 @@ export interface RootFieldAccess {
         verdict: AccessVerdict;
         by: string[];
     }>;
+    /**
+     * Variables in the field's arguments that were given no value: what
+     * they would write through relationship fields is not in `access`.
+     */
+    unresolved?: string[];
 }
 export interface OperationAccess {
     operation: "query" | "mutation" | "subscription";
@@ -39,9 +44,12 @@ export interface OperationAccess {
 }
 /**
  * Who may run `operation`: each root field's verdict per principal, read
- * off the same rules as `accessMatrix`. Root fields only: nested
- * selections answer to their own types' READ rules (see the matrix).
+ * off the same rules as `accessMatrix`. A mutation's inputs are read for
+ * the relationship writes they make, each a part of its root field's
+ * verdict; an input given as a variable is read when `variables` has its
+ * value and listed in `unresolved` when it does not. Selections below a
+ * root field answer to their own types' READ rules (see the matrix).
  */
-export declare function operationAccess(model: GraphModel, schema: GraphQLSchema, operation: OperationDefinitionNode, fragments: ReadonlyMap<string, FragmentDefinitionNode>): OperationAccess;
+export declare function operationAccess(model: GraphModel, schema: GraphQLSchema, operation: OperationDefinitionNode, fragments: ReadonlyMap<string, FragmentDefinitionNode>, variables?: Readonly<Record<string, unknown>>): OperationAccess;
 /** The access matrix of `model`, in a stable order. */
 export declare function accessMatrix(model: GraphModel, schema: GraphQLSchema): AccessEntry[];

package/dist/analyze/input-schemas.d.ts

@@ -0,0 +1,11 @@
+import { GraphModel } from '../model/types.js';
+export type JsonSchema = Record<string, unknown>;
+/**
+ * A JSON Schema per generated create and update input, by input type
+ * name (`PersonCreateInput`), describing the scalar fields a client may
+ * set and the rules on them. A pattern is anchored, since here it must
+ * match the whole value; a format is given both by name and, where it is
+ * an expression, as a pattern, since validators treat `format` as a
+ * remark by default.
+ */
+export declare function inputSchemas(model: GraphModel): Record<string, JsonSchema>;

package/dist/analyze/plans.d.ts

@@ -35,3 +35,11 @@ export declare function checkPlans(driver: LoraDriver, compiled: CompiledRead, o
  * that start from keys (every mutation statement) must have none.
  */
 export declare function scanExpands(statement: Statement, plan: QueryPlan): PlanFinding[];
+/**
+ * Plan the statements a mutation ran. Every one starts from keys, so none
+ * may expand from a full scan (`scanExpands`); the engine's row estimate
+ * is held to `rowBudget` when one is given.
+ */
+export declare function checkStatements(driver: LoraDriver, statements: readonly Statement[], options?: {
+    rowBudget?: number;
+}): Promise<PlanReport[]>;

package/dist/analyze/stored.d.ts

@@ -0,0 +1,29 @@
+import { LoraDriver } from '../driver.js';
+import { GraphModel } from '../model/types.js';
+/** A stored value that breaks a rule of its field. */
+export interface StoredViolation {
+    type: string;
+    /** The node's `@key`; for a relationship property, the declaring node's. */
+    key: unknown;
+    field: string;
+    /**
+     * The rule, as in a request's `violations`; `normalize` for a value not
+     * in its stored form; `fulltext` for one a full-text index skips.
+     */
+    rule: string;
+    message: string;
+}
+export interface StoredReport {
+    violations: StoredViolation[];
+    /**
+     * Nodes read per type, and relationships per `Owner.field` whose
+     * properties have rules; one with more than `limit` is read in part.
+     */
+    scanned: Record<string, number>;
+    /** Types with more nodes than were read. */
+    partial: string[];
+}
+export declare function scanStored(driver: LoraDriver, model: GraphModel, options?: {
+    limit?: number;
+    timeoutMs?: number;
+}): Promise<StoredReport>;

package/dist/analyze/verdicts.d.ts

@@ -42,4 +42,10 @@ export declare function fieldVerdict(ctx: CompileContext, node: NodeType, field:
     kind: string;
     authorization?: NodeType["authorization"];
 }): Pick<AccessEntry, "verdict" | "by">;
+/**
+ * The `@authentication` operation a relationship operation answers to: a
+ * connect is checked as CREATE_RELATIONSHIP on the field, a disconnect as
+ * DELETE_RELATIONSHIP. Edge reads and updates have none of their own.
+ */
+export declare function relationshipAuthentication(op: RelationshipOperation): AuthOperation | undefined;
 export declare function relationshipVerdict(ctx: CompileContext, node: NodeType, field: Parameters<typeof relationshipRules>[1], op: RelationshipOperation): Pick<AccessEntry, "verdict" | "by">;