@graphjson/sdk

High-level type-safe SDK for building GraphQL queries programmatically

The GraphJSON SDK provides a fluent, chainable API for building GraphQL queries with full TypeScript support. Build complex queries programmatically with autocomplete and type safety.

Why Use This?

• 🎯 Type-Safe - Full TypeScript support with autocomplete
• ⛓️ Chainable API - Fluent, readable query building
• 🚀 Powerful - Supports all GraphQL features
• 💡 IntelliSense - IDE autocomplete for all methods
• 🔧 Flexible - Programmatic query construction

Installation

npm install @graphjson/sdk

Quick Start

import { query, field, variable } from '@graphjson/sdk';
import { generateDocument } from '@graphjson/core';

const myQuery = query({
  users: field()
    .args({
      limit: variable('limit', 'Int!', 10),
      search: variable('search', 'String')
    })
    .select({
      id: true,
      name: true,
      email: true
    })
});

const { ast, variables } = generateDocument(myQuery);

Features

1. Query Builder

Build queries with a fluent API:

import { query, field } from '@graphjson/sdk';

const q = query({
  posts: field()
    .args({ first: 20 })
    .select({
      id: true,
      title: true,
      author: field()
        .select({
          name: true,
          avatar: true
        })
    })
});

2. Field Chaining

Chain methods for complex fields:

field()
  .args({ limit: 10 })
  .select({ id: true, name: true })
  .alias('usersList')
  .directive('include', { if: true })
  .paginate('relay')

3. Variables

Type-safe variable creation:

import { variable } from '@graphjson/sdk';

variable('userId', 'ID!')              // Required
variable('limit', 'Int', 10)           // With default
variable('filter', 'UserFilterInput')  // Optional

4. Pagination

Built-in pagination support:

field()
  .paginate('relay')  // Adds edges/node/pageInfo
  .args({ first: 20 })
  .select({ id: true, title: true })

5. Where Helpers

Type-safe filter building:

import { where, eq, gt, and, or } from '@graphjson/sdk';

const filters = where({
  age: gt(18),
  status: eq('active'),
  role: or(['admin', 'moderator'])
});

API Reference

query(fields: Record<string, Field>): JsonDocument

Creates a query operation.

query({
  users: field().select({ id: true }),
  posts: field().select({ title: true })
})

mutation(fields: Record<string, Field>): JsonDocument

Creates a mutation operation.

mutation({
  createUser: field()
    .args({ input: variable('user', 'UserInput!') })
    .select({ id: true, name: true })
})

field(): FieldBuilder

Creates a field builder with chainable methods.

Methods:

| Method | Description | |--------|-------------| | .args(obj) | Add field arguments | | .select(obj) | Select subfields | | .alias(name) | Set field alias | | .directive(name, args) | Add directive | | .paginate(style) | Add pagination |

variable(name: string, type: string, defaultValue?: any): JsonVariable

Creates a GraphQL variable reference.

variable('userId', 'ID!')           // Required variable
variable('limit', 'Int', 10)        // With default value

Usage Examples

Basic Query

import { query, field } from '@graphjson/sdk';

const q = query({
  users: field().select({
    id: true,
    name: true,
    email: true
  })
});

With Arguments

const q = query({
  user: field()
    .args({ id: '123' })
    .select({
      id: true,
      name: true
    })
});

With Variables

import { query, field, variable } from '@graphjson/sdk';

const q = query({
  users: field()
    .args({
      limit: variable('pageSize', 'Int!', 20),
      offset: variable('offset', 'Int', 0)
    })
    .select({
      id: true,
      name: true
    })
});

Nested Fields

const q = query({
  posts: field()
    .select({
      id: true,
      title: true,
      author: field()
        .select({
          id: true,
          name: true
        }),
      comments: field()
        .args({ first: 10 })
        .select({
          text: true,
          author: field().select({ name: true })
        })
    })
});

With Aliases

const q = query({
  recentPosts: field()
    .alias('recent')
    .args({ first: 10, orderBy: 'CREATED_DESC' })
    .select({ id: true, title: true }),
  
  popularPosts: field()
    .alias('popular')
    .args({ first: 10, orderBy: 'VIEWS_DESC' })
    .select({ id: true, title: true })
});

With Directives

const q = query({
  user: field()
    .select({
      id: true,
      name: true,
      email: field()
        .directive('include', { if: true }),
      phone: field()
        .directive('skip', { if: false })
    })
});

Relay Pagination

const q = query({
  posts: field()
    .paginate('relay')
    .args({ first: 20 })
    .select({
      id: true,
      title: true,
      content: true
    })
});

// Generates query with edges/node/pageInfo structure

Where Filters

import { query, field, where, eq, gt, contains } from '@graphjson/sdk';

const q = query({
  users: field()
    .args({
      where: where({
        age: gt(18),
        status: eq('active'),
        name: contains('john')
      })
    })
    .select({
      id: true,
      name: true
    })
});

TypeScript Support

Full type inference and autocomplete:

import { query, field } from '@graphjson/sdk';

// TypeScript knows the structure
const q = query({
  users: field()
    .args({ /* autocomplete works here */ })
    .select({ /* and here */ })
});

GraphJSON Ecosystem

| Package | Description | NPM | |---------|-------------|-----| | @graphjson/core | Core document generation | | | @graphjson/json-dsl | Type definitions | | | @graphjson/presets | Common presets | |

Examples

See the examples directory for complete examples:

• Advanced Example - Complete SDK showcase

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

License

MIT © NexaLeaf