@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.
- package/README.md +60 -62
- package/dist/endpoint.d.ts +14 -2
- package/dist/endpoint.d.ts.map +1 -1
- package/dist/executor.d.ts +20 -37
- package/dist/executor.d.ts.map +1 -1
- package/dist/explorer.d.ts +24 -0
- package/dist/explorer.d.ts.map +1 -0
- package/dist/graphql.d.ts +32 -95
- package/dist/graphql.d.ts.map +1 -1
- package/dist/handler.d.ts +7 -34
- package/dist/handler.d.ts.map +1 -1
- package/dist/index.d.ts +3 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +301 -1011
- package/dist/index.js.map +14 -23
- package/dist/once-per-request.d.ts +5 -0
- package/dist/once-per-request.d.ts.map +1 -1
- package/dist/operation.d.ts +2 -7
- package/dist/operation.d.ts.map +1 -1
- package/dist/options.d.ts +38 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/removed.d.ts +14 -0
- package/dist/removed.d.ts.map +1 -0
- package/dist/sandbox.d.ts +3 -17
- package/dist/sandbox.d.ts.map +1 -1
- package/dist/testing/client.d.ts +9 -7
- package/dist/testing/client.d.ts.map +1 -1
- package/dist/testing/index.js +5 -1
- package/dist/testing/index.js.map +3 -3
- package/dist/ws.d.ts +18 -30
- package/dist/ws.d.ts.map +1 -1
- package/docs/README.md +3 -2
- package/docs/guide/context.md +40 -32
- package/docs/guide/endpoint.md +42 -27
- package/docs/guide/executor.md +23 -8
- package/docs/guide/ide.md +27 -64
- package/docs/guide/{yoga.md → plugins.md} +87 -72
- package/docs/guide/production.md +115 -196
- package/docs/guide/testing.md +24 -24
- package/docs/guide/websockets.md +21 -14
- package/docs/migrating-to-graxia.md +283 -0
- package/docs/roadmap.md +7 -11
- package/docs/troubleshooting.md +231 -248
- package/package.json +15 -22
- package/dist/body-refusal.d.ts +0 -25
- package/dist/body-refusal.d.ts.map +0 -1
- package/dist/document-cache.d.ts +0 -39
- package/dist/document-cache.d.ts.map +0 -1
- package/dist/field-rate-limit/count.d.ts +0 -28
- package/dist/field-rate-limit/count.d.ts.map +0 -1
- package/dist/field-rate-limit/from-store.d.ts +0 -21
- package/dist/field-rate-limit/from-store.d.ts.map +0 -1
- package/dist/field-rate-limit/index.d.ts +0 -5
- package/dist/field-rate-limit/index.d.ts.map +0 -1
- package/dist/field-rate-limit/ipv6-network.d.ts +0 -8
- package/dist/field-rate-limit/ipv6-network.d.ts.map +0 -1
- package/dist/field-rate-limit/plugin.d.ts +0 -28
- package/dist/field-rate-limit/plugin.d.ts.map +0 -1
- package/dist/field-rate-limit/types.d.ts +0 -60
- package/dist/field-rate-limit/types.d.ts.map +0 -1
- package/dist/nesting.d.ts +0 -18
- package/dist/nesting.d.ts.map +0 -1
- package/dist/parse-limits.d.ts +0 -50
- package/dist/parse-limits.d.ts.map +0 -1
- package/dist/same-origin/index.d.ts +0 -2
- package/dist/same-origin/index.d.ts.map +0 -1
- package/dist/same-origin/same-origin.d.ts +0 -30
- package/dist/same-origin/same-origin.d.ts.map +0 -1
- package/dist/ws-operations.d.ts +0 -31
- package/dist/ws-operations.d.ts.map +0 -1
- package/dist/ws-server.d.ts +0 -32
- package/dist/ws-server.d.ts.map +0 -1
- package/dist/yoga.d.ts +0 -12
- package/dist/yoga.d.ts.map +0 -1
|
@@ -1,16 +1,16 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Graxia's plugins and options
|
|
2
2
|
|
|
3
|
-
This page covers what passes through to
|
|
4
|
-
Envelop's, error masking, batching, subscriptions over server-sent events
|
|
5
|
-
(and over WebSocket with [`ws`](websockets.md)),
|
|
6
|
-
|
|
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
|
|
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
|
|
31
|
-
|
|
28
|
+
`GraphQLOptions` is graxia's `GraxiaOptions`, minus the keys the package owns
|
|
29
|
+
or maps:
|
|
32
30
|
|
|
33
|
-
|
|
|
31
|
+
| graxia's option | Here |
|
|
34
32
|
| --- | --- |
|
|
35
|
-
| `
|
|
36
|
-
| `
|
|
37
|
-
| `
|
|
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
|
|
41
|
-
`
|
|
42
|
-
|
|
43
|
-
|
|
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
|
|
48
|
-
|
|
49
|
-
|
|
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
|
|
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 {
|
|
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
|
|
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 {
|
|
73
|
+
import { definePlugin } from '@graxia/core';
|
|
72
74
|
|
|
73
|
-
const slowOperations
|
|
75
|
+
const slowOperations = definePlugin({
|
|
76
|
+
name: 'slow-operations',
|
|
74
77
|
onExecute: ({ args }) => {
|
|
75
78
|
const started = performance.now();
|
|
76
|
-
return {
|
|
77
|
-
|
|
78
|
-
|
|
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
|
-
|
|
89
|
-
|
|
90
|
-
|
|
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
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
|
103
|
-
|
|
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 {
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
126
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
166
|
+
graxia's `createPubSub`:
|
|
155
167
|
|
|
156
168
|
```ts
|
|
157
|
-
import { createPubSub, createSchema } from '
|
|
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
|
-
|
|
199
|
-
`
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
- [
|
|
301
|
-
|
|
315
|
+
- [Migrating to graxia](../migrating-to-graxia.md): what changed from Yoga.
|
|
316
|
+
- [Troubleshooting](../troubleshooting.md): `Unexpected error.`, the `405`.
|