The best way to control Claude Code, Codex and more from any computer or phone
| 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. |