@loradb/lora-graphql 0.16.2 → 0.18.0

package/dist/errors.d.ts

@@ -15,6 +15,6 @@ export declare class ModelError extends Error {
     constructor(problems: ModelProblem[]);
 }
 export declare function formatProblem(p: ModelProblem): string;
-export type LoraGraphQLErrorCode = "BAD_USER_INPUT" | "INVALID_CURSOR" | "LIMIT_EXCEEDED" | "COST_EXCEEDED" | "UNAUTHENTICATED" | "FORBIDDEN" | "NOT_FOUND" | "CONSTRAINT_VIOLATION" | "DATABASE_ERROR";
+export type LoraGraphQLErrorCode = "BAD_USER_INPUT" | "INVALID_CURSOR" | "LIMIT_EXCEEDED" | "COST_EXCEEDED" | "UNAUTHENTICATED" | "FORBIDDEN" | "NOT_FOUND" | "CONSTRAINT_VIOLATION" | "DATABASE_ERROR" | "PERSISTED_QUERY_ONLY";
 /** A request-time error with a stable `extensions.code`. */
 export declare function requestError(code: LoraGraphQLErrorCode, message: string, cause?: unknown, extensions?: Record<string, unknown>): GraphQLError;

package/dist/index.js

@@ -1,5 +1,5 @@
-import { D as e, L as r, a as o, M as l, b as i, c as d, d as n, e as t, f, g as m, i as p, l as c, p as h, r as D, s as b, h as u, t as v, v as L } from "./driver-C8vA5fV-.js";
-import { d as x } from "./diff-BVP1Jzh3.js";
+import { D as e, L as r, a as o, M as l, b as i, c as d, d as n, e as t, f, g as m, i as p, l as c, p as h, r as D, s as b, h as u, t as v, v as L } from "./driver-CQj9gkvl.js";
+import { d as x } from "./diff-fpWH5KUa.js";
 export {
   e as DEFAULT_GUARDS,
   r as LoraGraphQL,

package/dist/lora-graphql.d.ts

@@ -59,9 +59,10 @@ export interface LoraGraphQLOptions extends ModelOptions, ObservabilityOptions {
     scalars?: Record<string, GraphQLScalarType>;
     /**
      * Feed subscriptions and `changes()` from the engine's committed change
-     * feed (lora-node `db.changes()`): writes from every path and process,
-     * in commit order. `onWrite` still reports this instance's mutations,
-     * and `previousState` needs them. Default false.
+     * feed (lora-node `db.changes()`): every write to the database, from
+     * any path in the process that owns it, in commit order. `onWrite`
+     * still reports this instance's mutations, and `previousState` needs
+     * them. Default false.
      */
     changeFeed?: boolean;
     /**
@@ -80,14 +81,15 @@ export interface LoraGraphQLOptions extends ModelOptions, ObservabilityOptions {
     /** Called with every database error, masked or not. */
     onError?: (event: DatabaseErrorEvent) => void;
     /**
-     * Limits on the documents `execute()` and `persist()` accept: depth,
+     * Limits on the documents `execute()`, `subscribe()` and `persist()`
+     * accept: depth,
      * aliases, root fields, tokens, introspection. `false` turns them off.
      * For other servers use `validationRules()` or `envelopPlugin()`.
      */
     guards?: DocumentGuards | false;
     /**
-     * Make `execute()` refuse `source` and run only persisted operations
-     * by `id`. Default false.
+     * Make `execute()` and `subscribe()` refuse `source` and run only
+     * persisted operations by `id`. Default false.
      */
     persistedOnly?: boolean;
 }
@@ -143,11 +145,17 @@ export interface CheckOptions {
      * that stops an index-ordered scan early.
      */
     rowBudget?: number;
-    /** Operations to compile and plan-check (S2), with example variables. */
+    /**
+     * Operations to compile and plan-check (S2), with example variables and
+     * the GraphQL context to compile them under (e.g. `{ jwt }`, so rules
+     * compile as they do for a signed-in caller). Without one, an operation
+     * compiles as an anonymous request would.
+     */
     operations?: Array<{
         name?: string;
         document: string | DocumentNode;
         variables?: Record<string, unknown>;
+        context?: unknown;
     }>;
 }
 export interface CheckReport {
@@ -263,10 +271,20 @@ export declare class LoraGraphQL {
      */
     loadManifest(manifest: OperationManifest): void;
     /**
-     * Execute an operation against the schema. Parsed and validated
-     * documents are cached by source text; persisted ones by id.
+     * Execute a query or mutation against the schema. Parsed and validated
+     * documents are cached by source text; persisted ones by id. A
+     * subscription runs with {@link LoraGraphQL.subscribe}.
      */
     execute(args: ExecuteArgs): Promise<ExecutionResult>;
+    /**
+     * Run a subscription: an async iterable of results, one per event, or a
+     * single result with the errors when it cannot start (an unknown id, a
+     * validation error, a denied subscribe). Takes the same arguments as
+     * {@link LoraGraphQL.execute}, a persisted id included, with the same
+     * document cache and guards. End it with `return()` on the iterator, or
+     * with an `AbortSignal` passed as `context.signal`.
+     */
+    subscribe(args: ExecuteArgs): Promise<AsyncIterableIterator<ExecutionResult> | ExecutionResult>;
     /** Called after every committed mutation with its exact write-set. */
     onWrite(listener: (change: WriteChange) => void): () => void;
     /**

package/dist/model/cypher-lexer.d.ts

@@ -8,3 +8,9 @@ export declare function scanParams(text: string): ParamRef[];
 export declare function renameParams(text: string, rename: (name: string) => string): string;
 /** Code outside strings and comments, uppercased, for construct checks. */
 export declare function codeOnly(text: string): string;
+/**
+ * `text` with the same length and offsets, strings and comments blanked
+ * and the insides of backtick-quoted names replaced by `_`, so structure
+ * (brackets, commas, keywords) can be read without being fooled by them.
+ */
+export declare function maskLiterals(text: string): string;

package/dist/model/inputs.d.ts

@@ -0,0 +1,12 @@
+import { GraphModel, NodeType, RelationshipField, RelationshipPropertiesType, ScalarField } from './types.js';
+/** Whether clients may set a field on `op` (`@settable`, `@readonly`, …). */
+export declare function settable(f: ScalarField | RelationshipField, op: "CREATE" | "UPDATE"): boolean;
+/**
+ * Whether an update input for `node` has any field: a scalar settable on
+ * update, or a relationship offering a nested operation.
+ */
+export declare function isUpdatable(model: GraphModel, node: NodeType, seen?: Set<string>): boolean;
+/** Whether the create or update input of `rel` offers any operation. */
+export declare function offersNested(model: GraphModel, rel: RelationshipField, update: boolean, seen?: Set<string>): boolean;
+/** Whether any property of a @relationshipProperties type is settable on `op`. */
+export declare function hasSettable(props: RelationshipPropertiesType, op: "CREATE" | "UPDATE"): boolean;

package/dist/model/types.d.ts

@@ -103,6 +103,14 @@ export interface RelationshipField extends FieldBase {
     onDelete: "DETACH" | "CASCADE" | "RESTRICT";
     /** Nested writes mutation inputs offer for the field. */
     nestedOperations: ReadonlySet<NestedOperation>;
+    /**
+     * `@settable` / `@readonly`: whether create and update inputs offer the
+     * field at all (an upsert of an existing node keeps its relationship).
+     */
+    settableOn: {
+        create: boolean;
+        update: boolean;
+    };
     /** Whether the field's connection and filters offer aggregates. */
     aggregate: boolean;
     cardinality: number | undefined;
@@ -162,6 +170,8 @@ export interface CustomField extends FieldBase {
     description: string | undefined;
 }
 export type Field = ScalarField | RelationshipField | CypherField | CustomField;
+/** A `${jwt.path}` / `${context.path}` placeholder inside a rule string. */
+export declare const PLACEHOLDER: RegExp;
 /** `{ node, jwt, AND, OR, NOT }`, as written in `@authorization`. */
 export type AuthorizationWhere = Record<string, unknown>;
 export interface AuthorizationFilterRule {
@@ -291,6 +301,8 @@ export interface GraphModel {
     warnings: readonly ModelWarning[];
     /** Custom scalars (`@storedAs`), by name: their storage type. */
     scalars: ReadonlyMap<string, ScalarType>;
+    /** Custom scalars' SDL descriptions, by name, when they have one. */
+    scalarDescriptions: ReadonlyMap<string, string>;
     /** Object types without @node that @cypher fields return. */
     objects: ReadonlyMap<string, PlainObjectType>;
     /** The `@jwt` claims shape, when declared: claim name → token path. */

package/dist/schema/mutations.d.ts

@@ -1,5 +1,7 @@
 import { GraphQLObjectType, GraphQLFieldConfigMap, GraphQLInputType, GraphQLResolveInfo } from 'graphql';
 import { GraphModel, MutationOperation, NodeType, ScalarField } from '../model/types.js';
+import { isUpdatable, settable } from '../model/inputs.js';
+export { isUpdatable, settable };
 /** A generated mutation: the single-node ones, and the bulk ones by where. */
 export type MutationKind = MutationOperation | "UPSERT" | "UPDATE_MANY" | "DELETE_MANY";
 export type MutationResolver = (operation: MutationKind, node: NodeType, info: GraphQLResolveInfo, context: unknown) => Promise<unknown>;
@@ -33,12 +35,8 @@ export interface MutationSchemaContext {
     inputType: (f: ScalarField) => GraphQLInputType;
     where: (typeName: string) => GraphQLInputType;
 }
-/** Whether clients may set a field on `op` (`@settable`, `@readonly`, …). */
-export declare function settable(f: ScalarField, op: "CREATE" | "UPDATE"): boolean;
 /** Whether the create input must carry the field. */
 export declare function requiredOnCreate(f: ScalarField): boolean;
-/** A type with nothing settable after create has no update. */
-export declare function isUpdatable(node: NodeType): boolean;
 /** Numeric and list fields take operators in `adjust`. */
 export declare function adjustable(f: ScalarField): boolean;
 export declare function buildMutations(ctx: MutationSchemaContext, resolve: MutationResolver): GraphQLFieldConfigMap<unknown, unknown>;

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { graphql as h } from "graphql";
-import { L as w, l as u } from "./driver-C8vA5fV-.js";
+import { L as w, l as u } from "./driver-CQj9gkvl.js";
 async function L(l) {
   let s;
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loradb/lora-graphql",
-  "version": "0.16.2",
+  "version": "0.18.0",
   "description": "Schema-first GraphQL for LoraDB: one annotated SDL becomes an executable, index-aware GraphQL API that compiles every operation to a single Cypher statement.",
   "license": "BUSL-1.1",
   "packageManager": "yarn@4.5.1",
@@ -55,6 +55,7 @@
     "build": "vite build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
+    "test:graphql17": "LORA_GRAPHQL_VERSION=17 vitest run",
     "test:watch": "vitest",
     "lint": "eslint src test bench",
     "lint:fix": "eslint src test bench --fix",
@@ -63,7 +64,7 @@
     "bench": "vitest bench --run"
   },
   "peerDependencies": {
-    "@loradb/lora-node": "^0.16.2",
+    "@loradb/lora-node": "^0.18.0",
     "graphql": "^16.8.0 || ^17.0.0"
   },
   "devDependencies": {
@@ -72,6 +73,7 @@
     "eslint": "^9.15.0",
     "fast-check": "^4.10.2",
     "graphql": "^16.9.0",
+    "graphql17": "npm:graphql@17.0.2",
     "typescript": "^5.6.0",
     "vite": "^5.4.0",
     "vite-plugin-dts": "^4.2.0",