{data.drawCard.name}
;\n};\n```\n",
"data": {
@@ -20,26 +10,26 @@ var htmlContent = {
},
"excerpt": ""
},
- "markdown/index.md": {
- "content": "\nStrongly Typed GraphQL from the team at [GraphQL Editor](https://graphqleditor.com/?utm_source=graphql_zeus_github)\n\nGraphQL Zeus is the absolute best way to interact with your GraphQL endpoints in a type-safe way. Zeus uses your schema to generate Typescript types and strongly typed clients to unlock the power, efficiency, productivity and safety of Typescript on your GraphQL requests.\n\n## Features\n\n\u26A1\uFE0F Types mapped from your schema \n\u26A1\uFE0F Works with Apollo Client, React Query, Stucco Subscriptions _(\\*more coming soon...)_
\n\u26A1\uFE0F Works with Subscriptions
\n\u26A1\uFE0F Infer complex response types
\n\u26A1\uFE0F Create reusable selection sets (like fragments) for use across multiple queries
\n\u26A1\uFE0F Supports GraphQL Unions, Interfaces, Aliases and Variables
\n\u26A1\uFE0F Handles **massive** schemas
\n\u26A1\uFE0F Supports Browsers, Node.js and React Native in Javascript and Typescript
\n\u26A1\uFE0F Schema downloader
\n\u26A1\uFE0F JSON schema generation
\n\n## Generate Types With Zeus CLI Example\n\nSimply run Zeus in your terminal to output your types file based on your graphql schema\n\n\n\n## Usage Example\n\nExample using a generated `chain` client. Queries, mutations and subscriptions are now type-safe in arguments, field selections and response types.\n\n\n\n## Support And Community\n\n[Join our GraphQL Editor Channel on Slack!](https://join.slack.com/t/graphqleditor/shared_invite/enQtNDkwOTgyOTM5OTc1LWI4YjU3N2U5NGVkNzQ2NzY5MGUxMTJiNjFlZDM1Zjc2OWRmNTI0NDM3OWUxYTk4Yjk3MzZlY2QwOWUzZmM2NDI)\n\nLeave a GitHub star \u2B50\uFE0F \u{1F60A}\n\nSpread the word!\n\n## Contribute\n\nFor a complete guide to contributing to GraphQL Editor, see the [Contribution Guide](CONTRIBUTING.md).\n\n1. Fork this repo\n2. Create your feature branch: git checkout -b feature-name\n3. Commit your changes: git commit -am 'Add some feature'\n4. Push to the branch: git push origin my-new-feature\n5. Submit a pull request\n\n## License\n\nMIT \u{1F54A}\n", + "markdown/plugins/typedDocumentNode.md": { + "content": "\n## Usage with Typed Document Node\n\nZeus can generate builders for [`TypedDocumentNode`][typed-document-node], a type-safe query\nrepresentation understood by most GraphQL clients (including Apollo, urql etc) by adding the\n`--typedDocumentNode` or `--td` flag to the CLI.\n\n### Generate Type-Safe Zeus Schema And TypedDocumentNode query builders\n\n```sh\n$ zeus https://yourschema.com/graphql ./ --typedDocumentNode\n# typedDocumentNode.ts file with typed document node builders is now in the output destination\n```\n\n### TypedDocumentNode + Apollo Client useQuery examples\n\nThe following example demonstrates usage with Apollo. Other clients should work similarly.\n\n```tsx\nimport { typedGql } from './zeus/typedDocumentNode';\nimport { Gql, SpecialSkills, Thunder, Zeus, InputType, Selector, GraphQLTypes, useZeusVariables } from './zeus';\nimport { useQuery } from '@apollo/client';\n\nconst variables = useZeusVariables({ cardId: 'String!' })({\n cardId: 'blabla',\n});\nconst { $ } = variables;\n\nconst myQuery = typedGql('query')(\n {\n drawCard: {\n id: true,\n Attack: true,\n Defense: true,\n },\n cardById: [{ cardId: $('cardId') }, { id: true }],\n },\n { variables },\n);\n\nconst Main = () => {\n const { data } = useQuery(myQuery, {\n // use those values or provide other values than default\n variables: variables.values,\n });\n // data response is typed\n return
{data.drawCard.name}
;\n};\n```\n\n[typed-document-node]: https://www.graphql-code-generator.com/plugins/typed-document-node\n",
"data": {
- "link": "",
- "title": ""
+ "link": "plugins/typedDocumentNode",
+ "title": "TypedDocumentNode",
+ "order": 4,
+ "category": "Plugins"
},
"excerpt": ""
},
- "markdown/plugins/react-query.md": {
- "content": "\n## Usage with React Query\n\nZeus can generate type-safe versions of React Query's `useQuery`, `useMutation` etc.. React hooks as `useTypedQuery`, `useTypedMutation` etc... by adding the `--reactQuery` flag to the CLI. All types `data` response are then inherited from the Zeus query. \u{1F680}\n\n```sh\n$ zeus schema.graphql ./ --reactQuery\n```\n\n```tsx\nimport { useTypedQuery } from './zeus/reactQuery';\n\nconst Main = () => {\n const { data } = useTypedQuery({\n // Get autocomplete here:\n drawCard: {\n name: true,\n },\n });\n // data response is now typed\n return {data.drawCard.name}
;\n};\n```\n",
+ "markdown/index.md": {
+ "content": "\nStrongly Typed GraphQL from the team at [GraphQL Editor](https://graphqleditor.com/?utm_source=graphql_zeus_github)\n\nGraphQL Zeus is the absolute best way to interact with your GraphQL endpoints in a type-safe way. Zeus uses your schema to generate Typescript types and strongly typed clients to unlock the power, efficiency, productivity and safety of Typescript on your GraphQL requests.\n\n## Features\n\n\u26A1\uFE0F Types mapped from your schema \n\u26A1\uFE0F Works with Apollo Client, React Query, Stucco Subscriptions _(\\*more coming soon...)_
\n\u26A1\uFE0F Works with Subscriptions
\n\u26A1\uFE0F Infer complex response types
\n\u26A1\uFE0F Create reusable selection sets (like fragments) for use across multiple queries
\n\u26A1\uFE0F Supports GraphQL Unions, Interfaces, Aliases and Variables
\n\u26A1\uFE0F Handles **massive** schemas
\n\u26A1\uFE0F Supports Browsers, Node.js and React Native in Javascript and Typescript
\n\u26A1\uFE0F Schema downloader
\n\u26A1\uFE0F JSON schema generation
\n\n## Generate Types With Zeus CLI Example\n\nSimply run Zeus in your terminal to output your types file based on your graphql schema\n\n\n\n## Usage Example\n\nExample using a generated `chain` client. Queries, mutations and subscriptions are now type-safe in arguments, field selections and response types.\n\n\n\n## Support And Community\n\n[Join our GraphQL Editor Channel on Slack!](https://join.slack.com/t/graphqleditor/shared_invite/enQtNDkwOTgyOTM5OTc1LWI4YjU3N2U5NGVkNzQ2NzY5MGUxMTJiNjFlZDM1Zjc2OWRmNTI0NDM3OWUxYTk4Yjk3MzZlY2QwOWUzZmM2NDI)\n\nLeave a GitHub star \u2B50\uFE0F \u{1F60A}\n\nSpread the word!\n\n## Contribute\n\nFor a complete guide to contributing to GraphQL Editor, see the [Contribution Guide](CONTRIBUTING.md).\n\n1. Fork this repo\n2. Create your feature branch: git checkout -b feature-name\n3. Commit your changes: git commit -am 'Add some feature'\n4. Push to the branch: git push origin my-new-feature\n5. Submit a pull request\n\n## License\n\nMIT \u{1F54A}\n", "data": { - "link": "plugins/react-query", - "title": "React Query", - "order": 2, - "category": "Plugins" + "link": "", + "title": "" }, "excerpt": "" }, "markdown/graphql/variables.md": { - "content": "\n## GraphQL Variables\n\nIt's simple to perform queries with variables by importing and using the `$` function from the Zeus output and calling it with the variable name in backticks.\n\n```ts\nimport { Gql, $ } from './zeus';\n\nconst addCardResult = await Gql('mutation')(\n {\n addCard: [\n {\n card: $`card`,\n },\n {\n id: true,\n description: true,\n name: true,\n Attack: true,\n skills: true,\n Children: true,\n Defense: true,\n cardImage: {\n bucket: true,\n region: true,\n key: true,\n },\n },\n ],\n },\n {\n variables: {\n card: {\n Attack: 2,\n Defense: 3,\n description: 'Lord of the mountains',\n name: 'Golrog',\n },\n },\n },\n);\n```\n\nNote: The mutation function created by the Zeus versions of React Hooks like the Apollo Client version of `useTypedMutation` can be supplied with variable values at invocation eg:\n\n```typescript\nconst [addCard, { data, loading, error }] = useTypedMutation({ ...myMutation });\n\nawait addCard({\n variables: {\n card: {\n Attack: 2,\n Defense: 3,\n description: 'Lord of the mountains',\n name: 'Golrog',\n },\n },\n});\n```\n", + "content": "\n## GraphQL Variables\n\nIt's simple to perform queries with variables by using `useZeusVariables` function. It forces you to be type-safe also\n\n```ts\nimport { Gql, useZeusVariables } from './zeus';\nconst variables = useZeusVariables({ Attack: 'Int!', Defense: 'Int!' })({\n card: {\n Attack: 2,\n Defense: 3,\n description: 'Lord of the mountains',\n name: 'Golrog',\n },\n});\nconst { $ } = variables;\n\nconst addCardResult = await Gql('mutation')(\n {\n addCard: [\n {\n card: $('card'),\n },\n {\n id: true,\n description: true,\n name: true,\n Attack: true,\n skills: true,\n Children: true,\n Defense: true,\n cardImage: {\n bucket: true,\n region: true,\n key: true,\n },\n },\n ],\n },\n {\n variables,\n },\n);\n```\n\nNote: The mutation function created by the Zeus versions of React Hooks like the Apollo Client version of `useTypedMutation` can be supplied with variable values at invocation eg:\n\n```typescript\nconst [addCard, { data, loading, error }] = useTypedMutation({ ...myMutation });\n\nawait addCard({\n variables: variables.values,\n});\n```\n", "data": { "link": "graphql/variables", "title": "Variables", @@ -48,12 +38,22 @@ var htmlContent = { }, "excerpt": "" }, - "markdown/graphql/interfaces-and-unions.md": { - "content": '\n## GraphQL Unions\n\nYou can use Zeus with [GraphQL Unions](https://spec.graphql.org/June2018/#sec-Unions):\n\n```js\nconst { drawChangeCard } = await chain(\'query\')({\n drawChangeCard: {\n __typename: true,\n \'...on EffectCard\': {\n effectSize: true,\n name: true,\n },\n \'...on SpecialCard\': {\n effect: true,\n name: true,\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n "effectSize": 195.99532210956377,\n "name": "Destinee",\n "__typename": "EffectCard"\n}\n```\n\n## GraphQL Interfaces\n\nZeus works with [GraphQL Interfaces](http://spec.graphql.org/June2018/#sec-Interfaces)\n\n```ts\nconst { nameables } = await Gql(\'query\')({\n nameables: {\n __typename: true,\n name: true,\n \'...on CardStack\': {\n cards: {\n Defense: true,\n },\n },\n \'...on Card\': {\n Attack: true,\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n "nameables": [\n {\n "__typename": "EffectCard",\n "name": "Hector"\n },\n {\n "__typename": "CardStack",\n "name": "Scotty",\n "cards": [\n {\n "Defense": 1950\n },\n {\n "Defense": 76566\n }\n ]\n },\n {\n "__typename": "SpecialCard",\n "name": "Itzel"\n }\n ]\n}\n```\n', + "markdown/plugins/stucco.md": { + "content": "\n## Usage with Stucco Subscriptions\n\nZeus can generate types for the Stucco Subscription library by adding the --stuccoSubscriptions flag to the CLI. All types in `data` are then inherited from the Zeus Query\n\n```sh\n$ zeus schema.graphql ./ --stuccoSubscriptions\n```\n\n```typescript\nstuccoSubscriptions(\n (apiFetchResult) => [apiFetchResult.url],\n 'https://my.backend/graphql',\n)({ drawCard: { Attack: true } }).on((args) => args.drawCard.Attack);\n```\n", "data": { - "link": "graphql/interfaces-and-unions", - "title": "Interfaces and Unions", - "order": 1, + "link": "plugins/stucco", + "title": "Stucco", + "order": 3, + "category": "Plugins" + }, + "excerpt": "" + }, + "markdown/graphql/scalars.md": { + "content": "\n## Scalars\n\nIn Zeus you can encode and decode scalars\n\n### Decode\n\nDecode function is called every time scalar returns from backend before passing the result from Chain,Subscription functions\n\n```gql\nscalar JSON\nscalar Datetime\ntype Card{\n info: JSON!\n createdAt: Datetime\n}\ntype Query:{\n drawCard: Card!\n}\n```\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst data = await chain('query', {\n scalars: {\n JSON: {\n encode: (e: unknown) => JSON.stringify(e),\n decode: (e: unknown) => JSON.parse(e as string),\n },\n Datetime: {\n decode: (e: unknown) => new Date(e as string),\n encode: (e: unknown) => (e as Date).toISOString(),\n },\n },\n})({\n drawCard: {\n info: true,\n },\n});\n```\n\nSo the `data.drawCard.info` will be of type `Date` as provided by decoder `ReturnType`\n\n### Encode Scalars\n\nYou can also encode scalars before sending them to backend\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query', {\n scalars: {\n JSON: {\n encode: (e: unknown) => JSON.stringify(e),\n decode: (e: unknown) => JSON.parse(e as string),\n },\n Datetime: {\n decode: (e: unknown) => new Date(e as string),\n encode: (e: unknown) => (e as Date).toISOString(),\n },\n },\n})({\n drawCard: {\n info: true,\n },\n});\n```\n\nEncoders require value to be encoded to string and don't work with variables yet.\n\n## Place decoders and encoders in one place for reuse\n\n```ts\nimport { Chain, ZeusScalars } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\nconst scalars = ZeusScalars({\n JSON: {\n encode: (e: unknown) => JSON.stringify(e),\n decode: (e: unknown) => JSON.parse(e as string),\n },\n Datetime: {\n decode: (e: unknown) => new Date(e as string),\n encode: (e: unknown) => (e as Date).toISOString(),\n },\n});\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query', {\n scalars,\n})({\n drawCard: {\n info: true,\n },\n});\n```\n", + "data": { + "link": "graphql/scalars", + "title": "Scalars", + "order": 6, "category": "GraphQL" }, "excerpt": "" @@ -68,8 +68,38 @@ var htmlContent = { }, "excerpt": "" }, + "markdown/graphql/directives.md": { + "content": "\n## GraphQL Directives\n\nZeus supports using directives on fields.\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query')({\n drawCard: {\n name: true,\n skills: true,\n Attack: `@skip(if: true)`,\n },\n});\n```\n\nSo you need to put full string instead of `true`.\n\n### Use on object field\n\nUse directive on `drawCard`\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query')({\n drawCard: {\n __directives: `@skip(if:true)`,\n name: true,\n skills: true,\n },\n});\n```\n\n### Use on function\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query')({\n drawCard: {\n name: true,\n skills: true,\n attack:[\n {\n cardId:['2312321']\n },\n {\n __directives: `@skip(if:true)`,\n name: true,\n skills: true,\n }\n ]\n }\n});\n```\n\n### Use it with variables\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\nconst variables = useZeusVariables({\n isDefense: 'Boolean!'\n})({\n isDefense:true\n});\nconst { $ } = variables;\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query')({\n drawCard: {\n name: true,\n skills: true,\n Attack: `@skip(if: ${$('isDefense')})`,\n },\n {\n variables\n }\n});\n```\n", + "data": { + "link": "graphql/directives", + "title": "Directives", + "order": 5, + "category": "GraphQL" + }, + "excerpt": "" + }, + "markdown/plugins/react-query.md": { + "content": "\n## Usage with React Query\n\nZeus can generate type-safe versions of React Query's `useQuery`, `useMutation` etc.. React hooks as `useTypedQuery`, `useTypedMutation` etc... by adding the `--reactQuery` flag to the CLI. All types `data` response are then inherited from the Zeus query. \u{1F680}\n\n```sh\n$ zeus schema.graphql ./ --reactQuery\n```\n\n```tsx\nimport { useTypedQuery } from './zeus/reactQuery';\n\nconst Main = () => {\n const { data } = useTypedQuery({\n // Get autocomplete here:\n drawCard: {\n name: true,\n },\n });\n // data response is now typed\n return
{data.drawCard.name}
;\n};\n```\n",
+ "data": {
+ "link": "plugins/react-query",
+ "title": "React Query",
+ "order": 2,
+ "category": "Plugins"
+ },
+ "excerpt": ""
+ },
+ "markdown/graphql/interfaces-and-unions.md": {
+ "content": '\n## GraphQL Unions\n\nYou can use Zeus with [GraphQL Unions](https://spec.graphql.org/June2018/#sec-Unions):\n\n```js\nconst { drawChangeCard } = await chain(\'query\')({\n drawChangeCard: {\n __typename: true,\n \'...on EffectCard\': {\n effectSize: true,\n name: true,\n },\n \'...on SpecialCard\': {\n effect: true,\n name: true,\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n "effectSize": 195.99532210956377,\n "name": "Destinee",\n "__typename": "EffectCard"\n}\n```\n\n## GraphQL Interfaces\n\nZeus works with [GraphQL Interfaces](http://spec.graphql.org/June2018/#sec-Interfaces)\n\n```ts\nconst { nameables } = await Gql(\'query\')({\n nameables: {\n __typename: true,\n name: true,\n \'...on CardStack\': {\n cards: {\n Defense: true,\n },\n },\n \'...on Card\': {\n Attack: true,\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n "nameables": [\n {\n "__typename": "EffectCard",\n "name": "Hector"\n },\n {\n "__typename": "CardStack",\n "name": "Scotty",\n "cards": [\n {\n "Defense": 1950\n },\n {\n "Defense": 76566\n }\n ]\n },\n {\n "__typename": "SpecialCard",\n "name": "Itzel"\n }\n ]\n}\n```\n',
+ "data": {
+ "link": "graphql/interfaces-and-unions",
+ "title": "Interfaces and Unions",
+ "order": 1,
+ "category": "GraphQL"
+ },
+ "excerpt": ""
+ },
"markdown/graphql/aliases.md": {
- "content": '\n## GraphQL Aliases\n\nZeus supports declaring aliases \u{1F978}\n\n```ts\nconst aliasedQueryExecute = await chain(\'query\')({\n listCards: {\n __alias: {\n atak: {\n attack: [\n { cardID: [\'1\'] },\n {\n name: true,\n description: true,\n },\n ],\n },\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n "listCards": [\n {\n "atak": {\n "attack": [\n {\n "name": "Zelma",\n "description": "Central"\n }\n ]\n }\n }\n ]\n}\n```\n\nNow you can access properties type-safe like this\n\n```javascript\naliasedQueryExecute.listCards.map((c) => c.atak.attack);\n```\n',
+ "content": '\n## GraphQL Aliases\n\nZeus supports declaring aliases \u{1F978}\n\n```ts\nconst aliasedQueryExecute = await chain(\'query\')({\n listCards: {\n __alias: {\n atak: {\n attack: [\n { cardID: [\'1\'] },\n {\n name: true,\n description: true,\n },\n ],\n },\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n "listCards": [\n {\n "atak": [\n {\n "name": "Zelma",\n "description": "Central"\n }\n ]\n }\n ]\n}\n```\n\nNow you can access properties type-safe like this\n\n```javascript\naliasedQueryExecute.listCards.map((c) => c.atak);\n```\n',
"data": {
"link": "graphql/aliases",
"title": "Aliases",
@@ -78,8 +108,28 @@ var htmlContent = {
},
"excerpt": ""
},
+ "markdown/examples/state.md": {
+ "content": "\nWhen query returns an object and you want to store it in React State, you can use zeus to have 100% type-safe objects in your state.\n\nHaving the following schema:\n\n```graphql\ntype Query {\n listUsers: [User!]\n}\n\ntype User {\n createdAt: String!\n firstName: String!\n lastName: String!\n age: Int\n username: String!\n id: String!\n}\n```\n\nYou can use zeus types to get the type of the objects received from GraphQL Backend\n\n```tsx\nimport React, { useState } from 'react';\nimport { GraphQLTypes, InputType, Selector, Chain } from './zeus';\n\nconst userSelector = Selector('User')({\n createdAt: true,\n firstName: true,\n lastName: true,\n id: true,\n});\n\ntype StoredUser = InputType\n {users.map((u) => (\n
\n );\n};\n```\n",
+ "data": {
+ "link": "state",
+ "title": "React State",
+ "order": 2,
+ "category": "Examples"
+ },
+ "excerpt": ""
+ },
+ "markdown/examples/forms.md": {
+ "content": "\nTo use zeus with forms you should make use of it's generated ValueTypes. When submitting form using a mutation It is much easier and type-safe to do it using `ValueTypes`.\n\nHaving the following schema:\n\n```graphql\ntype Mutation {\n createUser(user: CreateUser!): String\n}\n\ninput CreateUser {\n firstName: String!\n lastName: String!\n age: Int\n username: String!\n}\n```\n\nYou can use `ValueTypes['CreateUser']` as params for submit form function\n\n```ts\nconst submitForm = (values: ValueTypes['CreateUser']) => {\n // ..,rest of the code, validation\n return Chain('https://yourschemaurl.com/graphql', {\n headers: {\n Authorization: 'yourtoken',\n },\n })('mutation')({\n createUser: [{ user: values }, true],\n });\n};\n```\n",
+ "data": {
+ "link": "forms",
+ "title": "Forms",
+ "order": 1,
+ "category": "Examples"
+ },
+ "excerpt": ""
+ },
"markdown/basics/use-as-a-library.md": {
- "content": "\n## Generate Code\n\nThis will be rarely used, but here you are! Generate Typescript and Javascript from GraphQL definitions\n\n```js\nimport { TreeToTS } from 'graphql-zeus';\nimport { Parser } from 'graphql-js-tree';\n\nconst schemaFileContents = `\ntype Query{\n hello: String!\n}\nschema{\n query: Query\n}\n`;\n\nconst typeScriptDefinition = TreeToTS.resolveTree(Parser.parse(schemaFileContents));\n\nconst jsDefinition = TreeToTS.javascript(Parser.parse(schemaFileContents));\n```\n\n## Dynamically Fetch Schema\n\nThis is useful when you need your schema fetched from your GraphQL endpoint in-code\n\n```js\nimport { Utils } from 'graphql-zeus';\n\nUtils.getFromUrl('https://faker.graphqleditor.com/a-team/olympus/graphql').then((schemaContent) => {\n // Use schema content here\n});\n```\n",
+ "content": "\n## Generate Code\n\nThis will be rarely used, but here you are! Generate Typescript and Javascript from GraphQL definitions\n\n```js\nimport { TreeToTS } from 'graphql-zeus';\nimport { Parser } from 'graphql-js-tree';\n\nconst schemaFileContents = `\ntype Query{\n hello: String!\n}\nschema{\n query: Query\n}\n`;\n\nconst typeScriptDefinition = TreeToTS.resolveTree(Parser.parse(schemaFileContents));\n```\n\n## Dynamically Fetch Schema\n\nThis is useful when you need your schema fetched from your GraphQL endpoint in-code\n\n```js\nimport { Utils } from 'graphql-zeus';\n\nUtils.getFromUrl('https://faker.graphqleditor.com/a-team/olympus/graphql').then((schemaContent) => {\n // Use schema content here\n});\n```\n",
"data": {
"link": "library",
"title": "Use as a library",
@@ -89,7 +139,7 @@ var htmlContent = {
"excerpt": ""
},
"markdown/basics/spec.md": {
- "content": "\n## Zeus Spec\n\nPromise of type query data object is returned.\n\n```\nPROMISE_RETURNING_OBJECT = Chain.[OPERATION_NAME]({\n ...FUNCTION_FIELD_PARAMS\n})(\n ...QUERY_OBJECT\n).then ( RESPONSE_OBJECT => RESPONSE_OBJECT[OPERATION_FIELD] )\n```\n\nSimple function params object\n\n```\nFUNCTION_FIELD_PARAMS = {\n KEY: VALUE\n}\n```\n\nQuery object\n\n```\nQUERY_OBJECT = {\n ...RETURN_PARAMS\n}\n```\n\nReturn params is an object containing RETURN_KEY - true if it is a `scalar`, RETURN_PARAMS if `type` otherwise it is a function where you pass field params and type return params.\n\n```\nRETURN_PARAMS = {\n RETURN_KEY: true,\n RETURN_KEY: {\n ...RETURN_PARAMS\n },\n RETURN_FUNCTION_KEY:[\n {\n ...FUNCTION_FIELD_PARAMS\n },\n {\n ...RETURN_PARAMS\n }\n ]\n}\n```\n\n### Use Alias Spec\n\n```\nRETURN_PARAMS = {\n __alias: RETURN_PARAMS\n}\n```\n\nAccess aliased operation type-safe\n\n```\nPROMISE_RETURNING_OBJECT[ALIAS_STRING][OPERATION_NAME]\n```\n",
+ "content": "\n## Zeus Spec\n\nPromise of type query data object is returned.\n\n```\nPROMISE_RETURNING_OBJECT = Chain.[OPERATION_NAME]({\n ...FUNCTION_FIELD_PARAMS\n})(\n ...QUERY_OBJECT\n).then ( RESPONSE_OBJECT => RESPONSE_OBJECT[OPERATION_FIELD] )\n```\n\nSimple function params object\n\n```\nFUNCTION_FIELD_PARAMS = {\n KEY: VALUE\n}\n```\n\nQuery object\n\n```\nQUERY_OBJECT = {\n ...RETURN_PARAMS\n}\n```\n\nReturn params is an object containing RETURN_KEY - true if it is a `scalar`, RETURN_PARAMS if `type` otherwise it is a function where you pass field params and type return params.\n\n```\nRETURN_PARAMS = {\n RETURN_KEY: true,\n RETURN_KEY: {\n ...RETURN_PARAMS\n },\n RETURN_FUNCTION_KEY:[\n {\n ...FUNCTION_FIELD_PARAMS\n },\n {\n ...RETURN_PARAMS\n }\n ]\n}\n```\n\n### Use Alias Spec\n\n```\nRETURN_PARAMS = {\n __alias: RETURN_PARAMS\n}\n```\n\nAccess aliased operation type-safe\n\n```\nPROMISE_RETURNING_OBJECT[ALIAS_STRING]\n```\n",
"data": {
"link": "spec",
"title": "Specification",
@@ -98,6 +148,16 @@ var htmlContent = {
},
"excerpt": ""
},
+ "markdown/basics/getting-started.md": {
+ "content": "\n## Getting Started\n\nUse the Zeus CLI to generate types and GraphQL clients based on your schema which you can then import into your projects to autocomplete, query and use GraphQL responses in a type-safe way.\n\n## Quick Start\n\n### Installation\n\n```sh\n$ npm i -g graphql-zeus\n# OR\n# yarn global add graphql-zeus\n```\n\nYou can also install locally to a project and then use as a npm or yarn script command or with `npx` or `yarn` directly eg:\n\n```sh\n$ npx zeus schema.graphql ./\n# OR\n# yarn zeus schema.graphql ./\n```\n\n### TypeScript\n\nZeus is Typescript native, you can refer to imported types directly from the generated output of the CLI\n\n```sh\n$ zeus schema.graphql ./\n```\n\n## Demo Endpoint\n\nAll demo code here is using the demo GraphQL endpoint of [Olympus Cards](https://app.graphqleditor.com/a-team/olympus) built with [GraphQL Editor](https://graphqleditor.com/). Feel free to check out the [GraphiQL interface](https://faker.graphqleditor.com/a-team/olympus/graphql) too.\n\n## Query With Zeus Chain Client\n\nYou can now use the Zeus `Chain` client from the generated output to make type-safe queries and mutations to your endpoint and receive type-safe responses.\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query')({\n cardById: [\n {\n cardId: 'da21ce0a-40a0-43ba-85c2-6eec2bf1ae21',\n },\n {\n name: true,\n description: true,\n },\n ],\n listCards: {\n name: true,\n skills: true,\n attack: [\n { cardID: ['66c1af53-7d5e-4d89-94b5-1ebf593508f6', 'fc0e5757-4d8a-4f6a-a23b-356ce167f873'] },\n {\n name: true,\n },\n ],\n },\n drawCard: {\n name: true,\n skills: true,\n Attack: true,\n },\n});\n// listCardsAndDraw is now typed as the response of the query.\n```\n\nWhen querying a GraphQL field which takes an argument such as `cardById` above, then the fields are defined in terms of a tuple eg: cardById: `[ {...arguments} , {...response_selection_set} ]` the equivalent in gql syntax would be:\n\n```text\ncardById (cardId: \"da21ce0a-40a0-43ba-85c2-6eec2bf1ae21\") {\n name\n description\n}\n```\n\nFor fields which have no argument they receive only the response selection set object values.\n\nNote: `Chain` will also accept a second argument of fetch-like options to configure the client with properties such as `credentials`, `mode`, `headers` etc...\n\nNote: There is also an exported Zeus `Gql` convenience function is a Chain client pre-configured with the endpoint specified in the CLI.\n\n## Listen on a WebSocket - GraphQL Subscriptions\n\nUse the Zeus `Subscription` client creator in your generated output to create WebSocket connections to your GraphQL socket.\n\n```ts\nimport { Subscription } from './zeus';\n\n// Create a Subscription client instance with the endpoint\nconst sub = Subscription('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Call the client instance and listen for responses\nsub('subscription')({\n deck: {\n id: true,\n },\n}).on((response) => {\n console.log(response.deck);\n});\n```\n\n[Read more about subscriptions](./subscriptions)\n\n## Usage with NodeJS\n\nGenerates clients for use with Node.js\n\n```sh\n$ zeus schema.graphql ./ --node\n```\n\n## Usage with React Native\n\nAs normal\n\n```sh\n$ zeus schema.graphql ./\n```\n\n## Other CLI Options\n\nSpecify the output folder with second argument\n\n```sh\n$ zeus schema.graphql ./generated\n```\n\nOutput Typescript Only with `--typescript` flag\n\n```sh\n$ zeus schema.graphql ./ --typescript\n```\n\nLoad your schema from an URL with an URL in the first argument\n\n```sh\n$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./\n```\n\nDownload and save GraphQL schema to a local path with `--graphql=savePath` flag\n\n```sh\n$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --graphql=generated\n```\n\nGenerate and save a JSON schema to a local path with `--jsonSchema=savePath` flag\n\n```sh\n$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --graphql=generated\n```\n\nAdd a header value with `--header=value` flag\n\n```sh\n$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --header=Authorization:myNiceAuthHeader\n```\n\nGet help with Zeus CLI with:\n\n```sh\n$ zeus help\n```\n\n### Tip:\n\nAdd a script entry in your `package.json` file for quickly calling Zeus generation:\n\n```json\n\"scripts\": {\n//...\n\"generate\": \"zeus https://faker.graphqleditor.com/a-team/olympus/graphql zeusGenerated --typescript --header='My-Auth-Secret:JsercjjJY5MmghtHww6UF' --apollo\"\n},\n```\n",
+ "data": {
+ "link": "getting-started",
+ "title": "Getting Started",
+ "order": 0,
+ "category": "Basics"
+ },
+ "excerpt": ""
+ },
"markdown/basics/selector.md": {
"content": "\n## Generate Reusable Selection Sets\n\nIn TypeScript Zeus can help make type-safe Zeus selection sets to reuse across queries.\n\n```ts\nimport { Selector, Chain } from './zeus';\n\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\nconst cardSelector = Selector('Card')({\n name: true,\n description: true,\n Attack: true,\n skills: true,\n Defense: true,\n cardImage: {\n key: true,\n bucket: true,\n },\n});\n\nconst queryWithSelectionSet = await chain('query')({\n drawCard: cardSelector,\n});\n```\n\n## Inferring the response type\n\nSometimes you would like to infer the response type. The it is best to use selectors\n\n```tsx\nimport { Selector, InputType, GraphQLTypes } from './zeus';\n\nexport const drawCardQuery = Selector(\"Query\"){\n drawCard: {\n Attack: true,\n Children: true,\n id: true,\n },\n});\n\ntype InferredResponseType = InputType\n
\n ))}\n {getFullName(u)}
\n {u.createdAt}
\n Strongly Typed GraphQL from the team at GraphQL Editor
-GraphQL Zeus is the absolute best way to interact with your GraphQL endpoints in a type-safe way. Zeus uses your schema to generate Typescript types and strongly typed clients to unlock the power, efficiency, productivity and safety of Typescript on your GraphQL requests.
-Features
-⚡️ Types mapped from your schema
-⚡️ Works with Apollo Client, React Query, Stucco Subscriptions (*more coming soon...)
-⚡️ Works with Subscriptions
-⚡️ Infer complex response types
-⚡️ Create reusable selection sets (like fragments) for use across multiple queries
-⚡️ Supports GraphQL Unions, Interfaces, Aliases and Variables
-⚡️ Handles massive schemas
-⚡️ Supports Browsers, Node.js and React Native in Javascript and Typescript
-⚡️ Schema downloader
-⚡️ JSON schema generation
Generate Types With Zeus CLI Example
-Simply run Zeus in your terminal to output your types file based on your graphql schema
-
Usage Example
-Example using a generated chain client. Queries, mutations and subscriptions are now type-safe in arguments, field selections and response types.
Support And Community
-Join our GraphQL Editor Channel on Slack!
-Leave a GitHub star ⭐️ 😊
-Spread the word!
-Contribute
-For a complete guide to contributing to GraphQL Editor, see the Contribution Guide.
--
-
- Fork this repo -
- Create your feature branch: git checkout -b feature-name -
- Commit your changes: git commit -am 'Add some feature' -
- Push to the branch: git push origin my-new-feature -
- Submit a pull request -
License
-MIT 🕊
-Perform Queries with Thunder - An Abstracted Fetch Function
-With Zeus Thunder you have total control of fetch function but will not lose the result type. ⚡️
import { Thunder } from './zeus';
-
-// Create thunder fetch client with endpoint, options and response handlers
-const thunder = Thunder(async (query) => {
- const response = await fetch('https://faker.graphqleditor.com/a-team/olympus/graphql', {
- body: JSON.stringify({ query }),
- method: 'POST',
- headers: {
- 'Content-Type': 'application/json',
- },
- });
-
- if (!response.ok) {
- return new Promise((resolve, reject) => {
- response
- .text()
- .then((text) => {
- try {
- reject(JSON.parse(text));
- } catch (err) {
- reject(text);
- }
- })
- .catch(reject);
- });
- }
-
- const json = await response.json();
-
- return json.data;
-});
-
-// Call thunder client with type-safe arguments, fields and get type-safe result type
-const listCardsAndDraw = await thunder('query')({
- cardById: [
- {
- cardId: 'sdsd',
- },
- {
- description: true,
- },
- ],
- listCards: {
- name: true,
- skills: true,
- attack: [
- { cardID: ['s', 'sd'] },
- {
- name: true,
- },
- ],
- },
- drawCard: {
- name: true,
- skills: true,
- Attack: true,
- },
-});
-Return with .js import for esModules
-Due to validity of .js imports in TS for esmodules you can use flag es to generate .js imports
$ zeus schema.graphql ./ --es
-Zeus Included Examples
-To run the included examples navigate to: ./examples and install packages with:
$ npm i
-# OR
-# yarn
-then run the examples with
-$ npm run start
-# OR
-# yarn start
-Getting Started
-Use the Zeus CLI to generate types and GraphQL clients based on your schema which you can then import into your projects to autocomplete, query and use GraphQL responses in a type-safe way.
-Quick Start
-Installation
-$ npm i -g graphql-zeus
-# OR
-# yarn global add graphql-zeus
-You can also install locally to a project and then use as a npm or yarn script command or with npx or yarn directly eg:
$ npx zeus schema.graphql ./
-# OR
-# yarn zeus schema.graphql ./
-TypeScript
-Zeus is Typescript native, you can refer to imported types directly from the generated output of the CLI
-$ zeus schema.graphql ./
-Demo Endpoint
-All demo code here is using the demo GraphQL endpoint of Olympus Cards built with GraphQL Editor. Feel free to check out the GraphiQL interface too.
-Query With Zeus Chain Client
-You can now use the Zeus Chain client from the generated output to make type-safe queries and mutations to your endpoint and receive type-safe responses.
import { Chain } from './zeus';
-
-// Create a Chain client instance with the endpoint
-const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
-
-// Query the endpoint with Typescript autocomplete for arguments and response fields
-const listCardsAndDraw = await chain('query')({
- cardById: [
- {
- cardId: 'da21ce0a-40a0-43ba-85c2-6eec2bf1ae21',
- },
- {
- name: true,
- description: true,
- },
- ],
- listCards: {
- name: true,
- skills: true,
- attack: [
- { cardID: ['66c1af53-7d5e-4d89-94b5-1ebf593508f6', 'fc0e5757-4d8a-4f6a-a23b-356ce167f873'] },
- {
- name: true,
- },
- ],
- },
- drawCard: {
- name: true,
- skills: true,
- Attack: true,
- },
-});
-// listCardsAndDraw is now typed as the response of the query.
-When querying a GraphQL field which takes an argument such as cardById above, then the fields are defined in terms of a tuple eg: cardById: [ {...arguments} , {...response_selection_set} ] the equivalent in gql syntax would be:
cardById (cardId: "da21ce0a-40a0-43ba-85c2-6eec2bf1ae21") {
- name
- description
-}
-For fields which have no argument they receive only the response selection set object values.
-Note: Chain will also accept a second argument of fetch-like options to configure the client with properties such as credentials, mode, headers etc...
Note: There is also an exported Zeus Gql convenience function is a Chain client pre-configured with the endpoint specified in the CLI.
Listen on a WebSocket - GraphQL Subscriptions
-Use the Zeus Subscription client creator in your generated output to create WebSocket connections to your GraphQL socket.
import { Subscription } from './zeus';
-
-// Create a Subscription client instance with the endpoint
-const sub = Subscription('https://faker.graphqleditor.com/a-team/olympus/graphql');
-
-// Call the client instance and listen for responses
-sub('subscription')({
- deck: {
- id: true,
- },
-}).on((response) => {
- console.log(response.deck);
-});
-Usage with NodeJS
-Generates clients for use with Node.js
-$ zeus schema.graphql ./ --node
-Usage with React Native
-As normal
-$ zeus schema.graphql ./
-Other CLI Options
-Specify the output folder with second argument
-$ zeus schema.graphql ./generated
-Output Typescript Only with --typescript flag
$ zeus schema.graphql ./ --typescript
-Load your schema from an URL with an URL in the first argument
-$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./
-Download and save GraphQL schema to a local path with --graphql=savePath flag
$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --graphql=generated
-Generate and save a JSON schema to a local path with --jsonSchema=savePath flag
$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --graphql=generated
-Add a header value with --header=value flag
$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --header=Authorization:myNiceAuthHeader
-Get help with Zeus CLI with:
-$ zeus help
-Tip:
-Add a script entry in your package.json file for quickly calling Zeus generation:
"scripts": {
-//...
-"generate": "zeus https://faker.graphqleditor.com/a-team/olympus/graphql zeusGenerated --typescript --header='My-Auth-Secret:JsercjjJY5MmghtHww6UF' --apollo"
-},
-GraphQL Aliases
-Zeus supports declaring aliases 🥸
-const aliasedQueryExecute = await chain('query')({
- listCards: {
- __alias: {
- atak: {
- attack: [
- { cardID: ['1'] },
- {
- name: true,
- description: true,
- },
- ],
- },
- },
- },
-});
-Response:
-{
- "listCards": [
- {
- "atak": {
- "attack": [
- {
- "name": "Zelma",
- "description": "Central"
- }
- ]
- }
- }
- ]
-}
-Now you can access properties type-safe like this
-aliasedQueryExecute.listCards.map((c) => c.atak.attack);
-Generate GraphQL Gql Strings
-Use the Zeus function to generate a gql string
import { Zeus } from './zeus';
-
-const stringGql = Zeus('query', {
- listCards: {
- name: true,
- skills: true,
- Attack: true,
- },
-});
-
-// stringGql value:
-// query{listCards{name skills Attack}}
-GraphQL Unions
-You can use Zeus with GraphQL Unions:
-const { drawChangeCard } = await chain('query')({
- drawChangeCard: {
- __typename: true,
- '...on EffectCard': {
- effectSize: true,
- name: true,
- },
- '...on SpecialCard': {
- effect: true,
- name: true,
- },
- },
-});
-Response:
-{
- "effectSize": 195.99532210956377,
- "name": "Destinee",
- "__typename": "EffectCard"
-}
-GraphQL Interfaces
-Zeus works with GraphQL Interfaces
-const { nameables } = await Gql('query')({
- nameables: {
- __typename: true,
- name: true,
- '...on CardStack': {
- cards: {
- Defense: true,
- },
- },
- '...on Card': {
- Attack: true,
- },
- },
-});
-Response:
-{
- "nameables": [
- {
- "__typename": "EffectCard",
- "name": "Hector"
- },
- {
- "__typename": "CardStack",
- "name": "Scotty",
- "cards": [
- {
- "Defense": 1950
- },
- {
- "Defense": 76566
- }
- ]
- },
- {
- "__typename": "SpecialCard",
- "name": "Itzel"
- }
- ]
-}
-GraphQL Variables
-It's simple to perform queries with variables by importing and using the $ function from the Zeus output and calling it with the variable name in backticks.
import { Gql, $ } from './zeus';
-
-const addCardResult = await Gql('mutation')(
- {
- addCard: [
- {
- card: $`card`,
- },
- {
- id: true,
- description: true,
- name: true,
- Attack: true,
- skills: true,
- Children: true,
- Defense: true,
- cardImage: {
- bucket: true,
- region: true,
- key: true,
- },
- },
- ],
- },
- {
- variables: {
- card: {
- Attack: 2,
- Defense: 3,
- description: 'Lord of the mountains',
- name: 'Golrog',
- },
- },
- },
-);
-Note: The mutation function created by the Zeus versions of React Hooks like the Apollo Client version of useTypedMutation can be supplied with variable values at invocation eg:
const [addCard, { data, loading, error }] = useTypedMutation({ ...myMutation });
-
-await addCard({
- variables: {
- card: {
- Attack: 2,
- Defense: 3,
- description: 'Lord of the mountains',
- name: 'Golrog',
- },
- },
-});
-JavaScript
-To use with Javascript as an autocomplete tool you need to install Typescript, run the Zeus CLI, and then transform the result to JS using tsc
$ npm i -D typescript
-# OR
-# yarn add -D typescript
-Generate Zeus:
-$ zeus schema.graphql ./
-And transform it using Typescript:
-$ npx tsc ./zeus/*.ts --declaration --target es5 --skipLibCheck
-# OR
-# yarn tsc ./zeus/*.ts --declaration --target es5 --skipLibCheck
-This will generate an out.d.ts file so that you can have autocompletion.
Generate Code
-This will be rarely used, but here you are! Generate Typescript and Javascript from GraphQL definitions
-import { TreeToTS } from 'graphql-zeus';
-import { Parser } from 'graphql-js-tree';
-
-const schemaFileContents = `
-type Query{
- hello: String!
-}
-schema{
- query: Query
-}
-`;
-
-const typeScriptDefinition = TreeToTS.resolveTree(Parser.parse(schemaFileContents));
-
-const jsDefinition = TreeToTS.javascript(Parser.parse(schemaFileContents));
-Dynamically Fetch Schema
-This is useful when you need your schema fetched from your GraphQL endpoint in-code
-import { Utils } from 'graphql-zeus';
-
-Utils.getFromUrl('https://faker.graphqleditor.com/a-team/olympus/graphql').then((schemaContent) => {
- // Use schema content here
-});
-Usage with Apollo GraphQL
-Zeus can generate type-safe versions of Apollo Client's useQuery, useMutation, useSubscription and useLazyQuery React hooks as useTypedQuery, useTypedMutation etc... by adding the --apollo flag to the CLI. All types in the data response are then inherited from the Zeus query. 🚀
Generate Type-Safe Zeus Schema And Apollo Client Type-Safe Hooks
-$ zeus schema.graphql ./ --apollo
-# apollo.ts file with typed hooks is now in the output destination
-Apollo Client useTypedQuery Hook Example
-import { useTypedQuery } from './zeus/apollo';
-
-const Main = () => {
- const { data } = useTypedQuery({
- // Get autocomplete here:
- drawCard: {
- name: true,
- },
- });
- // data response is now typed
- return <div>{data.drawCard.name}</div>;
-};
-Inferring the response type for Apollo Client
-If you would like to infer the response type of your query for Apollo Client you can use the Zeus Selector function and InputType utility from the Zeus generated library
import { Selector, InputType, GraphQLTypes } from './zeus';
-
-export const drawCardQuery = Selector('Card')({
- drawCard: {
- id: true,
- name: true,
- Attack: true,
- Children: true,
- },
-});
-
-type DrawCardResponseType = InputType<GraphQLTypes['Card'], typeof drawCardQuery>;
-// DrawCardResponseType is now the response type from the query
-Now drawCardQuery can be reused directly in the typed Apollo Client useTypedQuery later
import { useTypedQuery } from './zeus/apollo';
-import { drawCardQuery } from './';
-
-const Main = () => {
- const { data } = useTypedQuery(drawCardQuery);
- // data is of type DrawCardResponseType as per the above example
- return <div>{data.drawCard.name}</div>;
-};
-Usage with React Query
-Zeus can generate type-safe versions of React Query's useQuery, useMutation etc.. React hooks as useTypedQuery, useTypedMutation etc... by adding the --reactQuery flag to the CLI. All types data response are then inherited from the Zeus query. 🚀
$ zeus schema.graphql ./ --reactQuery
-import { useTypedQuery } from './zeus/reactQuery';
-
-const Main = () => {
- const { data } = useTypedQuery({
- // Get autocomplete here:
- drawCard: {
- name: true,
- },
- });
- // data response is now typed
- return <div>{data.drawCard.name}</div>;
-};
-Usage with Stucco Subscriptions
-Zeus can generate types for the Stucco Subscription library by adding the --stuccoSubscriptions flag to the CLI. All types in data are then inherited from the Zeus Query
$ zeus schema.graphql ./ --stuccoSubscriptions
-stuccoSubscriptions(
- (apiFetchResult) => [apiFetchResult.url],
- 'https://my.backend/graphql',
-)({ drawCard: { Attack: true } }).on((args) => args.drawCard.Attack);
-Generate Reusable Selection Sets
-In TypeScript Zeus can help make type-safe Zeus selection sets to reuse across queries.
-import { Selector, Chain } from './zeus';
-
-const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
-
-const cardSelector = Selector('Card')({
- name: true,
- description: true,
- Attack: true,
- skills: true,
- Defense: true,
- cardImage: {
- key: true,
- bucket: true,
- },
-});
-
-const queryWithSelectionSet = await chain('query')({
- drawCard: cardSelector,
-});
-Inferring the response type
-Sometimes you would like to infer the response type. The it is best to use selectors
-import { Selector, InputType, GraphQLTypes } from './zeus';
-
-export const drawCardQuery = Selector("Query"){
- drawCard: {
- Attack: true,
- Children: true,
- id: true,
- },
-});
-
-type InferredResponseType = InputType<GraphQLTypes['Query'], typeof drawCardQuery>;
-Zeus Spec
-Promise of type query data object is returned.
-PROMISE_RETURNING_OBJECT = Chain.[OPERATION_NAME]({
- ...FUNCTION_FIELD_PARAMS
-})(
- ...QUERY_OBJECT
-).then ( RESPONSE_OBJECT => RESPONSE_OBJECT[OPERATION_FIELD] )
-Simple function params object
-FUNCTION_FIELD_PARAMS = {
- KEY: VALUE
-}
-Query object
-QUERY_OBJECT = {
- ...RETURN_PARAMS
-}
-Return params is an object containing RETURN_KEY - true if it is a scalar, RETURN_PARAMS if type otherwise it is a function where you pass field params and type return params.
RETURN_PARAMS = {
- RETURN_KEY: true,
- RETURN_KEY: {
- ...RETURN_PARAMS
- },
- RETURN_FUNCTION_KEY:[
- {
- ...FUNCTION_FIELD_PARAMS
- },
- {
- ...RETURN_PARAMS
- }
- ]
-}
-Use Alias Spec
-RETURN_PARAMS = {
- __alias: RETURN_PARAMS
-}
-Access aliased operation type-safe
-PROMISE_RETURNING_OBJECT[ALIAS_STRING][OPERATION_NAME]
-{data.drawCard.name}
;\n};\n```\n\n### Inferring the response type for Apollo Client\n\nIf you would like to infer the response type of your query for Apollo Client you can use the Zeus `Selector` function and `InputType` utility from the Zeus generated library\n\n```tsx\nimport { Selector, InputType, GraphQLTypes } from './zeus';\n\nexport const drawCardQuery = Selector('Card')({\n drawCard: {\n id: true,\n name: true,\n Attack: true,\n Children: true,\n },\n});\n\ntype DrawCardResponseType = InputType{data.drawCard.name}
;\n};\n```\n",
- "data": {
- "link": "plugins/apollo",
- "title": "Apollo",
- "order": 1,
- "category": "Plugins"
- },
- "excerpt": ""
- },
- "markdown/index.md": {
- "content": "\nStrongly Typed GraphQL from the team at [GraphQL Editor](https://graphqleditor.com/?utm_source=graphql_zeus_github)\n\nGraphQL Zeus is the absolute best way to interact with your GraphQL endpoints in a type-safe way. Zeus uses your schema to generate Typescript types and strongly typed clients to unlock the power, efficiency, productivity and safety of Typescript on your GraphQL requests.\n\n## Features\n\n\u26A1\uFE0F Types mapped from your schema \n\u26A1\uFE0F Works with Apollo Client, React Query, Stucco Subscriptions _(\\*more coming soon...)_
\n\u26A1\uFE0F Works with Subscriptions
\n\u26A1\uFE0F Infer complex response types
\n\u26A1\uFE0F Create reusable selection sets (like fragments) for use across multiple queries
\n\u26A1\uFE0F Supports GraphQL Unions, Interfaces, Aliases and Variables
\n\u26A1\uFE0F Handles **massive** schemas
\n\u26A1\uFE0F Supports Browsers, Node.js and React Native in Javascript and Typescript
\n\u26A1\uFE0F Schema downloader
\n\u26A1\uFE0F JSON schema generation
\n\n## Generate Types With Zeus CLI Example\n\nSimply run Zeus in your terminal to output your types file based on your graphql schema\n\n\n\n## Usage Example\n\nExample using a generated `chain` client. Queries, mutations and subscriptions are now type-safe in arguments, field selections and response types.\n\n\n\n## Support And Community\n\n[Join our GraphQL Editor Channel on Slack!](https://join.slack.com/t/graphqleditor/shared_invite/enQtNDkwOTgyOTM5OTc1LWI4YjU3N2U5NGVkNzQ2NzY5MGUxMTJiNjFlZDM1Zjc2OWRmNTI0NDM3OWUxYTk4Yjk3MzZlY2QwOWUzZmM2NDI)\n\nLeave a GitHub star \u2B50\uFE0F \u{1F60A}\n\nSpread the word!\n\n## Contribute\n\nFor a complete guide to contributing to GraphQL Editor, see the [Contribution Guide](CONTRIBUTING.md).\n\n1. Fork this repo\n2. Create your feature branch: git checkout -b feature-name\n3. Commit your changes: git commit -am 'Add some feature'\n4. Push to the branch: git push origin my-new-feature\n5. Submit a pull request\n\n## License\n\nMIT \u{1F54A}\n", - "data": { - "link": "", - "title": "" - }, - "excerpt": "" - }, - "markdown/plugins/react-query.md": { - "content": "\n## Usage with React Query\n\nZeus can generate type-safe versions of React Query's `useQuery`, `useMutation` etc.. React hooks as `useTypedQuery`, `useTypedMutation` etc... by adding the `--reactQuery` flag to the CLI. All types `data` response are then inherited from the Zeus query. \u{1F680}\n\n```sh\n$ zeus schema.graphql ./ --reactQuery\n```\n\n```tsx\nimport { useTypedQuery } from './zeus/reactQuery';\n\nconst Main = () => {\n const { data } = useTypedQuery({\n // Get autocomplete here:\n drawCard: {\n name: true,\n },\n });\n // data response is now typed\n return
{data.drawCard.name}
;\n};\n```\n",
- "data": {
- "link": "plugins/react-query",
- "title": "React Query",
- "order": 2,
- "category": "Plugins"
- },
- "excerpt": ""
- },
- "markdown/graphql/variables.md": {
- "content": "\n## GraphQL Variables\n\nIt's simple to perform queries with variables by importing and using the `$` function from the Zeus output and calling it with the variable name in backticks.\n\n```ts\nimport { Gql, $ } from './zeus';\n\nconst addCardResult = await Gql('mutation')(\n {\n addCard: [\n {\n card: $`card`,\n },\n {\n id: true,\n description: true,\n name: true,\n Attack: true,\n skills: true,\n Children: true,\n Defense: true,\n cardImage: {\n bucket: true,\n region: true,\n key: true,\n },\n },\n ],\n },\n {\n variables: {\n card: {\n Attack: 2,\n Defense: 3,\n description: 'Lord of the mountains',\n name: 'Golrog',\n },\n },\n },\n);\n```\n\nNote: The mutation function created by the Zeus versions of React Hooks like the Apollo Client version of `useTypedMutation` can be supplied with variable values at invocation eg:\n\n```typescript\nconst [addCard, { data, loading, error }] = useTypedMutation({ ...myMutation });\n\nawait addCard({\n variables: {\n card: {\n Attack: 2,\n Defense: 3,\n description: 'Lord of the mountains',\n name: 'Golrog',\n },\n },\n});\n```\n",
- "data": {
- "link": "graphql/variables",
- "title": "Variables",
- "order": 2,
- "category": "GraphQL"
- },
- "excerpt": ""
- },
- "markdown/graphql/interfaces-and-unions.md": {
- "content": '\n## GraphQL Unions\n\nYou can use Zeus with [GraphQL Unions](https://spec.graphql.org/June2018/#sec-Unions):\n\n```js\nconst { drawChangeCard } = await chain(\'query\')({\n drawChangeCard: {\n __typename: true,\n \'...on EffectCard\': {\n effectSize: true,\n name: true,\n },\n \'...on SpecialCard\': {\n effect: true,\n name: true,\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n "effectSize": 195.99532210956377,\n "name": "Destinee",\n "__typename": "EffectCard"\n}\n```\n\n## GraphQL Interfaces\n\nZeus works with [GraphQL Interfaces](http://spec.graphql.org/June2018/#sec-Interfaces)\n\n```ts\nconst { nameables } = await Gql(\'query\')({\n nameables: {\n __typename: true,\n name: true,\n \'...on CardStack\': {\n cards: {\n Defense: true,\n },\n },\n \'...on Card\': {\n Attack: true,\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n "nameables": [\n {\n "__typename": "EffectCard",\n "name": "Hector"\n },\n {\n "__typename": "CardStack",\n "name": "Scotty",\n "cards": [\n {\n "Defense": 1950\n },\n {\n "Defense": 76566\n }\n ]\n },\n {\n "__typename": "SpecialCard",\n "name": "Itzel"\n }\n ]\n}\n```\n',
- "data": {
- "link": "graphql/interfaces-and-unions",
- "title": "Interfaces and Unions",
- "order": 1,
- "category": "GraphQL"
- },
- "excerpt": ""
- },
- "markdown/graphql/gql.md": {
- "content": "\n## Generate GraphQL Gql Strings\n\nUse the `Zeus` function to generate a gql string\n\n```js\nimport { Zeus } from './zeus';\n\nconst stringGql = Zeus('query', {\n listCards: {\n name: true,\n skills: true,\n Attack: true,\n },\n});\n\n// stringGql value:\n// query{listCards{name skills Attack}}\n```\n",
- "data": {
- "link": "graphql/gql",
- "title": "Gql string",
- "order": 4,
- "category": "GraphQL"
- },
- "excerpt": ""
- },
- "markdown/graphql/aliases.md": {
- "content": '\n## GraphQL Aliases\n\nZeus supports declaring aliases \u{1F978}\n\n```ts\nconst aliasedQueryExecute = await chain(\'query\')({\n listCards: {\n __alias: {\n atak: {\n attack: [\n { cardID: [\'1\'] },\n {\n name: true,\n description: true,\n },\n ],\n },\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n "listCards": [\n {\n "atak": {\n "attack": [\n {\n "name": "Zelma",\n "description": "Central"\n }\n ]\n }\n }\n ]\n}\n```\n\nNow you can access properties type-safe like this\n\n```javascript\naliasedQueryExecute.listCards.map((c) => c.atak.attack);\n```\n',
- "data": {
- "link": "graphql/aliases",
- "title": "Aliases",
- "order": 3,
- "category": "GraphQL"
- },
- "excerpt": ""
- },
- "markdown/basics/use-as-a-library.md": {
- "content": "\n## Generate Code\n\nThis will be rarely used, but here you are! Generate Typescript and Javascript from GraphQL definitions\n\n```js\nimport { TreeToTS } from 'graphql-zeus';\nimport { Parser } from 'graphql-js-tree';\n\nconst schemaFileContents = `\ntype Query{\n hello: String!\n}\nschema{\n query: Query\n}\n`;\n\nconst typeScriptDefinition = TreeToTS.resolveTree(Parser.parse(schemaFileContents));\n\nconst jsDefinition = TreeToTS.javascript(Parser.parse(schemaFileContents));\n```\n\n## Dynamically Fetch Schema\n\nThis is useful when you need your schema fetched from your GraphQL endpoint in-code\n\n```js\nimport { Utils } from 'graphql-zeus';\n\nUtils.getFromUrl('https://faker.graphqleditor.com/a-team/olympus/graphql').then((schemaContent) => {\n // Use schema content here\n});\n```\n",
- "data": {
- "link": "library",
- "title": "Use as a library",
- "order": 5,
- "category": "Basics"
- },
- "excerpt": ""
- },
- "markdown/basics/spec.md": {
- "content": "\n## Zeus Spec\n\nPromise of type query data object is returned.\n\n```\nPROMISE_RETURNING_OBJECT = Chain.[OPERATION_NAME]({\n ...FUNCTION_FIELD_PARAMS\n})(\n ...QUERY_OBJECT\n).then ( RESPONSE_OBJECT => RESPONSE_OBJECT[OPERATION_FIELD] )\n```\n\nSimple function params object\n\n```\nFUNCTION_FIELD_PARAMS = {\n KEY: VALUE\n}\n```\n\nQuery object\n\n```\nQUERY_OBJECT = {\n ...RETURN_PARAMS\n}\n```\n\nReturn params is an object containing RETURN_KEY - true if it is a `scalar`, RETURN_PARAMS if `type` otherwise it is a function where you pass field params and type return params.\n\n```\nRETURN_PARAMS = {\n RETURN_KEY: true,\n RETURN_KEY: {\n ...RETURN_PARAMS\n },\n RETURN_FUNCTION_KEY:[\n {\n ...FUNCTION_FIELD_PARAMS\n },\n {\n ...RETURN_PARAMS\n }\n ]\n}\n```\n\n### Use Alias Spec\n\n```\nRETURN_PARAMS = {\n __alias: RETURN_PARAMS\n}\n```\n\nAccess aliased operation type-safe\n\n```\nPROMISE_RETURNING_OBJECT[ALIAS_STRING][OPERATION_NAME]\n```\n",
- "data": {
- "link": "spec",
- "title": "Specification",
- "order": 4,
- "category": "Basics"
- },
- "excerpt": ""
- },
- "markdown/basics/selector.md": {
- "content": "\n## Generate Reusable Selection Sets\n\nIn TypeScript Zeus can help make type-safe Zeus selection sets to reuse across queries.\n\n```ts\nimport { Selector, Chain } from './zeus';\n\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\nconst cardSelector = Selector('Card')({\n name: true,\n description: true,\n Attack: true,\n skills: true,\n Defense: true,\n cardImage: {\n key: true,\n bucket: true,\n },\n});\n\nconst queryWithSelectionSet = await chain('query')({\n drawCard: cardSelector,\n});\n```\n\n## Inferring the response type\n\nSometimes you would like to infer the response type. The it is best to use selectors\n\n```tsx\nimport { Selector, InputType, GraphQLTypes } from './zeus';\n\nexport const drawCardQuery = Selector(\"Query\"){\n drawCard: {\n Attack: true,\n Children: true,\n id: true,\n },\n});\n\ntype InferredResponseType = InputType
+ {users.map((u) => (
+
+ );
+};
+```
diff --git a/doc/src/markdown/graphql/aliases.md b/doc/src/markdown/graphql/aliases.md
index 2d9cb9e3..9934c694 100644
--- a/doc/src/markdown/graphql/aliases.md
+++ b/doc/src/markdown/graphql/aliases.md
@@ -33,14 +33,12 @@ Response:
{
"listCards": [
{
- "atak": {
- "attack": [
- {
- "name": "Zelma",
- "description": "Central"
- }
- ]
- }
+ "atak": [
+ {
+ "name": "Zelma",
+ "description": "Central"
+ }
+ ]
}
]
}
@@ -49,5 +47,5 @@ Response:
Now you can access properties type-safe like this
```javascript
-aliasedQueryExecute.listCards.map((c) => c.atak.attack);
+aliasedQueryExecute.listCards.map((c) => c.atak);
```
diff --git a/doc/src/markdown/graphql/directives.md b/doc/src/markdown/graphql/directives.md
new file mode 100644
index 00000000..ddc862fd
--- /dev/null
+++ b/doc/src/markdown/graphql/directives.md
@@ -0,0 +1,101 @@
+---
+link: graphql/directives
+title: Directives
+order: 5
+category: GraphQL
+---
+
+## GraphQL Directives
+
+Zeus supports using directives on fields.
+
+```ts
+import { Chain } from './zeus';
+
+// Create a Chain client instance with the endpoint
+const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
+
+// Query the endpoint with Typescript autocomplete for arguments and response fields
+const listCardsAndDraw = await chain('query')({
+ drawCard: {
+ name: true,
+ skills: true,
+ Attack: `@skip(if: true)`,
+ },
+});
+```
+
+So you need to put full string instead of `true`.
+
+### Use on object field
+
+Use directive on `drawCard`
+
+```ts
+import { Chain } from './zeus';
+
+// Create a Chain client instance with the endpoint
+const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
+
+// Query the endpoint with Typescript autocomplete for arguments and response fields
+const listCardsAndDraw = await chain('query')({
+ drawCard: {
+ __directives: `@skip(if:true)`,
+ name: true,
+ skills: true,
+ },
+});
+```
+
+### Use on function
+
+```ts
+import { Chain } from './zeus';
+
+// Create a Chain client instance with the endpoint
+const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
+
+// Query the endpoint with Typescript autocomplete for arguments and response fields
+const listCardsAndDraw = await chain('query')({
+ drawCard: {
+ name: true,
+ skills: true,
+ attack:[
+ {
+ cardId:['2312321']
+ },
+ {
+ __directives: `@skip(if:true)`,
+ name: true,
+ skills: true,
+ }
+ ]
+ }
+});
+```
+
+### Use it with variables
+
+```ts
+import { Chain } from './zeus';
+
+// Create a Chain client instance with the endpoint
+const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
+const variables = useZeusVariables({
+ isDefense: 'Boolean!'
+})({
+ isDefense:true
+});
+const { $ } = variables;
+// Query the endpoint with Typescript autocomplete for arguments and response fields
+const listCardsAndDraw = await chain('query')({
+ drawCard: {
+ name: true,
+ skills: true,
+ Attack: `@skip(if: ${$('isDefense')})`,
+ },
+ {
+ variables
+ }
+});
+```
diff --git a/doc/src/markdown/graphql/scalars.md b/doc/src/markdown/graphql/scalars.md
new file mode 100644
index 00000000..d7431e35
--- /dev/null
+++ b/doc/src/markdown/graphql/scalars.md
@@ -0,0 +1,112 @@
+---
+link: graphql/scalars
+title: Scalars
+order: 6
+category: GraphQL
+---
+
+## Scalars
+
+In Zeus you can encode and decode scalars
+
+### Decode
+
+Decode function is called every time scalar returns from backend before passing the result from Chain,Subscription functions
+
+```gql
+scalar JSON
+scalar Datetime
+type Card{
+ info: JSON!
+ createdAt: Datetime
+}
+type Query:{
+ drawCard: Card!
+}
+```
+
+```ts
+import { Chain } from './zeus';
+
+// Create a Chain client instance with the endpoint
+const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
+
+// Query the endpoint with Typescript autocomplete for arguments and response fields
+const data = await chain('query', {
+ scalars: {
+ JSON: {
+ encode: (e: unknown) => JSON.stringify(e),
+ decode: (e: unknown) => JSON.parse(e as string),
+ },
+ Datetime: {
+ decode: (e: unknown) => new Date(e as string),
+ encode: (e: unknown) => (e as Date).toISOString(),
+ },
+ },
+})({
+ drawCard: {
+ info: true,
+ },
+});
+```
+
+So the `data.drawCard.info` will be of type `Date` as provided by decoder `ReturnType`
+
+### Encode Scalars
+
+You can also encode scalars before sending them to backend
+
+```ts
+import { Chain } from './zeus';
+
+// Create a Chain client instance with the endpoint
+const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
+
+// Query the endpoint with Typescript autocomplete for arguments and response fields
+const listCardsAndDraw = await chain('query', {
+ scalars: {
+ JSON: {
+ encode: (e: unknown) => JSON.stringify(e),
+ decode: (e: unknown) => JSON.parse(e as string),
+ },
+ Datetime: {
+ decode: (e: unknown) => new Date(e as string),
+ encode: (e: unknown) => (e as Date).toISOString(),
+ },
+ },
+})({
+ drawCard: {
+ info: true,
+ },
+});
+```
+
+Encoders require value to be encoded to string and don't work with variables yet.
+
+## Place decoders and encoders in one place for reuse
+
+```ts
+import { Chain, ZeusScalars } from './zeus';
+
+// Create a Chain client instance with the endpoint
+const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
+const scalars = ZeusScalars({
+ JSON: {
+ encode: (e: unknown) => JSON.stringify(e),
+ decode: (e: unknown) => JSON.parse(e as string),
+ },
+ Datetime: {
+ decode: (e: unknown) => new Date(e as string),
+ encode: (e: unknown) => (e as Date).toISOString(),
+ },
+});
+
+// Query the endpoint with Typescript autocomplete for arguments and response fields
+const listCardsAndDraw = await chain('query', {
+ scalars,
+})({
+ drawCard: {
+ info: true,
+ },
+});
+```
diff --git a/doc/src/markdown/graphql/variables.md b/doc/src/markdown/graphql/variables.md
index 4cb329f5..75bbe02f 100644
--- a/doc/src/markdown/graphql/variables.md
+++ b/doc/src/markdown/graphql/variables.md
@@ -7,7 +7,7 @@ category: GraphQL
## GraphQL Variables
-It's simple to perform queries with variables by importing and using the `$` function from the Zeus output and calling it with the variable name in backticks.
+It's simple to perform queries with variables by using `useZeusVariables` function. It forces you to be type-safe also
```ts
import { Gql, $ } from './zeus';
@@ -16,7 +16,7 @@ const addCardResult = await Gql('mutation')(
{
addCard: [
{
- card: $`card`,
+ card: $('card'),
},
{
id: true,
@@ -36,30 +36,46 @@ const addCardResult = await Gql('mutation')(
},
{
variables: {
- card: {
- Attack: 2,
- Defense: 3,
- description: 'Lord of the mountains',
- name: 'Golrog',
- },
+ Attack: 2,
+ Defense: 3,
+ description: 'Lord of the mountains',
+ name: 'Golrog',
},
},
);
```
-Note: The mutation function created by the Zeus versions of React Hooks like the Apollo Client version of `useTypedMutation` can be supplied with variable values at invocation eg:
+### TypedDocumentNode + Apollo Client useMutation examples
-```typescript
-const [addCard, { data, loading, error }] = useTypedMutation({ ...myMutation });
+The following example demonstrates usage with Apollo. Other clients should work similarly.
-await addCard({
- variables: {
- card: {
- Attack: 2,
- Defense: 3,
- description: 'Lord of the mountains',
- name: 'Golrog',
- },
- },
+```tsx
+import { typedGql } from './zeus/typedDocumentNode';
+import { $ } from './zeus';
+import { useMutation } from '@apollo/client';
+
+const myMutation = typedGql('mutation')({
+ cardById: [{ cardId: $('cardId', 'String!') }, { name: true }],
});
+
+const Main = () => {
+ const [mutate] = useMutation(myMutation);
+ // data response is typed
+ return (
+
+
+ ))}
+ {getFullName(u)}
+ {u.createdAt}
+ {
+ // this are typesafe vars
+ mutate({
+ variables: {
+ cardId: 'du1hn298u1eh',
+ },
+ });
+ }}
+ >
+ Click
+
+ );
+};
```
+
+[typed-document-node]: https://www.graphql-code-generator.com/plugins/typed-document-node
diff --git a/doc/src/markdown/plugins/apollo.md b/doc/src/markdown/plugins/apollo.md
index 0e6d17e6..7a7987ad 100644
--- a/doc/src/markdown/plugins/apollo.md
+++ b/doc/src/markdown/plugins/apollo.md
@@ -7,61 +7,50 @@ category: Plugins
## Usage with Apollo GraphQL
-Zeus can generate type-safe versions of Apollo Client's `useQuery`, `useMutation`, `useSubscription` and `useLazyQuery` React hooks as `useTypedQuery`, `useTypedMutation` etc... by adding the `--apollo` flag to the CLI. All types in the `data` response are then inherited from the Zeus query. 🚀
+From 5.1.3 Zeus apollo should be used with graphql-typed-document-node
+
+```
+npm i @graphql-codegen/typed-document-node
+```
### Generate Type-Safe Zeus Schema And Apollo Client Type-Safe Hooks
```sh
-$ zeus schema.graphql ./ --apollo
+$ zeus schema.graphql ./ --typedDocumentNode
# apollo.ts file with typed hooks is now in the output destination
```
-### Apollo Client `useTypedQuery` Hook Example
-
-```tsx
-import { useTypedQuery } from './zeus/apollo';
-
-const Main = () => {
- const { data } = useTypedQuery({
- // Get autocomplete here:
- drawCard: {
- name: true,
- },
- });
- // data response is now typed
- return {data.drawCard.name}
;
-};
-```
-
-### Inferring the response type for Apollo Client
+### TypedDocumentNode + Apollo Client useMutation examples
-If you would like to infer the response type of your query for Apollo Client you can use the Zeus `Selector` function and `InputType` utility from the Zeus generated library
+The following example demonstrates usage with Apollo. Other clients should work similarly.
```tsx
-import { Selector, InputType, GraphQLTypes } from './zeus';
+import { typedGql } from './zeus/typedDocumentNode';
+import { $ } from './zeus';
+import { useMutation } from '@apollo/client';
-export const drawCardQuery = Selector('Card')({
- drawCard: {
- id: true,
- name: true,
- Attack: true,
- Children: true,
- },
+const myMutation = typedGql('mutation')({
+ cardById: [{ cardId: $('cardId', 'String!') }, { name: true }],
});
-type DrawCardResponseType = InputType{data.drawCard.name}
;
+ const [mutate] = useMutation(myMutation);
+ // data response is typed
+ return (
+ {
+ // this are typesafe vars
+ mutate({
+ variables: {
+ cardId: 'du1hn298u1eh',
+ },
+ });
+ }}
+ >
+ Click
+
+ );
};
```
+
+[typed-document-node]: https://www.graphql-code-generator.com/plugins/typed-document-node
diff --git a/doc/src/markdown/plugins/typedDocumentNode.md b/doc/src/markdown/plugins/typedDocumentNode.md
new file mode 100644
index 00000000..3a9951f5
--- /dev/null
+++ b/doc/src/markdown/plugins/typedDocumentNode.md
@@ -0,0 +1,58 @@
+---
+link: plugins/typedDocumentNode
+title: TypedDocumentNode
+order: 4
+category: Plugins
+---
+
+## Usage with Typed Document Node
+
+```
+npm i @graphql-codegen/typed-document-node
+```
+
+Zeus can generate builders for [`TypedDocumentNode`][typed-document-node], a type-safe query
+representation understood by most GraphQL clients (including Apollo, urql etc) by adding the
+`--typedDocumentNode` or `--td` flag to the CLI.
+
+### Generate Type-Safe Zeus Schema And TypedDocumentNode query builders
+
+```sh
+$ zeus https://yourschema.com/graphql ./ --typedDocumentNode
+# typedDocumentNode.ts file with typed document node builders is now in the output destination
+```
+
+### TypedDocumentNode + Apollo Client useMutation examples
+
+The following example demonstrates usage with Apollo. Other clients should work similarly.
+
+```tsx
+import { typedGql } from './zeus/typedDocumentNode';
+import { $ } from './zeus';
+import { useMutation } from '@apollo/client';
+
+const myMutation = typedGql('mutation')({
+ cardById: [{ cardId: $('cardId', 'String!') }, { name: true }],
+});
+
+const Main = () => {
+ const [mutate] = useMutation(myMutation);
+ // data response is typed
+ return (
+ {
+ // this are typesafe vars
+ mutate({
+ variables: {
+ cardId: 'du1hn298u1eh',
+ },
+ });
+ }}
+ >
+ Click
+
+ );
+};
+```
+
+[typed-document-node]: https://www.graphql-code-generator.com/plugins/typed-document-node
diff --git a/doc/src/purplehaze.d.ts b/doc/src/purplehaze.d.ts
index 6d85d816..5bc56274 100644
--- a/doc/src/purplehaze.d.ts
+++ b/doc/src/purplehaze.d.ts
@@ -1,90 +1,44 @@
-declare const ssg: {"envs": {"SHELL": string;
-"LSCOLORS": string;
-"SESSION_MANAGER": string;
-"COLORTERM": string;
-"XDG_CONFIG_DIRS": string;
+declare const ssg: {"envs": {"PYENV_VIRTUALENV_INIT": string;
+"USER": string;
+"GIT_ASKPASS": string;
+"SHLVL": string;
+"HOME": string;
"LESS": string;
-"XDG_SESSION_PATH": string;
-"NVM_INC": string;
-"XDG_MENU_PREFIX": string;
+"OLDPWD": string;
"TERM_PROGRAM_VERSION": string;
-"APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL": string;
-"HISTSIZE": string;
-"NODE": string;
-"LC_ADDRESS": string;
-"LC_NAME": string;
-"SSH_AUTH_SOCK": string;
-"BREAKPAD_DUMP_LOCATION": string;
-"DESKTOP_SESSION": string;
-"LC_MONETARY": string;
-"SSH_AGENT_PID": string;
-"BAMF_DESKTOP_FILE_HINT": string;
-"NO_AT_BRIDGE": string;
-"EDITOR": string;
-"GTK_MODULES": string;
-"XDG_SEAT": string;
-"PWD": string;
-"GSETTINGS_SCHEMA_DIR": string;
-"LOGNAME": string;
-"XDG_SESSION_DESKTOP": string;
-"QT_QPA_PLATFORMTHEME": string;
-"XDG_SESSION_TYPE": string;
-"PANEL_GDK_CORE_DEVICE_EVENTS": string;
-"_": string;
-"XAUTHORITY": string;
-"VSCODE_GIT_ASKPASS_NODE": string;
-"XDG_GREETER_DATA_DIR": string;
-"MOTD_SHOWN": string;
-"GDM_LANG": string;
-"GTK2_RC_FILES": string;
-"HOME": string;
-"LANG": string;
-"LC_PAPER": string;
-"LS_COLORS": string;
-"XDG_CURRENT_DESKTOP": string;
-"FORCE_COLOR": string;
-"DISABLE_WAYLAND": string;
-"GIT_ASKPASS": string;
-"XDG_SEAT_PATH": string;
-"SAVEHIST": string;
-"INIT_CWD": string;
-"CHROME_DESKTOP": string;
-"NVM_DIR": string;
-"VSCODE_GIT_ASKPASS_EXTRA_ARGS": string;
-"GEM_HOME": string;
-"XDG_SESSION_CLASS": string;
-"TERM": string;
-"LC_IDENTIFICATION": string;
+"VSCODE_IPC_HOOK_CLI": string;
+"LSCOLORS": string;
+"PYENV_SHELL": string;
"ZSH": string;
-"USER": string;
-"VSCODE_GIT_IPC_HANDLE": string;
-"DISPLAY": string;
-"SHLVL": string;
-"NVM_CD_FLAGS": string;
"PAGER": string;
-"LC_TELEPHONE": string;
-"ANDROID_SDK_ROOT": string;
-"LC_MEASUREMENT": string;
-"XDG_VTNR": string;
-"XDG_SESSION_ID": string;
-"XDG_RUNTIME_DIR": string;
-"LC_TIME": string;
"VSCODE_GIT_ASKPASS_MAIN": string;
-"QT_AUTO_SCREEN_SCALE_FACTOR": string;
-"GTK3_MODULES": string;
-"XDG_DATA_DIRS": string;
-"GDK_BACKEND": string;
-"BROWSER": string;
+"YARN_WRAP_OUTPUT": string;
+"VSCODE_GIT_ASKPASS_NODE": string;
+"COLORTERM": string;
+"WSL_DISTRO_NAME": string;
+"VOLTA_HOME": string;
+"_VOLTA_TOOL_RECURSION": string;
+"LOGNAME": string;
+"NAME": string;
+"WSL_INTEROP": string;
+"_": string;
+"TERM": string;
"PATH": string;
-"GDMSESSION": string;
-"ORIGINAL_XDG_CURRENT_DESKTOP": string;
-"DBUS_SESSION_BUS_ADDRESS": string;
-"NVM_BIN": string;
-"MAIL": string;
-"LC_NUMERIC": string;
-"OLDPWD": string;
+"NODE": string;
+"DENO_INSTALL": string;
+"LANG": string;
+"LS_COLORS": string;
"TERM_PROGRAM": string;
+"VSCODE_GIT_IPC_HANDLE": string;
+"SHELL": string;
+"VSCODE_GIT_ASKPASS_EXTRA_ARGS": string;
+"GPG_TTY": string;
+"PWD": string;
+"VIRTUAL_ENV_DISABLE_PROMPT": string;
+"HOSTTYPE": string;
+"INIT_CWD": string;
+"WSLENV": string;
"PATH_PREFIX": string};
"config": {"out": string;
"in": string;
diff --git a/doc/src/ssg/markdown.ts b/doc/src/ssg/markdown.ts
index c704d337..b0e11920 100644
--- a/doc/src/ssg/markdown.ts
+++ b/doc/src/ssg/markdown.ts
@@ -1,14 +1,4 @@
export const htmlContent = {
- "markdown/plugins/stucco.md": {
- "content": "\n## Usage with Stucco Subscriptions\n\nZeus can generate types for the Stucco Subscription library by adding the --stuccoSubscriptions flag to the CLI. All types in `data` are then inherited from the Zeus Query\n\n```sh\n$ zeus schema.graphql ./ --stuccoSubscriptions\n```\n\n```typescript\nstuccoSubscriptions(\n (apiFetchResult) => [apiFetchResult.url],\n 'https://my.backend/graphql',\n)({ drawCard: { Attack: true } }).on((args) => args.drawCard.Attack);\n```\n",
- "data": {
- "link": "plugins/stucco",
- "title": "Stucco",
- "order": 3,
- "category": "Plugins"
- },
- "excerpt": ""
- },
"markdown/plugins/apollo.md": {
"content": "\n## Usage with Apollo GraphQL\n\nZeus can generate type-safe versions of Apollo Client's `useQuery`, `useMutation`, `useSubscription` and `useLazyQuery` React hooks as `useTypedQuery`, `useTypedMutation` etc... by adding the `--apollo` flag to the CLI. All types in the `data` response are then inherited from the Zeus query. 🚀\n\n### Generate Type-Safe Zeus Schema And Apollo Client Type-Safe Hooks\n\n```sh\n$ zeus schema.graphql ./ --apollo\n# apollo.ts file with typed hooks is now in the output destination\n```\n\n### Apollo Client `useTypedQuery` Hook Example\n\n```tsx\nimport { useTypedQuery } from './zeus/apollo';\n\nconst Main = () => {\n const { data } = useTypedQuery({\n // Get autocomplete here:\n drawCard: {\n name: true,\n },\n });\n // data response is now typed\n return {data.drawCard.name}
;\n};\n```\n\n### Inferring the response type for Apollo Client\n\nIf you would like to infer the response type of your query for Apollo Client you can use the Zeus `Selector` function and `InputType` utility from the Zeus generated library\n\n```tsx\nimport { Selector, InputType, GraphQLTypes } from './zeus';\n\nexport const drawCardQuery = Selector('Card')({\n drawCard: {\n id: true,\n name: true,\n Attack: true,\n Children: true,\n },\n});\n\ntype DrawCardResponseType = InputType{data.drawCard.name}
;\n};\n```\n",
"data": {
@@ -19,26 +9,26 @@ export const htmlContent = {
},
"excerpt": ""
},
- "markdown/index.md": {
- "content": "\nStrongly Typed GraphQL from the team at [GraphQL Editor](https://graphqleditor.com/?utm_source=graphql_zeus_github)\n\nGraphQL Zeus is the absolute best way to interact with your GraphQL endpoints in a type-safe way. Zeus uses your schema to generate Typescript types and strongly typed clients to unlock the power, efficiency, productivity and safety of Typescript on your GraphQL requests.\n\n## Features\n\n⚡️ Types mapped from your schema \n⚡️ Works with Apollo Client, React Query, Stucco Subscriptions _(\\*more coming soon...)_
\n⚡️ Works with Subscriptions
\n⚡️ Infer complex response types
\n⚡️ Create reusable selection sets (like fragments) for use across multiple queries
\n⚡️ Supports GraphQL Unions, Interfaces, Aliases and Variables
\n⚡️ Handles **massive** schemas
\n⚡️ Supports Browsers, Node.js and React Native in Javascript and Typescript
\n⚡️ Schema downloader
\n⚡️ JSON schema generation
\n\n## Generate Types With Zeus CLI Example\n\nSimply run Zeus in your terminal to output your types file based on your graphql schema\n\n\n\n## Usage Example\n\nExample using a generated `chain` client. Queries, mutations and subscriptions are now type-safe in arguments, field selections and response types.\n\n\n\n## Support And Community\n\n[Join our GraphQL Editor Channel on Slack!](https://join.slack.com/t/graphqleditor/shared_invite/enQtNDkwOTgyOTM5OTc1LWI4YjU3N2U5NGVkNzQ2NzY5MGUxMTJiNjFlZDM1Zjc2OWRmNTI0NDM3OWUxYTk4Yjk3MzZlY2QwOWUzZmM2NDI)\n\nLeave a GitHub star ⭐️ 😊\n\nSpread the word!\n\n## Contribute\n\nFor a complete guide to contributing to GraphQL Editor, see the [Contribution Guide](CONTRIBUTING.md).\n\n1. Fork this repo\n2. Create your feature branch: git checkout -b feature-name\n3. Commit your changes: git commit -am 'Add some feature'\n4. Push to the branch: git push origin my-new-feature\n5. Submit a pull request\n\n## License\n\nMIT 🕊\n", + "markdown/plugins/typedDocumentNode.md": { + "content": "\n## Usage with Typed Document Node\n\nZeus can generate builders for [`TypedDocumentNode`][typed-document-node], a type-safe query\nrepresentation understood by most GraphQL clients (including Apollo, urql etc) by adding the\n`--typedDocumentNode` or `--td` flag to the CLI.\n\n### Generate Type-Safe Zeus Schema And TypedDocumentNode query builders\n\n```sh\n$ zeus https://yourschema.com/graphql ./ --typedDocumentNode\n# typedDocumentNode.ts file with typed document node builders is now in the output destination\n```\n\n### TypedDocumentNode + Apollo Client useQuery examples\n\nThe following example demonstrates usage with Apollo. Other clients should work similarly.\n\n```tsx\nimport { typedGql } from './zeus/typedDocumentNode';\nimport { Gql, SpecialSkills, Thunder, Zeus, InputType, Selector, GraphQLTypes, useZeusVariables } from './zeus';\nimport { useQuery } from '@apollo/client';\n\nconst variables = useZeusVariables({ cardId: 'String!' })({\n cardId: 'blabla',\n});\nconst { $ } = variables;\n\nconst myQuery = typedGql('query')(\n {\n drawCard: {\n id: true,\n Attack: true,\n Defense: true,\n },\n cardById: [{ cardId: $('cardId') }, { id: true }],\n },\n { variables },\n);\n\nconst Main = () => {\n const { data } = useQuery(myQuery, {\n // use those values or provide other values than default\n variables: variables.values,\n });\n // data response is typed\n return
{data.drawCard.name}
;\n};\n```\n\n[typed-document-node]: https://www.graphql-code-generator.com/plugins/typed-document-node\n",
"data": {
- "link": "",
- "title": ""
+ "link": "plugins/typedDocumentNode",
+ "title": "TypedDocumentNode",
+ "order": 4,
+ "category": "Plugins"
},
"excerpt": ""
},
- "markdown/plugins/react-query.md": {
- "content": "\n## Usage with React Query\n\nZeus can generate type-safe versions of React Query's `useQuery`, `useMutation` etc.. React hooks as `useTypedQuery`, `useTypedMutation` etc... by adding the `--reactQuery` flag to the CLI. All types `data` response are then inherited from the Zeus query. 🚀\n\n```sh\n$ zeus schema.graphql ./ --reactQuery\n```\n\n```tsx\nimport { useTypedQuery } from './zeus/reactQuery';\n\nconst Main = () => {\n const { data } = useTypedQuery({\n // Get autocomplete here:\n drawCard: {\n name: true,\n },\n });\n // data response is now typed\n return {data.drawCard.name}
;\n};\n```\n",
+ "markdown/index.md": {
+ "content": "\nStrongly Typed GraphQL from the team at [GraphQL Editor](https://graphqleditor.com/?utm_source=graphql_zeus_github)\n\nGraphQL Zeus is the absolute best way to interact with your GraphQL endpoints in a type-safe way. Zeus uses your schema to generate Typescript types and strongly typed clients to unlock the power, efficiency, productivity and safety of Typescript on your GraphQL requests.\n\n## Features\n\n⚡️ Types mapped from your schema \n⚡️ Works with Apollo Client, React Query, Stucco Subscriptions _(\\*more coming soon...)_
\n⚡️ Works with Subscriptions
\n⚡️ Infer complex response types
\n⚡️ Create reusable selection sets (like fragments) for use across multiple queries
\n⚡️ Supports GraphQL Unions, Interfaces, Aliases and Variables
\n⚡️ Handles **massive** schemas
\n⚡️ Supports Browsers, Node.js and React Native in Javascript and Typescript
\n⚡️ Schema downloader
\n⚡️ JSON schema generation
\n\n## Generate Types With Zeus CLI Example\n\nSimply run Zeus in your terminal to output your types file based on your graphql schema\n\n\n\n## Usage Example\n\nExample using a generated `chain` client. Queries, mutations and subscriptions are now type-safe in arguments, field selections and response types.\n\n\n\n## Support And Community\n\n[Join our GraphQL Editor Channel on Slack!](https://join.slack.com/t/graphqleditor/shared_invite/enQtNDkwOTgyOTM5OTc1LWI4YjU3N2U5NGVkNzQ2NzY5MGUxMTJiNjFlZDM1Zjc2OWRmNTI0NDM3OWUxYTk4Yjk3MzZlY2QwOWUzZmM2NDI)\n\nLeave a GitHub star ⭐️ 😊\n\nSpread the word!\n\n## Contribute\n\nFor a complete guide to contributing to GraphQL Editor, see the [Contribution Guide](CONTRIBUTING.md).\n\n1. Fork this repo\n2. Create your feature branch: git checkout -b feature-name\n3. Commit your changes: git commit -am 'Add some feature'\n4. Push to the branch: git push origin my-new-feature\n5. Submit a pull request\n\n## License\n\nMIT 🕊\n", "data": { - "link": "plugins/react-query", - "title": "React Query", - "order": 2, - "category": "Plugins" + "link": "", + "title": "" }, "excerpt": "" }, "markdown/graphql/variables.md": { - "content": "\n## GraphQL Variables\n\nIt's simple to perform queries with variables by importing and using the `$` function from the Zeus output and calling it with the variable name in backticks.\n\n```ts\nimport { Gql, $ } from './zeus';\n\nconst addCardResult = await Gql('mutation')(\n {\n addCard: [\n {\n card: $`card`,\n },\n {\n id: true,\n description: true,\n name: true,\n Attack: true,\n skills: true,\n Children: true,\n Defense: true,\n cardImage: {\n bucket: true,\n region: true,\n key: true,\n },\n },\n ],\n },\n {\n variables: {\n card: {\n Attack: 2,\n Defense: 3,\n description: 'Lord of the mountains',\n name: 'Golrog',\n },\n },\n },\n);\n```\n\nNote: The mutation function created by the Zeus versions of React Hooks like the Apollo Client version of `useTypedMutation` can be supplied with variable values at invocation eg:\n\n```typescript\nconst [addCard, { data, loading, error }] = useTypedMutation({ ...myMutation });\n\nawait addCard({\n variables: {\n card: {\n Attack: 2,\n Defense: 3,\n description: 'Lord of the mountains',\n name: 'Golrog',\n },\n },\n});\n```\n", + "content": "\n## GraphQL Variables\n\nIt's simple to perform queries with variables by using `useZeusVariables` function. It forces you to be type-safe also\n\n```ts\nimport { Gql, useZeusVariables } from './zeus';\nconst variables = useZeusVariables({ Attack: 'Int!', Defense: 'Int!' })({\n card: {\n Attack: 2,\n Defense: 3,\n description: 'Lord of the mountains',\n name: 'Golrog',\n },\n});\nconst { $ } = variables;\n\nconst addCardResult = await Gql('mutation')(\n {\n addCard: [\n {\n card: $('card'),\n },\n {\n id: true,\n description: true,\n name: true,\n Attack: true,\n skills: true,\n Children: true,\n Defense: true,\n cardImage: {\n bucket: true,\n region: true,\n key: true,\n },\n },\n ],\n },\n {\n variables,\n },\n);\n```\n\nNote: The mutation function created by the Zeus versions of React Hooks like the Apollo Client version of `useTypedMutation` can be supplied with variable values at invocation eg:\n\n```typescript\nconst [addCard, { data, loading, error }] = useTypedMutation({ ...myMutation });\n\nawait addCard({\n variables: variables.values,\n});\n```\n", "data": { "link": "graphql/variables", "title": "Variables", @@ -47,12 +37,22 @@ export const htmlContent = { }, "excerpt": "" }, - "markdown/graphql/interfaces-and-unions.md": { - "content": "\n## GraphQL Unions\n\nYou can use Zeus with [GraphQL Unions](https://spec.graphql.org/June2018/#sec-Unions):\n\n```js\nconst { drawChangeCard } = await chain('query')({\n drawChangeCard: {\n __typename: true,\n '...on EffectCard': {\n effectSize: true,\n name: true,\n },\n '...on SpecialCard': {\n effect: true,\n name: true,\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n \"effectSize\": 195.99532210956377,\n \"name\": \"Destinee\",\n \"__typename\": \"EffectCard\"\n}\n```\n\n## GraphQL Interfaces\n\nZeus works with [GraphQL Interfaces](http://spec.graphql.org/June2018/#sec-Interfaces)\n\n```ts\nconst { nameables } = await Gql('query')({\n nameables: {\n __typename: true,\n name: true,\n '...on CardStack': {\n cards: {\n Defense: true,\n },\n },\n '...on Card': {\n Attack: true,\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n \"nameables\": [\n {\n \"__typename\": \"EffectCard\",\n \"name\": \"Hector\"\n },\n {\n \"__typename\": \"CardStack\",\n \"name\": \"Scotty\",\n \"cards\": [\n {\n \"Defense\": 1950\n },\n {\n \"Defense\": 76566\n }\n ]\n },\n {\n \"__typename\": \"SpecialCard\",\n \"name\": \"Itzel\"\n }\n ]\n}\n```\n", + "markdown/plugins/stucco.md": { + "content": "\n## Usage with Stucco Subscriptions\n\nZeus can generate types for the Stucco Subscription library by adding the --stuccoSubscriptions flag to the CLI. All types in `data` are then inherited from the Zeus Query\n\n```sh\n$ zeus schema.graphql ./ --stuccoSubscriptions\n```\n\n```typescript\nstuccoSubscriptions(\n (apiFetchResult) => [apiFetchResult.url],\n 'https://my.backend/graphql',\n)({ drawCard: { Attack: true } }).on((args) => args.drawCard.Attack);\n```\n", "data": { - "link": "graphql/interfaces-and-unions", - "title": "Interfaces and Unions", - "order": 1, + "link": "plugins/stucco", + "title": "Stucco", + "order": 3, + "category": "Plugins" + }, + "excerpt": "" + }, + "markdown/graphql/scalars.md": { + "content": "\n## Scalars\n\nIn Zeus you can encode and decode scalars\n\n### Decode\n\nDecode function is called every time scalar returns from backend before passing the result from Chain,Subscription functions\n\n```gql\nscalar JSON\nscalar Datetime\ntype Card{\n info: JSON!\n createdAt: Datetime\n}\ntype Query:{\n drawCard: Card!\n}\n```\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst data = await chain('query', {\n scalars: {\n JSON: {\n encode: (e: unknown) => JSON.stringify(e),\n decode: (e: unknown) => JSON.parse(e as string),\n },\n Datetime: {\n decode: (e: unknown) => new Date(e as string),\n encode: (e: unknown) => (e as Date).toISOString(),\n },\n },\n})({\n drawCard: {\n info: true,\n },\n});\n```\n\nSo the `data.drawCard.info` will be of type `Date` as provided by decoder `ReturnType`\n\n### Encode Scalars\n\nYou can also encode scalars before sending them to backend\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query', {\n scalars: {\n JSON: {\n encode: (e: unknown) => JSON.stringify(e),\n decode: (e: unknown) => JSON.parse(e as string),\n },\n Datetime: {\n decode: (e: unknown) => new Date(e as string),\n encode: (e: unknown) => (e as Date).toISOString(),\n },\n },\n})({\n drawCard: {\n info: true,\n },\n});\n```\n\nEncoders require value to be encoded to string and don't work with variables yet.\n\n## Place decoders and encoders in one place for reuse\n\n```ts\nimport { Chain, ZeusScalars } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\nconst scalars = ZeusScalars({\n JSON: {\n encode: (e: unknown) => JSON.stringify(e),\n decode: (e: unknown) => JSON.parse(e as string),\n },\n Datetime: {\n decode: (e: unknown) => new Date(e as string),\n encode: (e: unknown) => (e as Date).toISOString(),\n },\n});\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query', {\n scalars,\n})({\n drawCard: {\n info: true,\n },\n});\n```\n", + "data": { + "link": "graphql/scalars", + "title": "Scalars", + "order": 6, "category": "GraphQL" }, "excerpt": "" @@ -67,8 +67,38 @@ export const htmlContent = { }, "excerpt": "" }, + "markdown/graphql/directives.md": { + "content": "\n## GraphQL Directives\n\nZeus supports using directives on fields.\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query')({\n drawCard: {\n name: true,\n skills: true,\n Attack: `@skip(if: true)`,\n },\n});\n```\n\nSo you need to put full string instead of `true`.\n\n### Use on object field\n\nUse directive on `drawCard`\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query')({\n drawCard: {\n __directives: `@skip(if:true)`,\n name: true,\n skills: true,\n },\n});\n```\n\n### Use on function\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query')({\n drawCard: {\n name: true,\n skills: true,\n attack:[\n {\n cardId:['2312321']\n },\n {\n __directives: `@skip(if:true)`,\n name: true,\n skills: true,\n }\n ]\n }\n});\n```\n\n### Use it with variables\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\nconst variables = useZeusVariables({\n isDefense: 'Boolean!'\n})({\n isDefense:true\n});\nconst { $ } = variables;\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query')({\n drawCard: {\n name: true,\n skills: true,\n Attack: `@skip(if: ${$('isDefense')})`,\n },\n {\n variables\n }\n});\n```\n", + "data": { + "link": "graphql/directives", + "title": "Directives", + "order": 5, + "category": "GraphQL" + }, + "excerpt": "" + }, + "markdown/plugins/react-query.md": { + "content": "\n## Usage with React Query\n\nZeus can generate type-safe versions of React Query's `useQuery`, `useMutation` etc.. React hooks as `useTypedQuery`, `useTypedMutation` etc... by adding the `--reactQuery` flag to the CLI. All types `data` response are then inherited from the Zeus query. 🚀\n\n```sh\n$ zeus schema.graphql ./ --reactQuery\n```\n\n```tsx\nimport { useTypedQuery } from './zeus/reactQuery';\n\nconst Main = () => {\n const { data } = useTypedQuery({\n // Get autocomplete here:\n drawCard: {\n name: true,\n },\n });\n // data response is now typed\n return
{data.drawCard.name}
;\n};\n```\n",
+ "data": {
+ "link": "plugins/react-query",
+ "title": "React Query",
+ "order": 2,
+ "category": "Plugins"
+ },
+ "excerpt": ""
+ },
+ "markdown/graphql/interfaces-and-unions.md": {
+ "content": "\n## GraphQL Unions\n\nYou can use Zeus with [GraphQL Unions](https://spec.graphql.org/June2018/#sec-Unions):\n\n```js\nconst { drawChangeCard } = await chain('query')({\n drawChangeCard: {\n __typename: true,\n '...on EffectCard': {\n effectSize: true,\n name: true,\n },\n '...on SpecialCard': {\n effect: true,\n name: true,\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n \"effectSize\": 195.99532210956377,\n \"name\": \"Destinee\",\n \"__typename\": \"EffectCard\"\n}\n```\n\n## GraphQL Interfaces\n\nZeus works with [GraphQL Interfaces](http://spec.graphql.org/June2018/#sec-Interfaces)\n\n```ts\nconst { nameables } = await Gql('query')({\n nameables: {\n __typename: true,\n name: true,\n '...on CardStack': {\n cards: {\n Defense: true,\n },\n },\n '...on Card': {\n Attack: true,\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n \"nameables\": [\n {\n \"__typename\": \"EffectCard\",\n \"name\": \"Hector\"\n },\n {\n \"__typename\": \"CardStack\",\n \"name\": \"Scotty\",\n \"cards\": [\n {\n \"Defense\": 1950\n },\n {\n \"Defense\": 76566\n }\n ]\n },\n {\n \"__typename\": \"SpecialCard\",\n \"name\": \"Itzel\"\n }\n ]\n}\n```\n",
+ "data": {
+ "link": "graphql/interfaces-and-unions",
+ "title": "Interfaces and Unions",
+ "order": 1,
+ "category": "GraphQL"
+ },
+ "excerpt": ""
+ },
"markdown/graphql/aliases.md": {
- "content": "\n## GraphQL Aliases\n\nZeus supports declaring aliases 🥸\n\n```ts\nconst aliasedQueryExecute = await chain('query')({\n listCards: {\n __alias: {\n atak: {\n attack: [\n { cardID: ['1'] },\n {\n name: true,\n description: true,\n },\n ],\n },\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n \"listCards\": [\n {\n \"atak\": {\n \"attack\": [\n {\n \"name\": \"Zelma\",\n \"description\": \"Central\"\n }\n ]\n }\n }\n ]\n}\n```\n\nNow you can access properties type-safe like this\n\n```javascript\naliasedQueryExecute.listCards.map((c) => c.atak.attack);\n```\n",
+ "content": "\n## GraphQL Aliases\n\nZeus supports declaring aliases 🥸\n\n```ts\nconst aliasedQueryExecute = await chain('query')({\n listCards: {\n __alias: {\n atak: {\n attack: [\n { cardID: ['1'] },\n {\n name: true,\n description: true,\n },\n ],\n },\n },\n },\n});\n```\n\nResponse:\n\n```json\n{\n \"listCards\": [\n {\n \"atak\": [\n {\n \"name\": \"Zelma\",\n \"description\": \"Central\"\n }\n ]\n }\n ]\n}\n```\n\nNow you can access properties type-safe like this\n\n```javascript\naliasedQueryExecute.listCards.map((c) => c.atak);\n```\n",
"data": {
"link": "graphql/aliases",
"title": "Aliases",
@@ -77,8 +107,28 @@ export const htmlContent = {
},
"excerpt": ""
},
+ "markdown/examples/state.md": {
+ "content": "\nWhen query returns an object and you want to store it in React State, you can use zeus to have 100% type-safe objects in your state.\n\nHaving the following schema:\n\n```graphql\ntype Query {\n listUsers: [User!]\n}\n\ntype User {\n createdAt: String!\n firstName: String!\n lastName: String!\n age: Int\n username: String!\n id: String!\n}\n```\n\nYou can use zeus types to get the type of the objects received from GraphQL Backend\n\n```tsx\nimport React, { useState } from 'react';\nimport { GraphQLTypes, InputType, Selector, Chain } from './zeus';\n\nconst userSelector = Selector('User')({\n createdAt: true,\n firstName: true,\n lastName: true,\n id: true,\n});\n\ntype StoredUser = InputType\n {users.map((u) => (\n
\n );\n};\n```\n",
+ "data": {
+ "link": "state",
+ "title": "React State",
+ "order": 2,
+ "category": "Examples"
+ },
+ "excerpt": ""
+ },
+ "markdown/examples/forms.md": {
+ "content": "\nTo use zeus with forms you should make use of it's generated ValueTypes. When submitting form using a mutation It is much easier and type-safe to do it using `ValueTypes`.\n\nHaving the following schema:\n\n```graphql\ntype Mutation {\n createUser(user: CreateUser!): String\n}\n\ninput CreateUser {\n firstName: String!\n lastName: String!\n age: Int\n username: String!\n}\n```\n\nYou can use `ValueTypes['CreateUser']` as params for submit form function\n\n```ts\nconst submitForm = (values: ValueTypes['CreateUser']) => {\n // ..,rest of the code, validation\n return Chain('https://yourschemaurl.com/graphql', {\n headers: {\n Authorization: 'yourtoken',\n },\n })('mutation')({\n createUser: [{ user: values }, true],\n });\n};\n```\n",
+ "data": {
+ "link": "forms",
+ "title": "Forms",
+ "order": 1,
+ "category": "Examples"
+ },
+ "excerpt": ""
+ },
"markdown/basics/use-as-a-library.md": {
- "content": "\n## Generate Code\n\nThis will be rarely used, but here you are! Generate Typescript and Javascript from GraphQL definitions\n\n```js\nimport { TreeToTS } from 'graphql-zeus';\nimport { Parser } from 'graphql-js-tree';\n\nconst schemaFileContents = `\ntype Query{\n hello: String!\n}\nschema{\n query: Query\n}\n`;\n\nconst typeScriptDefinition = TreeToTS.resolveTree(Parser.parse(schemaFileContents));\n\nconst jsDefinition = TreeToTS.javascript(Parser.parse(schemaFileContents));\n```\n\n## Dynamically Fetch Schema\n\nThis is useful when you need your schema fetched from your GraphQL endpoint in-code\n\n```js\nimport { Utils } from 'graphql-zeus';\n\nUtils.getFromUrl('https://faker.graphqleditor.com/a-team/olympus/graphql').then((schemaContent) => {\n // Use schema content here\n});\n```\n",
+ "content": "\n## Generate Code\n\nThis will be rarely used, but here you are! Generate Typescript and Javascript from GraphQL definitions\n\n```js\nimport { TreeToTS } from 'graphql-zeus';\nimport { Parser } from 'graphql-js-tree';\n\nconst schemaFileContents = `\ntype Query{\n hello: String!\n}\nschema{\n query: Query\n}\n`;\n\nconst typeScriptDefinition = TreeToTS.resolveTree(Parser.parse(schemaFileContents));\n```\n\n## Dynamically Fetch Schema\n\nThis is useful when you need your schema fetched from your GraphQL endpoint in-code\n\n```js\nimport { Utils } from 'graphql-zeus';\n\nUtils.getFromUrl('https://faker.graphqleditor.com/a-team/olympus/graphql').then((schemaContent) => {\n // Use schema content here\n});\n```\n",
"data": {
"link": "library",
"title": "Use as a library",
@@ -88,7 +138,7 @@ export const htmlContent = {
"excerpt": ""
},
"markdown/basics/spec.md": {
- "content": "\n## Zeus Spec\n\nPromise of type query data object is returned.\n\n```\nPROMISE_RETURNING_OBJECT = Chain.[OPERATION_NAME]({\n ...FUNCTION_FIELD_PARAMS\n})(\n ...QUERY_OBJECT\n).then ( RESPONSE_OBJECT => RESPONSE_OBJECT[OPERATION_FIELD] )\n```\n\nSimple function params object\n\n```\nFUNCTION_FIELD_PARAMS = {\n KEY: VALUE\n}\n```\n\nQuery object\n\n```\nQUERY_OBJECT = {\n ...RETURN_PARAMS\n}\n```\n\nReturn params is an object containing RETURN_KEY - true if it is a `scalar`, RETURN_PARAMS if `type` otherwise it is a function where you pass field params and type return params.\n\n```\nRETURN_PARAMS = {\n RETURN_KEY: true,\n RETURN_KEY: {\n ...RETURN_PARAMS\n },\n RETURN_FUNCTION_KEY:[\n {\n ...FUNCTION_FIELD_PARAMS\n },\n {\n ...RETURN_PARAMS\n }\n ]\n}\n```\n\n### Use Alias Spec\n\n```\nRETURN_PARAMS = {\n __alias: RETURN_PARAMS\n}\n```\n\nAccess aliased operation type-safe\n\n```\nPROMISE_RETURNING_OBJECT[ALIAS_STRING][OPERATION_NAME]\n```\n",
+ "content": "\n## Zeus Spec\n\nPromise of type query data object is returned.\n\n```\nPROMISE_RETURNING_OBJECT = Chain.[OPERATION_NAME]({\n ...FUNCTION_FIELD_PARAMS\n})(\n ...QUERY_OBJECT\n).then ( RESPONSE_OBJECT => RESPONSE_OBJECT[OPERATION_FIELD] )\n```\n\nSimple function params object\n\n```\nFUNCTION_FIELD_PARAMS = {\n KEY: VALUE\n}\n```\n\nQuery object\n\n```\nQUERY_OBJECT = {\n ...RETURN_PARAMS\n}\n```\n\nReturn params is an object containing RETURN_KEY - true if it is a `scalar`, RETURN_PARAMS if `type` otherwise it is a function where you pass field params and type return params.\n\n```\nRETURN_PARAMS = {\n RETURN_KEY: true,\n RETURN_KEY: {\n ...RETURN_PARAMS\n },\n RETURN_FUNCTION_KEY:[\n {\n ...FUNCTION_FIELD_PARAMS\n },\n {\n ...RETURN_PARAMS\n }\n ]\n}\n```\n\n### Use Alias Spec\n\n```\nRETURN_PARAMS = {\n __alias: RETURN_PARAMS\n}\n```\n\nAccess aliased operation type-safe\n\n```\nPROMISE_RETURNING_OBJECT[ALIAS_STRING]\n```\n",
"data": {
"link": "spec",
"title": "Specification",
@@ -97,6 +147,16 @@ export const htmlContent = {
},
"excerpt": ""
},
+ "markdown/basics/getting-started.md": {
+ "content": "\n## Getting Started\n\nUse the Zeus CLI to generate types and GraphQL clients based on your schema which you can then import into your projects to autocomplete, query and use GraphQL responses in a type-safe way.\n\n## Quick Start\n\n### Installation\n\n```sh\n$ npm i -g graphql-zeus\n# OR\n# yarn global add graphql-zeus\n```\n\nYou can also install locally to a project and then use as a npm or yarn script command or with `npx` or `yarn` directly eg:\n\n```sh\n$ npx zeus schema.graphql ./\n# OR\n# yarn zeus schema.graphql ./\n```\n\n### TypeScript\n\nZeus is Typescript native, you can refer to imported types directly from the generated output of the CLI\n\n```sh\n$ zeus schema.graphql ./\n```\n\n## Demo Endpoint\n\nAll demo code here is using the demo GraphQL endpoint of [Olympus Cards](https://app.graphqleditor.com/a-team/olympus) built with [GraphQL Editor](https://graphqleditor.com/). Feel free to check out the [GraphiQL interface](https://faker.graphqleditor.com/a-team/olympus/graphql) too.\n\n## Query With Zeus Chain Client\n\nYou can now use the Zeus `Chain` client from the generated output to make type-safe queries and mutations to your endpoint and receive type-safe responses.\n\n```ts\nimport { Chain } from './zeus';\n\n// Create a Chain client instance with the endpoint\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Query the endpoint with Typescript autocomplete for arguments and response fields\nconst listCardsAndDraw = await chain('query')({\n cardById: [\n {\n cardId: 'da21ce0a-40a0-43ba-85c2-6eec2bf1ae21',\n },\n {\n name: true,\n description: true,\n },\n ],\n listCards: {\n name: true,\n skills: true,\n attack: [\n { cardID: ['66c1af53-7d5e-4d89-94b5-1ebf593508f6', 'fc0e5757-4d8a-4f6a-a23b-356ce167f873'] },\n {\n name: true,\n },\n ],\n },\n drawCard: {\n name: true,\n skills: true,\n Attack: true,\n },\n});\n// listCardsAndDraw is now typed as the response of the query.\n```\n\nWhen querying a GraphQL field which takes an argument such as `cardById` above, then the fields are defined in terms of a tuple eg: cardById: `[ {...arguments} , {...response_selection_set} ]` the equivalent in gql syntax would be:\n\n```text\ncardById (cardId: \"da21ce0a-40a0-43ba-85c2-6eec2bf1ae21\") {\n name\n description\n}\n```\n\nFor fields which have no argument they receive only the response selection set object values.\n\nNote: `Chain` will also accept a second argument of fetch-like options to configure the client with properties such as `credentials`, `mode`, `headers` etc...\n\nNote: There is also an exported Zeus `Gql` convenience function is a Chain client pre-configured with the endpoint specified in the CLI.\n\n## Listen on a WebSocket - GraphQL Subscriptions\n\nUse the Zeus `Subscription` client creator in your generated output to create WebSocket connections to your GraphQL socket.\n\n```ts\nimport { Subscription } from './zeus';\n\n// Create a Subscription client instance with the endpoint\nconst sub = Subscription('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\n// Call the client instance and listen for responses\nsub('subscription')({\n deck: {\n id: true,\n },\n}).on((response) => {\n console.log(response.deck);\n});\n```\n\n[Read more about subscriptions](./subscriptions)\n\n## Usage with NodeJS\n\nGenerates clients for use with Node.js\n\n```sh\n$ zeus schema.graphql ./ --node\n```\n\n## Usage with React Native\n\nAs normal\n\n```sh\n$ zeus schema.graphql ./\n```\n\n## Other CLI Options\n\nSpecify the output folder with second argument\n\n```sh\n$ zeus schema.graphql ./generated\n```\n\nOutput Typescript Only with `--typescript` flag\n\n```sh\n$ zeus schema.graphql ./ --typescript\n```\n\nLoad your schema from an URL with an URL in the first argument\n\n```sh\n$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./\n```\n\nDownload and save GraphQL schema to a local path with `--graphql=savePath` flag\n\n```sh\n$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --graphql=generated\n```\n\nGenerate and save a JSON schema to a local path with `--jsonSchema=savePath` flag\n\n```sh\n$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --graphql=generated\n```\n\nAdd a header value with `--header=value` flag\n\n```sh\n$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./ --header=Authorization:myNiceAuthHeader\n```\n\nGet help with Zeus CLI with:\n\n```sh\n$ zeus help\n```\n\n### Tip:\n\nAdd a script entry in your `package.json` file for quickly calling Zeus generation:\n\n```json\n\"scripts\": {\n//...\n\"generate\": \"zeus https://faker.graphqleditor.com/a-team/olympus/graphql zeusGenerated --typescript --header='My-Auth-Secret:JsercjjJY5MmghtHww6UF' --apollo\"\n},\n```\n",
+ "data": {
+ "link": "getting-started",
+ "title": "Getting Started",
+ "order": 0,
+ "category": "Basics"
+ },
+ "excerpt": ""
+ },
"markdown/basics/selector.md": {
"content": "\n## Generate Reusable Selection Sets\n\nIn TypeScript Zeus can help make type-safe Zeus selection sets to reuse across queries.\n\n```ts\nimport { Selector, Chain } from './zeus';\n\nconst chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');\n\nconst cardSelector = Selector('Card')({\n name: true,\n description: true,\n Attack: true,\n skills: true,\n Defense: true,\n cardImage: {\n key: true,\n bucket: true,\n },\n});\n\nconst queryWithSelectionSet = await chain('query')({\n drawCard: cardSelector,\n});\n```\n\n## Inferring the response type\n\nSometimes you would like to infer the response type. The it is best to use selectors\n\n```tsx\nimport { Selector, InputType, GraphQLTypes } from './zeus';\n\nexport const drawCardQuery = Selector(\"Query\"){\n drawCard: {\n Attack: true,\n Children: true,\n id: true,\n },\n});\n\ntype InferredResponseType = InputType\n
\n ))}\n {getFullName(u)}
\n {u.createdAt}
\n