GraphQL Zeus creates autocomplete client library for JavaScript
or TypeScript
which provides autocompletion for strongly typed queries.
⚡⚡ From version 2.0 Zeus support mapped types
⚡⚡⚡ From version 3.0 Zeus supports
- JSON schema generation
- Subscriptions
- ZeusHook Type for extracting the response type
Supported Languages:
- Javascript
- Browser
- NodeJS
- React Native
- TypeScript
- Browser
- NodeJS
- React Native
Given the following schema Olympus Cards
- How it works
- Table of contents
- License
- How to use
- Support
- Contribute
- Parsing
MIT
Main usage of graphql zeus should be as a CLI.
Install globally
$ npm i -g graphql-zeus
Of course you can install locally to a project and then use as a npm command or with npx
$ zeus schema.graphql ./
It will also generate corresponding out.d.ts file so you can have autocompletion,
$ zeus schema.graphql ./ --ts
$ zeus schema.graphql ./ --node
Same as browser
$ zeus schema.graphql ./
$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./generated
With Authorization header
$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./generated --header=Authorization:dsadasdASsad
$ zeus https://faker.graphqleditor.com/a-team/olympus/graphql ./generated
import { Chain } from './zeus';
const createCards = async () => {
const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
const listCardsAndDraw = await chain.query({
cardById: [
{
cardId: 'sdsd'
},
{
description: true
}
],
listCards: {
name: true,
skills: true,
attack: [
{ cardID: ['s', 'sd'] },
{
name: true
}
]
},
drawCard: {
name: true,
skills: true,
Attack: true
}
});
};
createCards();
// Result of a query
// {
// "drawCard": {
// "Attack": 83920,
// "name": "Raphaelle",
// "skills": [
// "RAIN",
// "
",
// ]
// },
// "cardById": {
// "description": "Customer"
// },
// "listCards": [
// {
// "name": "Lon",
// "skills": [
// "THUNDER"
// ],
// "attack": [
// {
// "name": "Christop"
// },
// {
// "name": "Theodore"
// },
// {
// "name": "Marcelle"
// }
// ]
// },
// {
// "name": "Etha",
// "skills": null,
// "attack": [
// {
// "name": "Naomie"
// }
// ]
// },
// {
// "attack": [
// {
// "name": "Kyle"
// },
// ],
// "name": "Arlene",
// "skills": [
// "FIRE",
// ]
// }
// ]
// }
This creates websocket connection between your backend GraphQL socket and web browser one.
const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
chain
.subscription({
cardPile: {
id: true,
},
})
.on((response) => {
console.log(response.cardPile);
});
With thunder you have total control of fetch function not losing the result format the same time.
import { Thunder } from './zeus';
const createCards = async () => {
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;
});
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,
},
});
};
createCards();
// Result of a query
// {
// "drawCard": {
// "Attack": 83920,
// "name": "Raphaelle",
// "skills": [
// "RAIN",
// "THUNDER",
// ]
// },
// "cardById": {
// "description": "Customer"
// },
// "listCards": [
// {
// "name": "Lon",
// "skills": [
// "THUNDER"
// ],
// "attack": [
// {
// "name": "Christop"
// },
// {
// "name": "Theodore"
// },
// {
// "name": "Marcelle"
// }
// ]
// },
// {
// "name": "Etha",
// "skills": null,
// "attack": [
// {
// "name": "Naomie"
// }
// ]
// },
// {
// "attack": [
// {
// "name": "Kyle"
// },
// ],
// "name": "Arlene",
// "skills": [
// "FIRE",
// ]
// }
// ]
// }
You can use Zeus with unions:
const { drawChangeCard } = await chain.query({
drawChangeCard: {
__typename: true,
'...on EffectCard': {
effectSize: true,
name: true,
},
'...on SpecialCard': {
effect: true,
name: true,
},
},
});
// drawChangeCard result:
// {
// "effectSize": 195.99532210956377,
// "name": "Destinee",
// "__typename": "EffectCard"
// }
And interfaces.
const { nameables } = await Gql.query({
nameables: {
__typename: true,
name: true,
'...on CardStack': {
cards: {
Defense: true,
},
},
'...on Card': {
Attack: true,
},
},
});
// result
// {
// "nameables": [
// {
// "__typename": "EffectCard",
// "name": "Hector"
// },
// {
// "__typename": "CardStack",
// "name": "Scotty",
// "cards": [
// {
// "Defense": 1950
// },
// {
// "Defense": 76566
// },
// {
// "Defense": 64261
// }
// ]
// },
// {
// "__typename": "SpecialCard",
// "name": "Itzel"
// },
// ]
// }
const aliasedQueryExecute = await chain.query({
listCards: {
__alias: {
atak: {
attack: [
{ cardID: ['1'] },
{
name: true,
description: true,
},
],
},
},
},
});
// RESULT
// {
// "listCards": [
// {
// "atak": {
// "attack": [
// {
// "name": "Zelma",
// "description": "Central"
// }
// ]
// }
// }
// ]
// }
So you can access properties type-safe like this
aliasedQueryExecute.listCards.map((c) => c.atak.attack);
To perform query with variables please import $
function and pass the variables to query
const test = 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,
},
},
],
},
{
card: {
Attack: 2,
Defense: 3,
description: 'Lord of the mountains',
name: 'Golrog',
},
},
);
Use Zeus to generate gql string
import { Zeus } from './zeus';
const createCards = async () => {
const stringGql = Zeus.query({
listCards: {
name: true,
skills: true,
Attack: true,
},
});
// query{listCards{name skills Attack}}
};
createCards();
To run the example navigate to: ./examples
and run
$ npm i
then run
$ npm run start
Use Api
for single queries mutations and Chain
for query chaining
You can cast your response from fetch/apollo/other-lib to correct type even if you are using JavaScript:
import { Cast } from './zeus';
const myQuery = Cast.query(myLib('somegraphqlendpoint'));
In TypeScript you can make type-safe selection sets to reuse them across queries
You can use Selectors on operations or ZeusSelect on concrete type. Only Selectors
make sense in JS as usage of ZeusSelect
on type is impossible without type support :)
import { ZeusSelect, Selectors, Chain, ValueTypes } from './zeus';
const chain = Chain('https://faker.graphqleditor.com/a-team/olympus/graphql');
const { drawCard: cardSelector } = Selectors.query({
drawCard: {
name: true,
description: true,
Attack: true,
skills: true,
Defense: true,
cardImage: {
key: true,
bucket: true,
},
},
});
const cardSelector2 = ZeusSelect<ValueTypes['Card']>()({
name: true,
description: true,
Attack: true,
skills: true,
Defense: true,
cardImage: {
key: true,
bucket: true,
},
});
const queryWithSelectionSet = await chain.query({
drawCard: cardSelector,
listCards: cardSelector2,
});
GraphQL Zeus can be used in combination with Apollo Client's React hooks to provide typed versions of useQuery()
, useMutation()
, and useSubscription()
. Below is what the implementation looks like (please note the comment about root typenames, like query_root
).
import {
gql,
MutationHookOptions,
QueryHookOptions,
SubscriptionHookOptions,
useMutation,
useQuery,
useSubscription,
} from '@apollo/client';
/**
* If your query/mutation/subscription root fields are named differently
* you will need to alter the imports and references in "ValueTypes" below
*/
import { MapType, ValueTypes, Zeus, mutation_root, query_root, subscription_root } from './generated/graphql-zeus';
export function useTypedQuery<Q extends ValueTypes['query_root']>(
query: Q,
options?: QueryHookOptions<MapType<query_root, Q>, Record<string, any>>,
) {
return useQuery<MapType<query_root, Q>>(gql(Zeus.query(query)), options);
}
export function useTypedMutation<Q extends ValueTypes['mutation_root']>(
mutation: Q,
options?: MutationHookOptions<MapType<mutation_root, Q>, Record<string, any>>,
) {
return useMutation<MapType<mutation_root, Q>>(gql(Zeus.mutation(mutation)), options);
}
export function useTypedSubscription<Q extends ValueTypes['subscription_root']>(
subscription: Q,
options?: SubscriptionHookOptions<MapType<subscription_root, Q>, Record<string, any>>,
) {
return useSubscription<MapType<subscription_root, Q>>(gql(Zeus.subscription(subscription)), options);
}
Assuming that you created hook like function
import { Gql, ZeusHook } from './zeus';
export const useZeus = () => {
const drawACard = () => {
return Gql.query({
drawCard: {
name: true,
Attack: true,
Defense: true,
Children: true,
description: true,
},
});
};
return { drawACard };
};
type DrawCardResponse = ZeusHook<typeof useZeus, 'drawACard'>;
Zeus generates an easy to use Type so you can decalare your zeus queries inside function
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 containg RETURN_KEY - true if it is a scalar
, RETURN_PARAMS if type
otherwise it is a function where you pass Fiel params and type return params.
RETURN_PARAMS = {
RETURN_KEY: true,
RETURN_KEY: {
...RETURN_PARAMS
},
RETURN_FUNCTION_KEY:[
{
...FUNCTION_FIELD_PARAMS
},
{
...RETURN_PARAMS
}
]
}
RETURN_PARAMS = {
__alias: RETURN_PARAMS
}
Access aliased operation type-safe
PROMISE_RETURNING_OBJECT[ALIAS_STRING][OPERATION_NAME]
This will be rarely used, but here you are!
import { Parser, TreeToTS } from 'graphql-zeus';
const schemaFileContents = `
type Query{
hello: String!
}
schema{
query: Query
}
`;
const typeScriptDefinition = TreeToTS.resolveTree(Parser.parse(schemaFileContents));
const jsDefinition = TreeToTS.javascript(Parser.parse(schemaFileContents));
This is useful when you need some schema fetched from your GraphQL endpoint
import { Utils } from 'graphql-zeus';
Utils.getFromUrl('https://faker.graphqleditor.com/a-team/olympus/graphql').then((schemaContent) => {
// Use schema content here
});
Join our GraphQL Editor Channel
Leave a star ;)
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
Simplier approach to GraphQL parsing. Using graphql-js library and parsing AST to simplier types.