Zeus | GraphQL TypeScript generator

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.

LLM Quickstart

- This package documents how to use the generated client. For a working reference, see examples/typescript-node/src/index.ts.
- Typical generated entry points: ./zeus/index.ts and ./zeus/typedDocumentNode.ts.

``ts
import {
Gql,
Zeus,
Thunder,
Selector,
fields,
GraphQLTypes,
InputType,
ZeusScalars,
$,
} from './zeus';
import { typedGql } from './zeus/typedDocumentNode';

// 1) Query/mutation with variables
const created = await Gql('mutation')(
{
addCard: [
{ card: { Attack: $('Attack', 'Int!'), Defense: 1, name: 'A', description: 'B' } },
{ id: true, '...on Card': { Attack: true } },
],
},
{ variables: { Attack: 1 } },
);

// 2) Reusable selections and inferred types
const q = Selector('Query')({ drawCard: { id: true, Attack: true } });
type DrawCard = InputType;
const { drawCard } = await Gql('query')(q);

// 3) Aliases and string generation
const gqlStr = Zeus('query', {
__alias: { myCards: { listCards: { name: true } } },
});

// 4) TypedDocumentNode for Apollo/urql
const byId = typedGql('query')({ cardById: [{ cardId: $('id', 'String!') }, { name: true }] });

// 5) Custom fetch without losing types
const thunder = Thunder(async (query) => {
const r = await fetch('https://your.graphql/endpoint', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ query }),
});
const j = await r.json();
return j.data;
});
const data = await thunder('query')({ drawCard: { id: true, Attack: true } });

// 6) Scalars encode/decode (one place)
const scalars = ZeusScalars({
JSON: { encode: JSON.stringify, decode: (e) => e as unknown },
});
await Gql('query', { scalars })({ drawCard: { info: true } });

// 7) Spread all scalar fields of a type
await Gql('query')({ drawCard: { ...fields('Card') } });
`

Tips
- Prefer Gql for a preconfigured Chain, Zeus for building raw query strings, and typedGql when integrating with GraphQL clients.
- Variables use the $ helper: $('name', 'String!') both declares and types the variable.
- Interface/union selections use inline fragments: '...on Type': { ... }.

Features

⚡️ Types mapped from your schema\
⚡️ Works with Apollo Client, React Query, Stucco Subscriptions _(\*more coming soon...)_\
⚡️ Works with Subscriptions\
⚡️ Allows inferring complex response types\
⚡️ Creates 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\
⚡️ Has a schema downloader\
⚡️ Supports JSON schema generation\

Getting Started | Zeus GraphQL TypeScript generator

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.

Zeus Spec

To return the promise of type query for data object:

`
PROMISE_RETURNING_OBJECT = Chain.OPERATION_NAME(
...QUERY_OBJECT
).then ( RESPONSE_OBJECT => RESPONSE_OBJECT[OPERATION_FIELD] )
`

The simple command for object function params:

`
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
}
]
}
`

$3

`
RETURN_PARAMS = {
__alias: RETURN_PARAMS
}
`

Access aliased operation in a type-safe way:

`
PROMISE_RETURNING_OBJECT[ALIAS_STRING]
`

Usage

Generated code from TranslateToTS specification

$3

Add a script entry in your package.json file for quickly calling Zeus generation:

`json
"scripts": {
//...
"generate": "zeus https://faker.graphqleditor.com/a-team/olympus/graphql zeusGenerated --typescript --header='My-Auth-Secret:JsercjjJY5MmghtHww6UF' --apollo"
},
`

Demo Endpoint

All demo code here is using the demo GraphQL endpoint of Olympus Cards{rel="nofollow"} built with GraphQL Editor. Feel free to check out the GraphiQL interface{rel="nofollow"} 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.

`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')({
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 that takes an argument like cardById above, the fields are defined in terms of a tuple for example: cardById: [ {...arguments} , {...response_selection_set} ] and the equivalent in gql syntax would be:

`text
cardById (cardId: "da21ce0a-40a0-43ba-85c2-6eec2bf1ae21") {
name
description
}
`

For fields that 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 in 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.

`ts
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);
});
`

Selectors | Zeus GraphQL TypeScript generator

$3

In TypeScript Zeus can help you make type-safe Zeus selection sets to reuse across queries.

`typescript
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,
});
`

$3

Use FromSelector to convert a selector into a concrete TypeScript type for a given schema type.

`ts
import { Selector, FromSelector } from './zeus';

const nameableSelector = Selector('Nameable')({
__typename: true,
name: true,
'...on Card': { description: true },
'...on EffectCard': { effectSize: true },
'...on CardStack': { cards: { id: true } },
});

type Nameable = FromSelector;

const handle = (n: Nameable) => {
if (n.__typename === 'Card') n.description;
if (n.__typename === 'EffectCard') n.effectSize;
if (n.__typename === 'CardStack') n.cards;
};
`

$3

Pass selections as values to compose queries dynamically using ComposableSelector.

`ts
import { Gql, ComposableSelector } from './zeus';

const withCardById = >(id: string, selection: T) =>
Gql('query')({
cardById: [{ cardId: id }, selection],
});

const a = await withCardById('12', { id: true });
const b = await withCardById('12', { Attack: true, Defense: true });
`

Or build on existing selections by spreading the returned selection objects:

`ts
const base = Selector('Card')({ id: true, name: true });
const extended = Selector('Card')({ ...base, Attack: true });
`

$3

Thread custom scalar decoders/encoders into your inferred types by supplying the third generic to FromSelector.

`ts
import { ZeusScalars, Selector, FromSelector } from './zeus';

const scalars = ZeusScalars({
JSON: { encode: JSON.stringify, decode: (e) => e as { power: number } },
ID: { decode: (e) => Number(e) },
});

const cardSel = Selector('Card')({ id: true, info: true }); // info is JSON

type CardWithScalars = FromSelector;
// CardWithScalars['info'] is now { power: number }
`

$3

Sometimes you might want to infer the response type. In that case, it is best to use selectors:

`tsx
import { Selector, InputType, GraphQLTypes } from './zeus';

export const drawCardQuery = Selector("Query"){
drawCard: {
Attack: true,
Children: true,
id: true,
},
});

type InferredResponseType = InputType;
`

Custom fetch

Use the Zeus Thunder to get total control over the fetch function and ensure you won't lose the result type. ⚡️

`typescript
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,
},
});
`

Interfaces and Unions

$3

You can use Zeus with GraphQL Unions:

`typescript
const { drawChangeCard } = await chain('query')({
drawChangeCard: {
__typename: true,
'...on EffectCard': {
effectSize: true,
name: true,
},
'...on SpecialCard': {
effect: true,
name: true,
},
},
});
`

and it will give you this response:

`json
{
"effectSize": 195.99532210956377,
"name": "Destinee",
"__typename": "EffectCard"
}
`

$3

Zeus also works with GraphQL Interfaces

`typescript
const { nameables } = await Gql('query')({
nameables: {
__typename: true,
name: true,
'...on CardStack': {
cards: {
Defense: true,
},
},
'...on Card': {
Attack: true,
},
},
});
`

giving the following response:

`json
{
"nameables": [
{
"__typename": "EffectCard",
"name": "Hector"
},
{
"__typename": "CardStack",
"name": "Scotty",
"cards": [
{
"Defense": 1950
},
{
"Defense": 76566
}
]
},
{
"__typename": "SpecialCard",
"name": "Itzel"
}
]
}
`

Aliases

Zeus supports declaring aliases by using:

`graphql
const aliasedQueryExecute = await chain('query')({
listCards: {
__alias: {
atak: {
attack: [
{ cardID: ['1'] },
{
name: true,
description: true,
},
],
},
},
},
});
`

and this is the response:

`json
{
"listCards": [
{
"atak": [
{
"name": "Zelma",
"description": "Central"
}
]
}
]
}
`

Now you can access properties in a type-safe way like this:

`javascript
aliasedQueryExecute.listCards.map((c) => c.atak);
`

Directives

Zeus supports using directives on fields.

`typescript
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),
},
});
`

remember that you need to put in the 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
}
});
`

Variables

It's simple to perform queries with variables by using the useZeusVariables function. It also forces you to be type-safe.

`ts
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: {
Attack: 2,
Defense: 3,
description: 'Lord of the mountains',
name: 'Golrog',
},
},
);
`

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 (
onClick={() => {
// this are typesafe vars
mutate({
variables: {
cardId: 'du1hn298u1eh',
},
});
}}>
Click