@loradb/lora-graphql 0.24.1 → 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
@@ -1369,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
@@ -1608,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/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>;