{"id":13727228,"url":"https://github.com/dotansimha/graphql-typed-document-node","last_synced_at":"2025-05-14T01:04:17.233Z","repository":{"id":37029726,"uuid":"279532580","full_name":"dotansimha/graphql-typed-document-node","owner":"dotansimha","description":"An improved version of `DocumentNode` for seamless TypeScript integration for GraphQL. ","archived":false,"fork":false,"pushed_at":"2025-04-16T23:05:42.000Z","size":720,"stargazers_count":395,"open_issues_count":23,"forks_count":21,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-22T00:38:24.430Z","etag":null,"topics":["generated","graphql","graphql-codegen","types","typescript"],"latest_commit_sha":null,"homepage":"https://the-guild.dev/blog/typed-document-node","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/dotansimha.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-07-14T08:51:23.000Z","updated_at":"2025-04-18T03:28:23.000Z","dependencies_parsed_at":"2023-02-18T21:15:53.034Z","dependency_job_id":"cf0a66eb-37fb-4e6b-bcac-c9a604d8b3ad","html_url":"https://github.com/dotansimha/graphql-typed-document-node","commit_stats":{"total_commits":118,"total_committers":17,"mean_commits":"6.9411764705882355","dds":0.4661016949152542,"last_synced_commit":"59e6f17b26f5b36f70d984f491fbea5897eee25e"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotansimha%2Fgraphql-typed-document-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotansimha%2Fgraphql-typed-document-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotansimha%2Fgraphql-typed-document-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotansimha%2Fgraphql-typed-document-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotansimha","download_url":"https://codeload.github.com/dotansimha/graphql-typed-document-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250358248,"owners_count":21417445,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["generated","graphql","graphql-codegen","types","typescript"],"created_at":"2024-08-03T01:03:45.202Z","updated_at":"2025-05-14T01:04:17.178Z","avatar_url":"https://github.com/dotansimha.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"## `graphql-typed-document-node`\n\nThis repository is the home for `graphql-typed-document-node` and integration related to it.\n\n[You can read more, see example and try it out live here](https://the-guild.dev/blog/typed-document-node)\n\n`graphql-typed-document-node` is a development tool for creating fully typed `DocumentNode` objects. It means that just by passing the GraphQL query/mutation/subscription/fragment to a supporting GraphQL client library, you'll get a fully type result object and variables object.\n\nIt made possible by [TypeScript type inference](https://www.typescriptlang.org/docs/handbook/type-inference.html).\n\n\u003cimg src=\"https://thumbs.gfycat.com/ArtisticAgreeableHapuku-size_restricted.gif\" width=\"100%\" /\u003e\n\nThis project works in the following way:\n\n1. Configure your project to use this library (see `How to use?` below).\n2. Write your GraphQL operations (`query` / `mutation` / `subscription` / `fragment`).\n3. [GraphQL Code Generator](https://graphql-code-generator.com/) will generate a `TypedDocumentNode` for your operations (which is a bundle of pre-compiled `DocumentNode` with the operation result type and variables type).\n4. You'll get automatic type inference, auto-complete and type checking based on your GraphQL operation.\n\n## Supported Libraries\n\nAs of 2022, most GraphQL Client libraries supports `TypedDocumentNode` out of the box.\n\nThe following patches are currently supported:\n\n### Built-in support\n\n- `@apollo/client` (v4 and also, `\u003e=3.2.0`, if you are using React Components (`\u003cQuery\u003e`) you **still need a patch**)\n- `apollo-angular` (since `2.6.0`)\n- `@urql/core` (since `1.15.0`)\n- `@urql/preact` (since `1.4.0`)\n- `urql` (since `1.11.0`)\n- `@urql/exchange-graphcache` (since `3.1.11`)\n- `@urql/svelte` (since `1.1.3`)\n- `villus` (since `1.0.0-beta.8`)\n- `graphql-js` (since `15.2.0`)\n- `@vue/apollo-composable` (since `4.0.0-alpha.13`)\n- `graphql-request` (since `5.0.0`)\n- `graphql-js` (since v16)\n\n## How to use?\n\n\u003e ‼️ In most cases, you should not deal with `TypedDocumentNode` directly, but use a library that supports it under the hood.\n\nWe recommend to use GraphQL Codegen with [`client-preset`](https://the-guild.dev/graphql/codegen/plugins/presets/preset-client) for the ideal setup. [You can follow the guides section in GraphQL-Codegen website](https://the-guild.dev/graphql/codegen/docs/guides/react-vue)\n\n## Utils\n\nThe `core` package of typed-document-node exports 3 types only:\n\n- `TypedDocumentNode` - the base of this library.\n- `ResultOf` - a utils for extracting the result type from an existing `TypeDocumentNode` instance (`ResultOf\u003ctypeof MyQueryDocument\u003e`)\n- `VariablesOf` - a utils for extracting the variables type from an existing `TypeDocumentNode` instance (`VariablesOf\u003ctypeof MyQueryDocument\u003e`)\n\n## How can I support this in my library?\n\nIf you are a library maintainer, and you wish to have built-in TS support in your library, you can add support for `TypedDocumentNode` without having any breaking changes to your API.\n\nBasically, in any place where you need to have typed access to the result type of an operation, or to a typed variables object, make sure to have generics for both types, and use `TypeDocumentNode` in your arguments, instead of `DocumentNode`. This will allow TypeScript to infer the types based on the object you are passing to it later.\n\n#### Before\n\n```ts\ntype GqlFetchResult = {\n  data?: any;\n  errors?: Error[];\n};\n\nexport function gqlFetch(\n  operation: DocumentNode,\n  variables?: Record\u003cstring, any\u003e\n): GqlFetchResult {\n  // ...\n}\n```\n\n#### After\n\n```ts\nimport { TypedDocumentNode } from \"@graphql-typed-document-node/core\";\n\ntype GqlFetchResult\u003cTData = any\u003e = {\n  data?: TData;\n  errors?: Error[];\n};\n\nexport function gqlFetch\u003cTData = any, TVariables = Record\u003cstring, any\u003e\u003e(\n  operation: TypedDocumentNode\u003cTData, TVariables\u003e,\n  variables?: TVariables\n): GqlFetchResult\u003cTData\u003e;\nexport function gqlFetch\u003cTData = any, TVariables = Record\u003cstring, any\u003e\u003e(\n  operation: DocumentNode,\n  variables?: TVariables\n): GqlFetchResult\u003cTData\u003e {\n  // ...\n}\n```\n\n# Thanks \u0026 Inspiration\n\n- https://github.com/dotansimha/graphql-code-generator/issues/1777#issue-437813742 for the concept of generating unified clients support\n- https://github.com/Shopify/quilt/blob/main/packages/graphql-typed/src/index.ts for similar idea\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotansimha%2Fgraphql-typed-document-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotansimha%2Fgraphql-typed-document-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotansimha%2Fgraphql-typed-document-node/lists"}