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 (error) {
  if (error instanceof GraphQLError) {
    console.log(error.message + `\n in ${error.source?.name}`)
  }
  throw error
}

Last updated on October 4, 2022

Schema Loading GraphQL Tag Pluck