GraphQL Zeus Documentation

The GraphQL Zeus documentation is currently ~50% complete and covers several key areas of the library.

Completed Core Areas

• Getting Started: Installation, quickstart, CLI usage, and first query tutorials.
• Core Concepts: Chain client, selectors (including FromSelector), type inference, thunder (custom fetch implementation), and understanding generated types.
• Queries & Mutations: Basic queries (pagination, filtering, sorting), mutations (create, update, delete, file uploads), and type-safe variables.
• Advanced: SSE (Server-Sent Events) subscriptions including API methods (on, error, open, off, close) and React integration.
• Integrations: TypedDocumentNode guide for Apollo Client, React Query, and urql.
• Examples: Node.js + TypeScript project structure and selector patterns.

Key Technical Features Documented

• Type Inference: Selection-based inference for nested objects, arrays, unions, interfaces, and enums.
• Thunder Client: Custom fetch implementation supporting authentication (Bearer, dynamic, refresh), retry logic with exponential backoff, and file uploads.
• Generated Types: Distinction between ValueTypes and ModelTypes, as well as GraphQLTypes, InputTypes, Enums, and Scalars.

Zeus provides built-in support for real-time data via WebSockets and Server-Sent Events (SSE).

• WebSocket Subscriptions: Use the Subscription class to connect to a WebSocket endpoint.
• SSE Subscriptions: Use the SSESubscription class for Server-Sent Events.

Both methods allow you to define a subscription query and use an .on(callback) listener to handle incoming data.

import { Subscription, SSESubscription } from './zeus';

// WebSocket subscriptions
const sub = Subscription('wss://api.com/graphql');
sub('subscription')({
  messageAdded: {
    id: true,
    content: true,
    author: { name: true },
  },
}).on((data) => {
  console.log('New message:', data.messageAdded);
});

// SSE subscriptions
const sse = SSESubscription('https://api.com/graphql');
const stream = sse('subscription')({
  liveMetrics: {
    timestamp: true,
    activeUsers: true,
  },
});

stream.on((data) => {
  console.log('Metrics:', data.liveMetrics);
});

Zeus provides a type-safe way to interact with GraphQL endpoints by using your schema to generate TypeScript types and strongly typed clients.

Instead of writing raw GraphQL strings (which are not type-safe), you use a Zeus syntax that allows you to define queries and selectors using objects. This enables features like:

• Type-safe selectors: Defining which fields to fetch using object keys.
• Variable handling: Using the $(name, type) syntax for variables.
• Reusable selection sets: Using fields("TypeName") to fetch all primitive fields of a type, similar to fragments.

// Zeus syntax (type-safe)
{
  usersQuery: {
    admin: {
      sequenceById: [
        { id: $("id", "String!") },
        {
          _id: true,
          name: true,
          analytics: { ...fields("SequenceAnalytics") },
          replies: {
            ...fields("SequenceTrackReply"),
          },
          messages: {
            ...fields("Message"),
          },
          tracks: {
            ...fields("SequenceTrack"),
            contact: {
              linkedInId: true,
            },
          },
        },
      ],
    },
  },
}

Scalar Fields

Select scalar fields (String, Number, Boolean, etc.) by setting them to true in the selection object.

No Arguments

If a field requires no arguments, omit the array syntax and pass the selection object directly.

Nested Objects

For nested objects, use a nested object structure within the selection. This can be done deeply for complex hierarchies.

Arrays and Lists

To query a list, pass the selection object. If the list requires arguments (like pagination or filtering), use the array syntax [ { arguments }, { selections } ].

// Nested objects
const result = await chain('query')({
  user: [
    { id: '123' },
    {
      name: true,
      profile: {
        avatar: true,
        location: {
          city: true,
        },
      },
    },
  ],
});

// Lists with arguments
const result = await chain('query')({
  users: [
    { first: 10, orderBy: 'CREATED_AT' },
    { id: true, name: true },
  ],
});