@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
package/README.md
CHANGED
|
@@ -1,29 +1,23 @@
|
|
|
1
1
|
# @alxia/graphql
|
|
2
2
|
|
|
3
3
|
GraphQL for [alxia](https://www.npmjs.com/package/@alxia/core), served by
|
|
4
|
-
[
|
|
4
|
+
[`@graxia/core`](https://www.npmjs.com/package/@graxia/core). The endpoint is a
|
|
5
5
|
route like any other: behind the app's middlewares, guarded by its guards, its
|
|
6
6
|
resolvers reading the context those middlewares built — typed, and checked.
|
|
7
|
-
|
|
7
|
+
Graxia's plugin system is yours whole: `plugins` takes its hooks, and
|
|
8
|
+
`@graxia/envelop` (install it yourself) adapts an Envelop plugin.
|
|
8
9
|
|
|
9
10
|
```sh
|
|
10
|
-
bun add @alxia/graphql
|
|
11
|
+
bun add @alxia/graphql @graxia/core @graxia/graphiql graphql @alxia/core
|
|
11
12
|
bun add -d typescript
|
|
13
|
+
bun add @graxia/envelop @envelop/depth-limit # install yourself to use Envelop plugins
|
|
12
14
|
```
|
|
13
15
|
|
|
14
|
-
`
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
`logging` value, and its `@graphql-yoga/plugin-*` 4.x need Yoga 6.
|
|
20
|
-
|
|
21
|
-
Yoga's own request id is off (`requestId: false`): a client-sent `x-request-id`
|
|
22
|
-
is never echoed or logged, so the app's own id is the only one. Passing
|
|
23
|
-
`requestId: true` or an object keeps `trustHeader: false` unless you set it.
|
|
24
|
-
Yoga 5 ignores `requestId`. `logging` defaults to `'warn'` on both majors, so
|
|
25
|
-
Yoga 6's per-request INFO line is off and an app that never set `logging` no
|
|
26
|
-
longer sees Yoga's info lines; pass `logging: true` or `'info'` to get them.
|
|
16
|
+
`@graxia/core` (`^0.10.0`), `@graxia/graphiql` (`^0.2.4`) and `graphql` (17.1 or later) are peers:
|
|
17
|
+
the package declares no dependency. `@graxia/graphiql` serves the IDE and is
|
|
18
|
+
required. CSRF protection is graxia's default (on): a `GET` needs one of the
|
|
19
|
+
`x-graphql-csrf`, `graphql-require-preflight`, `apollo-require-preflight` or
|
|
20
|
+
`x-apollo-operation-name` headers.
|
|
27
21
|
|
|
28
22
|
## Usage
|
|
29
23
|
|
|
@@ -31,13 +25,13 @@ longer sees Yoga's info lines; pass `logging: true` or `'info'` to get them.
|
|
|
31
25
|
import { alxia } from '@alxia/core';
|
|
32
26
|
import { graphql, type GraphQLContext } from '@alxia/graphql';
|
|
33
27
|
import { bearer } from '@alxia/jwt';
|
|
34
|
-
import { createSchema } from '
|
|
28
|
+
import { createSchema } from '@graxia/core';
|
|
35
29
|
|
|
36
30
|
const base = alxia()
|
|
37
31
|
.decorate({ db })
|
|
38
32
|
.use(bearer({ jwt, schema: Claims })); // every route after it needs a token
|
|
39
33
|
|
|
40
|
-
const schema = createSchema<GraphQLContext<typeof base>>({
|
|
34
|
+
const schema = createSchema<GraphQLContext<typeof base>>()({
|
|
41
35
|
typeDefs: /* GraphQL */ `type Query { me: String! }`,
|
|
42
36
|
resolvers: {
|
|
43
37
|
Query: { me: (_, __, { user, db }) => db.name(user.sub) }, // user and db typed
|
|
@@ -54,7 +48,7 @@ to `app.plugin` as a function, it stays in the chain and sees the app's type.
|
|
|
54
48
|
|
|
55
49
|
## The context
|
|
56
50
|
|
|
57
|
-
A resolver's context is
|
|
51
|
+
A resolver's context is graxia's (`request`, `params`), the app's — every
|
|
58
52
|
`decorate`, every `derive`, every middleware's: `user`, `db`, `log`,
|
|
59
53
|
`requestId` — and `set`, through which it sets a header or a cookie:
|
|
60
54
|
|
|
@@ -77,7 +71,7 @@ the schema's resolvers read a context the app does not build: missing user
|
|
|
77
71
|
A field that loads a record per parent — `Note.author` over 50 notes — is
|
|
78
72
|
51 queries. Build [DataLoaders](https://github.com/graphql/dataloader) in
|
|
79
73
|
the `context` option and type them through `GraphQLContext`'s second
|
|
80
|
-
argument. (
|
|
74
|
+
argument. (The `batching` option, below, is another thing: several
|
|
81
75
|
operations in one HTTP request.)
|
|
82
76
|
|
|
83
77
|
```sh
|
|
@@ -92,7 +86,7 @@ const createLoaders = () => ({
|
|
|
92
86
|
});
|
|
93
87
|
type Loaders = ReturnType<typeof createLoaders>;
|
|
94
88
|
|
|
95
|
-
const schema = createSchema<GraphQLContext<typeof base, { loaders: Loaders }>>({
|
|
89
|
+
const schema = createSchema<GraphQLContext<typeof base, { loaders: Loaders }>>()({
|
|
96
90
|
typeDefs,
|
|
97
91
|
resolvers: { Note: { author: (note: { authorId: string }, _, { loaders }) => loaders.user.load(note.authorId) } },
|
|
98
92
|
});
|
|
@@ -138,25 +132,25 @@ const resolvers = freshPerMutation({ Query, Mutation, Ward });
|
|
|
138
132
|
It takes no dependency: `dataloader` stays yours. See
|
|
139
133
|
[One value per request](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/guide/context.md#one-value-per-request).
|
|
140
134
|
|
|
141
|
-
##
|
|
135
|
+
## Graxia's plugins
|
|
142
136
|
|
|
143
|
-
Every
|
|
144
|
-
sets, and
|
|
137
|
+
Every `createGraxia` option passes through, but the endpoint path, which `path`
|
|
138
|
+
sets, and the IDE, which `ide` decides:
|
|
145
139
|
|
|
146
140
|
```ts
|
|
147
141
|
import { useDepthLimit } from '@envelop/depth-limit';
|
|
148
|
-
import {
|
|
142
|
+
import { fromEnvelop } from '@graxia/envelop';
|
|
149
143
|
|
|
150
144
|
graphql(app, {
|
|
151
145
|
schema,
|
|
152
|
-
plugins: [useDepthLimit({ maxDepth: 8 })
|
|
153
|
-
maskedErrors: true, //
|
|
146
|
+
plugins: [fromEnvelop(useDepthLimit({ maxDepth: 8 }))],
|
|
147
|
+
maskedErrors: true, // the default: an error's message never leaks
|
|
154
148
|
ide: Bun.env.NODE_ENV === 'development' && 'apollo-sandbox', // at runtime, never process.env: bun build inlines it
|
|
155
149
|
batching: true,
|
|
156
150
|
});
|
|
157
151
|
```
|
|
158
152
|
|
|
159
|
-
- **Subscriptions** are served over server-sent events
|
|
153
|
+
- **Subscriptions** are served over server-sent events:
|
|
160
154
|
`async *subscribe` in a resolver, `Accept: text/event-stream` on the
|
|
161
155
|
request; over WebSocket too with [`ws: true`](#websocket). `@alxia/compress` leaves an event stream alone by default.
|
|
162
156
|
- **An IDE** answers a `GET` from a browser at the endpoint, with a
|
|
@@ -172,12 +166,12 @@ graphql(app, {
|
|
|
172
166
|
|
|
173
167
|
| `ide` | |
|
|
174
168
|
| --- | --- |
|
|
175
|
-
| none (default) |
|
|
176
|
-
| `'graphiql'` |
|
|
177
|
-
| `'apollo-sandbox'` | [Apollo Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox), embedded, pointed at the address the page was opened at, prefix included — `https` behind a proxy that terminates TLS ([IDE guide](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/guide/ide.md#apollo-sandbox)). `sandbox` takes `title`, `initialDocument`, `initialHeaders`, `
|
|
169
|
+
| none (default) | GraphiQL in dev (`isDev`), nothing otherwise |
|
|
170
|
+
| `'graphiql'` | GraphiQL (`@graxia/graphiql`), everywhere; `graphiql` takes its options |
|
|
171
|
+
| `'apollo-sandbox'` | [Apollo Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox), embedded, pointed at the address the page was opened at, prefix included — `https` behind a proxy that terminates TLS ([IDE guide](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/guide/ide.md#apollo-sandbox)). `sandbox` takes `title`, `initialDocument`, `initialHeaders`, `includeCookies` |
|
|
178
172
|
| `false` | none |
|
|
179
|
-
- **CORS** is `@alxia/cors`'s for the whole app
|
|
180
|
-
`
|
|
173
|
+
- **CORS** is `@alxia/cors`'s for the whole app; `cors` is not an option of
|
|
174
|
+
`graphql()`.
|
|
181
175
|
|
|
182
176
|
## Which operation ran
|
|
183
177
|
|
|
@@ -186,7 +180,9 @@ which operation it executes. Behind `use(logger())` the request's line
|
|
|
186
180
|
carries `operationName` and `operationType`, and behind
|
|
187
181
|
`use(telemetry({ … }))` its span is named `query GetNotes`, with
|
|
188
182
|
OpenTelemetry's `graphql.operation.name` and `graphql.operation.type`. A
|
|
189
|
-
batched body is one line and one span, `batch`, with every name.
|
|
183
|
+
batched body is one line and one span, `batch`, with every name. graxia's
|
|
184
|
+
own operation span is off by default (`telemetry: { operationSpans: false }`), so an operation is one span, with graxia's parse, validate and execute spans under it; see
|
|
185
|
+
[graxia's own spans](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/guide/endpoint.md#graxias-own-spans).
|
|
190
186
|
|
|
191
187
|
```ts
|
|
192
188
|
const app = alxia()
|
|
@@ -205,10 +201,9 @@ and [the WebSocket guide](https://github.com/softistx/alxia/blob/develop/package
|
|
|
205
201
|
## WebSocket
|
|
206
202
|
|
|
207
203
|
`ws: true` serves the endpoint over WebSocket too, with the
|
|
208
|
-
`graphql-transport-ws` protocol
|
|
209
|
-
the default of Apollo Client's `GraphQLWsLink` and urql's
|
|
210
|
-
`subscriptionExchange`.
|
|
211
|
-
events stay served at the same path. Install it with `bun add graphql-ws`.
|
|
204
|
+
`graphql-transport-ws` protocol, spoken by graxia itself (no extra
|
|
205
|
+
install), the default of Apollo Client's `GraphQLWsLink` and urql's
|
|
206
|
+
`subscriptionExchange`. Server-sent events stay served at the same path.
|
|
212
207
|
|
|
213
208
|
```ts
|
|
214
209
|
const app = base.plugin((app) => graphql(app, { schema, ws: true })); // ws://…/graphql too
|
|
@@ -223,7 +218,7 @@ const client = createClient({ url: 'wss://api.example.com/graphql', connectionPa
|
|
|
223
218
|
The upgrade runs the app's middlewares — a guard's `401` refuses the
|
|
224
219
|
socket, what they add is in the context, beside the `connectionParams`
|
|
225
220
|
the client sent — each operation runs through
|
|
226
|
-
|
|
221
|
+
graxia's plugins, and a shutdown closes the sockets with `1001`, completing
|
|
227
222
|
their subscriptions. `ws: { path, keepAlive }` moves the socket or spaces
|
|
228
223
|
its pings. See [the WebSocket guide](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/guide/websockets.md),
|
|
229
224
|
Apollo Client's and urql's setup included.
|
|
@@ -251,34 +246,38 @@ const subscribe = (
|
|
|
251
246
|
|
|
252
247
|
The stream ends cleanly when idle or old, throws when `check` throws, and
|
|
253
248
|
releases the source as soon as the client leaves. See
|
|
254
|
-
[
|
|
249
|
+
[the plugins and options guide](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/guide/plugins.md#bound-a-subscription).
|
|
255
250
|
|
|
256
251
|
## Limits
|
|
257
252
|
|
|
258
253
|
Four limits bound what a request costs before any resolver runs. A document
|
|
259
|
-
may hold at most **15 000 tokens** (`
|
|
254
|
+
may hold at most **15 000 tokens** (`limits.tokens`, or the deprecated `maxTokens`; `false` for no cap): a longer
|
|
260
255
|
one is refused by the parser as `GRAPHQL_PARSE_FAILED`, 400 under
|
|
261
256
|
`application/graphql-response+json`, and never reaches the schema. It may
|
|
262
|
-
nest at most **1 000 levels** of `{`, `(` and `[` (`
|
|
263
|
-
no limit): graphql-js parses by recursion and overflows the stack a few
|
|
257
|
+
nest at most **1 000 levels** of `{`, `(` and `[` (`limits.nesting`, or the deprecated
|
|
258
|
+
`maxNesting`; `false` for no limit): graphql-js parses by recursion and overflows the stack a few
|
|
264
259
|
thousand levels down, so a deeper document is refused the same way before the
|
|
265
260
|
parser recurses into it, never a 500. It counts `{`, `(` and `[` together,
|
|
266
261
|
arguments and lists included, so it is not a selection-depth rule; use a
|
|
267
262
|
validation rule for that. The
|
|
268
|
-
documents
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
263
|
+
documents graxia parses are kept in a cache (`caches.parse`, or the
|
|
264
|
+
deprecated `parseCache`; `caches: false` for none). A `POST` body may hold **1 MiB** (`bodyLimit`, graxia's `limits.bodyBytes`) unless the
|
|
265
|
+
app declared its own `bodyLimit()` before `graphql()`, which graxia then
|
|
266
|
+
enforces; a body past it is a `413` with `extensions.code: 'BODY_TOO_LARGE'`,
|
|
267
|
+
declared by `Content-Length` or counted as it arrives. Every refusal graxia
|
|
268
|
+
builds before execution has a stable code (`UNSUPPORTED_MEDIA_TYPE` 415,
|
|
269
|
+
`BODY_NOT_JSON` 400, `PARAMS_INVALID` 400, `NOT_ACCEPTABLE` 406…): match
|
|
270
|
+
`errors[0].extensions.code`, never the message
|
|
271
|
+
([the table](https://github.com/softistx/graxia/blob/develop/packages/core/docs/guide/http.md#refusal-codes);
|
|
272
|
+
`GraxiaErrorCode` is re-exported as a type). Under `Accept: application/json` (the default) a 400 refusal is a `200`; `413`, `415`, `404`, `405` and `406` never change. `bodyLimit` bounds a `POST`
|
|
273
273
|
alone: a WebSocket `subscribe` message is bounded by Bun's `maxPayloadLength`
|
|
274
274
|
(16 MiB by default):
|
|
275
275
|
|
|
276
276
|
```ts
|
|
277
277
|
graphql(app, {
|
|
278
278
|
schema,
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
parseCache: { maxBytes: 32 * 1024 * 1024, max: 512, ttl: 30 * 60_000 }, // false: no cache
|
|
279
|
+
limits: { tokens: 20_000, nesting: 2_000 }, // false: no cap
|
|
280
|
+
caches: { parse: { max: 512, ttlMs: 30 * 60_000 } }, // false: no cache
|
|
282
281
|
bodyLimit: 5 * 1024 * 1024, // 1 MiB by default; a multipart upload needs more
|
|
283
282
|
});
|
|
284
283
|
```
|
|
@@ -294,7 +293,7 @@ A client query is a few thousand tokens; the introspection query is 163. See
|
|
|
294
293
|
|
|
295
294
|
A limit on HTTP requests counts one request however many times it selects
|
|
296
295
|
`signIn` under aliases (`a: signIn(...) b: signIn(...) …`). `fieldRateLimit`
|
|
297
|
-
is a
|
|
296
|
+
is a graxia plugin that walks the operation about to run, aliases, inline
|
|
298
297
|
fragments and fragment spreads expanded, and consumes the number of
|
|
299
298
|
selections of each chosen field on a limit keyed by the client. Past the
|
|
300
299
|
limit nothing executes: a 429 `RATE_LIMITED` (the `code` option names it
|
|
@@ -407,31 +406,30 @@ See
|
|
|
407
406
|
|
|
408
407
|
| export | |
|
|
409
408
|
| --- | --- |
|
|
410
|
-
| `graphql(app, options)` | the endpoint: `schema`, `path`, `ide`, `sandbox`, `ws`, `
|
|
411
|
-
| `graphqlExecutor(options)` | `(request: { query, operationName?, variables? }, context, { signal? }?) => Promise<{ data?, errors? }
|
|
409
|
+
| `graphql(app, options)` | the endpoint: `schema`, `path`, `ide`, `sandbox`, `ws`, `limits`, `caches`, `csrf`, `maskErrors`, `bodyLimit`, and every `createGraxia` option (the older `maxTokens`, `maxNesting`, `parseCache` and `maskedErrors` still map, deprecated) |
|
|
410
|
+
| `graphqlExecutor(options)` | `(request: { query, operationName?, variables? }, context, { signal? }?) => Promise<{ data?, errors? }>` with a `dispose()`: a query or mutation in process, through the options of `graphql()` without the route's (`path`, `ide`, `ws`, `bodyLimit`) |
|
|
412
411
|
| `ExecutorRequest`, `ExecutorResult`, `ExecutorError`, `ExecutorCall`, `GraphQLExecutor`, `GraphQLExecutorOptions` | its types |
|
|
413
412
|
| `GraphQLWsOptions` | `ws`'s options: `path`, `keepAlive` |
|
|
414
413
|
| `GraphQLWsContext` | what an operation over WebSocket adds to the context: `connectionParams` |
|
|
415
|
-
| `
|
|
416
|
-
| `SandboxOptions` | its options: `title`, `initialDocument`, `initialHeaders`, `pollForSchemaUpdates`, `includeCookies` |
|
|
414
|
+
| `SandboxOptions` | its options: `title`, `initialDocument`, `initialHeaders`, `includeCookies` |
|
|
417
415
|
| `GraphQLContext<App, UserContext?>` | what a resolver reads |
|
|
418
416
|
| `oncePerRequest(request, key, load)` | `load()`'s value, computed at most once per request object and `key` (a `string`); returns `T`, a promise kept as the same promise, a throw or rejection not kept |
|
|
419
417
|
| `clearRequestCache(request)` | empties what `oncePerRequest` kept for that request object; the next call loads again; returns `void` |
|
|
420
|
-
| `freshPerMutation(resolvers)` | the same resolvers (same type) with each function of `Mutation` wrapped to call `clearRequestCache(context)` first: each root mutation field starts empty, its sub-fields share, a query is untouched |
|
|
421
|
-
| `fieldRateLimit({ fields, key?, ipv6Prefix?, code? })` | a
|
|
422
|
-
| `sameOrigin({ allow?, json?, refuse? })` | a Yoga plugin, listed first, for a cookie-authenticated endpoint: 403 `FORBIDDEN` (no CORS header) for a request whose `Origin` is not the endpoint's host nor in `allow` (`Origin: null` included), and for a `POST` that is not `application/json` unless `json: false`; `refuse(request)` chooses the answer; no `Origin` passes |
|
|
423
|
-
| `SameOriginOptions` | its options |
|
|
418
|
+
| `freshPerMutation(resolvers)` | the same resolvers (same type; an array of maps gives an array) with each function of `Mutation` wrapped to call `clearRequestCache(context)` first: each root mutation field starts empty, its sub-fields share, a query is untouched |
|
|
419
|
+
| `fieldRateLimit({ fields, key?, ipv6Prefix?, code? })` | re-exported from `@graxia/core`, a plugin, listed first: consumes the number of selections (aliases and fragments expanded) of each chosen field on its limit, keyed by `key(context)` (the client address by default, its IPv6 network under `ipv6Prefix`); 429 `RATE_LIMITED` (`code`) with `retryAfter`, or 400 `FIELD_SELECTED_ONCE` for a `single` field; units spent before a refusal stay spent |
|
|
424
420
|
| `limitFromStore(store, policy?)` | an `@alxia/rate-limit` store as a `FieldLimit`: one consume per unit of cost, stopped at the first refusal (up to `limit + 1` round trips); `policy` may come from `store.policy` and must not differ from it |
|
|
425
421
|
| `FieldLimit`, `FieldDecision`, `FieldRule`, `FieldRateLimitOptions`, `CostlessStore` | their types |
|
|
426
422
|
| `boundedStream(source, options)` | `source` (an `AsyncIterable` or `AsyncIterator`) as an `AsyncIterableIterator<T>` for a subscription's `subscribe`: ends cleanly after `idleMs` without an event and `totalMs` in all, runs `check` every `checkEveryMs` and before an event when the last check is `checkDebounceMs` old, throws `mapError(error)` when `check` fails or the source itself throws, and calls the source's `return()` on disconnect or any end |
|
|
427
423
|
| `BoundedStreamOptions` | its options: `idleMs`, `totalMs`, `checkEveryMs`, `checkDebounceMs?`, `check`, `mapError?`, `signal?` |
|
|
424
|
+
| `GraphQLContextInit<App>` | the parameter of a `context` factory that reads `serverContext`, typed from the app: `({ serverContext }: GraphQLContextInit<typeof app>) => …` |
|
|
428
425
|
| `ServerContext<Ctx>`, `GraphQLOptions` | its types |
|
|
429
|
-
| `
|
|
426
|
+
| `GraxiaErrorCode` | graxia's union of refusal codes (`BODY_TOO_LARGE`, `CSRF_HEADER_REQUIRED`, …), re-exported as a type |
|
|
427
|
+
| `graphqlClient(app, { path?, headers?, method?, csrfHeader? })` (`@alxia/graphql/testing`) | `query(document, { variables?, operationName?, headers?, method?, extensions?, persisted? })`, or `query({ persisted })` with no document, in process: `{ status, data?, errors?, response }` |
|
|
430
428
|
| `GraphQLClient`, `GraphQLResult`, `QueryDocument`, `QueryOptions`, `PersistedQueryOptions`, `HttpMethod`, `GraphQLClientOptions`, `ResponseError` (`@alxia/graphql/testing`) | its types |
|
|
431
429
|
|
|
432
430
|
## Documentation
|
|
433
431
|
|
|
434
|
-
- [Guide](https://github.com/softistx/alxia/tree/develop/packages/graphql/docs): a page per area — mounting the endpoint, the typed context,
|
|
432
|
+
- [Guide](https://github.com/softistx/alxia/tree/develop/packages/graphql/docs): a page per area — mounting the endpoint, the typed context, graxia's plugins and options, GraphQL over WebSocket, running operations in process, GraphiQL and Apollo Sandbox, and [hardening an API for production](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/guide/production.md) (rate limits, depth limits, introspection, errors, body size, CSRF, persisted operations).
|
|
435
433
|
- [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/troubleshooting.md): an error message, and what to do about it.
|
|
436
434
|
- [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/roadmap.md): what is coming, and what is not planned.
|
|
437
435
|
- [Recipes](https://github.com/softistx/alxia/blob/develop/docs/recipes/README.md): [A GraphQL API](https://github.com/softistx/alxia/blob/develop/docs/recipes/graphql-api.md), [Authenticate requests](https://github.com/softistx/alxia/blob/develop/docs/recipes/authentication.md), [Test an alxia app](https://github.com/softistx/alxia/blob/develop/docs/recipes/testing.md), [Health checks and graceful shutdown](https://github.com/softistx/alxia/blob/develop/docs/recipes/health-and-shutdown.md), and more.
|
package/dist/endpoint.d.ts
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
import type { Alxia } from '@alxia/core';
|
|
2
2
|
import type { graphqlSocket } from './ws';
|
|
3
|
-
/** `
|
|
4
|
-
export
|
|
3
|
+
/** What `declareEndpoint` asks its caller to build once the body limit is known. */
|
|
4
|
+
export interface Mounted {
|
|
5
|
+
readonly handler: (ctx: never) => unknown;
|
|
6
|
+
readonly socket: ReturnType<typeof graphqlSocket> | undefined;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* `GET` and `POST` at `path` on `app`, and the WebSocket when `ws` is on.
|
|
10
|
+
* `mount` receives the bytes graxia's `limits.bodyBytes` must hold: the
|
|
11
|
+
* option, else the `bodyLimit()` the app declared before, else 1 MiB.
|
|
12
|
+
* A bad limit, the option or an inherited `bodyLimit(0)` (core accepts 0,
|
|
13
|
+
* graxia does not), throws before any route is declared, so the app stays
|
|
14
|
+
* as it was.
|
|
15
|
+
*/
|
|
16
|
+
export declare function declareEndpoint(app: Alxia<never, string>, path: string, bodyLimit: number | undefined, mount: (bodyBytes: number) => Mounted): void;
|
|
5
17
|
//# sourceMappingURL=endpoint.d.ts.map
|
package/dist/endpoint.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../src/endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../src/endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAY1C,oFAAoF;AACpF,MAAM,WAAW,OAAO;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,GAAG,SAAS,CAAC;CAC9D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC9B,GAAG,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,EACzB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,GACnC,IAAI,CA0BN"}
|
package/dist/executor.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { Empty } from '@alxia/core';
|
|
2
|
-
import
|
|
3
|
-
import type {
|
|
4
|
-
import type
|
|
2
|
+
import { type GraxiaOptions } from '@graxia/core';
|
|
3
|
+
import type { GraphQLSchema } from 'graphql';
|
|
4
|
+
import { type LegacyOptions } from './options';
|
|
5
5
|
/** What an in-process call asks for: a GraphQL-over-HTTP request's parameters. */
|
|
6
6
|
export interface ExecutorRequest {
|
|
7
7
|
readonly query: string;
|
|
@@ -25,42 +25,25 @@ export interface ExecutorResult {
|
|
|
25
25
|
}
|
|
26
26
|
/** Per call: the signal that stops the operation, as a client leaving does. */
|
|
27
27
|
export interface ExecutorCall {
|
|
28
|
+
/**
|
|
29
|
+
* An aborted signal, before the call or while it runs, resolves to
|
|
30
|
+
* `{ errors: [{ extensions: { code: 'OPERATION_ABORTED' } }] }`: it never rejects.
|
|
31
|
+
*/
|
|
28
32
|
readonly signal?: AbortSignal;
|
|
29
33
|
}
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
/** The schema, as for `graphql()`. */
|
|
37
|
-
readonly schema: GraphQLSchemaWithContext<SchemaCtx>;
|
|
38
|
-
/** At most this many tokens in a document, 15 000 by default, or `false`. */
|
|
39
|
-
readonly maxTokens?: number | false;
|
|
40
|
-
/** At most this many levels of `{`, `(` and `[`, 1 000 by default, or `false`. */
|
|
41
|
-
readonly maxNesting?: number | false;
|
|
42
|
-
/** The cache of parsed documents, this executor's own. `false` parses every call. */
|
|
43
|
-
readonly parseCache?: false | ParseCacheOptions;
|
|
34
|
+
export interface GraphQLExecutorOptions<SchemaCtx = unknown> extends Omit<GraxiaOptions<any, GraphQLSchema, any, any>, 'path' | 'schema' | 'subscriptions' | 'context' | 'plugins'>, LegacyOptions {
|
|
35
|
+
readonly schema: GraphQLSchema & {
|
|
36
|
+
readonly '~context'?: SchemaCtx;
|
|
37
|
+
};
|
|
38
|
+
readonly context?: GraxiaOptions['context'];
|
|
39
|
+
readonly plugins?: GraxiaOptions['plugins'];
|
|
44
40
|
}
|
|
45
41
|
/** Runs one operation in process. */
|
|
46
|
-
export type GraphQLExecutor<ServerCtx> = (request: ExecutorRequest, context: ServerCtx, call?: ExecutorCall) => Promise<ExecutorResult
|
|
47
|
-
/**
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
*
|
|
54
|
-
* ```ts
|
|
55
|
-
* const execute = graphqlExecutor({ schema, plugins: [useJanus(...)] });
|
|
56
|
-
* const { data, errors } = await execute(
|
|
57
|
-
* { query: '{ me { id } }' },
|
|
58
|
-
* { viewer, services },
|
|
59
|
-
* );
|
|
60
|
-
* ```
|
|
61
|
-
*
|
|
62
|
-
* It does not run `graphql()`'s middlewares: the context is whatever is
|
|
63
|
-
* passed. It keeps its own parse cache, apart from the route's.
|
|
64
|
-
*/
|
|
65
|
-
export declare function graphqlExecutor<SchemaCtx, UserCtx extends YogaContext = Empty, ServerCtx = Omit<SchemaCtx, keyof YogaInitialContext>>(options: GraphQLExecutorOptions<YogaContext, UserCtx, SchemaCtx>): GraphQLExecutor<ServerCtx>;
|
|
42
|
+
export type GraphQLExecutor<ServerCtx> = ((request: ExecutorRequest, context: ServerCtx, call?: ExecutorCall) => Promise<ExecutorResult>) & {
|
|
43
|
+
/** Releases what the instance holds (plugins' `onDispose`, in-flight operations). A call after it rejects. */
|
|
44
|
+
dispose(): Promise<void>;
|
|
45
|
+
};
|
|
46
|
+
/** Runs a GraphQL operation in the process, through `graxia.execute`. Queries and mutations only (graxia refuses a subscription). */
|
|
47
|
+
export declare function graphqlExecutor<SchemaCtx, ServerCtx = Omit<SchemaCtx, 'signal'>>(options: GraphQLExecutorOptions<SchemaCtx>): GraphQLExecutor<ServerCtx>;
|
|
48
|
+
export type { Empty };
|
|
66
49
|
//# sourceMappingURL=executor.d.ts.map
|
package/dist/executor.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE9D,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CACnE;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxD;AAED,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CAC3C;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAsB,CAAC,SAAS,GAAG,OAAO,CAC1D,SAAQ,IAAI,CACV,aAAa,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,CAAC,EAC3C,MAAM,GAAG,QAAQ,GAAG,eAAe,GAAG,SAAS,GAAG,SAAS,CAC3D,EACD,aAAa;IACd,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CAC5C;AAED,qCAAqC;AACrC,MAAM,MAAM,eAAe,CAAC,SAAS,IAAI,CAAC,CACzC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,YAAY,KACf,OAAO,CAAC,cAAc,CAAC,CAAC,GAAG;IAC/B,8GAA8G;IAC9G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB,CAAC;AASF,qIAAqI;AACrI,wBAAgB,eAAe,CAC9B,SAAS,EACT,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,EACpC,OAAO,EAAE,sBAAsB,CAAC,SAAS,CAAC,GAAG,eAAe,CAAC,SAAS,CAAC,CAiCxE;AACD,YAAY,EAAE,KAAK,EAAE,CAAC"}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/** The IDE of `graphql()`: graxia's GraphiQL or Apollo Sandbox plugin, from alxia's `ide` options. */
|
|
2
|
+
import type { GraxiaPlugin } from '@graxia/core';
|
|
3
|
+
import { type GraphiQLOptions } from '@graxia/graphiql';
|
|
4
|
+
import type { SandboxOptions } from './sandbox';
|
|
5
|
+
/**
|
|
6
|
+
* The requests the endpoint handler has seen, with the app's dev flag at the
|
|
7
|
+
* moment of each: what the IDE's `enabled` function reads, since graxia hands
|
|
8
|
+
* it the `Request` alone.
|
|
9
|
+
*/
|
|
10
|
+
export type DevOfRequest = WeakMap<Request, boolean>;
|
|
11
|
+
export interface ExplorerOptions {
|
|
12
|
+
readonly ide?: 'graphiql' | 'apollo-sandbox' | false | undefined;
|
|
13
|
+
readonly graphiql?: GraphiQLOptions | false | undefined;
|
|
14
|
+
readonly sandbox?: SandboxOptions | undefined;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* The IDE plugins: Sandbox for `ide: 'apollo-sandbox'`, nothing for
|
|
18
|
+
* `ide: false` or `graphiql: false`, GraphiQL otherwise. By default GraphiQL
|
|
19
|
+
* answers while the serving app is in dev (`alxia({ dev })`, else
|
|
20
|
+
* `NODE_ENV=development`, read per request from `devs`, which the endpoint
|
|
21
|
+
* handler fills), and everywhere under `ide: 'graphiql'`.
|
|
22
|
+
*/
|
|
23
|
+
export declare function explorerPlugins(options: ExplorerOptions, devs: DevOfRequest): GraxiaPlugin<any, any>[];
|
|
24
|
+
//# sourceMappingURL=explorer.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"explorer.d.ts","sourceRoot":"","sources":["../src/explorer.ts"],"names":[],"mappings":"AAAA,sGAAsG;AAEtG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAGN,KAAK,eAAe,EAGpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAErD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,GAAG,gBAAgB,GAAG,KAAK,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,GAAG,KAAK,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CAC9C;AA0BD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,YAAY,GAChB,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAW1B"}
|
package/dist/graphql.d.ts
CHANGED
|
@@ -1,126 +1,63 @@
|
|
|
1
1
|
import type { Alxia, BaseContext, Empty, RoutePath } from '@alxia/core';
|
|
2
|
-
import type
|
|
3
|
-
import {
|
|
4
|
-
import type {
|
|
2
|
+
import { type ContextInit, type ContextOf, type CoreContext, type GraxiaOptions, type GraxiaPlugin } from '@graxia/core';
|
|
3
|
+
import type { GraphiQLOptions } from '@graxia/graphiql';
|
|
4
|
+
import type { GraphQLSchema } from 'graphql';
|
|
5
|
+
import { type LegacyOptions, type RemovedOptions } from './options';
|
|
5
6
|
import type { SandboxOptions } from './sandbox';
|
|
6
7
|
import { type GraphQLWsOptions } from './ws';
|
|
7
|
-
/** The parts of a route's context
|
|
8
|
+
/** The parts of a route's context graxia owns, or that mean nothing to a resolver. */
|
|
8
9
|
type RouteOnly = 'params' | 'query' | 'headers' | 'cookies' | 'body' | 'reply' | 'redirect';
|
|
9
10
|
/**
|
|
10
|
-
* What alxia hands
|
|
11
|
-
*
|
|
12
|
-
* which a resolver sets a cookie or a header on the response.
|
|
11
|
+
* What alxia hands graxia for each request as its `serverContext`: the
|
|
12
|
+
* context its middlewares built with `request`, `url`, `ip` and `set`.
|
|
13
13
|
*/
|
|
14
14
|
export type ServerContext<Ctx> = Omit<BaseContext & Ctx, RouteOnly>;
|
|
15
|
-
/**
|
|
16
|
-
* What an operation over WebSocket adds to its context (`ws` on): the
|
|
17
|
-
* `connectionParams` the client sent when it connected. `undefined` over
|
|
18
|
-
* HTTP, and for a client that sent none.
|
|
19
|
-
*/
|
|
15
|
+
/** What an operation over WebSocket adds to its context: the client's `connectionParams`. */
|
|
20
16
|
export interface GraphQLWsContext {
|
|
21
17
|
readonly connectionParams?: Readonly<Record<string, unknown>>;
|
|
22
18
|
}
|
|
23
19
|
/**
|
|
24
|
-
* What a resolver reads as its context:
|
|
25
|
-
* the `context` option adds, and over WebSocket the `connectionParams`.
|
|
26
|
-
*
|
|
27
|
-
* ```ts
|
|
28
|
-
* const base = alxia().use(bearer({ jwt }));
|
|
29
|
-
* const schema = createSchema<GraphQLContext<typeof base>>({ ... });
|
|
30
|
-
* ```
|
|
20
|
+
* What a resolver reads as its context: graxia's `signal`, the app's, what
|
|
21
|
+
* the `context` option adds, and over WebSocket the `connectionParams`.
|
|
31
22
|
*/
|
|
32
23
|
export type GraphQLContext<App, UserContext = Empty> = App extends {
|
|
33
24
|
readonly '~context': infer Ctx;
|
|
34
|
-
} ?
|
|
25
|
+
} ? CoreContext & ServerContext<Ctx> & GraphQLWsContext & UserContext : {
|
|
35
26
|
readonly '~error': 'GraphQLContext needs the type of an app: GraphQLContext<typeof app>';
|
|
36
27
|
};
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
28
|
+
type Passed = 'path' | 'schema' | 'context' | 'subscriptions' | 'plugins' | 'limits' | 'caches';
|
|
29
|
+
export interface GraphQLOptions<Ctx, Path extends RoutePath, SchemaCtx = unknown, Made extends object = object, Plugins extends readonly GraxiaPlugin<any, any>[] = readonly GraxiaPlugin<any, any>[]> extends Omit<GraxiaOptions<ServerContext<Ctx>, GraphQLSchema, any, Made>, Passed>, LegacyOptions, RemovedOptions {
|
|
30
|
+
readonly schema: GraphQLSchema & {
|
|
31
|
+
readonly '~context'?: SchemaCtx;
|
|
32
|
+
};
|
|
33
|
+
readonly context?: (init: ContextInit<ServerContext<Ctx>>) => Made | Promise<Made>;
|
|
34
|
+
readonly plugins?: Plugins;
|
|
35
|
+
readonly limits?: GraxiaOptions['limits'];
|
|
36
|
+
readonly caches?: GraxiaOptions['caches'];
|
|
44
37
|
readonly ide?: 'graphiql' | 'apollo-sandbox' | false;
|
|
45
|
-
|
|
46
|
-
readonly graphiql?: Exclude<YogaServerOptions<ServerCtx, UserCtx>['graphiql'], boolean>;
|
|
47
|
-
/** Apollo Sandbox's options, when `ide` is `apollo-sandbox`. */
|
|
38
|
+
readonly graphiql?: GraphiQLOptions | false;
|
|
48
39
|
readonly sandbox?: SandboxOptions;
|
|
49
|
-
/**
|
|
50
|
-
* The schema, from Yoga's `createSchema`, Pothos, or any tool that types
|
|
51
|
-
* its context. Its context must be one the app builds: a resolver that
|
|
52
|
-
* reads `user` behind no middleware that adds one is a compile error.
|
|
53
|
-
*/
|
|
54
|
-
readonly schema: GraphQLSchemaWithContext<SchemaCtx>;
|
|
55
|
-
/** Where the endpoint is, under the app's prefix. `/graphql` by default. */
|
|
56
40
|
readonly path?: Path;
|
|
57
|
-
/**
|
|
58
|
-
* Yoga's own CORS. Off by default: `@alxia/cors` answers for the whole
|
|
59
|
-
* app, this endpoint included.
|
|
60
|
-
*/
|
|
61
|
-
readonly cors?: YogaServerOptions<ServerCtx, UserCtx>['cors'];
|
|
62
|
-
/**
|
|
63
|
-
* GraphQL over WebSocket too, the `graphql-transport-ws` protocol of
|
|
64
|
-
* Apollo Client's and urql's default link, served by the optional peer
|
|
65
|
-
* `graphql-ws` at the endpoint's path: `true`, or where and how often it
|
|
66
|
-
* pings. Off by default: subscriptions are served over server-sent
|
|
67
|
-
* events, which stay served beside it.
|
|
68
|
-
*/
|
|
69
41
|
readonly ws?: boolean | GraphQLWsOptions;
|
|
70
|
-
/**
|
|
71
|
-
* The most tokens a document may hold, 15 000 by default (Apollo
|
|
72
|
-
* Router's own), or `false` for no cap. A longer document is refused by
|
|
73
|
-
* the parser before anything runs, as Yoga refuses any document it
|
|
74
|
-
* cannot parse: `GRAPHQL_PARSE_FAILED`.
|
|
75
|
-
*/
|
|
76
|
-
readonly maxTokens?: number | false;
|
|
77
|
-
/**
|
|
78
|
-
* The most levels of `{`, `(` and `[` a document may nest, 1 000 by
|
|
79
|
-
* default, or `false` for no limit. A deeper document is refused before
|
|
80
|
-
* the parser recurses into it, as `GRAPHQL_PARSE_FAILED`: graphql-js
|
|
81
|
-
* overflows the stack a few thousand levels down, well under
|
|
82
|
-
* `maxTokens`. A document that overflows it anyway is refused the same
|
|
83
|
-
* way.
|
|
84
|
-
*/
|
|
85
|
-
readonly maxNesting?: number | false;
|
|
86
|
-
/**
|
|
87
|
-
* The cache of parsed documents, one per endpoint, weighed by its tokens and bytes:
|
|
88
|
-
* `maxBytes` (64 MiB by default), `max` documents (1 024) and `ttl`
|
|
89
|
-
* milliseconds (one hour). `false` parses every request. Yoga's own
|
|
90
|
-
* `parserAndValidationCache` replaces it, and cannot be given with it.
|
|
91
|
-
*/
|
|
92
|
-
readonly parseCache?: false | ParseCacheOptions;
|
|
93
|
-
/**
|
|
94
|
-
* The most bytes a `POST` body may hold, over which core answers a 413.
|
|
95
|
-
* Without it, the `bodyLimit()` the app declared before `graphql()`
|
|
96
|
-
* applies as it is; without that, 1 MiB. An upload through a
|
|
97
|
-
* `multipart` mutation needs a larger one.
|
|
98
|
-
*/
|
|
99
42
|
readonly bodyLimit?: number;
|
|
100
43
|
}
|
|
101
44
|
/**
|
|
102
|
-
* The
|
|
103
|
-
*
|
|
104
|
-
*
|
|
45
|
+
* The parameter of a `context` factory that reads the app's `serverContext`,
|
|
46
|
+
* typed from the app: `context: ({ serverContext }: GraphQLContextInit<typeof app>) => …`,
|
|
47
|
+
* with no `['~context']` to write.
|
|
105
48
|
*/
|
|
49
|
+
export type GraphQLContextInit<App> = App extends {
|
|
50
|
+
readonly '~context': infer Ctx;
|
|
51
|
+
} ? ContextInit<ServerContext<Ctx>> : {
|
|
52
|
+
readonly '~error': 'GraphQLContextInit needs the type of an app: GraphQLContextInit<typeof app>';
|
|
53
|
+
};
|
|
106
54
|
type ProvidesContext<Provided, Required> = Provided extends Required ? unknown : {
|
|
107
55
|
readonly schema: `the schema's resolvers read a context the app does not build: missing ${Exclude<keyof Required, keyof Provided> & string}`;
|
|
108
56
|
};
|
|
109
57
|
/**
|
|
110
|
-
* A GraphQL endpoint on `app`, served by
|
|
111
|
-
*
|
|
112
|
-
* before it. A guard before it guards it; what the middlewares added is in each
|
|
113
|
-
* resolver's context, typed. Yoga's options pass through — `plugins`
|
|
114
|
-
* (Envelop's and Yoga's), `graphiql`, `maskedErrors`, `batching`… —
|
|
115
|
-
* and subscriptions are served over server-sent events, and over
|
|
116
|
-
* WebSocket too with `ws: true`.
|
|
117
|
-
*
|
|
118
|
-
* ```ts
|
|
119
|
-
* const app = alxia()
|
|
120
|
-
* .use(bearer({ jwt }))
|
|
121
|
-
* .plugin((app) => graphql(app, { schema, plugins: [useDepthLimit()] }));
|
|
122
|
-
* ```
|
|
58
|
+
* A GraphQL endpoint on `app`, served by `@graxia/core`: `GET` and `POST`
|
|
59
|
+
* at `path`, behind every middleware given to `use` on `app` before it.
|
|
123
60
|
*/
|
|
124
|
-
export declare function graphql<Ctx extends object, Prefix extends string, SchemaCtx,
|
|
61
|
+
export declare function graphql<Ctx extends object, Prefix extends string, SchemaCtx, Made extends object = Empty, const Path extends RoutePath = '/graphql', const Plugins extends readonly GraxiaPlugin<any, any>[] = readonly GraxiaPlugin<any, any>[]>(app: Alxia<Ctx, Prefix>, options: GraphQLOptions<Ctx, Path, SchemaCtx, Made, Plugins> & ProvidesContext<CoreContext & ServerContext<Ctx> & Made & ContextOf<Plugins>, SchemaCtx>): Alxia<Ctx, Prefix>;
|
|
125
62
|
export {};
|
|
126
63
|
//# sourceMappingURL=graphql.d.ts.map
|
package/dist/graphql.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../src/graphql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../src/graphql.ts"],"names":[],"mappings":"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"}
|