graphql-api-koa

GraphQL execution and error handling middleware written from scratch for Koa.

Setup

To install graphql-api-koa and graphql from npm run:

npm install graphql-api-koa graphql

See the execute middleware examples to get started.

API

Table of contents

• function errorHandler
• function execute
• type ExecuteOptions
• type ExecuteOptionsOverride

function errorHandler

Creates Koa middleware to handle errors. Use this before other middleware to catch all errors for a correctly formated GraphQL response. When intentionally throwing an error, create it with status and expose properties using http-errors or the response will be a generic 500 error for security.

Returns: Function — Koa middleware.

Examples

How to throw an error determining the response.

const Koa = require('koa')
const bodyParser = require('koa-bodyparser')
const { errorHandler, execute } = require('graphql-api-koa')
const createError = require('http-errors')
const schema = require('./schema')
 
const app = new Koa()
  .use(errorHandler())
  .use(async (ctx, next) => {
    if (
      // It’s Saturday.
      new Date().getDay() === 6
    )
      throw createError(503, 'No work on the sabbath.', { expose: true })
 
    await next()
  })
  .use(bodyParser())
  .use(execute({ schema }))

function execute

Creates Koa middleware to execute GraphQL. Use after the errorHandler and body parser middleware.

Returns: Function — Koa middleware.

Examples

A basic GraphQL API.

const Koa = require('koa')
const bodyParser = require('koa-bodyparser')
const { errorHandler, execute } = require('graphql-api-koa')
const schema = require('./schema')
 
const app = new Koa()
  .use(errorHandler())
  .use(bodyParser())
  .use(execute({ schema }))

type ExecuteOptions

execute Koa middleware options.

Type: object

Examples

execute middleware options that sets the schema once but populates the user in the GraphQL context from the Koa context each request.

const schema = require('./schema')
 
const executeOptions = {
  schema,
  override: ctx => ({
    contextValue: {
      user: ctx.state.user
    }
  })
}

type ExecuteOptionsOverride

Overrides any ExecuteOptions (except override) per request.

Type: Function

Returns: object — execute middleware options subset.

Examples

An execute middleware options override that populates the user in the GraphQL context from the Koa request context.

const executeOptionsOverride = ctx => ({
  contextValue: {
    user: ctx.state.user
  }
})