{"id":21931517,"url":"https://github.com/sar1008/graphql-typed-client","last_synced_at":"2026-04-17T00:31:01.236Z","repository":{"id":230783688,"uuid":"780047949","full_name":"sar1008/graphql-typed-client","owner":"sar1008","description":"A tool that generates a strongly typed client library for any GraphQL endpoint. The client allows writing GraphQL queries as plain JS objects (with type safety, awesome code completion experience, custom scalar type mapping, type guards and more)","archived":false,"fork":false,"pushed_at":"2024-03-31T15:00:09.000Z","size":219,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-22T13:12:27.998Z","etag":null,"topics":["client","graphql","javascript","nodejs","types","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sar1008.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-03-31T14:55:46.000Z","updated_at":"2024-03-31T15:00:49.000Z","dependencies_parsed_at":"2024-03-31T23:21:51.756Z","dependency_job_id":"0eac8323-08fe-47df-8a1f-bfc44a57a171","html_url":"https://github.com/sar1008/graphql-typed-client","commit_stats":null,"previous_names":["sar1008/graphql-typed-client"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sar1008/graphql-typed-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sar1008%2Fgraphql-typed-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sar1008%2Fgraphql-typed-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sar1008%2Fgraphql-typed-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sar1008%2Fgraphql-typed-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sar1008","download_url":"https://codeload.github.com/sar1008/graphql-typed-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sar1008%2Fgraphql-typed-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31909825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","graphql","javascript","nodejs","types","typescript"],"created_at":"2024-11-28T23:14:11.941Z","updated_at":"2026-04-17T00:31:01.196Z","avatar_url":"https://github.com/sar1008.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# graphql-typed-client [![npm version](https://img.shields.io/npm/v/graphql-typed-client.svg?style=flat-square)](https://www.npmjs.com/package/graphql-typed-client) [![Build Status](https://img.shields.io/travis/helios1138/graphql-typed-client/master.svg?style=flat-square)](https://travis-ci.org/helios1138/graphql-typed-client)\n\nA tool that generates a strongly typed client library for any GraphQL endpoint. The client allows writing GraphQL queries\nas plain JS objects (with type safety, awesome code completion experience, custom scalar type mapping, type guards and more)\n\n#### Chain request syntax\n\n![](https://i.gyazo.com/18e4670782b792f06c0e97abdee41bf2.gif)\n\n#### Raw request syntax\n\n![](https://i.gyazo.com/5f0255b59f0f9c7eebdbe6c077e39cb0.gif)\n\nThe request above is then converted to the GraphQL query and variables\n\n```graphql\nquery Query($v1: String!, $v2: SearchType!, $v3: Int) {\n  search(query: $v1, type: $v2, first: $v3) {\n    nodes {\n      ...f3\n    }\n  }\n}\nfragment f1 on User {\n  name\n}\nfragment f2 on Organization {\n  name\n}\nfragment f3 on Repository {\n  name\n  owner {\n    ...f1\n    ...f2\n  }\n}\n```\n\n```json\n{ \"v1\": \"graphql\", \"v2\": \"REPOSITORY\", \"v3\": 5 }\n```\n\n## Install\n\n```bash\nyarn global add graphql-typed-client # needed for the CLI to work globally\nyarn add graphql-typed-client # needed for the generated client to work\n```\n\n## Generate the client\n\nTo generate the client, use the CLI tool\n\n```bash\ngenerate-graphql-client\n```\n\n```bash\nUsage: generate-graphql-client [options]\n\nOptions:\n  -o, --output \u003c./myClient\u003e                    output directory\n  -e, --endpoint \u003chttp://example.com/graphql\u003e  GraphQL endpoint\n  -p, --post                                   use POST for introspection query\n  -s, --schema \u003c./*.graphql\u003e                   glob pattern to match GraphQL schema definition files\n  -f, --fetcher \u003c./schemaFetcher.js\u003e           path to introspection query fetcher file\n  -c, --config \u003c./myConfig.js\u003e                 path to config file\n  -v, --verbose                                verbose output\n  -h, --help                                   output usage information\n```\n\nIf your endpoint is able to respond to introspection query without authentication, provide the `endpoint` option\n(use `post` option to use POST request)\n\n```bash\ngenerate-graphql-client -e http://example.com/graphql -o myClient\n\n# or using POST\ngenerate-graphql-client -e http://example.com/graphql -p -o myClient\n```\n\nIf your endpoint requires authentication or maybe some custom headers, use `fetcher` option to provide\na custom fetcher function.\nWe will pass [`fetch`](https://github.com/matthew-andrews/isomorphic-fetch) and [`qs`](https://github.com/ljharb/qs)\ninstances to your function for convenience, but you can use anything you like to fetch the introspection query\n\n```bash\ngenerate-graphql-client -f customFetcher.js -o myClient\n```\n\n```js\n// customFetcher.js\n\nmodule.exports = function(query, fetch, qs) {\n  return fetch(`https://api.github.com/graphql?${qs.stringify({ query: query })}`, {\n    headers: {\n      Authorization: 'bearer YOUR_GITHUB_API_TOKEN',\n    },\n  }).then(r =\u003e r.json())\n}\n```\n\nIf instead of making a query to some endpoint, you just want to use a GraphQL schema definition, use `schema` option\n\n```bash\ngenerate-graphql-client -s mySchema.graphql -o myClient\n\n# or\ngenerate-graphql-client -s *.graphql -o myClient\n\n# this will also work\ngenerate-graphql-client -s \"type User { name: String } type Query { users: [User] }\" -o myClient\n```\n\nAlternatively, you can use a JS or JSON config file to define how you want the client to be generated.\nAlso, using the config file you can define more than one client.\n\nThe config file should contain an object or an array of objects, each representing a client to be generated.\nObject fields are named the same way as the CLI arguments described above + `options` field\nfor passing various parsing/generation options (see [config.ts](src/config.ts) to learn more)\n\n```bash\ngenerate-graphql-client -c myConfig.js\n```\n\n```js\n// myConfig.js\n\nmodule.exports = [\n  {\n    schema: 'type Query { hello: String }',\n    output: 'clients/simpleClient',\n  },\n  {\n    schema: 'schemas/**/*.graphql',\n    output: 'clients/clientFromSchema',\n  },\n  {\n    endpoint: 'http://example.com/graphql',\n    post: true,\n    output: 'clients/exampleClient',\n  },\n  {\n    fetcher: 'customFetcher.js',\n    output: 'clients/customClient',\n  },\n  {\n    fetcher: (query, fetch, qs) =\u003e\n      fetch(`https://api.github.com/graphql?${qs.stringify({ query })}`, {\n        headers: {\n          Authorization: 'bearer YOUR_GITHUB_API_TOKEN',\n        },\n      }).then(r =\u003e r.json()),\n    output: 'clients/githubClient',\n  },\n]\n```\n\n## Create the client instance\n\nTo create the client instance, you have to call `createClient()` function that was generated with the client\n\nIf you want to execute Queries and Mutations, provide a `fetcher` function.\n\nJust like with the fetcher that can be used for client generation, we will\npass [`fetch`](https://github.com/matthew-andrews/isomorphic-fetch) and [`qs`](https://github.com/ljharb/qs) instances\ninside for convenience, but the function can be implemented in any way you want\n\nIf you want to execute Subscriptions, provide `subscriptionCreatorOptions` object with `uri` and `options` fields, where\n`options` are `ClientOptions` passed down\nto [`subscriptions-transport-ws`](https://github.com/apollographql/subscriptions-transport-ws)\n(`reconnect` and `lazy` options are already enabled by default)\n\n```js\n// myClient.js\n\nimport { createClient } from './clients/myClient/createClient'\n\nexport const myClient = createClient({\n  fetcher: ({ query, variables }, fetch, qs) =\u003e\n    fetch(`http://example.com/graphql?${qs.stringify({ query, variables })}`, {\n      headers: {\n        Authorization: 'bearer MY_TOKEN',\n      },\n    }).then(r =\u003e r.json()),\n  subscriptionCreatorOptions: {\n    uri: 'wss://example.com/graphql-subscriptions',\n    options: {\n      connectionParams: {\n        token: 'MY_TOKEN',\n      },\n    },\n  },\n})\n```\n\n## Making GraphQL requests in JS\n\n#### Raw request syntax\n\nThe format for the request object is visually similar to an actual GraphQL query, so something like\n\n\u003c!-- prettier-ignore --\u003e\n```js\nquery({\n  user: [{ id: 'USER_ID' }, {\n      username: 1,\n      email: 1,\n      on_AdminUser: {\n        isSuperAdmin: 1,\n      },\n  }],\n})\n```\n\nis easily recognizable as\n\n```graphql\nquery {\n  user(id: \"USER_ID\") {\n    username\n    email\n    ... on AdminUser {\n      isSuperAdmin\n    }\n  }\n}\n```\n\nHere are the rules governing the format:\n\n- fields with scalar types are written as\n\n  `name: 1` or `name: true`\n\n- fields with object types are written as JS objects\n\n  `user: { name: 1 }`\n\n- fields that have arguments are written as arrays with argument object and the field selection\n\n  `user: [{ id: 'USER_ID' }, { name: 1 }]`\n\n  - if the field has arguments, but the return type is scalar, just pass the array with argument object\n\n    `userCount: [{ status: 'active' }]`\n\n  - if all the arguments for the field are optional, you can omit the array and just pass the field selection\n\n    `friend: { name: 1 }` is the same as `friend: [{}, { name: 1 }]`\n\n- fields with `union` or `interface` types can have fragments defined on them to select fields of a specific type\n\n  `on_AdminUser: { superAdmin: 1 }`\n\n- **additionally**, there is a special `__scalar` field, that can be included in the field selection to automatically include\n  all scalar fields from an object/interface type\n  (excluding `__typename`, which you have to request manually if you need it)\n\n  `user: { __scalar: 1 }`\n\nHere is an example request object, showing all possible field types\n\n\u003c!-- prettier-ignore --\u003e\n```js\nmyClient.query({\n  user: [{ id: 'USER_ID' }, {\n    username: 1,\n    email: 1,\n    wasEmployed: [{ recently: true }],\n    friends: {\n      username: 1,\n      email: 1,\n    },\n    posts: [{ limit: 5 }, {\n      __scalar: 1,\n    }],\n    pets: {\n      name: 1,\n      on_Cat: {\n        eyeColor: 1,\n      },\n      on_Snake: {\n        length: 1,\n      },\n    },\n  }],\n})\n```\n\nWhen executed, it will send the following GraphQL `query` and `variables` to the server\n\n```json\n{ \"v1\": \"USER_ID\", \"v2\": true, \"v3\": 5 }\n```\n\n```graphql\nquery($v1: ID!, $v2: Boolean, $v3: Int) {\n  user(id: $v1) {\n    username\n    email\n    wasEmployed(recently: $v2)\n    friends {\n      username\n      email\n    }\n    posts(limit: $v3) {\n      ...f1\n    }\n    pets {\n      name\n      ...f2\n      ...f3\n    }\n  }\n}\nfragment f1 on Post {\n  id\n  title\n  content\n}\nfragment f2 on Cat {\n  eyeColor\n}\nfragment f3 on Snake {\n  length\n}\n```\n\n#### Chain request syntax\n\n```js\nmyClient.chain.query.user({ id: 'USER_ID' }).execute({\n  username: 1,\n  email: 1,\n  on_AdminUser: {\n    isSuperAdmin: 1,\n  },\n})\n\n// execute() returns Promise\u003cUser\u003e on query/mutation and Observable\u003cUser\u003e on subscription\n```\n\nIn the chain, each member refers to a GraphQL field going down the tree. Fields with arguments can be called like methods.\nYou can continue the chain so long as the fields that are mentioned are object types or interfaces (not arrays, unions etc.).\nAt any point, you can finish the chain by calling `execute(fieldRequest, defaultValue)`. Calling `execute()` returns\na `Promise` (for query/mutation) or an `Observable` (subscription) of type equal to the type of the last field in the chain.\nUnlike in raw request syntax, where GraphQL errors are just returned in the response, chain execution will **throw** an error\nif GraphQL endpoint responds with `errors`, empty `data` or empty value at the requested path when no `defaultValue`\nwas provided.\n\n##### Default value logic clarification\n\n```graphql\ntype User {\n  status: String\n}\n```\n\n```js\nconst status = await myClient.chain.query.user({ id: 'USER_ID' }).status.execute()\n// status is `String | null`, which means that if user with specified ID exists, any string or null\n// are both considered valid\n// but if the user with specified ID is not found, the Promise returned from `execute()`\n// will throw an error\n\nconst status = await myClient.chain.query.user({ id: 'USER_ID' }).status.execute(1, 'default status')\n// in this case, if the user with specified ID is not found, returned status will be 'default status'\n```\n\n## Custom scalar type mapping\n\nBy default, all custom scalar types are generated as aliases to TypeScript's `any`\n\nYou can override this behavior by providing your own type mapper that will be used during the schema generation and applied\nto query responses\n\nFor example, let's say you have a custom `Date` type. To specify how this type should be serialized/deserialized, create\na type mapper file (`.ts` or `.js`) somewhere in your app\n\n```typescript\n// path/to/typeMapper.ts\n\nimport moment, { Moment } from 'moment'\n\nexport const typeMapper = {\n  Date: {\n    serialize: (date: Moment) =\u003e date.toISOString(),\n    deserialize: (date: string) =\u003e moment(date),\n  },\n}\n```\n\nAdd `typeMapper` option to client generation config\n\n```js\nmodule.exports = {\n  endpoint: 'http://example.com/graphql',\n  output: 'clients/myClient',\n  options: { typeMapper: { location: 'path/to/typeMapper', types: ['Date'] } },\n}\n```\n\nNow, all fields of `Date` type in query responses will be automatically **deserialized**, and the return type of the\n`deserialize()` function is going to be used as the definition for `Date` in generated TypeScript (enabling correct code\ncompletion and type checking). All query variables of `Date` type and input object types that have `Date` fields will be\nautomatically **serialized** before sending.\n\n\u003c!-- prettier-ignore --\u003e\n```typescript\nmyClient\n  .query({\n    // `activatedAfter` is a `Date` argument, so now it accepts `Moment` instances\n    user: [{ id: 'USER_ID', activatedAfter: moment('1999-01-01') }, {\n      name: 1,\n      birthday: 1,\n    }],\n  })\n  .then(result =\u003e {\n    if (!result.data) return\n    const user = result.data.user\n\n    // moment's methods are now available for `birthday` field in the response\n    console.log(user.birthday.startOf('day').toISOString())\n  })\n```\n\n## Type guards\n\nAdditionally, Typescript [type guard functions](https://www.typescriptlang.org/docs/handbook/advanced-types.html) are\ngenerated for every object, interface and union type in your schema\n\n\u003c!-- prettier-ignore --\u003e\n```typescript\nimport { isCat, isSnake } from './clients/testClient/schema'\n\nmyClient\n  .query({\n    pet: [{ id: 'PET_ID' }, {\n      name: 1,\n      on_Cat: { eyeColor: 1 },\n      on_Snake: { length: 1 },\n    }],\n  })\n  .then(result =\u003e {\n    if (!result.data) return\n    const pet = result.data.pet\n\n    console.log(pet.name) // pet type is abstract type Pet, so you only get access to shared fields\n\n    if (isCat(pet)) {\n      console.log(pet.eyeColor) // pet type is Cat, so you get access to fields of the specific type\n    } else if (isSnake(pet)) {\n      console.log(pet.length) // same here\n    }\n  })\n```\n\n## Notes on type annotation generation\n\n- all known Scalar types are converted to their Typescript counterparts\n- all unknown Scalar types are converted to type aliases for `any` unless type mapper is provided\n- all Enum types are converted to Typescript enums, so you can import and use them in your code\n  (even if you're not using Typescript)\n\n## Notes on subscriptions\n\nThe generated client uses [Apollo](https://www.apollographql.com/)'s\n[`subscriptions-transport-ws`](https://github.com/apollographql/subscriptions-transport-ws) for executing **Subscriptions**\n\nSubscriptions are wrapped in [RxJs](https://github.com/ReactiveX/rxjs)' `Observable` which is chained\nto the `SubscriptionClient` so that a connection is opened when you subscribe to the first subscription,\nshared among all subscriptions and closed when you unsubscribe from the last one.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsar1008%2Fgraphql-typed-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsar1008%2Fgraphql-typed-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsar1008%2Fgraphql-typed-client/lists"}