Raw

Examples -> Headers Raw Raw Document Node Raw Document Node Typed Raw String Raw String Typed

Raw methods allow you to work directly with GraphQL syntax. They approximate what graphql-request was before it turned into graffle.

Sending Document Nodes

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

Graffle exports a utility template tag gql to easily create them. Its name is also strategically chosen to leverage automatic GraphQL syntax highlighting that editors generally provide.

Example

Raw Document Node

import { Opentelemetry, OrThrow } from 'graffle/extensions'
import { gql, Graffle } from 'graffle'

const graffle = Graffle.create({
  schema: `https://countries.trevorblades.com/graphql`,
})
  .use(OrThrow())
  .use(Opentelemetry())

const data = await graffle.raw({
  document: gql`
    query countries ($filter: [String!]) {
      countries (filter: { name: { in: $filter } }) {
        name
        continent {
          name
        }
      }
    }
  `,
  variables: { filter: [`Canada`, `Germany`, `Japan`] },
})

console.log(data)

{
  countries: [
    { name: 'Canada', continent: { name: 'North America' } },
    { name: 'Germany', continent: { name: 'Europe' } },
    { name: 'Japan', continent: { name: 'Asia' } }
  ]
}

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

Raw Document Node Typed

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

const graffle = Graffle.create({
  schema: `https://countries.trevorblades.com/graphql`,
})

/*************************************** Variation 1 ***************************************
 * -
 * -
 * -
 * You can pass type variables to the `gql` template tag.
 * -
 */

{
  const document = gql<{ countries: { name: string; continent: { name: string } }[] }, { filter: string[] }>`
    query countries ($filter: [String!]) {
      countries (filter: { name: { in: $filter } }) {
        name
        continent {
          name
        }
      }
    }
  `

  const data = await graffle.raw({ document, variables: { filter: [`Canada`, `Germany`, `Japan`] } })

  console.log(data?.countries)
}

/*************************************** Variation 2 ***************************************
 * -
 * -
 * -
 * You can also cast the type if you have a reference to a pre constructed type.
 * -
 */

{
  type Document = TypedQueryDocumentNode<
    { countries: { name: string; continent: { name: string } }[] },
    { filter: string[] }
  >

  const document: Document = gql`
    query countries ($filter: [String!]) {
      countries (filter: { name: { in: $filter } }) {
        name
        continent {
          name
        }
      }
    }
  `

  const data = await graffle.raw({ document, variables: { filter: [`Canada`, `Germany`, `Japan`] } })

  console.log(data?.countries)
}

[
  { name: 'Canada', continent: { name: 'North America' } },
  { name: 'Germany', continent: { name: 'Europe' } },
  { name: 'Japan', continent: { name: 'Asia' } }
]

[
  { name: 'Canada', continent: { name: 'North America' } },
  { name: 'Germany', continent: { name: 'Europe' } },
  { name: 'Japan', continent: { name: 'Asia' } }
]

Sending Strings

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

Example

Raw String

import { Graffle } from 'graffle'

const graffle = Graffle.create({
  schema: `https://countries.trevorblades.com/graphql`,
})

const document = /* gql */ `
  {
    countries {
      name
    }
  }	
`

const data = await graffle.rawString({ document })

console.log(data)

{
  countries: [
    { name: 'Andorra' },
    { name: 'United Arab Emirates' },
    { name: 'Afghanistan' },
    { name: 'Antigua and Barbuda' },
    { name: 'Anguilla' },
    { name: 'Albania' },
    { name: 'Armenia' },
    { name: 'Angola' },
    { name: 'Antarctica' },
    { name: 'Argentina' },
    { name: 'American Samoa' },
    { name: 'Austria' },
    { name: 'Australia' },
    { name: 'Aruba' },
    { name: 'Åland' },
    { name: 'Azerbaijan' },
    { name: 'Bosnia and Herzegovina' },
    { name: 'Barbados' },
    { name: 'Bangladesh' },
    { name: 'Belgium' },
    { name: 'Burkina Faso' },
    { name: 'Bulgaria' },
    { name: 'Bahrain' },
    { name: 'Burundi' },
    { name: 'Benin' },
    { name: 'Saint Barthélemy' },
    { name: 'Bermuda' },
    { name: 'Brunei' },
    { name: 'Bolivia' },
    { name: 'Bonaire' },
    { name: 'Brazil' },
    { name: 'Bahamas' },
    { name: 'Bhutan' },
    { name: 'Bouvet Island' },
    { name: 'Botswana' },
    { name: 'Belarus' },
    { name: 'Belize' },
    { name: 'Canada' },
    { name: 'Cocos [Keeling] Islands' },
    { name: 'Democratic Republic of the Congo' },
    { name: 'Central African Republic' },
    { name: 'Republic of the Congo' },
    { name: 'Switzerland' },
    { name: 'Ivory Coast' },
    { name: 'Cook Islands' },
    { name: 'Chile' },
    { name: 'Cameroon' },
    { name: 'China' },
    { name: 'Colombia' },
    { name: 'Costa Rica' },
    { name: 'Cuba' },
    { name: 'Cape Verde' },
    { name: 'Curacao' },
    { name: 'Christmas Island' },
    { name: 'Cyprus' },
    { name: 'Czech Republic' },
    { name: 'Germany' },
    { name: 'Djibouti' },
    { name: 'Denmark' },
    { name: 'Dominica' },
    { name: 'Dominican Republic' },
    { name: 'Algeria' },
    { name: 'Ecuador' },
    { name: 'Estonia' },
    { name: 'Egypt' },
    { name: 'Western Sahara' },
    { name: 'Eritrea' },
    { name: 'Spain' },
    { name: 'Ethiopia' },
    { name: 'Finland' },
    { name: 'Fiji' },
    { name: 'Falkland Islands' },
    { name: 'Micronesia' },
    { name: 'Faroe Islands' },
    { name: 'France' },
    { name: 'Gabon' },
    { name: 'United Kingdom' },
    { name: 'Grenada' },
    { name: 'Georgia' },
    { name: 'French Guiana' },
    { name: 'Guernsey' },
    { name: 'Ghana' },
    { name: 'Gibraltar' },
    { name: 'Greenland' },
    { name: 'Gambia' },
    { name: 'Guinea' },
    { name: 'Guadeloupe' },
    { name: 'Equatorial Guinea' },
    { name: 'Greece' },
    { name: 'South Georgia and the South Sandwich Islands' },
    { name: 'Guatemala' },
    { name: 'Guam' },
    { name: 'Guinea-Bissau' },
    { name: 'Guyana' },
    { name: 'Hong Kong' },
    { name: 'Heard Island and McDonald Islands' },
    { name: 'Honduras' },
    { name: 'Croatia' },
    { name: 'Haiti' },
    { name: 'Hungary' },
    ... 150 more items
  ]
}

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

Example

Raw String Typed

import { Graffle, type TypedDocumentString } from 'graffle'

const graffle = Graffle.create({
  schema: `https://countries.trevorblades.com/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/jasonkuhrt/graffle/issues/997
 */
type Document = TypedDocumentString<
  { countries: { name: string; continent: { name: string } }[] },
  { filter: string[] }
>

const document: Document = /* gql */ `
  query countries ($filter: [String!]) {
    countries (filter: { name: { in: $filter } }) {
      name
      continent {
        name
      }
    }
  }
`

const data = await graffle.rawString({
  document,
  variables: { filter: [`Canada`, `Germany`, `Japan`] },
})

console.log(data?.countries)

[
  { name: 'Canada', continent: { name: 'North America' } },
  { name: 'Germany', continent: { name: 'Europe' } },
  { name: 'Japan', continent: { name: 'Asia' } }
]