apollo-helpers

DEPRECATION NOTICE This module is deprecated and no longer supported. Apollo 2.0 implemented tools that make it easy to merge schemas.

A collection of functions I would rewrite over and over again the more I dealt with Apollo graphql-tools, and other graphql setups.

Installation

npm install apollo-helpers

API

apolloHelpers.compileGraphqlResources(modules)

This is used to combine an array of "graphql resources", each with their own schema, resolvers, and context definitions, into a single set of properties you can use to pass into { makeExecutableSchema } from 'graphql-tools'.

const graphqlModules = [
  {
    schema: `type Query { health }`,
    resolvers: { Query: { health: () => 'ok' } }
  },
  {
    schema: `extend type Query { health2 }`,
    resolvers: {
      Query: {
        health2: (parent, args, context) => context.newHealth
      }
    },
    context: req => ({ newHealth: 'A-O-K' })
  }
]
const graphqlResources = compileGraphqlResources(graphqlModules)
const schema = makeExecutableSchema({
  typeDefs: graphqlResources.typeDefs,
  resolvers: graphqlResources.resolvers
})
app.use(
  '/graphql',
  graphqlExpress(req => ({
    schema,
    context: graphqlResources.getContext(req)
  }))
)

The only argument is the array of graphql modules. Each of the graphql modules can have the following properties:

• module.schema - A string, or a function that returns an array of strings
  which represent the schema (and dependent schemas) of your graphql module. See
  the apollo docs
  for how modularizing schemas works. Note that one of your modules will need to
  expose a type Query {} with something in it. An example graphql module will
  show you below.
• module.resolvers - An object, who's shape lines up with your schema. This
  object will be deeply merged into the rest of the resolvers for each of your
  modules. Each resolver function takes in three arguments: parent which is
  the object or value returned from the "parent" type (or the root value of your
  schema as might be the case), args which are the arguments that you've
  defined in your GraphQL Schema, and context which is the context of the
  query, which we'll look at in a minute.
• module.context - A function which takes in the request from whatever
  server framework you're using and should return an object, which will be
  merged together on every graphql request and passed as the context variable
  in your resolvers, allowing each graphql module to define it's own context.
  Note that every one of your "graphql module" contexts will be merged together
  regardless of which resolvers are being called, and merged in a shallow way
  (top level keys only, unlike resolvers).

The result of this function gives you an object which you can give to the graphql-tools makeExecutableSchema and middleware function. The object will be referred to as graphqlResources

• graphqlResources.typeDefs - The array of graphql type definiions needed to
  pass into makeExecutableSchema.
• graphqlResources.resolvers - An object containing the resolvers for your
  queries.
• graphqlResources.getContext - A function that you call with your server
  framework "request context" variable, and will return you the merged context
  object from all of your graphql modules.

// resources/system/system.graphql.js
const systemController = {
  health: () => 'ok',
  echo: msg => msg
}

exports.schema = `
  type Query {
    health: String!
  }
  type Mutation {
    echo(msg: String!): String!
  }
`

exports.context = req => ({
  user: req.user || { id: null },
  system: systemController
})

exports.resolvers = {
  Query: {
    health(parent, args, context) {
      return context.system.health()
    }
  },
  Mutation: {
    echo(parent, args, context) {
      return context.system.echo(args.msg)
    }
  }
}

// resources/todos/todos.graphql.js
// NOTE that in the examples, the business logic is happening in the resolvers.
// My personal opinion is that the logic should happen in the controller, and
// the resolvers should just call functions straight into the controller and
// just act as a translation layer.
const todoController = require('./todos.controller')

exports.schema = `
  type Todo {
    id: ID!
    label: String!
    completed: Boolean!
  }
  extend type Query {
    todos(completed: Boolean): [Todo]!
    todo(id: ID!): Todo
  }
  extend type Mutation {
    createTodo(label: String!): Todo
    updateTodo(
      id: ID!
      label: String
      completed: Boolean
    ): Todo
    deleteTodo(id: ID!): Todo
  }
`

exports.context = req => ({
  todos: todoController
})

exports.resolvers = {
  Todo: {
    id(parent) {
      return String(parent._id)
    }
  },
  Query: {
    todos(parent, args, context) {
      const query = Object.assign({}, args, { owner: context.user.id })
      return context.todos.find(query)
    },
    todo(parent, { id }, context) {
      return context.todos.findOne({
        _id: id,
        owner: context.user.id
      })
    }
  },
  Mutation: {
    createTodo(parent, { label }, context) {
      return context.todos.create({
        label,
        completed: false,
        owner: context.user.id
      })
    },
    updateTodo(parent, { id, ...update }, context) {
      return context.todos.findOneAndUpdate(
        {
          _id: id,
          owner: context.user.id
        },
        update,
        { new: true }
      )
    },
    deleteTodo(parent, { id }, context) {
      return context.todos.findOneAndRemove({
        _id: id,
        owner: context.user.id
      })
    }
  }
}

// app.js
const express = require('express')
const bodyParser = require('body-parser')
const { graphqlExpress } = require('apollo-server-express')
const { makeExecutableSchema } = require('graphq-tools')
const { compileGraphqlResources } = require('apollo-helpers')

// Resources
const system = require('./resources/system/system.graphql')
const todos = require('./resources/todos/todos.graphql')
const graphqlResources = compileGraphqlResources([system, todos])

const schema = makeExecutableSchema({
  typeDefs: graphqlResources.typeDefs,
  resolvers: graphqlResources.resolvers
})

app.use(bodyParser.json())
app.use(
  '/graphql',
  graphqlExpress(req => ({
    schema,
    context: graphqlResources.getContext(req)
  }))
)

apolloHelpers.createExecutor(graphqlModule)

Creates a function that you can call which will execute a graphql query without needing to setup apollo dev server or anything like that. Useful for testing your graphql modules separate from each other.

• graphqlModule - This module follows the same shape/symantics of the graphql
  modules used in compileGraphqlResources, with a schema, context, and
  resolvers property. You can also pass in an array of modules if your module
  depends on another to work property.

Returns an object with a method you can call to run the query.

const { createExecutor } = require('apollo-helpers')
const pubsub = new require('graphql-subscriptions').PubSub()

const graphqlModule = {
  schema: `
    Query { health: String! }
    Mutation { echo(msg: String!): String! }
    Subscription { tick: Int! }
  `,
  resolvers: {
    Query: {
      health: () => 'ok'
    },
    Mutation: {
      echo: (parent, args) => args.msg
    },
    Subscription: {
      tick: {
        subscribe: () => pubsub.asyncIterator('tick')
      }
    }
  }
}
setInterval(() => {
  pubsub.publish('tick', { tick: Date.now() })
}, 1000)

const executor = createExecutor(graphqlModule)

executor.run(`query { health }`).then(result => console.log(result)) // { data: { health: 'ok' } }

executor
  .run(
    `
    mutation Echo($message: String!) {
      echo(msg: $message)
    }
  `,
    {
      variableValues: { message: 'Hello world!' }
    }
  )
  .then(result => console.log(result)) // { data: { echo: 'Hello world!' } }

executor.subscribe(`subscription { tick }`, {}, result => {
  console.log(result) // { data: { tick: 1510239888797 }}
})

• executor.run(query, graphqlOptions) Runs the query and returns a promise which resolves with the data.

  • query - The graphql query to run
  • graphqlOptions - An object of object which help give more context to the
    query.
    • graphqlOptions.contextArg - The argument to pass to each of the
      .context() functions on each of the graphqlModules
    • graphqlOptions.rootValue - The parent object (first argument) to all of
      the top level query and mutation resolvers
    • graphqlOptions.operationName - If you have multiple operations defined
      in your query, you need to specify an operationName to tell the executor
      which query to run
    • graphqlOptions.contextValue - Additional context to pass into the
      context argument
    • graphqlOptions.variableValues - Variables to pass into the graphqlQuery

• executor.subscribe(query, graphqlOptions, callback) Subscribes to a given subscription and calls the callback when that query publishes an event.