GQL

Examples -> Gql Document Node Gql Document Node Typed Gql String Gql String Typed

The gql method allows you to work directly with GraphQL syntax. It approximates what graphql-request was before it turned into graffle. Its name is also strategically chosen to leverage automatic GraphQL syntax highlighting that editors generally provide.

Sending Document Nodes

Graffle allows you to send DocumentNode instances (created from a class in the graphql package) directly.

Example

Gql Document Node

import { parse } from 'graphql'
import { Opentelemetry } from 'graffle/extensions/opentelemetry'
import { Throws } from 'graffle/extensions/throws'
import { Graffle } from 'graffle'

const graffle = Graffle.create({
  schema: `http://localhost:3000/graphql`,
})
  .use(Throws())
  .use(Opentelemetry())

const data = await graffle.gql(parse(`
  query pokemonByName ($name: String!) {
    pokemonByName (name: $name) {
      name
      trainer {
        name
      }
    }
  }
`)).send({ name: `Pikachu` })

console.log(data)

{
  pokemonByName: [ { name: 'Pikachu', trainer: { name: 'Ash' } } ]
}

You can attain type safety by creating your document with type variables. In a typical real project this would be something that a tool like GraphQL Code Generator automatically does for you.

Example

Gql Document Node Typed

import { parse, type TypedQueryDocumentNode } from 'graphql'
import { Graffle } from 'graffle'

const graffle = Graffle.create({
  schema: `http://localhost:3000/graphql`,
})

type Document = TypedQueryDocumentNode<
  {
    pokemonByName: {
      id: string
      name: string
      hp: number
      attack: number
      defense: number
      trainer: { name: string }
    }
  },
  { name: string }
>

const document = parse(`
    query ($name: String!) {
      pokemonByName (name: $name) {
        name
        hp
        attack
        defense
        trainer {
          name
        }
      }
    }
  `) as Document

const data = await graffle.gql(document).send({ name: `Pikachu` })

console.log(data?.pokemonByName)

[
  {
    name: 'Pikachu',
    hp: 35,
    attack: 55,
    defense: 40,
    trainer: { name: 'Ash' }
  }
]

Sending Strings

You can skip creating document nodes if you don't need them, instead just sending a string directly.

Example

Gql String

import { Graffle } from 'graffle'

const graffle = Graffle.create({
  schema: `http://localhost:3000/graphql`,
})

const data = await graffle.gql`
  {
    pokemon {
      name
    }
  }
`.send()

console.log(data)

{
  pokemon: [
    { name: 'Pikachu' },
    { name: 'Charizard' },
    { name: 'Squirtle' },
    { name: 'Bulbasaur' },
    { name: 'Caterpie' },
    { name: 'Weedle' }
  ]
}

You can still attain type safety even for the string input by casting your string to TypedDocumentString.

Example

Gql String Typed

import { Graffle, type TypedDocument } from 'graffle'

const graffle = Graffle.create({
  schema: `http://localhost:3000/graphql`,
})

/**
 * @remarks Typically this type would come from your code generation tool.
 *
 * @see https://the-guild.dev/graphql/codegen/plugins/presets/preset-client#documentmode
 * @see https://github.com/graffle-js/graffle/issues/997
 */
type Document = TypedDocument.String<
  {
    pokemonByName: {
      id: string
      name: string
      hp: number
      attack: number
      defense: number
      trainer: {
        name: string
      }
    }
  },
  { name: string }
>

const data = await graffle.gql<Document>`
  query pokemonByName ($name: String!) {
    pokemonByName (name: $name) {
      name
      hp
      attack
      defense
      trainer {
        name
      }
    }
  }
`.send({ name: `Pikachu` })

console.log(data?.pokemonByName)

[
  {
    name: 'Pikachu',
    hp: 35,
    attack: 55,
    defense: 40,
    trainer: { name: 'Ash' }
  }
]