@cyphra/graphql 0.0.0-stage → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Cyphra contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,62 @@
1
- # Temporary Holding Version
1
+ # @cyphra/graphql
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > Part of [Cyphra](https://www.cyphra.dev), the TypeScript ORM for Neo4j. **GraphQL:** [docs](https://www.cyphra.dev/graphql)
4
+
5
+ Serves the GraphQL API that `@neo4j/graphql` v7 generates from your type definitions (same types,
6
+ fields, filters and results) on the Cyphra runtime, so frontends switch without changing their
7
+ queries.
8
+
9
+ ```bash
10
+ npm i @cyphra/graphql graphql neo4j-driver
11
+ ```
12
+
13
+ ```ts
14
+ import { compat } from "@cyphra/graphql";
15
+
16
+ // Before: await new Neo4jGraphQL({ typeDefs, driver }).getSchema()
17
+ const schema = compat.v7.makeSchema({ typeDefs, driver });
18
+ ```
19
+
20
+ Serve `schema` with GraphQL Yoga, Apollo Server or any GraphQL server.
21
+
22
+ Status (early release):
23
+
24
+ - The full v7 schema is generated; its printed SDL is identical to `@neo4j/graphql` 7.6.8.
25
+ - Read API: list and connection queries, filters, sorting, `limit` / `offset`, cursor pagination,
26
+ nested relationships and connections with edge properties, connection `aggregate` selections and
27
+ aggregation filters.
28
+ - Mutations: `create`, `update`, `delete` with `info` counters, nested `create` / `connect` /
29
+ `disconnect` / `update` / `delete` with edge properties, every update operator (deprecated forms
30
+ included), `@id`, `@timestamp` and `@default`. No APOC needed.
31
+ - `@authentication` / `@authorization` (type, field and `extend schema` level), `@jwt` and
32
+ `@jwtClaim`: rules are compiled into the Cypher statement (filters in its `WHERE`, `validate`
33
+ checks inside it, a failed check rolls the statement back), never applied in JavaScript.
34
+ - `@cypher` fields on node types, relationship properties, `Query` and `Mutation`: scalar and
35
+ node results, arguments (always passed as parameters), `this`, `$jwt`, `where` and `sort` on
36
+ scalar fields, filters on node results, the READ rules of returned nodes.
37
+ - `@fulltext` queries (`score`, `where`, `sort`, `first` / `after`) on full-text indexes you
38
+ create, as in v7.
39
+ - One Cypher statement per root field, in its own transaction. Needs Neo4j 5.23+.
40
+ - Not yet: interfaces, unions, subscriptions, `@vector`, `Point` / `Duration` and custom scalars
41
+ (`makeSchema` throws `UnsupportedTypeDefsError`).
42
+
43
+ JWTs are verified like v7, with `features.authorization` and the request's `Authorization` header
44
+ as `token` in the context (a decoded `jwt` in the context is trusted as it is):
45
+
46
+ ```ts
47
+ const schema = compat.v7.makeSchema({
48
+ typeDefs,
49
+ driver,
50
+ features: { authorization: { key: process.env.JWT_SECRET! } }, // or { key: { url: jwksUrl } }
51
+ });
52
+ // GraphQL server context: ({ request }) => ({ token: request.headers.get("authorization") })
53
+ ```
54
+
55
+ Read the [authorization docs](https://www.cyphra.dev/graphql#authentication-and-authorization) for
56
+ the v7 behaviours that matter for security (filters on fields the user cannot read, AGGREGATE vs
57
+ READ rules, relationship-only updates) and the few cases where Cyphra is stricter than v7.
58
+
59
+ Compatibility is measured against the real `@neo4j/graphql` by the suite in
60
+ [`compat/graphql`](https://github.com/Cyphra-dev/cyphra/tree/main/compat/graphql).
61
+
62
+ The package also contains `convertGraphQLTypeDefs`, the converter behind `cyphra import graphql`.
@@ -0,0 +1,483 @@
1
+ import { ConstValueNode, GraphQLSchema } from 'graphql';
2
+ import { SchemaDocument, SchemaModel } from '@cyphra/schema';
3
+ import { CyphraClient } from '@cyphra/runtime';
4
+ import { Driver } from 'neo4j-driver';
5
+ import { RemoteJWKSetOptions, JWTVerifyOptions } from 'jose';
6
+
7
+ /**
8
+ * The mapping from `@neo4j/graphql` v7 type definitions to Cyphra, in one place.
9
+ *
10
+ * Each GraphQL scalar, type-level directive and field-level directive has one entry here. When
11
+ * Cyphra gains a feature (`Point`, `Duration`, …), supporting it in the importer means changing
12
+ * that entry: the converter in `convert.ts` only walks the SDL and applies these rules.
13
+ *
14
+ * Semantics follow `@neo4j/graphql` 7.x (checked against 7.6.8):
15
+ * - only object types with `@node` are nodes; `@node(labels)` sets the Neo4j labels;
16
+ * - `@id` takes no arguments, is only valid on `ID` fields, autogenerates a UUID and does not
17
+ * create a uniqueness constraint;
18
+ * - `@unique` no longer exists (removed in v7);
19
+ * - `@timestamp(operations)` defaults to `[CREATE, UPDATE]`;
20
+ * - `@relationship(type, direction)` requires both; `properties` names a `@relationshipProperties`
21
+ * object type.
22
+ *
23
+ * @packageDocumentation
24
+ */
25
+
26
+ /** How serious a report entry is. */
27
+ type ImportSeverity =
28
+ /** Not converted: the type, field or directive is missing from the Cyphra schema. */
29
+ "unsupported"
30
+ /** Converted, but it behaves differently in Cyphra: review it. */
31
+ | "changed"
32
+ /** API-level setting of `@neo4j/graphql` with no effect on the data model. */
33
+ | "ignored";
34
+ /** One line of the import report. */
35
+ type ImportIssue = {
36
+ readonly severity: ImportSeverity;
37
+ /** GraphQL location: `Type` or `Type.field`. */
38
+ readonly at: string;
39
+ /** What it is about, e.g. `@cypher`, `Duration`, `enum`. */
40
+ readonly feature: string;
41
+ readonly message: string;
42
+ };
43
+
44
+ /**
45
+ * Convert `@neo4j/graphql` v7 type definitions (SDL) to a Cyphra {@link SchemaDocument}.
46
+ *
47
+ * Pure: no file system, no printing. Rules for each scalar and directive live in `mappings.ts`;
48
+ * this module walks the SDL, applies them and links relationships.
49
+ *
50
+ * @packageDocumentation
51
+ */
52
+
53
+ /** One type definitions file. */
54
+ type GraphQLSource = {
55
+ readonly name: string;
56
+ readonly body: string;
57
+ };
58
+ type GraphQLImportResult = {
59
+ readonly document: SchemaDocument;
60
+ /** Everything that was not converted or behaves differently, in source order. */
61
+ readonly issues: readonly ImportIssue[];
62
+ /**
63
+ * Comment lines to print inside a declaration (keyed by Cyphra declaration name), one per
64
+ * field that was not converted.
65
+ */
66
+ readonly notes: ReadonlyMap<string, readonly string[]>;
67
+ };
68
+ /** The type definitions are not valid GraphQL (syntax error, unknown type, duplicate type). */
69
+ declare class GraphQLImportError extends Error {
70
+ name: string;
71
+ }
72
+ /**
73
+ * Convert type definitions to a Cyphra schema document plus a report of what was not
74
+ * converted. Never throws for unsupported features; only for invalid SDL.
75
+ *
76
+ * @param input - SDL text, or several named sources (merged like one document).
77
+ * @throws {GraphQLImportError} On a syntax error, an unknown type or a duplicate type.
78
+ */
79
+ declare function convertGraphQLTypeDefs(input: string | readonly GraphQLSource[]): GraphQLImportResult;
80
+
81
+ /**
82
+ * Print a {@link GraphQLImportResult} as `.cyphra` source, merge it into an existing schema, and
83
+ * format the import report.
84
+ *
85
+ * @packageDocumentation
86
+ */
87
+
88
+ /**
89
+ * The imported schema as a new `.cyphra` file.
90
+ *
91
+ * @param result - Output of {@link convertGraphQLTypeDefs}.
92
+ */
93
+ declare function printImportedSchema(result: GraphQLImportResult): string;
94
+ /**
95
+ * Merge the imported schema into an existing `.cyphra` source.
96
+ *
97
+ * Existing declarations, fields and comments are kept as written. Fields the existing nodes lack
98
+ * are added at the end of their block; new nodes and relationships are appended. When a field or
99
+ * relationship exists on both sides with a different definition, the existing one wins and an
100
+ * issue says so.
101
+ *
102
+ * @returns The merged source and the extra issues the merge produced.
103
+ * @throws When the existing source does not parse, or the merged schema does not resolve.
104
+ */
105
+ declare function mergeImportedSchema(existing: string, result: GraphQLImportResult): {
106
+ source: string;
107
+ issues: ImportIssue[];
108
+ };
109
+ /**
110
+ * The import report as plain text, grouped by severity. Empty string when there is nothing to
111
+ * report.
112
+ */
113
+ declare function formatImportReport(issues: readonly ImportIssue[]): string;
114
+
115
+ type ExecutorOptions = {
116
+ /** A `neo4j-driver` driver. */
117
+ driver?: Driver;
118
+ /** Or a Cyphra client (`new CyphraClient(...)`). */
119
+ client?: CyphraClient;
120
+ /** Database name for `driver` (default database when omitted). */
121
+ database?: string;
122
+ /** Log each generated statement and its parameter keys (never values). */
123
+ debug?: boolean;
124
+ };
125
+
126
+ /**
127
+ * JWT verification for `@authentication` / `@authorization`, configured like `@neo4j/graphql` v7
128
+ * (`features.authorization`): the bearer token of the request (`context.token`) is verified with
129
+ * `jose` against a symmetric secret or a JWKS endpoint. A token that is missing, malformed, expired,
130
+ * not yet valid or signed with another key leaves the request unauthenticated (no error), like v7.
131
+ *
132
+ * @packageDocumentation
133
+ */
134
+
135
+ type AnyRecord$1 = Record<string, unknown>;
136
+ /** A symmetric secret (HS256 / HS384 / HS512), or the URL of a JWKS endpoint. */
137
+ type JwtKey = string | {
138
+ url: string;
139
+ options?: RemoteJWKSetOptions;
140
+ };
141
+ /** `features.authorization` of `Neo4jGraphQL`: how tokens are verified. */
142
+ type AuthorizationFeature = {
143
+ /** The key, or a function of the GraphQL context returning it (per request). */
144
+ key: JwtKey | ((context: AnyRecord$1) => JwtKey);
145
+ /**
146
+ * `false` decodes tokens without verifying the signature (v7 option). Only for tokens already
147
+ * verified upstream (e.g. by a gateway): anyone can forge an unverified token.
148
+ */
149
+ verify?: boolean;
150
+ /** Passed to `jose`'s `jwtVerify` (`issuer`, `audience`, `algorithms`, `clockTolerance`, …). */
151
+ verifyOptions?: JWTVerifyOptions;
152
+ };
153
+ type Features = {
154
+ authorization?: AuthorizationFeature;
155
+ };
156
+
157
+ /**
158
+ * The `@neo4j/graphql` v7 type definitions, read into the model the v7 API is generated from.
159
+ *
160
+ * Unlike `convertGraphQLTypeDefs` (which maps to a Cyphra schema and drops what Cyphra cannot
161
+ * express), this keeps every detail that changes the generated API: `ID` vs `String`, list element
162
+ * nullability, `@cypher` fields, `@timestamp`, `@default`, relationship property types.
163
+ *
164
+ * @packageDocumentation
165
+ */
166
+
167
+ type TypeRef = {
168
+ /** Named type: a scalar or an enum. */
169
+ readonly name: string;
170
+ readonly list: boolean;
171
+ /** Outer `!`. */
172
+ readonly required: boolean;
173
+ /** `[T!]` (only for lists). */
174
+ readonly elementRequired: boolean;
175
+ };
176
+ type CypherAnnotation = {
177
+ readonly statement: string;
178
+ readonly columnName: string;
179
+ };
180
+ /** An argument of a `@cypher` field (scalar or enum, list or not), e.g. `tags(prefix: String = "x")`. */
181
+ type FieldArgument = {
182
+ readonly name: string;
183
+ readonly type: TypeRef;
184
+ readonly kind: "scalar" | "enum";
185
+ readonly description?: string;
186
+ /** The raw default value AST, printed in the SDL and applied by GraphQL. */
187
+ readonly defaultAst?: ConstValueNode;
188
+ };
189
+ /** A `@cypher` field of a node type returning nodes (`[Person!]!` or `Person`). */
190
+ type CypherNodeField = {
191
+ readonly name: string;
192
+ /** Node type of the returned nodes. */
193
+ readonly target: string;
194
+ readonly type: TypeRef;
195
+ readonly cypher: CypherAnnotation;
196
+ readonly args: readonly FieldArgument[];
197
+ readonly description?: string;
198
+ readonly deprecated?: string;
199
+ };
200
+ /** A `@cypher` field of `Query` or `Mutation`. */
201
+ type CypherRootField = {
202
+ readonly name: string;
203
+ readonly type: TypeRef;
204
+ /** `node` when the named type is a `@node` type. */
205
+ readonly kind: "scalar" | "enum" | "node";
206
+ readonly cypher: CypherAnnotation;
207
+ readonly args: readonly FieldArgument[];
208
+ readonly description?: string;
209
+ readonly deprecated?: string;
210
+ /** Field-level `@authentication`. */
211
+ readonly authentication?: AuthenticationAnnotation;
212
+ };
213
+ /** The custom fields of `Query` or `Mutation`, with the type-level `@authentication`. */
214
+ type CypherRootType = {
215
+ readonly fields: readonly CypherRootField[];
216
+ readonly authentication?: AuthenticationAnnotation;
217
+ };
218
+ /** One index of `@fulltext(indexes: [{ indexName, queryName, fields }])`. */
219
+ type FulltextIndex = {
220
+ readonly indexName: string;
221
+ /** Root query field, e.g. `moviesByTitle`. */
222
+ readonly queryName: string;
223
+ readonly fields: readonly string[];
224
+ };
225
+ type Attribute = {
226
+ readonly name: string;
227
+ /** Property key in Neo4j (`@alias(property)`), defaults to the field name. */
228
+ readonly property: string;
229
+ readonly type: TypeRef;
230
+ readonly kind: "scalar" | "enum";
231
+ readonly description?: string;
232
+ /** `@id`: generated, not in create/update inputs. */
233
+ readonly id: boolean;
234
+ /** `@default(value)` as a JS value. */
235
+ readonly defaultValue?: unknown;
236
+ /** The raw `@default(value: …)` AST, printed as the input default. */
237
+ readonly defaultAst?: ConstValueNode;
238
+ /** `@timestamp(operations)`. */
239
+ readonly timestamp?: readonly ("CREATE" | "UPDATE")[];
240
+ readonly cypher?: CypherAnnotation;
241
+ /** Arguments of a `@cypher` field (other fields have none). */
242
+ readonly args: readonly FieldArgument[];
243
+ /** User `@deprecated(reason)` on the field. */
244
+ readonly deprecated?: string;
245
+ /** Field-level `@authentication` / `@authorization`. */
246
+ readonly auth?: AuthAnnotations;
247
+ };
248
+ type Relationship = {
249
+ readonly name: string;
250
+ readonly source: string;
251
+ readonly target: string;
252
+ readonly type: string;
253
+ readonly direction: "IN" | "OUT";
254
+ /** Name of the `@relationshipProperties` type, if any. */
255
+ readonly properties?: string;
256
+ readonly list: boolean;
257
+ readonly required: boolean;
258
+ readonly elementRequired: boolean;
259
+ readonly description?: string;
260
+ readonly deprecated?: string;
261
+ };
262
+ /** Operations `@authentication` / `@authorization` rules apply to. */
263
+ declare const AUTH_OPERATIONS: readonly ["READ", "AGGREGATE", "CREATE", "UPDATE", "DELETE", "CREATE_RELATIONSHIP", "DELETE_RELATIONSHIP", "SUBSCRIBE"];
264
+ type AuthOperation = (typeof AUTH_OPERATIONS)[number];
265
+ type AnyRecord = Record<string, unknown>;
266
+ /** `@authentication(operations, jwt)`. */
267
+ type AuthenticationAnnotation = {
268
+ readonly operations: ReadonlySet<AuthOperation>;
269
+ /** `jwt: { … }` filter the decoded JWT must match (checked in JS, before the statement runs). */
270
+ readonly jwt?: AnyRecord;
271
+ };
272
+ /** One `filter` rule of `@authorization`. */
273
+ type AuthorizationRule = {
274
+ readonly operations: readonly AuthOperation[];
275
+ /** Default `true`: the rule only holds for authenticated requests. */
276
+ readonly requireAuthentication: boolean;
277
+ /** `{ node, jwt, AND, OR, NOT }` with `$jwt.<claim>` / `$context.<path>` string references. */
278
+ readonly where: AnyRecord;
279
+ };
280
+ /** One `validate` rule of `@authorization`. */
281
+ type AuthorizationValidateRule = AuthorizationRule & {
282
+ /** Default both: checked before and after the write. */
283
+ readonly when: readonly ("BEFORE" | "AFTER")[];
284
+ };
285
+ type AuthorizationAnnotation = {
286
+ readonly filter: readonly AuthorizationRule[];
287
+ readonly validate: readonly AuthorizationValidateRule[];
288
+ };
289
+ /** `@authentication` / `@authorization` of a type or of a field. */
290
+ type AuthAnnotations = {
291
+ readonly authentication?: AuthenticationAnnotation;
292
+ readonly authorization?: AuthorizationAnnotation;
293
+ };
294
+ type NodeType = {
295
+ readonly name: string;
296
+ readonly description?: string;
297
+ /** Neo4j labels; the first is the main label. */
298
+ readonly labels: readonly string[];
299
+ /** Root list field, e.g. `movies`. */
300
+ readonly plural: string;
301
+ /** `Movies`. */
302
+ readonly pascalPlural: string;
303
+ readonly attributes: readonly Attribute[];
304
+ readonly relationships: readonly Relationship[];
305
+ /** `@cypher` fields returning nodes. */
306
+ readonly cypherNodes: readonly CypherNodeField[];
307
+ /** `@fulltext` indexes. */
308
+ readonly fulltext: readonly FulltextIndex[];
309
+ readonly auth: AuthAnnotations;
310
+ };
311
+ type PropertiesType = {
312
+ readonly name: string;
313
+ readonly attributes: readonly Attribute[];
314
+ };
315
+ type EnumType = {
316
+ readonly name: string;
317
+ readonly description?: string;
318
+ readonly values: readonly {
319
+ name: string;
320
+ description?: string;
321
+ deprecated?: string;
322
+ }[];
323
+ };
324
+ type V7Model = {
325
+ readonly nodes: readonly NodeType[];
326
+ /** Schema-level `extend schema @authentication(…)`: applies to every operation on every type. */
327
+ readonly authentication?: AuthenticationAnnotation;
328
+ /**
329
+ * `@jwtClaim(path)` of the `@jwt` type: field name → dotted path in the JWT payload. Like v7, the
330
+ * mapping is applied to tokens the library verified, not to a decoded `jwt` passed in the context.
331
+ */
332
+ readonly jwtClaims: ReadonlyMap<string, string>;
333
+ readonly properties: ReadonlyMap<string, PropertiesType>;
334
+ readonly enums: ReadonlyMap<string, EnumType>;
335
+ /** `@cypher` fields of `type Query` / `type Mutation`. */
336
+ readonly query: CypherRootType;
337
+ readonly mutation: CypherRootType;
338
+ node(name: string): NodeType;
339
+ };
340
+ /** The type definitions use a feature `@cyphra/graphql` cannot serve yet. */
341
+ declare class UnsupportedTypeDefsError extends Error {
342
+ name: string;
343
+ }
344
+ /**
345
+ * Read v7 type definitions. Throws {@link UnsupportedTypeDefsError} for features `@cyphra/graphql`
346
+ * does not serve yet (interfaces, unions, spatial and some temporal types, …), so the generated
347
+ * API never silently differs from v7.
348
+ */
349
+ declare function readTypeDefs(typeDefs: string): V7Model;
350
+
351
+ /**
352
+ * Generates the GraphQL schema `@neo4j/graphql` v7 builds from type definitions: root queries and
353
+ * mutations, connection and edge types, every `where` / `sort` / `create` / `update` / `connect` /
354
+ * `disconnect` / `delete` input, aggregate selection types, and the deprecated `field_OPERATOR`
355
+ * fields v7 still prints. Names, descriptions and deprecation reasons are the v7 ones, so the
356
+ * printed SDL is identical.
357
+ *
358
+ * Only types reachable from `Query` / `Mutation` end up in the schema (as with v7).
359
+ *
360
+ * @packageDocumentation
361
+ */
362
+
363
+ /** Builds the v7 schema (without resolvers) for a model. */
364
+ declare function buildV7Schema(model: V7Model): GraphQLSchema;
365
+
366
+ /**
367
+ * Compiles one v7 root query field (`movies`, `moviesConnection`) with its whole selection set into a
368
+ * single Cypher statement, plus a decoder that turns the returned value into the GraphQL result.
369
+ *
370
+ * Nested relationship fields become `COLLECT { … }` subqueries, connections become a `COUNT { … }`
371
+ * (for `totalCount` / `pageInfo`) and a `COLLECT { … }` of edges. Cursors are v7 offset cursors:
372
+ * `base64("arrayconnection:<offset>")`.
373
+ *
374
+ * Connection `aggregate` selections follow v7 7.6: `count.nodes` / `count.edges` count distinct
375
+ * nodes / relationships; each `node.<field>` / `edge.<field>` aggregate runs over the distinct nodes
376
+ * (relationships) matching the connection `where` (not `first` / `after`); `shortest` / `longest` are
377
+ * the last / first values ordered by `size(…)` descending; `sum` of an empty set is `0`, the other
378
+ * aggregates are `null`. Int `average` is a Float, BigInt values (including `average`) are strings.
379
+ *
380
+ * Authorization (v7 7.6): the READ `filter` rules of the type (and of the selected fields) are part
381
+ * of the `WHERE` of every node selection, root or nested, and of connection `totalCount`; connection
382
+ * `aggregate` selections use the AGGREGATE rules instead. When READ (AGGREGATE) `validate` rules fail
383
+ * for one node matching the selection's filters (before pagination, like v7), the selection is
384
+ * replaced by a {@link FORBIDDEN_KEY} marker and the field fails with `Forbidden`: the projection of
385
+ * a node that is not allowed is never returned by the database.
386
+ *
387
+ * @packageDocumentation
388
+ */
389
+
390
+ declare function offsetToCursor(offset: number): string;
391
+ /** Offset of the cursor, or `undefined` when it is not a valid v7 cursor (first page then). */
392
+ declare function cursorToOffset(cursor: unknown): number | undefined;
393
+
394
+ /**
395
+ * `@neo4j/graphql` v7 compatible API: the same generated schema, served on the Cyphra runtime.
396
+ *
397
+ * @packageDocumentation
398
+ */
399
+
400
+ type MakeSchemaOptions = ExecutorOptions & {
401
+ /** v7 type definitions (`@node`, `@relationship`, …). */
402
+ typeDefs: string;
403
+ /**
404
+ * v7 `features`. `authorization` configures JWT verification for `@authentication` /
405
+ * `@authorization`: the request's `context.token` (`Bearer <jwt>`) is verified with `key` (a
406
+ * secret, a JWKS `{ url }`, or a function of the context returning one). Without it, only a
407
+ * decoded `context.jwt` (trusted as-is) authenticates requests.
408
+ */
409
+ features?: Features;
410
+ };
411
+ /**
412
+ * Build the GraphQL schema `@neo4j/graphql` v7 generates for `typeDefs`, with resolvers that run on
413
+ * Neo4j through `driver` or `client`. Drop-in for `new Neo4jGraphQL({ typeDefs, driver }).getSchema()`.
414
+ *
415
+ * Today: the full v7 schema (SDL identical to v7), the read API (list and connection queries,
416
+ * filters, sorting, offset and cursor pagination, nested relationships and connections with edge
417
+ * properties, connection `aggregate` selections and aggregation filters), mutations (create,
418
+ * update, delete with every nested operation and `info` counters) and `@authentication` /
419
+ * `@authorization` (compiled into each statement; JWTs verified with `features.authorization`),
420
+ * `@cypher` fields (on node types, relationship properties, `Query` and `Mutation`; sortable and
421
+ * filterable like v7) and `@fulltext` queries (on indexes the application creates).
422
+ *
423
+ * @example
424
+ * ```ts
425
+ * import { compat } from "@cyphra/graphql";
426
+ * const schema = compat.v7.makeSchema({ typeDefs, driver });
427
+ * ```
428
+ */
429
+ declare function makeSchema(options: MakeSchemaOptions): GraphQLSchema;
430
+ /**
431
+ * The GraphQL `contextValue` for a request, as v7 reads it: `token` is the `Authorization` header
432
+ * (`Bearer <jwt>`, verified with `features.authorization`), `jwt` a payload the server already
433
+ * verified (trusted as-is, takes precedence over `token`). Other keys are kept for
434
+ * `$context.<path>` references in rules.
435
+ */
436
+ declare function contextFor(opts?: {
437
+ jwt?: Record<string, unknown>;
438
+ token?: string;
439
+ [key: string]: unknown;
440
+ }): Record<string, unknown>;
441
+ /**
442
+ * The Cyphra schema for the same type definitions (through `convertGraphQLTypeDefs`, the converter
443
+ * behind `cyphra import graphql`): use it with `createOrm` to work on the graph the GraphQL API
444
+ * serves. `issues` lists what Cyphra models differently (e.g. `@cypher` fields are not converted).
445
+ */
446
+ declare function cyphraSchema(typeDefs: string): {
447
+ document: SchemaDocument;
448
+ model: SchemaModel;
449
+ issues: readonly ImportIssue[];
450
+ };
451
+
452
+ type v7_AuthorizationFeature = AuthorizationFeature;
453
+ type v7_Features = Features;
454
+ type v7_JwtKey = JwtKey;
455
+ type v7_MakeSchemaOptions = MakeSchemaOptions;
456
+ type v7_UnsupportedTypeDefsError = UnsupportedTypeDefsError;
457
+ declare const v7_UnsupportedTypeDefsError: typeof UnsupportedTypeDefsError;
458
+ type v7_V7Model = V7Model;
459
+ declare const v7_buildV7Schema: typeof buildV7Schema;
460
+ declare const v7_contextFor: typeof contextFor;
461
+ declare const v7_cursorToOffset: typeof cursorToOffset;
462
+ declare const v7_cyphraSchema: typeof cyphraSchema;
463
+ declare const v7_makeSchema: typeof makeSchema;
464
+ declare const v7_offsetToCursor: typeof offsetToCursor;
465
+ declare const v7_readTypeDefs: typeof readTypeDefs;
466
+ declare namespace v7 {
467
+ export { type v7_AuthorizationFeature as AuthorizationFeature, type v7_Features as Features, type v7_JwtKey as JwtKey, type v7_MakeSchemaOptions as MakeSchemaOptions, v7_UnsupportedTypeDefsError as UnsupportedTypeDefsError, type v7_V7Model as V7Model, v7_buildV7Schema as buildV7Schema, v7_contextFor as contextFor, v7_cursorToOffset as cursorToOffset, v7_cyphraSchema as cyphraSchema, v7_makeSchema as makeSchema, v7_offsetToCursor as offsetToCursor, v7_readTypeDefs as readTypeDefs };
468
+ }
469
+
470
+ /**
471
+ * GraphQL for Neo4j on the Cyphra runtime.
472
+ *
473
+ * `compat.v7` serves the API `@neo4j/graphql` v7 generates from the same type definitions, so
474
+ * frontends can switch without changing their queries.
475
+ *
476
+ * @packageDocumentation
477
+ */
478
+
479
+ declare const compat: {
480
+ readonly v7: typeof v7;
481
+ };
482
+
483
+ export { type AuthorizationFeature, type Features, GraphQLImportError, type GraphQLImportResult, type GraphQLSource, type ImportIssue, type ImportSeverity, type JwtKey, type MakeSchemaOptions, UnsupportedTypeDefsError, compat, convertGraphQLTypeDefs, formatImportReport, mergeImportedSchema, printImportedSchema };