graphql-api-koa

GraphQL API Koa middleware.

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

• errorHandler
  • Examples
• execute
  • Parameters
  • Examples
• Types
  • ExecuteOptions
    • Properties
    • Examples
  • MiddlewareOptionsOverride
    • Parameters
    • Examples

errorHandler

Creates Koa middleware to handle errors. Use this as the first 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.

Examples

How to throw an error determining the response.

import Koa from 'koa'
import bodyParser from 'koa-bodyparser'
import { errorHandler, execute } from 'graphql-api-koa'
import createError from 'http-errors'
import schema from './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 }))

Returns Function Koa middleware.

execute

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

Parameters

• options ExecuteOptions Options.

Examples

A basic GraphQL API.

import Koa from 'koa'
import bodyParser from 'koa-bodyparser'
import { errorHandler, execute } from 'graphql-api-koa'
import schema from './schema'

const app = new Koa()
  .use(errorHandler())
  .use(bodyParser())
  .use(execute({ schema }))

Returns Function Koa middleware.

Types

The following types are for documentation only and are not exported.

ExecuteOptions

GraphQL execute Koa middleware options.

Type: Object

Properties

• schema module:graphql.GraphQLSchema GraphQL schema.
• rootValue any? Value passed to the first resolver.
• contextValue any? Execution context (usually an object) passed to resolvers.
• fieldResolver Function? Custom default field resolver.
• override MiddlewareOptionsOverride? Override any ExecuteOptions (except override) per request.

Examples

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

import schema from './schema'

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

MiddlewareOptionsOverride

Per-request Koa middleware options override.

Type: Function

Parameters

• context module:koa.Context Koa context.

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
  }
})

Returns Object Options.