@alxia/graphql 0.16.5 → 0.18.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.
Files changed (74) hide show
  1. package/README.md +60 -62
  2. package/dist/endpoint.d.ts +14 -2
  3. package/dist/endpoint.d.ts.map +1 -1
  4. package/dist/executor.d.ts +20 -37
  5. package/dist/executor.d.ts.map +1 -1
  6. package/dist/explorer.d.ts +24 -0
  7. package/dist/explorer.d.ts.map +1 -0
  8. package/dist/graphql.d.ts +32 -95
  9. package/dist/graphql.d.ts.map +1 -1
  10. package/dist/handler.d.ts +7 -34
  11. package/dist/handler.d.ts.map +1 -1
  12. package/dist/index.d.ts +3 -4
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +301 -1011
  15. package/dist/index.js.map +14 -23
  16. package/dist/once-per-request.d.ts +5 -0
  17. package/dist/once-per-request.d.ts.map +1 -1
  18. package/dist/operation.d.ts +2 -7
  19. package/dist/operation.d.ts.map +1 -1
  20. package/dist/options.d.ts +38 -0
  21. package/dist/options.d.ts.map +1 -0
  22. package/dist/removed.d.ts +14 -0
  23. package/dist/removed.d.ts.map +1 -0
  24. package/dist/sandbox.d.ts +3 -17
  25. package/dist/sandbox.d.ts.map +1 -1
  26. package/dist/testing/client.d.ts +9 -7
  27. package/dist/testing/client.d.ts.map +1 -1
  28. package/dist/testing/index.js +5 -1
  29. package/dist/testing/index.js.map +3 -3
  30. package/dist/ws.d.ts +18 -30
  31. package/dist/ws.d.ts.map +1 -1
  32. package/docs/README.md +3 -2
  33. package/docs/guide/context.md +40 -32
  34. package/docs/guide/endpoint.md +42 -27
  35. package/docs/guide/executor.md +23 -8
  36. package/docs/guide/ide.md +27 -64
  37. package/docs/guide/{yoga.md → plugins.md} +87 -72
  38. package/docs/guide/production.md +115 -196
  39. package/docs/guide/testing.md +24 -24
  40. package/docs/guide/websockets.md +21 -14
  41. package/docs/migrating-to-graxia.md +283 -0
  42. package/docs/roadmap.md +7 -11
  43. package/docs/troubleshooting.md +231 -248
  44. package/package.json +15 -22
  45. package/dist/body-refusal.d.ts +0 -25
  46. package/dist/body-refusal.d.ts.map +0 -1
  47. package/dist/document-cache.d.ts +0 -39
  48. package/dist/document-cache.d.ts.map +0 -1
  49. package/dist/field-rate-limit/count.d.ts +0 -28
  50. package/dist/field-rate-limit/count.d.ts.map +0 -1
  51. package/dist/field-rate-limit/from-store.d.ts +0 -21
  52. package/dist/field-rate-limit/from-store.d.ts.map +0 -1
  53. package/dist/field-rate-limit/index.d.ts +0 -5
  54. package/dist/field-rate-limit/index.d.ts.map +0 -1
  55. package/dist/field-rate-limit/ipv6-network.d.ts +0 -8
  56. package/dist/field-rate-limit/ipv6-network.d.ts.map +0 -1
  57. package/dist/field-rate-limit/plugin.d.ts +0 -28
  58. package/dist/field-rate-limit/plugin.d.ts.map +0 -1
  59. package/dist/field-rate-limit/types.d.ts +0 -60
  60. package/dist/field-rate-limit/types.d.ts.map +0 -1
  61. package/dist/nesting.d.ts +0 -18
  62. package/dist/nesting.d.ts.map +0 -1
  63. package/dist/parse-limits.d.ts +0 -50
  64. package/dist/parse-limits.d.ts.map +0 -1
  65. package/dist/same-origin/index.d.ts +0 -2
  66. package/dist/same-origin/index.d.ts.map +0 -1
  67. package/dist/same-origin/same-origin.d.ts +0 -30
  68. package/dist/same-origin/same-origin.d.ts.map +0 -1
  69. package/dist/ws-operations.d.ts +0 -31
  70. package/dist/ws-operations.d.ts.map +0 -1
  71. package/dist/ws-server.d.ts +0 -32
  72. package/dist/ws-server.d.ts.map +0 -1
  73. package/dist/yoga.d.ts +0 -12
  74. package/dist/yoga.d.ts.map +0 -1
@@ -1,16 +1,16 @@
1
- # Yoga's plugins and options
1
+ # Graxia's plugins and options
2
2
 
3
- This page covers what passes through to GraphQL Yoga: its plugins and
4
- Envelop's, error masking, batching, subscriptions over server-sent events
5
- (and over WebSocket with [`ws`](websockets.md)),
6
- and how CORS and compression meet the endpoint.
3
+ This page covers what passes through to graxia (`@graxia/core`): its plugins
4
+ and Envelop's, error masking, batching, subscriptions over server-sent events
5
+ (and over WebSocket with [`ws`](websockets.md)), and how CORS and
6
+ compression meet the endpoint.
7
7
 
8
8
  ```ts
9
9
  import { alxia } from '@alxia/core';
10
10
  import { graphql } from '@alxia/graphql';
11
- import { createSchema, useExecutionCancellation } from 'graphql-yoga';
11
+ import { createSchema } from '@graxia/core';
12
12
 
13
- const schema = createSchema({
13
+ const schema = createSchema()({
14
14
  typeDefs: /* GraphQL */ `type Query { hello: String! }`,
15
15
  resolvers: { Query: { hello: () => 'world' } },
16
16
  });
@@ -18,100 +18,107 @@ const schema = createSchema({
18
18
  const app = alxia().plugin((app) =>
19
19
  graphql(app, {
20
20
  schema,
21
- plugins: [useExecutionCancellation()], // stop resolvers when the client goes away
22
21
  batching: { limit: 5 },
23
- logging: Bun.env['NODE_ENV'] === 'production' ? 'warn' : 'debug',
24
22
  }),
25
23
  );
26
24
  ```
27
25
 
28
26
  ## What passes through
29
27
 
30
- `GraphQLOptions` is Yoga's `YogaServerOptions`, minus four keys the package
31
- owns:
28
+ `GraphQLOptions` is graxia's `GraxiaOptions`, minus the keys the package owns
29
+ or maps:
32
30
 
33
- | Yoga's option | Here |
31
+ | graxia's option | Here |
34
32
  | --- | --- |
35
- | `graphqlEndpoint` | set from `path` and the app's prefix ([Mounting the endpoint](endpoint.md#where-it-is-served)) |
36
- | `graphiql` | set from `ide`; `graphiql` takes GraphiQL's options only, not `true`/`false` ([GraphiQL and Apollo Sandbox](ide.md)) |
37
- | `cors` | `false` unless given ([CORS](#cors)) |
33
+ | `path` | set from `path` and the app's prefix ([Mounting the endpoint](endpoint.md#where-it-is-served)) |
34
+ | `plugins` | yours, plus the package's own: the IDE ([GraphiQL and Apollo Sandbox](ide.md)) and the reporter that names the operation for `@alxia/logger` and `@alxia/telemetry` |
35
+ | `limits` | `bodyBytes` is set from `bodyLimit`; `tokens` and `nesting` may also come from the deprecated `maxTokens` and `maxNesting` ([Cap what a request costs](production.md#cap-what-a-request-costs)) |
36
+ | `caches` | `parse` may also come from the deprecated `parseCache` |
37
+ | `subscriptions` | set from `ws`: server-sent events always, WebSocket when `ws` is on ([GraphQL over WebSocket](websockets.md)) |
38
38
  | `schema` | required, and checked against the app's context ([The typed context](context.md)) |
39
+ | `telemetry` | `operationSpans: false`, so an operation is one span, the one `@alxia/telemetry` makes |
39
40
 
40
- Everything else — `plugins`, `context`, `maskedErrors`, `batching`,
41
- `logging`, `landingPage`, `healthCheckEndpoint`, `parserAndValidationCache`,
42
- `multipart`… — goes to `createYoga` as it is, with Yoga's defaults. Its
43
- reference is [Yoga's documentation](https://the-guild.dev/graphql/yoga-server/docs).
41
+ Everything else (`context`, `maskErrors`, `batching`, `csrf`, `trustedDocuments`,
42
+ `uploads`…) goes to `createGraxia` as it is, with graxia's defaults. Its
43
+ reference is [graxia's documentation](https://github.com/softistx/graxia/tree/develop/packages/core/docs).
44
+
45
+ Some of Yoga's options no longer exist and are refused where `graphql()` is
46
+ declared, with the fix in the message: `logging`, `requestId`, `cors` and
47
+ `sameOrigin`. See [Migrating to graxia](../migrating-to-graxia.md).
44
48
 
45
49
  ## Plugins
46
50
 
47
- `plugins` takes Yoga's plugins and Envelop's, in the order they run. Those
48
- Yoga ships are imported from `graphql-yoga`; the others are packages of their
49
- own, installed beside it:
51
+ `plugins` takes graxia's plugins, in the order they run
52
+ ([graxia's plugin guide](https://github.com/softistx/graxia/blob/develop/packages/core/docs/guide/plugins.md)).
53
+ An Envelop plugin goes through `fromEnvelop` from `@graxia/envelop`, which is not a peer: install `@graxia/envelop` yourself to use Envelop plugins.
50
54
 
51
55
  ```sh
52
- bun add @envelop/depth-limit @graphql-yoga/plugin-response-cache
56
+ bun add @graxia/envelop @envelop/depth-limit
53
57
  ```
54
58
 
55
59
  ```ts
56
60
  import { useDepthLimit } from '@envelop/depth-limit';
57
- import { useResponseCache } from '@graphql-yoga/plugin-response-cache';
61
+ import { fromEnvelop } from '@graxia/envelop';
58
62
 
59
63
  graphql(app, {
60
64
  schema,
61
- plugins: [
62
- useDepthLimit({ maxDepth: 8 }),
63
- useResponseCache({ session: ({ request }) => request.headers.get('authorization') }),
64
- ],
65
+ plugins: [fromEnvelop([useDepthLimit({ maxDepth: 8 })])],
65
66
  });
66
67
  ```
67
68
 
68
- A plugin of your own is an object of hooks, typed `Plugin`:
69
+ A plugin of your own is an object with a `name` and the hooks it needs,
70
+ typed by `definePlugin`:
69
71
 
70
72
  ```ts
71
- import { type Plugin } from 'graphql-yoga';
73
+ import { definePlugin } from '@graxia/core';
72
74
 
73
- const slowOperations: Plugin = {
75
+ const slowOperations = definePlugin({
76
+ name: 'slow-operations',
74
77
  onExecute: ({ args }) => {
75
78
  const started = performance.now();
76
- return {
77
- onExecuteDone: () => {
78
- const ms = performance.now() - started;
79
- if (ms > 500) console.warn(`slow operation ${args.operationName ?? 'anonymous'}: ${ms}ms`);
80
- },
79
+ return () => {
80
+ const ms = performance.now() - started;
81
+ if (ms > 500) console.warn(`slow operation ${args.operationName ?? 'anonymous'}: ${ms}ms`);
81
82
  };
82
83
  },
83
- };
84
+ });
84
85
 
85
86
  graphql(app, { schema, plugins: [slowOperations] });
86
87
  ```
87
88
 
88
- Yoga's plugins run inside the route, after the app's middlewares: a plugin
89
- sees only requests the middlewares let through, and its context holds what
90
- they added.
89
+ Two plugins with the same `name` throw a `GraxiaConfigError` where
90
+ `graphql()` is declared. A plugin that adds to the context (`onContext`
91
+ returns the added fields) is the way to give a resolver a value, and what it adds is part of the context the schema is checked against (a `plugins` array literal is read as a tuple, so each plugin's added fields count); for one that
92
+ depends on the request alone, the `context` option does the same
93
+ ([The typed context](context.md#the-context-option)).
94
+
95
+ Graxia's plugins run inside the route, after the app's middlewares: a plugin
96
+ sees only requests the middlewares let through, and its `serverContext` holds
97
+ what they added.
91
98
 
92
99
  ## Errors
93
100
 
94
- Yoga masks errors by default (`maskedErrors: true`): an `Error` thrown by a
95
- resolver reaches the client as `Unexpected error.`, and its message — a
96
- connection string, a stack — stays on the server.
101
+ graxia masks errors by default (`maskErrors: true`; the deprecated
102
+ `maskedErrors: false` is the same as `maskErrors: false`): an `Error` thrown
103
+ by a resolver reaches the client as `Unexpected error.`, with a correlation
104
+ id in `extensions.reference`, and its message — a connection string, a
105
+ stack — stays on the server.
97
106
 
98
107
  ```text
99
- 200 {"errors":[{"message":"Unexpected error.","path":["crash"],"extensions":{"code":"INTERNAL_SERVER_ERROR"}}],"data":{"crash":null}}
108
+ 200 {"errors":[{"message":"Unexpected error.","path":["crash"],"extensions":{"code":"INTERNAL_SERVER_ERROR","reference":"…"}}],"data":{"crash":null}}
100
109
  ```
101
110
 
102
- An error meant for the client is a `GraphQLError`; `createGraphQLError`
103
- makes one, with a code and an HTTP status in its extensions:
111
+ An error meant for the client is made with `exposedError(code, message)`
112
+ from `@graxia/core`, which carries a stable `code` and an optional `fix`:
104
113
 
105
114
  ```ts
106
- import { createGraphQLError } from 'graphql-yoga';
115
+ import { exposedError } from '@graxia/core';
107
116
 
108
117
  const resolvers = {
109
118
  Query: {
110
119
  admin: (_: unknown, __: unknown, { viewer }: GraphQLContext<typeof base>) => {
111
120
  if (viewer !== 'admin')
112
- throw createGraphQLError('Admins only', {
113
- extensions: { code: 'FORBIDDEN', http: { status: 403 } },
114
- });
121
+ throw exposedError('FORBIDDEN', 'Admins only', { fix: 'Sign in as an admin.' });
115
122
  return 'welcome';
116
123
  },
117
124
  },
@@ -119,11 +126,14 @@ const resolvers = {
119
126
  ```
120
127
 
121
128
  ```text
122
- 403 {"errors":[{"message":"Admins only","path":["admin"],"extensions":{"code":"FORBIDDEN"}}],"data":{"admin":null}}
129
+ 200 {"errors":[{"message":"Admins only","path":["admin"],"extensions":{"code":"FORBIDDEN","fix":"Sign in as an admin."}}],"data":{"admin":null}}
123
130
  ```
124
131
 
125
- `maskedErrors: false` sends every message as it is: for development only.
126
- A resolver's error is Yoga's to answer; it never reaches a try/catch
132
+ A `GraphQLError` of your own with no `originalError` is exposed as it is.
133
+ Yoga's `http: { status }` extension is not read: a resolver's error is
134
+ answered with the operation's status (200 under `application/json`).
135
+ `maskErrors: false` sends every message as it is: for development only.
136
+ A resolver's error is graxia's to answer; it never reaches a try/catch
127
137
  middleware before the endpoint, which sees only what fails around it — a
128
138
  middleware that throws, say.
129
139
 
@@ -141,24 +151,26 @@ POST [{"query":"{ admin }"},{"query":"{ __typename }"}]
141
151
  200 [{"data":{"admin":"welcome"}},{"data":{"__typename":"Query"}}]
142
152
  ```
143
153
 
144
- A batch is one request, so one log line and one span: `@alxia/logger` writes
154
+ `batching: true` allows 10 operations. Without it, a batch is refused with
155
+ `400 BATCHING_DISABLED`; one over the limit is `BATCH_TOO_LARGE`. A batch is
156
+ one request, so one log line and one span: `@alxia/logger` writes
145
157
  `operationType: 'batch'` and every name, `operationName: 'GetNotes,AddNote'`,
146
158
  and `@alxia/telemetry` names the span `batch GetNotes,AddNote`
147
159
  ([endpoint guide](endpoint.md#the-operation-in-the-log-and-the-trace)).
148
160
 
149
161
  ## Subscriptions
150
162
 
151
- Subscriptions are served over server-sent events, Yoga's default: a
163
+ Subscriptions are served over server-sent events: a
152
164
  `POST` (or `GET`) with `Accept: text/event-stream` gets a stream of results.
153
165
  A resolver's `subscribe` is an async iterable — an `async *` generator, or
154
- Yoga's `createPubSub`:
166
+ graxia's `createPubSub`:
155
167
 
156
168
  ```ts
157
- import { createPubSub, createSchema } from 'graphql-yoga';
169
+ import { createPubSub, createSchema } from '@graxia/core';
158
170
 
159
- const pubsub = createPubSub<{ message: [{ text: string }] }>();
171
+ const pubsub = createPubSub<{ message: [payload: { text: string }] }>();
160
172
 
161
- const schema = createSchema({
173
+ const schema = createSchema()({
162
174
  typeDefs: /* GraphQL */ `
163
175
  type Query { ok: Boolean }
164
176
  type Mutation { send(text: String!): Boolean! }
@@ -188,19 +200,21 @@ const schema = createSchema({
188
200
 
189
201
  ```sh
190
202
  curl -N localhost:3000/graphql -H 'content-type: application/json' -H 'accept: text/event-stream' \
203
+ -H 'x-graphql-csrf: 1' \
191
204
  -d '{"query":"subscription { countdown(from: 2) }"}'
192
205
  # event: next
193
206
  # data: {"data":{"countdown":2}}
194
207
  # …
195
208
  ```
196
209
 
197
- A subscription asked for with `Accept: application/json` is refused with
198
- `406`. A client that speaks WebSocket — `graphql-ws`, Apollo Client's
199
- `GraphQLWsLink`, urql's `subscriptionExchange` — needs `ws: true`
200
- ([GraphQL over WebSocket](websockets.md)); server-sent events stay served
201
- beside it. `createPubSub` lives in one
202
- process; across several, give it an event target backed by a broker, as
203
- [Yoga's subscriptions guide](https://the-guild.dev/graphql/yoga-server/docs/features/subscriptions)
210
+ A subscription asked for with `Accept: application/json` is refused with an
211
+ error (400 under `application/graphql-response+json`, 200 under
212
+ `application/json`): there is no stream to send it on. A client that speaks WebSocket —
213
+ `graphql-ws`, Apollo Client's `GraphQLWsLink`, urql's `subscriptionExchange` —
214
+ needs `ws: true` ([GraphQL over WebSocket](websockets.md)); server-sent events
215
+ stay served beside it. `createPubSub` lives in one process; across several,
216
+ give it an event target backed by a broker, as
217
+ [graxia's PubSub guide](https://github.com/softistx/graxia/blob/develop/packages/core/docs/guide/pubsub.md)
204
218
  describes.
205
219
 
206
220
  `@alxia/compress` leaves a `text/event-stream` alone by default, so results
@@ -251,12 +265,13 @@ const resolvers = {
251
265
  - `source` is any `AsyncIterable` or `AsyncIterator`. No timer is left behind
252
266
  once the stream has ended.
253
267
 
254
- Yoga's keep-alive pings are not events of the source, so they do not reset
268
+ graxia's keep-alive comments are not events of the source, so they do not reset
255
269
  `idleMs`.
256
270
 
257
271
  ### Keep an idle subscription open
258
272
 
259
- Yoga sends a keep-alive ping on an open stream every 12 seconds. `Bun.serve`
273
+ graxia sends a keep-alive comment on an open stream every 12 seconds
274
+ (`subscriptions.sse.keepAliveMs`). `Bun.serve`
260
275
  closes a connection that has been idle for `idleTimeout` seconds, 10 by
261
276
  default, so on a real server a subscription that has nothing to send is reset
262
277
  at about 8 to 10 seconds, before the first ping. `app.request(…)` in a spec
@@ -274,7 +289,7 @@ than 12 seconds too. See
274
289
 
275
290
  ## CORS
276
291
 
277
- Yoga's own CORS is off (`cors: false`): the endpoint is a route of the app,
292
+ graxia has no CORS of its own: the endpoint is a route of the app,
278
293
  and `@alxia/cors` answers for the whole app, preflights included.
279
294
 
280
295
  ```ts
@@ -290,12 +305,12 @@ const app = alxia()
290
305
 
291
306
  Without it, a browser's preflight `OPTIONS /graphql` is a
292
307
  `405 {"error":"method_not_allowed"}`, and the browser blocks the call.
293
- Passing Yoga's `cors` turns Yoga's on for this endpoint; do not use both.
308
+ A `cors` option is refused where `graphql()` is declared.
294
309
 
295
310
  ## See also
296
311
 
297
312
  - [Mounting the endpoint](endpoint.md): what the endpoint answers.
298
313
  - [The typed context](context.md): the `context` option.
299
314
  - [Harden it for production](production.md): depth limits, introspection off, a body limit, CSRF and persisted operations, run.
300
- - [Troubleshooting](../troubleshooting.md): `Unexpected error.`, the `406`
301
- and the `405`.
315
+ - [Migrating to graxia](../migrating-to-graxia.md): what changed from Yoga.
316
+ - [Troubleshooting](../troubleshooting.md): `Unexpected error.`, the `405`.