Loading GraphQL operation documents from different sources#

Similar to schema loading - but meant to use for GraphQL documents (query/mutation/subscription/fragment).

Any input provided as a source will be recognized by utils automatically.

It also extracts usages of gql from code files using @graphql-tools/graphql-tag-pluck.

For notes on typescript, refer to Schema Loading > Loaders

Usage#

const { loadDocuments } = require('@graphql-tools/load')
const { GraphQLFileLoader } = require('@graphql-tools/graphql-file-loader')
const { CodeFileLoader } = require('@graphql-tools/code-file-loader')

// load from string
const document1 = loadDocuments('query { f }', {
  loaders: []
})

// load from a single file
const document2 = loadDocuments('./users.query.graphql', {
  loaders: [new GraphQLFileLoader()]
})

// load from multiple files using glob
const document3 = loadDocuments('./src/**/*.graphql', {
  loaders: [new GraphQLFileLoader()]
})

// load from code file
const document4 = loadDocuments('./src/my-component.ts', {
  loaders: [new CodeFileLoader()]
})

loadDocuments returns an array of document sources. Each source object has the following structure:

interface DocumentSource {
  document: DocumentNode // Object representation of GraphQL Content
  rawSDL: string // SDL in text
  location: string // Way to access to that source
}

loadDocuments takes in additional configuration via the options object (the second argument). There are some defaults to be aware of - to learn more, see the full API documentation.

You can learn more about loaders to load documents from different sources.

Error handling#

No files found#

In case no documents were found and loaded via the provided glob an exception is thrown.

import { loadDocuments } from '@graphql-tools/load'
import { GraphQLFileLoader } from '@graphql-tools/graphql-file-loader'

const documents = await loadDocuments(['i-do-not-exist.graphql'], {
  loaders: [new GraphQLFileLoader()]
})

If i-do-not-exist.graphql does not exist this throws the following error:

Error:
      Unable to find any GraphQL type definitions for the following pointers:

          - *.graphql

Syntax error within a file#

In case you try to load a GraphQL file with invalid syntax, the loadDocuments function will throw a GraphQLError.

You can identify the exact file that caused this GraphQLError by using the errors source property.

import { loadDocuments } from '@graphql-tools/load'
import { GraphQLFileLoader } from '@graphql-tools/graphql-file-loader'
import { CodeFileLoader } from '@graphql-tools/code-file-loader'
import { GraphQLError } from 'graphql'

try {
  const documents = await loadDocuments(['packages/**/*.graphql', 'packages/**/*.ts(x)'], {
    loaders: [new GraphQLFileLoader(), new CodeFileLoader()]
  })
  console.log(documents)
} catch (err) {
  if (err instanceof GraphQLError) {
    console.log(err.message + `\n in ${err.source?.name}`)
  }
  throw err
}