@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
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
- [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server). The endpoint is a
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
- Yoga's plugin system is yours whole: Envelop's plugins and Yoga's own.
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 graphql-yoga graphql @alxia/core
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
- `graphql-yoga` and `graphql` are peers: the package declares no dependency.
15
- `graphql-ws` is an optional one, for [`ws`](#websocket) alone.
16
- `graphql` 16 and 17 both work; with 17, `graphql-yoga` must be 5.22 or
17
- later, the first to accept it. `graphql-yoga` 5 (from 5.16) and 6 both work;
18
- the specs run on 6. Yoga 6 takes a `@graphql-hive/logger` `Logger` as a custom
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 'graphql-yoga';
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 Yoga's (`request`, `params`), the app's — every
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. (Yoga's `batching` option, below, is another thing: several
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
- ## Yoga's plugins
135
+ ## Graxia's plugins
142
136
 
143
- Every Yoga option passes through, but `graphqlEndpoint`, which `path`
144
- sets, and `graphiql`, which `ide` decides:
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 { useResponseCache } from '@graphql-yoga/plugin-response-cache';
142
+ import { fromEnvelop } from '@graxia/envelop';
149
143
 
150
144
  graphql(app, {
151
145
  schema,
152
- plugins: [useDepthLimit({ maxDepth: 8 }), useResponseCache({ session: ({ request }) => ... })],
153
- maskedErrors: true, // Yoga's default: an error's message never leaks
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, Yoga's default:
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) | Yoga's GraphiQL in dev (`isDev`), nothing otherwise |
176
- | `'graphiql'` | Yoga's GraphiQL, everywhere; `graphiql` takes its options |
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`, `pollForSchemaUpdates`, `includeCookies` |
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: Yoga's own is off unless
180
- `cors` is given.
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 of [`graphql-ws`](https://the-guild.dev/graphql/ws),
209
- the default of Apollo Client's `GraphQLWsLink` and urql's
210
- `subscriptionExchange`. `graphql-ws` is an optional peer; server-sent
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
- Yoga's plugins, and a shutdown closes the sockets with `1001`, completing
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
- [Yoga's plugins and options](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/guide/yoga.md#bound-a-subscription).
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** (`maxTokens`, `false` for no cap): a longer
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 `[` (`maxNesting`, `false` for
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 Yoga parses are kept in a cache bounded by weight, **64 MiB** per
269
- endpoint, **1 024** documents, **one hour** (`parseCache`), where Yoga's own
270
- has no size bound. A `POST` body may hold **1 MiB** (`bodyLimit`) unless the
271
- app declared its own `bodyLimit()` before `graphql()`, which is kept; a body
272
- past it is core's 413 and never reaches Yoga. `bodyLimit` bounds a `POST`
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
- maxTokens: 20_000, // false: no cap
280
- maxNesting: 2_000, // 1 000 by default; false: no cap
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 Yoga plugin that walks the operation about to run, aliases, inline
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`, `maxTokens`, `maxNesting`, `parseCache`, `bodyLimit`, and every Yoga option |
411
- | `graphqlExecutor(options)` | `(request: { query, operationName?, variables? }, context, { signal? }?) => Promise<{ data?, errors? }>`: a query or mutation in process, through the options of `graphql()` without the route's (`path`, `ide`, `ws`, `bodyLimit`, `cors`) |
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
- | `renderSandbox(endpoint, options?)`, `SANDBOX_POLICY` | the Sandbox page, and the policy it loads under |
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 Yoga 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 |
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
- | `graphqlClient(app, { path?, headers?, method? })` (`@alxia/graphql/testing`) | `query(document, { variables?, operationName?, headers?, method?, extensions?, persisted? })`, or `query({ persisted })` with no document, in process: `{ status, data?, errors?, response }` |
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, Yoga'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).
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.
@@ -1,5 +1,17 @@
1
1
  import type { Alxia } from '@alxia/core';
2
2
  import type { graphqlSocket } from './ws';
3
- /** `GET` and `POST` at `path` on `app`, and the WebSocket when `ws` is on. */
4
- export declare function declareEndpoint(app: Alxia<never, string>, path: string, handler: unknown, bodyLimit: number | undefined, socket: ReturnType<typeof graphqlSocket> | undefined): void;
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
@@ -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;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAK1C,8EAA8E;AAC9E,wBAAgB,eAAe,CAC9B,GAAG,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,GAAG,SAAS,GAClD,IAAI,CAoBN"}
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"}
@@ -1,7 +1,7 @@
1
1
  import type { Empty } from '@alxia/core';
2
- import type { GraphQLSchemaWithContext, YogaInitialContext, YogaServerOptions } from 'graphql-yoga';
3
- import type { YogaContext } from './handler';
4
- import type { ParseCacheOptions } from './parse-limits';
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
- * The options of `graphqlExecutor()`: those of `graphql()` that mean
32
- * something without a route. Put an HTTP-only plugin (a client-header
33
- * check, `cache-control`) in the route's list and not here.
34
- */
35
- export interface GraphQLExecutorOptions<ServerCtx extends YogaContext, UserCtx extends YogaContext, SchemaCtx = unknown> extends Omit<YogaServerOptions<ServerCtx, UserCtx>, 'graphqlEndpoint' | 'cors' | 'schema' | 'graphiql' | 'landingPage' | 'parserAndValidationCache'> {
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
- * Runs a GraphQL operation in the process, through the same Yoga setup as
49
- * `graphql()` — its plugins, `maxTokens`, `maxNesting`, the parse cache, the
50
- * masking of errors — with a server context the caller gives, and no HTTP
51
- * route in between. For a caller that is not a browser: an MCP tool, a job.
52
- * Queries and mutations only.
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
@@ -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,EACX,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,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,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CACtC,SAAS,SAAS,WAAW,EAC7B,OAAO,SAAS,WAAW,EAC3B,SAAS,GAAG,OAAO,CAClB,SAAQ,IAAI,CACZ,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC,EACnC,iBAAiB,GACjB,MAAM,GACN,QAAQ,GACR,UAAU,GACV,aAAa,GACb,0BAA0B,CAC5B;IACD,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC,SAAS,CAAC,CAAC;IACrD,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACpC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACrC,qFAAqF;IACrF,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,GAAG,iBAAiB,CAAC;CAChD;AAED,qCAAqC;AACrC,MAAM,MAAM,eAAe,CAAC,SAAS,IAAI,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,YAAY,KACf,OAAO,CAAC,cAAc,CAAC,CAAC;AAY7B;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC9B,SAAS,EACT,OAAO,SAAS,WAAW,GAAG,KAAK,EACnC,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,kBAAkB,CAAC,EAErD,OAAO,EAAE,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,GAC9D,eAAe,CAAC,SAAS,CAAC,CAuC5B"}
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 { GraphQLSchemaWithContext, YogaInitialContext, YogaServerOptions } from 'graphql-yoga';
3
- import { type YogaContext } from './handler';
4
- import type { ParseCacheOptions } from './parse-limits';
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 Yoga owns, or that mean nothing to a resolver. */
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 Yoga for each request: the context its middlewares built —
11
- * `user`, `db`, `log`… — with `request`, `url`, `ip` and `set`, through
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: Yoga's own, the app's, what
25
- * the `context` option adds, and over WebSocket the `connectionParams`. Type a schema with it:
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
- } ? YogaInitialContext & ServerContext<Ctx> & GraphQLWsContext & UserContext : {
25
+ } ? CoreContext & ServerContext<Ctx> & GraphQLWsContext & UserContext : {
35
26
  readonly '~error': 'GraphQLContext needs the type of an app: GraphQLContext<typeof app>';
36
27
  };
37
- export interface GraphQLOptions<ServerCtx extends YogaContext, UserCtx extends YogaContext, Path extends RoutePath, SchemaCtx = unknown> extends Omit<YogaServerOptions<ServerCtx, UserCtx>, 'graphqlEndpoint' | 'cors' | 'schema' | 'graphiql'> {
38
- /**
39
- * What a browser gets at the endpoint: Yoga's GraphiQL, Apollo Sandbox,
40
- * or nothing. By default, GraphiQL in the serving app's dev alone
41
- * (`isDev`: `alxia({ dev })`, else `NODE_ENV=development`), nothing
42
- * otherwise; `graphiql` or `apollo-sandbox` serves one everywhere.
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
- /** GraphiQL's options, Yoga's own, when `ide` is `graphiql`. */
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 check Yoga's types leave out: the context the app builds must hold
103
- * what the schema's resolvers read. A mistake comes back as a `schema`
104
- * whose type is the message.
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 [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server):
111
- * `GET` and `POST` at `path`, behind every middleware given to `use` on `app`
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, UserCtx extends YogaContext = Empty, const Path extends RoutePath = '/graphql'>(app: Alxia<Ctx, Prefix>, options: GraphQLOptions<ServerContext<Ctx>, UserCtx, Path, SchemaCtx> & ProvidesContext<YogaInitialContext & ServerContext<Ctx> & UserCtx, SchemaCtx>): Alxia<Ctx, Prefix>;
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
@@ -1 +1 @@
1
- {"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../src/graphql.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../src/graphql.ts"],"names":[],"mappings":"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"}