The best way to control Claude Code, Codex and more from any computer or phone

main
md 685 lines 31 KB
Rendered Raw
1 # @effect/graphql-generator
2
3 Generates typed operations for the experimental `effect/graphql` client from
4 `.graphql` documents and a GraphQL schema. The lexer, parser and validation are
5 built in; `graphql-js` isn't needed.
6
7 ## Installation
8
9 ```sh
10 npm install effect @effect/platform-node
11 npm install --save-dev @effect/graphql-generator
12 ```
13
14 The package provides the `graphqlgen` command. It loads `graphql.config.ts`
15 with a plain `import()`, so it needs Bun, Deno, or Node.js 22.18 or later
16 (where type stripping is on by default). Under Node the config can only use
17 erasable TypeScript syntax: no `enum`, no `namespace` with values, no
18 constructor parameter properties.
19
20 ## Configuration
21
22 Put a `graphql.config.ts` in the directory you run `graphqlgen` from:
23
24 ```ts
25 import { defineConfig } from "@effect/graphql-generator/Config"
26
27 export default defineConfig({
28 // An SDL file (.graphql) or an introspection result (.json)
29 schema: "./schema/github.graphql",
30 // Glob patterns for the operation documents
31 documents: ["src/**/*.graphql"],
32 // One Schema codec per custom scalar, as "<module>#<export>"
33 scalars: {
34 GitObjectID: "effect/Schema#String"
35 }
36 })
37 ```
38
39 `schema` and `documents` are the keys graphql-config reads, so the VS Code
40 GraphQL extension can share the file.
41
42 | Key | Description |
43 | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44 | `schema` | The schema file, relative to the config file. It is never treated as a document. |
45 | `documents` | Glob patterns (`*`, `**`, `?`, `{a,b}`) relative to the config file; absolute patterns are rejected. `node_modules`, dot-directories and dangling symlinks are skipped. Documents (`.graphql` or `.gql`) hold only operations and fragments. |
46 | `scalars` | Optional. A codec per custom scalar; can also override the built-in `Int`, `Float` and `ID`. |
47 | `shared` | Optional. Where the shared module goes. Defaults to the schema's name next to it: `github.graphql` or `github.json` gives `github.graphql.ts`. It can't be the schema, a document or a document's output. |
48 | `importExtension` | Optional. `".ts"` (default) or `".js"`, used in imports between generated files and to relative scalar modules. |
49
50 In a pattern, a `{` without a closing `}` matches itself.
51
52 One config means one schema: for two schemas, write two config files and run
53 `graphqlgen --config <file>` for each.
54
55 ### Scalars
56
57 Each scalar maps to a `Schema` codec, used for variables and results alike. The
58 value is a `"<module>#<export>"` string because the generator emits an
59 `import` for it. A relative module resolves against the config file and is
60 rewritten relative to the shared module, with a `.ts`, `.js` or missing
61 extension replaced by `importExtension` and any other extension, such as
62 `.mjs`, kept; a bare module is imported as written.
63 The generator doesn't check the target; `tsc` does.
64
65 Unless overridden, `Int` is a 32-bit integer, `Float` a finite number and `ID`
66 a string. Custom scalars named exactly `DateTime` and `URI` default to
67 `Schema.DateTimeUtcFromString` and `Schema.String`. A `scalars` entry overrides
68 any of these defaults. Other custom scalars without a mapping decode as
69 `Schema.Json`, with one warning listing every unmapped scalar the operations
70 reach. Defaulted scalars are not included in that warning.
71
72 ## Generated files
73
74 `foo.graphql` generates `foo.graphql.ts` next to it (`foo.gql` generates
75 `foo.gql.ts`), exporting:
76
77 - a `GraphQL.query`, `GraphQL.mutation` or `GraphQL.subscription` per
78 operation, carrying the compact document and the variables and result
79 Schemas, plus a type namespace such as `RepoIssues.Variables` and
80 `RepoIssues.Result`. Queries and mutations give the document as a
81 `GraphQL.DocumentTemplate`, which marks the variable and fragment names a
82 batch would rename; the operation joins it into the same compact text.
83 - a Schema per fragment
84 - a `Schema.Struct` const and a same-named interface per nested object
85 selection and per member of an interface or union selection
86 - `FooGraphQLGroup`, a `GraphQLGroup` with every operation in the file
87
88 A nested selection's schema and interface are named after its GraphQL type,
89 such as `Issue` or `User`, inside fragments too. Each is a top-level export of the
90 file, so operations and fragments in one file draw from the same names. The
91 member covering the types an interface or union selection doesn't name ends
92 in `Other`, such as `EventOther`. An interface or union selection without any
93 `... on` type conditions is one struct rather than a union, so its schema takes
94 the abstract type's name with no `Other`, such as `Event`.
95
96 Selections of a type share one schema and interface across the whole file when they select
97 the same fields under the same response keys, with the same nested
98 selections and `@skip` / `@include` optionality, in any order. When different
99 selections would get the same name, or a name is already taken by an
100 operation, fragment or import in the file, by the file's group or by
101 `Schema`, `GraphQL`, `GraphQLGroup` or `Shared`, each adds its field's
102 response key (`AuthorUser`), then parent response keys one at a time
103 (`CommentsAuthorUser`), then the operation or fragment name
104 (`RepoIssuesCommentsAuthorUser`), until the names are free. A shared schema
105 uses the path of its first occurrence. A clash left after all of that is an
106 error: alias the field.
107
108 Object fragments and ordinary input objects use the same declaration shape:
109
110 ```ts
111 export const Author = Schema.Struct({
112 name: Schema.NullOr(Schema.String)
113 })
114 export interface Author extends Schema.Struct.Type<typeof Author.fields> {}
115 ```
116
117 The const is the runtime schema, including decoding, encoding and `make`; the
118 interface supplies a named decoded type without the type-checking overhead of
119 an Opaque class. Custom scalar codecs retain their encoded types. Unlike the
120 previous Opaque classes, nested selections in inferred types and editor hovers
121 can expand structurally instead of showing these names. Use the exported
122 interfaces in explicit type annotations when a named type is useful. Abstract
123 fragments still use a union schema and type alias, and `@oneOf` inputs retain
124 their Opaque union schema and explicit type alias.
125
126 The shared module holds only the scalars, enums, input objects and
127 `__typename` unions the operations reach. Commit the generated files, and
128 exclude `*.graphql.ts` from your linter and formatter: the output has one fixed
129 style, and a reformatted file shows up as out of date in `graphqlgen --check`.
130
131 After a successful run, `graphqlgen` deletes each `*.graphql.ts` or `*.gql.ts`
132 under the `documents` glob roots whose first line exactly matches the generated
133 header naming its sibling `.graphql` or `.gql` source, if that source is
134 missing. Shared modules and files without a matching document header are never
135 touched.
136
137 ## CLI
138
139 ```sh
140 graphqlgen [--config <path>] [--watch | --check]
141 ```
142
143 | Flag | Description |
144 | ---------------- | --------------------------------------------------------------------------------------- |
145 | `--config`, `-c` | The config file. Defaults to `graphql.config.ts` in the current directory. |
146 | `--watch`, `-w` | Keep running and regenerate on changes. |
147 | `--check` | Write nothing; list every file that would be created, updated or deleted. Use it in CI. |
148
149 Diagnostics go to stderr as `file:line:col: error|warning: message` with a code
150 excerpt. Any error means nothing is written.
151
152 | Exit code | Meaning |
153 | --------- | ------------------------------------------------------------------------------------------------------------ |
154 | `0` | Success, including runs with warnings only. |
155 | `1` | Generation reported an error, a file couldn't be read or written, or `--check` found out-of-date files. |
156 | `2` | Invalid CLI usage (including `--watch --check`), or the config couldn't be loaded or doesn't fit the schema. |
157
158 ### Watch mode
159
160 `graphqlgen --watch` runs once, then watches the config file, the schema file
161 and the static prefix of each `documents` glob (`src` for `src/**/*.graphql`).
162 Changes are debounced by about 50 ms, and only files whose bytes changed are
163 written. A cycle with errors writes nothing, so the last good output stays; a
164 successful one prints a line such as `regenerated 3 files, deleted 1`.
165
166 Editing the config re-imports it, keeping the previous config if the new one
167 fails to load. Only a config that fails at startup exits (with code `2`).
168 Modules the config imports are not reloaded: restart after editing them.
169
170 ## Using the generated code
171
172 Merge the groups you need and build a client, a service with one method per
173 operation:
174
175 ```ts
176 import { Context, Layer } from "effect"
177 import { GraphQLClient, GraphQLGroup, GraphQLProtocol } from "effect/graphql"
178 import { FetchHttpClient } from "effect/http"
179 import { IssuesGraphQLGroup } from "./src/issues.graphql.ts"
180 import { ViewerGraphQLGroup } from "./src/viewer.graphql.ts"
181
182 export class GitHub extends Context.Service<GitHub>()("app/GitHub", {
183 make: GraphQLClient.make(GraphQLGroup.merge(IssuesGraphQLGroup, ViewerGraphQLGroup))
184 }) {
185 static readonly layer = Layer.effect(GitHub, GitHub.make).pipe(
186 Layer.provide(GraphQLProtocol.layerHttp({ url: "https://api.github.com/graphql" })),
187 Layer.provide(FetchHttpClient.layer)
188 )
189 }
190
191 // const { viewer } = yield* github.Viewer()
192 // const { repository } = yield* github.RepoIssues({ owner: "Effect-TS", name: "effect" })
193 ```
194
195 The getting-started example under `ai-docs/src/52_graphql` shows auth
196 middleware and paging; the `effect/graphql` API reference covers
197 subscriptions, errors and `{ partial: true }` for responses that carry both
198 `data` and `errors`.
199
200 ### Paging and `$after`
201
202 `GraphQLClient.items` and `GraphQLClient.pages` page forward through a cursor
203 connection. Name the cursor variable `$after`, declare it as a nullable
204 `String`, pass it to the connection and select `pageInfo`:
205
206 ```graphql
207 query RepoIssues($owner: String!, $name: String!, $after: String) {
208 repository(owner: $owner, name: $name) {
209 issues(first: 50, after: $after) {
210 pageInfo {
211 hasNextPage
212 endCursor
213 }
214 nodes {
215 number
216 title
217 }
218 }
219 }
220 }
221 ```
222
223 ```ts
224 const issues = GraphQLClient.items(github.RepoIssues, {
225 variables: { owner: "Effect-TS", name: "effect" }, // everything except `after`
226 connection: (result) => result.repository?.issues
227 })
228 ```
229
230 An operation without `$after` or `pageInfo`, or without `nodes` for `items`,
231 doesn't compile. The generator needs nothing beyond this convention.
232
233 ### Paging with a cap
234
235 Pages are fetched as the stream is pulled, so `Stream.take` on `pages` caps
236 the number of requests. The last page's `pageInfo.hasNextPage` tells you
237 whether the cap cut the read short. `Stream.runCollect` drops every row when
238 the stream fails, so catch the `PaginationError` inside the stream to keep the
239 rows read before it, and mark the result partial:
240
241 ```ts
242 import { Effect, Stream } from "effect"
243 import { GraphQLClient } from "effect/graphql"
244
245 export const recentIssues = Effect.fn("recentIssues")(function*(maxPages: number) {
246 // `Stream.take(0)` reads nothing, which would look like a complete read
247 if (!Number.isInteger(maxPages) || maxPages < 1) {
248 return yield* Effect.die(new RangeError(`maxPages must be a positive integer, got ${maxPages}`))
249 }
250 const github = yield* GitHub
251 const pages = yield* GraphQLClient.pages(github.RepoIssues, {
252 variables: { owner: "Effect-TS", name: "effect" },
253 connection: (result) => result.repository?.issues
254 }).pipe(
255 Stream.take(maxPages),
256 // End the stream with a `null` marker instead of failing it
257 Stream.catchReason("GraphQLClientError", "PaginationError", () => Stream.make(null)),
258 Stream.runCollect
259 )
260 const last = pages.at(-1)
261 return {
262 issues: pages.flatMap((page) => page?.nodes ?? []),
263 partial: last === null || last?.pageInfo.hasNextPage === true
264 }
265 })
266 ```
267
268 Other errors still fail the whole read. To keep rows on those as well, catch
269 `GraphQLClientError` the same way.
270
271 ### Batching
272
273 `GraphQLResolver` from `effect/graphql` collects concurrent lookups and makes
274 one call to a generated operation, DataLoader style. Generate
275 `repos.graphql.ts` from this GitHub document. Create the client and reusable
276 resolver in the `GitHub` service:
277
278 ```graphql
279 query RepoNodes($ids: [ID!]!) {
280 nodes(ids: $ids) {
281 __typename
282 ... on Repository { id nameWithOwner }
283 }
284 }
285 ```
286
287 ```ts
288 import { Context, Effect, Layer, RequestResolver } from "effect"
289 import { GraphQLClient, GraphQLGroup, GraphQLProtocol, GraphQLResolver } from "effect/graphql"
290 import { FetchHttpClient } from "effect/http"
291 import { IssuesGraphQLGroup } from "./src/issues.graphql.ts"
292 import { ReposGraphQLGroup } from "./src/repos.graphql.ts"
293 import { ViewerGraphQLGroup } from "./src/viewer.graphql.ts"
294
295 export class GitHub extends Context.Service<GitHub>()("app/GitHub", {
296 make: Effect.gen(function*() {
297 const client = yield* GraphQLClient.make(
298 GraphQLGroup.merge(IssuesGraphQLGroup, ViewerGraphQLGroup, ReposGraphQLGroup)
299 )
300 const RepoById = GraphQLResolver.ordered(client.RepoNodes, {
301 variables: (ids: ReadonlyArray<string>) => ({ ids }),
302 path: ["nodes"],
303 typename: "Repository"
304 }).pipe(RequestResolver.batchN(100)) // GitHub's nodes(ids:) limit
305 return { ...client, getRepo: GraphQLResolver.request(RepoById) }
306 })
307 }) {
308 static readonly layer = Layer.effect(GitHub, GitHub.make).pipe(
309 Layer.provide(GraphQLProtocol.layerHttp({ url: "https://api.github.com/graphql" })),
310 Layer.provide(FetchHttpClient.layer)
311 )
312 }
313
314 export const repoNames = Effect.fn("repoNames")(function*(ids: ReadonlyArray<string>) {
315 const github = yield* GitHub
316 const repos = yield* Effect.forEach(ids, github.getRepo, { concurrency: "unbounded" })
317 return repos.map((repo) => repo.nameWithOwner)
318 })
319
320 export const program = repoNames(["R_1", "R_2"]).pipe(Effect.provide(GitHub.layer))
321 ```
322
323 `ordered` matches the `nodes` list to the ids by position. `path` leads from
324 the result to the list, one autocompleted key at a time, and `typename`
325 narrows each entry to `Repository`. A `null` entry or a node of another type
326 fails only its own lookup, with `Cause.NoSuchElementError`, and a GraphQL
327 error at `["nodes", i]` fails only entry `i`. Any other GraphQL error, and
328 transport or decoding failures, fail the whole batch. Middleware still run,
329 because the resolver calls the generated client.
330
331 Each batch makes one call with the services of one of its lookups. When a
332 middleware `requires` a per-request service, such as the signed-in user,
333 `ordered` and `findById` require a `batchKey` that reads it. Only lookups
334 with equal keys share a call, so one user's lookups never go out with another
335 user's token:
336
337 ```ts
338 const RepoById = GraphQLResolver.ordered(client.RepoNodes, {
339 variables: (ids: ReadonlyArray<string>) => ({ ids }),
340 path: ["nodes"],
341 typename: "Repository",
342 batchKey: (context) => Context.get(context, CurrentUser).id
343 })
344 ```
345
346 Without services, `batchKey` isn't accepted and all lookups share a batch.
347 A middleware that reads a `Context.Reference` with a default value doesn't
348 add it to the services, so `batchKey` doesn't cover it.
349
350 When results come back in any order, as from a search, `findById` matches them
351 by a key read from each result. Add a `SearchRepos` operation to `repos.graphql`,
352 then create its resolver inside `GitHub.make`, after the client:
353
354 ```ts
355 // search(query: $query, type: REPOSITORY, first: 50) { pageInfo { hasNextPage } nodes { ... } }
356 const RepoByName = GraphQLResolver.findById(client.SearchRepos, {
357 key: (repo) => repo.nameWithOwner,
358 variables: (names) => ({ query: names.map((name) => `repo:${name}`).join(" ") }),
359 path: ["search", "nodes"],
360 typename: "Repository"
361 }).pipe(RequestResolver.batchN(50))
362 const getRepoByName = GraphQLResolver.request(RepoByName)
363 ```
364
365 Include `getRepoByName` in the returned service and use it with `Effect.forEach`,
366 as with `getRepo` above. Write `key` before `variables`, so that the key type is
367 inferred from it.
368
369 A list field returns one page, so a key past the end of the page would look
370 missing. Set the page size (`first`, `limit`) and `RequestResolver.batchN` to
371 the same value; when the object holding the list reports
372 `pageInfo.hasNextPage: true`, the whole batch fails instead.
373
374 - For the simplest option, call a method per item with
375 `Effect.forEach(items, f, { concurrency: 4 })`, at the cost of one request
376 (and rate-limit charge) per item.
377
378 See [the RequestResolver example](../../../ai-docs/src/05_batching/10_request-resolver.ts).
379
380 ### Aliased batching
381
382 Some lookups have no list field. GitHub finds a pull request by repository
383 and number, one at a time. `GraphQLResolver.aliased` repeats a generated query
384 under aliases in one request, so each slice still has the generated types.
385 Add this operation to `repos.graphql`:
386
387 ```graphql
388 query PullRequest($owner: String!, $name: String!, $number: Int!) {
389 repository(owner: $owner, name: $name) {
390 pullRequest(number: $number) { number title }
391 }
392 }
393 ```
394
395 Then create the resolver inside `GitHub.make`, after the client:
396
397 ```ts
398 const PullRequests = GraphQLResolver.aliased(client.PullRequest)
399 const getPullRequest = GraphQLResolver.request(PullRequests)
400 ```
401
402 `getPullRequest` takes the operation's variables and returns the decoded
403 result, like `getRepo` above. Concurrent calls go out as one `POST`, built
404 from the document template the generator emits:
405
406 ```graphql
407 query PullRequest($_0_owner: String!, $_0_name: String!, $_0_number: Int!, $_1_owner: String!, ...) {
408 _0_repository: repository(owner: $_0_owner, name: $_0_name) { pullRequest(number: $_0_number) { number title } }
409 _1_repository: repository(owner: $_1_owner, name: $_1_name) { pullRequest(number: $_1_number) { number title } }
410 }
411 ```
412
413 The response is split by prefix and each slice is decoded with the generated
414 result Schema. A GraphQL error under `_1_repository` fails only the second
415 call; an error without a `path` fails them all. Calls whose variables encode
416 to the same JSON share a slice. A batch holds 10 slices unless you pipe
417 `RequestResolver.batchN`, because GitHub's query cost and timeouts grow with
418 its size.
419
420 An error fails every slice when the root field and every field down to the
421 error are non-null, since the `null` reaches `data`. One nullable field on
422 the way keeps it inside the slice. GitHub's `repository` and `pullRequest`
423 are both nullable. Middleware that hash the query should hash
424 `request.query`, which holds the batched document, and allowlists of trusted
425 documents can't cover batches.
426
427 ### Partial results
428
429 When a field fails, GraphQL sets it to `null`. If the field is non-null, the
430 `null` moves up to the nearest nullable parent, and on to `data` if there is
431 none. An error stays inside one alias or list entry only when some field from
432 that alias or entry down to the failed field is nullable, so the `null` stops
433 there. Otherwise it wipes out data that other aliases or entries share. This
434 holds for `{ partial: true }`, `aliased` slices and `ordered` / `findById`
435 entries alike. In `repository { pullRequest { title } }`, an error on `title`
436 (a `String!`) nulls `pullRequest`, which GitHub declares nullable, so the rest
437 of the response survives.
438
439 ## GitHub
440
441 GitHub's API has a few behaviours worth handling from the start: rate-limit
442 headers, typed errors, rate limits, timeouts and per-installation tokens.
443 The snippets below use the `GitHub` service and the operations from the
444 sections above.
445
446 ### Rate-limit headers
447
448 GitHub reports the primary rate limit on every response in
449 `x-ratelimit-remaining`, `x-ratelimit-used` and `x-ratelimit-reset` (epoch
450 seconds). A middleware reads them from the result `next` returns:
451
452 ```ts
453 import { Effect, Layer } from "effect"
454 import { GraphQLMiddleware } from "effect/graphql"
455
456 export class RateLimit extends GraphQLMiddleware.Service<RateLimit>()("app/RateLimit") {
457 static readonly layer = Layer.succeed(RateLimit, {
458 execute: ({ next, request }) =>
459 Effect.tap(next(request), (result) => {
460 const remaining = Number(result.headers?.["x-ratelimit-remaining"])
461 return remaining < 500
462 ? Effect.logWarning(`GitHub rate limit: ${remaining} points left`)
463 : Effect.void
464 }),
465 subscribe: ({ next, request }) => next(request)
466 })
467 }
468 ```
469
470 Attach it with `GraphQLGroup.merge(...).middleware(RateLimit)` and provide
471 `RateLimit.layer`. A response with GraphQL `errors` still reaches the
472 middleware as a result; a transport failure fails `next` instead. Either
473 way, a failed call keeps the response `headers` and `status`, which
474 `GraphQLClientError` exposes for both reasons.
475
476 ### Error types
477
478 GitHub adds a top-level `type` to each GraphQL error, such as `NOT_FOUND`,
479 `FORBIDDEN`, `INSUFFICIENT_SCOPES` or `RATE_LIMITED`. `GraphQLError` keeps
480 fields it doesn't know as JSON, so `type` can be read from
481 `ResponseError.errors`:
482
483 ```ts
484 import { Effect } from "effect"
485 import type { GraphQLClientError } from "effect/graphql"
486
487 const hasErrorType = (error: GraphQLClientError.GraphQLClientError, type: string) =>
488 error.reason._tag === "ResponseError" && error.reason.errors.every((entry) => entry.type === type)
489
490 export const findPullRequest = Effect.fn("findPullRequest")(function*(owner: string, name: string, number: number) {
491 const github = yield* GitHub
492 return yield* github.PullRequest({ owner, name, number }).pipe(
493 Effect.map(({ repository }) => repository?.pullRequest ?? null),
494 Effect.catchIf((error) => hasErrorType(error, "NOT_FOUND"), () => Effect.succeed(null))
495 )
496 })
497 ```
498
499 `every` keeps a `NOT_FOUND` that comes with another error a failure.
500
501 ### Rate limits
502
503 GitHub's secondary rate limits, on concurrent requests and points per
504 minute, answer 403 or 429 with a JSON body that isn't a GraphQL response. The
505 client reports them as a `TransportError` with `status` and `headers`. They
506 usually come with `retry-after`, and an error with a `retry-after` is
507 retryable at any status. A primary rate limit arrives as a `RATE_LIMITED`
508 GraphQL error with `x-ratelimit-remaining: 0` and often no `retry-after`, so
509 `isRetryable` can be `false` and only the headers show it. GitHub asks
510 clients to wait for `retry-after` when it is set, and until
511 `x-ratelimit-reset` (epoch seconds) when `x-ratelimit-remaining` is `0`:
512
513 ```ts
514 import { Duration, Effect, Schedule } from "effect"
515 import type { GraphQLClientError } from "effect/graphql"
516
517 const rateLimited = (error: GraphQLClientError.GraphQLClientError) => error.headers?.["x-ratelimit-remaining"] === "0"
518
519 const gitHubRetry = Schedule.exponential("1 second").pipe(
520 Schedule.setInputType<GraphQLClientError.GraphQLClientError>(),
521 Schedule.modifyDelay(({ duration, input, now }) => {
522 if (input.retryAfter !== undefined) return Effect.succeed(input.retryAfter)
523 if (!rateLimited(input)) return Effect.succeed(duration)
524 const reset = Number(input.headers?.["x-ratelimit-reset"]) * 1000
525 return Effect.succeed(Number.isFinite(reset) ? Duration.millis(Math.max(0, reset - now)) : Duration.minutes(1))
526 })
527 )
528
529 export const retryGitHub = <A, R>(effect: Effect.Effect<A, GraphQLClientError.GraphQLClientError, R>) =>
530 Effect.retry(effect, {
531 schedule: gitHubRetry,
532 while: (error) => error.isRetryable || rateLimited(error),
533 times: 5
534 })
535 ```
536
537 `retryGitHub(github.RepoIssues(variables))` waits as long as GitHub asks
538 after a rate limit, and backs off exponentially after other retryable
539 errors. Don't retry on `isRetryable` with a plain backoff instead: it ignores
540 `retry-after`, and GitHub may ban an integration that keeps sending requests
541 while rate limited. Subscriptions reconnect on their own after a retryable
542 failure, and `GraphQLClient.defaultSubscriptionRetry` never reconnects sooner
543 than its `retryAfter`. A primary rate limit without `retry-after` isn't
544 retryable, though, so it ends the subscription, whatever `subscriptionRetry`
545 says. Wait until `x-ratelimit-reset` before subscribing again.
546
547 ### Timeouts
548
549 GitHub stops a query that runs too long and answers 502 or 504, usually with
550 a GraphQL body such as `{"data":null,"errors":[{"message":"Something went
551 wrong while executing your query..."}]}`. That is a `ResponseError`, and
552 `isRetryable` is `true` for any 429 or 5xx status. A 5xx without a GraphQL
553 body is a retryable `TransportError`. `retryGitHub` above retries both.
554
555 `Stream.retry` on `pages` or `items` starts again from the first page. To
556 retry only the page that timed out, repeat the call in a middleware. A
557 timeout with a GraphQL body reaches the middleware as a result of `next`, and
558 one without fails `next` with a `TransportError`, so check the `status` of
559 both, and wait for a `retry-after` on either:
560
561 ```ts
562 import { Duration, Effect, Layer, Result, Schedule } from "effect"
563 import { type GraphQLClientError, GraphQLMiddleware, type GraphQLProtocol } from "effect/graphql"
564
565 type Outcome = Result.Result<GraphQLProtocol.ExecutionResult, GraphQLClientError.GraphQLClientError>
566
567 const timedOut = (outcome: Outcome) => {
568 const status = Result.isSuccess(outcome) ? outcome.success.status : outcome.failure.status
569 return status === 502 || status === 504
570 }
571
572 // A result's headers are raw, so read `retry-after` as seconds or an HTTP
573 // date, as the client does for errors
574 const retryAfter = (outcome: Outcome, now: number) => {
575 if (Result.isFailure(outcome)) return outcome.failure.retryAfter
576 const value = outcome.success.headers?.["retry-after"]?.trim()
577 if (value === undefined) return undefined
578 const millis = /^\d+$/.test(value) ? Number(value) * 1000 : Date.parse(value) - now
579 return Number.isNaN(millis) ? undefined : Duration.millis(Math.max(0, millis))
580 }
581
582 const timeoutRetry = Schedule.exponential("1 second").pipe(
583 Schedule.setInputType<Outcome>(),
584 Schedule.modifyDelay(({ duration, input, now }) => Effect.succeed(retryAfter(input, now) ?? duration))
585 )
586
587 export class RetryTimeouts extends GraphQLMiddleware.Service<RetryTimeouts>()("app/RetryTimeouts") {
588 static readonly layer = Layer.succeed(RetryTimeouts, {
589 execute: ({ next, request }) =>
590 Effect.result(next(request)).pipe(
591 Effect.repeat({ while: timedOut, schedule: timeoutRetry, times: 3 }),
592 Effect.flatMap(Effect.fromResult)
593 ),
594 subscribe: ({ next, request }) => next(request)
595 })
596 }
597 ```
598
599 Attach `RetryTimeouts` only to operations that are safe to send twice, and
600 don't wrap other mutations in `retryGitHub` either. A mutation that timed
601 out may still have been applied.
602
603 ### Pull requests per installation
604
605 A GitHub App calls the API with one token per installation. When the auth
606 middleware `requires` the installation, `aliased` needs a `batchKey`, so pull
607 requests for different installations never share a request:
608
609 ```ts
610 import { Context, Effect, Layer, Redacted } from "effect"
611 import { GraphQLClient, GraphQLGroup, GraphQLMiddleware, GraphQLProtocol, GraphQLResolver } from "effect/graphql"
612 import { FetchHttpClient, Headers } from "effect/http"
613 import { IssuesGraphQLGroup } from "./src/issues.graphql.ts"
614 import { ReposGraphQLGroup } from "./src/repos.graphql.ts"
615
616 // The installation a call runs as, with its access token
617 export class Installation extends Context.Service<Installation, {
618 readonly id: number
619 readonly token: Redacted.Redacted
620 }>()("app/Installation") {}
621
622 export class InstallationAuth extends GraphQLMiddleware.Service<InstallationAuth, {
623 requires: Installation
624 }>()("app/InstallationAuth") {
625 static readonly layer = Layer.succeed(
626 InstallationAuth,
627 GraphQLMiddleware.mapRequest(Effect.fnUntraced(function*(request) {
628 const { token } = yield* Installation
629 return { ...request, headers: Headers.set(request.headers, "authorization", `Bearer ${Redacted.value(token)}`) }
630 }))
631 )
632 }
633
634 export class GitHub extends Context.Service<GitHub>()("app/GitHub", {
635 make: Effect.gen(function*() {
636 const client = yield* GraphQLClient.make(
637 GraphQLGroup.merge(IssuesGraphQLGroup, ReposGraphQLGroup).middleware(InstallationAuth)
638 )
639 const PullRequests = GraphQLResolver.aliased(client.PullRequest, {
640 batchKey: (context) => Context.get(context, Installation).id
641 })
642 return { ...client, getPullRequest: GraphQLResolver.request(PullRequests) }
643 })
644 }) {
645 static readonly layer = Layer.effect(GitHub, GitHub.make).pipe(
646 Layer.provide(InstallationAuth.layer),
647 Layer.provide(GraphQLProtocol.layerHttp({ url: "https://api.github.com/graphql" })),
648 Layer.provide(FetchHttpClient.layer)
649 )
650 }
651
652 export const pullRequestTitles = Effect.fn("pullRequestTitles")(function*(
653 installation: Installation["Service"],
654 repo: { readonly owner: string; readonly name: string },
655 numbers: ReadonlyArray<number>
656 ) {
657 const github = yield* GitHub
658 const results = yield* Effect.forEach(
659 numbers,
660 (number) => github.getPullRequest({ ...repo, number }),
661 { concurrency: "unbounded" }
662 ).pipe(Effect.provideService(Installation, installation))
663 return results.map((result) => result.repository?.pullRequest?.title ?? null)
664 })
665 ```
666
667 Every method of this client requires `Installation`. Concurrent
668 `pullRequestTitles` calls for two installations send one request per
669 installation, each with up to 10 pull requests and that installation's token.
670
671 ## Links
672
673 - [Website](https://effect.website): documentation, guides, and news.
674 - [Reference](https://effect.website/docs/v4/api/graphql-generator): API documentation for this package.
675 - [Discord](https://discord.gg/effect-ts): ask questions, share what you're building, and talk to the core team.
676 - [Community](https://effect.website/community-hub): meetups and events, or bring Effect to your own.
677 - [Issues](https://github.com/Effect-TS/effect/issues): bug reports and feature requests.
678
679 ## Let's talk
680
681 Whether your team is considering Effect, rolling it out, or already running it in production, we'd love to hear from you: what you're building, what works, and what you need from Effect next.
682
683 - **Talk to the maintainers.** Introduce your team on [Discord](https://discord.gg/effect-ts) or email [contact@effectful.co](mailto:contact@effectful.co). We're happy to connect privately on Slack or Discord for feedback and help with adoption.
684 - **Production support.** We're exploring how to better support teams running Effect in production. If your organization has specific support needs, let's discuss them.
685 - **Adoption help.** Our [adoption partners](https://effect.website/adoption-partners) offer implementation, consulting, team extension, training, and commercial support.