{"id":13880779,"url":"https://github.com/GraphtonLib/Graphton","last_synced_at":"2025-07-16T17:31:10.854Z","repository":{"id":44366985,"uuid":"433876714","full_name":"GraphtonLib/Graphton","owner":"GraphtonLib","description":"The TypeScript SDK code generator for any (external) GraphQL API.","archived":false,"fork":false,"pushed_at":"2025-06-06T08:09:24.000Z","size":101261,"stargazers_count":14,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-06T15:03:45.415Z","etag":null,"topics":["graphql","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/GraphtonLib.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":"FUNDING.yml","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},"funding":{"patreon":"roboroads","ko_fi":"roboroads","custom":"https://www.paypal.com/donate/?business=GVP8H97X2KWPS\u0026no_recurring=0\u0026currency_code=EUR"}},"created_at":"2021-12-01T15:15:06.000Z","updated_at":"2023-12-01T18:40:45.000Z","dependencies_parsed_at":"2024-11-24T12:19:30.704Z","dependency_job_id":null,"html_url":"https://github.com/GraphtonLib/Graphton","commit_stats":{"total_commits":177,"total_committers":5,"mean_commits":35.4,"dds":"0.29378531073446323","last_synced_commit":"c1cf8ca1682bbf8a60e6468307beec1903416ed3"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/GraphtonLib/Graphton","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GraphtonLib%2FGraphton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GraphtonLib%2FGraphton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GraphtonLib%2FGraphton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GraphtonLib%2FGraphton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GraphtonLib","download_url":"https://codeload.github.com/GraphtonLib/Graphton/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GraphtonLib%2FGraphton/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265139897,"owners_count":23717432,"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":["graphql","typescript"],"created_at":"2024-08-06T08:03:28.451Z","updated_at":"2025-07-16T17:31:08.769Z","avatar_url":"https://github.com/GraphtonLib.png","language":"TypeScript","funding_links":["https://patreon.com/roboroads","https://ko-fi.com/roboroads","https://www.paypal.com/donate/?business=GVP8H97X2KWPS\u0026no_recurring=0\u0026currency_code=EUR","https://www.patreon.com/roboroads"],"categories":["TypeScript"],"sub_categories":[],"readme":"![Graphton Logo](./.github/Branding/logo-text.png)\n\n![Current package version](https://img.shields.io/github/package-json/v/GraphtonLib/Graphton?label=Current%20Version\u0026style=flat-square)\n![Downloads on NPM](https://img.shields.io/npm/dt/@graphtonlib/graphton?style=flat-square\u0026label=Downloads)\n![GitHub Release Date](https://img.shields.io/github/release-date/GraphtonLib/Graphton?label=Release%20Date\u0026style=flat-square)\n![GitHub last commit](https://img.shields.io/github/last-commit/GraphtonLib/Graphton?style=flat-square)\n\n# Graphton\n\nA JS/TS generator that builds a GraphQL query builder for your API\n\n## Index\n\n- [Installing](#installing)\n    - [Yarn](#yarn)\n    - [npm](#npm)\n- [CLI Usage \u0026 options](#cli-usage--options)\n    - [Example CLI usage](#example-cli-usage)\n    - [Tip: add to scripts](#tip-add-to-scripts)\n- [Using the generated file](#using-the-generated-file)\n    - [Build a query](#build-a-query)\n    - [Add returnfields](#add-returnfields)\n    - [Execute the query](#execute-the-query)\n    - [Running a mutation](#running-a-mutation)\n    - [Dynamically changing return fields](#dynamically-changing-return-fields)\n    - [Global Settings](#global-settings)\n- [Reference](#reference)\n    - [Note: abstraction](#note-abstraction)\n    - [GraphtonBaseQuery](#graphtonbasequery)\n        - [setArgs](#setargs)\n        - [select](#select)\n        - [deselect](#deselect)\n        - [toQuery](#toquery)\n        - [get](#get)\n        - [do](#do)\n    - [GraphtonEnum](#graphtonenum)\n        - [parse](#parse)\n        - [list](#list)\n    - [GraphtonSettings](#graphtonsettings)\n        - [headers](#headers)\n        - [graphqlEndpoint](#graphqlendpoint)\n- [Links](#links)\n- [Credits](#credits)\n- [Contributing](#contributing)\n\n## Installing\n\nYou can install Graphton to your dev-dependencies using a package manager.\n\n#### Yarn\n\n```bash\nyarn add -D @graphtonlib/grapton\n# Then to run:\nyarn graphton generate https://example.com/graphql\n```\n\n#### npm\n\n```bash\nnpm i --save-dev @graphtonlib/grapton\n# Then to run:\nnpm run graphton generate https://example.com/graphql\n```\n\n## CLI Usage \u0026 options\n\n```text\nUsage: graphton generate [options] \u003cschemaUri\u003e\n\nArguments:\n  schemaUri                                 URL to GraphQL endpoint or path to introspection json.\n\nOptions:\n  -o, --outputFile \u003cpath\u003e                   Path to the generated js/ts file (default: \"./src/graphton.generated.ts\")\n  -q, --exportQueryFactoryAs \u003cname\u003e         How you want to import your query factory. (default: \"Query\")\n  -m, --exportMutationFactoryAs \u003cname\u003e      How you want to import your mutation factory. (default: \"Mutation\")\n  -s, --exportSubscriptionFactoryAs [name]  If you want a subscription factory, if no name provided \"Subscription\" will be used. (default: false)\n  -Q, --queryFunction \u003cname\u003e                The name of the function that posts the query. (default: \"get\")\n  -M, --mutateFunction \u003cname\u003e               The name of the function that posts the mutation. (default: \"do\")\n  -S, --subscribeFunction \u003cname\u003e            The name of the function that posts the subscription. (default: \"subscribe\")\n  -d, --defineScalar \u003cscalars...\u003e           Define custom scalars and their TS type. Use this if you don't want (some) scalars to be typed as string by default. (eg. --defineScalar Date=number Time=any)\n  -h, --help                                display help for command\n```\n\n### Example CLI usage\n\n```bash\nyarn graphton generate -o ./src/lib/graphton.js https://example.com/graphql\n```\n\n### Tip: add to scripts\n\nAs you are creating a complete custom command to generate your SDK, it might become cumbersome to remember all the options you added to the command. It's a good idea to add it to your scripts object in your `package.json` so you and your team always use the same generator command.\n\n```json\n//package.json\n{\n  \"scripts\": {\n    \"generate\": \"graphton generate -o ./src/lib/graphton.js https://example.com/graphql\"\n  }\n}\n```\n\nThen generate the files using:\n\n```bash\nyarn generate\n# Or\nnpm run generate\n```\n\n## Using the generated file\n\nWhen the ts/js file is generated you can import the `Query` and `Mutation` factory instances from it.\n\n```typescript\nimport { Query, Mutation } from \"./graphton.generated.js\";\n```\n\n\u003e Note: the names `Query` and `Mutation` are configurable! See [CLI Usage \u0026 options](#CLI+Usage+\u0026+options)\n\n\u003e Note: Since graphton does not handle subscriptions (yet?) since implementations can differ per-situation, subscription queries are optional. See [CLI Usage \u0026 options](#CLI+Usage+\u0026+options) to how to generate them. You can use `getQuery` to output the query and use your own implementation.\n\n\u003e For the following examples, the example graphql schema from [example/schema.graphql](example/schema.graphql) will be used.\n\n### Build a query\n\nStarting a new query is fairly simple. Import `Query` from the generated file and call the method with the same name as the query you want to execute.\n\n```typescript\nimport { Query } from \"./example/graphton.generated.js\";\n\nconst usersQuery = Query.users();\nconst getFirstUserQuery = Query.user({ id: 1 });\n```\n\n### Add returnfields\n\nIn GraphQL you have to define which fields you want to get in return. You define which ones by using `select`\n\n```typescript\nimport { Query } from \"./example/graphton.generated.js\";\n\nconst usersQuery = Query.users().returnFields((r) =\u003e r.all());\nconst getFirstUserQuery = Query.user({ id: 1 }).select({\n  id: {},\n  name: {},\n  posts: {\n    text: {},\n  },\n});\n```\n\n### Execute the query\n\nAfter building the query, you can directly execute it with the `get()` method.\n\n```typescript\nimport { Query } from \"./example/graphton.generated.js\";\n\nconst firstUser = await Query.user({ id: 1 })\n  .select({\n    id: {},\n    name: {},\n    posts: {\n      text: {},\n    },\n  })\n  .get();\n\n// firstUser = {\n//     data: {\n//         id: 1,\n//         name: 'User One',\n//         posts: [\n//             {\n//                 text: 'A sample post!'\n//             },\n//             {\n//                 text: 'Enother sample post'\n//             }\n//         ]\n//     },\n//     axiosResponse: /*AxiosReponse*/,\n// }\n```\n\n### Running a mutation\n\nRunning mutations is about the same as running a query. The only diferences are:\n\n- You import `Mutation` instead of `Query`.\n- Instead of `.get()` you run `.do()`\n\n```typescript\nimport { Mutation } from \"./example/graphton.generated.js\";\n\nconst newUser = await Mutation.createUser({ name: \"User Infinite\" })\n  .select({ _all: {} }) // _all will expand automatically to return all shallow fields\n  .do();\nconst updatedUser = await Mutation.updateUser({ id: 1, name: \"User NotOne\", age: 12 })\n  .select({ _all: {} }) // Selecting all shallow fields again\n  .deselect({ name: {} }) // But removing name\n  .do();\n```\n\n### Dynamically changing return fields\n\nReturn fields can be dynamically changed.\n\n```typescript\nimport { Query } from \"./example/graphton.generated.js\";\n\nconst firstUserQuery = Query.user({ id: 1 }).select({\n  id: {},\n  name: {}\n});\n\nif (getUserPosts) {\n  // Adds text of all posts to the query - does NOT replace the already selected id and name\n  firstUserQuery.select({\n    posts: {\n      text: {},\n    },\n  });\n}\n```\n\n### Global Settings\n\nYou can change some of the settings, used for making the call to the server, like URL or headers.\n\n```typescript\nimport { GraphtonSettings } from \"./example/graphton.generated.js\";\n\nGraphtonSettings.headers = { Authentication: \"Bearer XXX\" };\n```\n\n## Reference\n\n### Note: abstraction\n\nMost of the reference underneath here is **very abstract**, since we do not know how the external GraphQL schema looks like which you are going to use this on. Because of this, whenever you see a `$` next to something in this guide means that **it's a value or type that is replaced to accomodate your GraphQL schema**.\n\nThat said, if you use the .ts variant of the generated output, tsc or your IDE can tell you exactly where something goes wrong.\n\n**This is why we recommend TypeScript**. The JavaScrips variant works just fine, but without any error correction or autocomplete it might be a little harder to do the thing you want to do.\n\n### GraphtonBaseQuery\n\n_GraphtonBaseQuery_ is abstract, the classes you will call are generated and extended from this base class.\n\n#### setArgs\n\n_Only available if the query has arguments_\n\nSignature: `setArgs(queryArgs: $ArgumentType): this`\n\nSet the arguments for this query to `queryArgs` (overwriting previous arguments).\n\n#### select\n\n_Only available if the return type is an OBJECT_\n\n`select(fields: Partial\u003c$FieldSelectorType\u003e): this`\n\nAdd new fields to the return object (merges recursively).\n\n#### deselect\n\n_Only available if the return type is an OBJECT_\n\nSignature: `deselect(fields: Partial\u003c$FieldSelectorType\u003e): this`\n\nRemoves selected fields from the query.\n\n\u003e Note: _all will also remove objects instead of just the shallow fields.\n\n#### toQuery\n\nSignature: `toQuery(): string`\n\nTransform to graphql Query string.\n\n#### get\n\n_Only available on Query type requests_\n\nSignature: `get(requestConfig: AxiosRequestConfig = {}): Promise\u003cQueryResponse \u0026 { [p:string]: any; axiosResponse: AxiosResponse; }\u003e`\n\nExecute the query and get the results.\n\n#### do\n\n_Only available on Mutation type requests_\n\nSignature: `do(requestConfig: AxiosRequestConfig = {}): Promise\u003cQueryResponse \u0026 { [p:string]: any; axiosResponse: AxiosResponse; }\u003e`\n\nDo the mutation on the server.\n\n### GraphtonEnum\n\nIntermediary class used to correctly parse Enums in arguments. Your Enum values can be gotten with how you would normally call an enum.\n\n```typescript\nQuery.usersOrdered({\n  orderBy: [\n    {\n      column: UserSortColumn.age,\n      order: SortOrder.ASC,\n    },\n  ],\n});\n```\n\n#### parse\n\n\u003e public static parse(value: keyof typeof $GraphtonEnum.possibleValues): $GraphtonEnum\n\nTransforms a string into an enum.\n\nAlias:\n\n```typescript\n$GraphtonEnum.VALUE;\n// Is the same as\n$GraphtonEnum.parse(\"VALUE\");\n```\n\n#### list\n\n\u003e public static list(): $GraphtonEnum[]\n\nGives you a list of possible enums\n\n### GraphtonSettings\n\nGraphton uses the static properties of this class, so you can customize these.\n\n#### headers\n\n\u003e public static headers = { };\n\nSet the headers for each following request to the server.\n\n```typescript\nGraphtonSettings.headers = { Authorization: \"Bearer 123abc\" };\n```\n\n#### graphqlEndpoint\n\n\u003e public static graphqlEndpoint: string = '\u003cURL of retrospection\u003e';\n\nSet the URL to the GraphQL endpoint, defaults to the URL used when generating the file.\n\n```typescript\nGraphtonSettings.graphqlEndpoint = \"https://mycoolexample.app/graphql\";\n```\n\n## Links\n\n- [💡 GitHub Issues](https://github.com/Roboroads/laravel-tinker/issues): feature requests and bug reports\n- [🙏🏼 Patreon](https://www.patreon.com/roboroads): Consider supporting this project if it helped you 😊\n\n## Credits\n\n- [Robbin \"Roboroads\" Schepers](https://github.com/Roboroads) - Creator / First contributor.\n- Other github projects:\n    - [laravel/laravel](https://github.com/laravel/laravel) - This plugin is inspired by the way Laravel Eloquent builds queries.\n- [Contributors to this project](https://github.com/Roboroads/laravel-tinker/graphs/contributors)\n    - _I **will** name you seperately if your amount of contributions is exceptional_\n\n## Contributing\n\nAny tips or feedback is welcome in the [Issues Tab](https://github.com/Roboroads/laravel-tinker/issues) - or better, make me a PR!\n\nWant to be part of Graphton? Every positive contribution is welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGraphtonLib%2FGraphton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGraphtonLib%2FGraphton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGraphtonLib%2FGraphton/lists"}