@loradb/lora-graphql 0.24.1 → 0.25.1

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.
@@ -148,22 +156,26 @@ Model:
 
 API:
 
-| Directive                                             | On                                           | Meaning                                                                                                       |
-| ----------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `@query(read:, aggregate:)`                           | type, interface, union                       | Generated reads                                                                                               |
-| `@mutation(operations: [CREATE, UPDATE, DELETE])`     | type                                         | Generated mutations; none without it                                                                          |
-| `@subscription(operations: [CREATE, UPDATE, DELETE])` | type                                         | Generated subscriptions; none without it                                                                      |
-| `@filterable(byValue: [...])`                         | field                                        | Filter operators. Bare: `EQ` and `IN` (lists: `INCLUDES`). On a relationship: enables relationship filters    |
-| `@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`                                        |
-| `@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                                                                     |
-| `@jwt`, `@jwtClaim(path:)`                            | type, field                                  | The claims shape; rules may only use declared claims                                                          |
-| `@viewer(type:, field:)`                              | `@jwt` claim                                 | The claim naming the caller's node (by a `@key` or `@unique` field): enables `isViewer` and `viewer` in rules |
+| Directive                                             | On                                                        | Meaning                                                                                                                                                                   |
+| ----------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@query(read:, aggregate:)`                           | type, interface, union                                    | Generated reads                                                                                                                                                           |
+| `@mutation(operations: [CREATE, UPDATE, DELETE])`     | type                                                      | Generated mutations; none without it                                                                                                                                      |
+| `@subscription(operations: [CREATE, UPDATE, DELETE])` | type                                                      | Generated subscriptions; none without it                                                                                                                                  |
+| `@filterable(byValue: [...])`                         | field                                                     | Filter operators. Bare: `EQ` and `IN` (lists: `INCLUDES`). On a relationship: enables relationship filters                                                                |
+| `@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                                                                                                                                                          |
+| `@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`; list relationship | How many items it holds; on an argument, `max` (default `maxListArgument`); on a relationship, `max` items per nested `connect`, `create`, `disconnect` and `update` list |
+| `@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                                                                                                                                 |
+| `@jwt`, `@jwtClaim(path:)`                            | type, field                                               | The claims shape; rules may only use declared claims                                                                                                                      |
+| `@viewer(type:, field:)`                              | `@jwt` claim                                              | The claim naming the caller's node (by a `@key` or `@unique` field): enables `isViewer` and `viewer` in rules                                                             |
 
 `directiveTypeDefs` (or `lora-graphql directives`) prints these as SDL for
 editors and codegen.
@@ -178,6 +190,30 @@ 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, `@normalize` included: it changes the argument
+before its rules are checked and before the statement sees it. 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
@@ -514,7 +550,11 @@ entry), and a delete reaches at most `maxBatch` nodes through
 `onDelete: CASCADE`. Relationships written (connects, each key of a
 `disconnect` list, nested `update` entries) count up to ten times
 `maxBatch`. Going over is `LIMIT_EXCEEDED`, before the writes that
-would exceed it. `@key` is not updatable.
+would exceed it. For a bound per field, `@size(max:)` on a list
+relationship (`following: [Person!]! @relationship(...) @size(max: 50)`)
+caps each nested `connect`, `create`, `disconnect` and `update` list of
+one input; a longer list is `BAD_USER_INPUT` before the transaction
+opens. `@key` is not updatable.
 `info` reports `nodesCreated`, `nodesUpdated`, `nodesDeleted`,
 `relationshipsCreated` and `relationshipsDeleted`.
 
@@ -636,6 +676,22 @@ inferred when the statement's last top-level `RETURN` has one item,
 Fields returning `@node` types are projected with the selection like any
 other node, and read filters apply to them.
 
+A `Mutation` statement says what it wrote in two more columns, read as a
+trigger statement's are: the nodes it returns as `created` and `updated`
+are its write-set, so its change is not `broad` and subscriptions on
+their types fire. Without either column the change is `broad`, and
+`check()` lints the mutation.
+
+```graphql
+type Mutation {
+  addGenre(key: String!, name: String!): Genre
+    @cypher(
+      statement: "CREATE (g:Genre {key: $key, name: $name}) RETURN g, g AS created"
+      columnName: "g"
+    )
+}
+```
+
 Statements are checked, not trusted:
 
 - at startup: every `$parameter` must be an argument, `$jwt` or
@@ -717,7 +773,10 @@ createPost(key: String!, hashtags: [String!] = [] @size(max: 30)): Post
 Int and Float arguments take bounds the same way: `@range(min:, max:)`
 (either or both, inclusive) checks the value, or each item of a list,
 before the statement runs, and a default outside the bounds is a model
-error. Null is not checked; that is the type's business.
+error. Null is not checked; that is the type's business. A String or ID
+argument takes `@normalize` (`text: String! @normalize(trim: true)
+@length(min: 1, max: 280)`): the trimmed value is what `@length` counts
+and what the statement gets.
 
 ```graphql
 nearby(lat: Float! @range(min: -90, max: 90), km: Int = 10 @range(min: 1, max: 500)): [Festival!]!
@@ -1245,8 +1304,8 @@ reported as an API break with no data migration.
 ```ts
 lora.onWrite((change) => {
   // Per type: lists, counts and connections of these types may have
-  // changed, not only the entities. A broad change (a @cypher mutation)
-  // names nothing, so it invalidates every type.
+  // changed, not only the entities. A broad change (a @cypher mutation
+  // that does not say what it wrote) names nothing: every type goes.
   const types = change.broad ? allNodeTypes : change.types;
   cache.invalidate(types.map((typename) => ({ typename })));
 });
@@ -1260,7 +1319,8 @@ relationships `connected` and `disconnected` (by field and both keys),
 included), and the touched `types` and `relationshipTypes`. Every compiled
 read carries a read-set (labels and relationship types);
 `lora.affects(reads, change)` tells whether a cached read may be stale.
-`@cypher` mutations have no known write-set and are reported with
+A `@cypher` mutation's write-set is the nodes its statement returns as
+`created` and `updated`; one that returns neither is reported with
 `broad: true`. Only writes made through the library are seen. A consumer
 that falls `maxQueuedChanges` (default 1000) behind is ended with an error
 rather than buffering without bound.
@@ -1369,6 +1429,91 @@ 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.
+- `@trigger(on: [CONNECT], field: "following", statement: ...)` runs
+  once per relationship the mutation created through that field, from
+  either side, with `this` and `target` bound: "tell a person who
+  followed them" without reading any other relationship. `DISCONNECT`
+  does the same for a relationship removed. A trigger function reads
+  them in `change.connected` and `change.disconnected`.
+- 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
@@ -1608,37 +1753,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, and ten times as many relationships; bulk `limit` by default. A nested `connect` list is bounded per field by `@size(max:)` on the relationship |
+| `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/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>;