README

apollo-server-tools

Helper for apollo-server

Install

Install with npm:

$ npm install --save apollo-server-tools

Example

const path = require('path');
const { syncDocs, CommentVersionPlugin } = require('apollo-server-tools');
const { ApolloServer } = require('apollo-server');
const request = require('request-promise');

const typeDefs = `
    type Query {
        # [deprecated] 1.0.0 Deprecated, add reason and what to do...
        messages: [Message!]!
    }
    # [deprecated] 2.0.0 Also Deprecated, notice the date
    type Message {
        id: String
        # [deprecated] 3.0.0 Yep, Deprecated, we can deprecate everything now
        content: String
        # [required] 3.0.0
        payload: String
    }
`;
const resolvers = {
  Query: {
    messages: () => [
      { id: 1, content: 'Data', payload: null }
    ]
  }
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [CommentVersionPlugin({
    apiVersionHeader: 'x-api-version',
    forceSunset: false,
    sunsetDurationInDays: 7 * 52,
    versions: {
      '0.0.1': '2018-01-01',
      '1.0.0': '2019-01-01',
      '2.0.0': '2019-02-02',
      '3.0.0': '2019-03-03'
    }
  })],
  introspection: false // clients should obtain this from the generated file (see below)
});

// --- deprecation header are returned when deprecated functionality is accessed

server.listen().then(async (serverInfo) => {
  const r = await request({
    method: 'POST',
    uri: `${serverInfo.url}graphql`,
    json: true,
    body: { query: 'query Messages { messages { id, content } }' },
    headers: {
      'x-api-version': '0.0.1'
    },
    resolveWithFullResponse: true
  });
  // As per example https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5
  console.log('Deprecation Header:', r.headers.deprecation);
  console.log('Sunset Header:', r.headers.sunset);
  console.log('Response Body:', JSON.stringify(r.body));
  serverInfo.server.close();
});

// --- how you could sync graph api documentation to file

syncDocs(path.join(__dirname, 'graph-docs.json'), server.schema);

Functions

parseInfo({ ast, fragments = {}, vars = {} })

Parse info object to easily access relevant information.

getDeprecationMeta({ versions, sunsetDurationInDays, schema, ast, fragments = {}, vars = {} })

Parse out relevant deprecation information for all accessed functionality.

Expects custom deprecation syntax, see below.

The versions parameter is expected to be an object mapping versions to their respective introduction Date.

Can e.g. be used to return a Sunset header.

getDeprecationDetails({ schema, ast, fragments = {}, vars = {} })

Fetch deprecated entities that are accessed by the query. Expects custom deprecation syntax, see below.

CommentVersionPlugin({ sunsetDurationInDays: Integer, forceSunset: Boolean, versions: Object })

Graphql Plugin that injects appropriate headers into responses.

If forceSunset is set to true and sunset functionality is accessed, an error is thrown.

Versions is expected to be an object mapping versions to their creation date string as "YYYY-MM-DD".

Can make optional arguments required from a certain version by using e.g [required] 1.0.0 as a comment.

syncDocs(filepath, schema, stripDeprecated = true)

Write introspection result into file. Order is stable. Returns true iff the content has changed. Deprecated entities are removed if option is set. Expects custom deprecation syntax, see below.

generateDocs(schema, stripDeprecated = true)

Generate and return introspection result. Deprecated entities are removed if option is set. Expects custom deprecation syntax, see below.

Deprecation Syntax

Deprecation functionality is very limited in graphql. This tool allows overloading of comments, which means that everything in the schema can be deprecated.

The deprecation comment is expected to be in the form [deprecated] YYYY-MM-DD description, where the date indicates the date of deprecation.

Usage no npm install needed!