Merge branch 'master' into abernix/re-new-request-pipeline

README.md

@@ -115,8 +115,10 @@ const server = new ApolloServer({ typeDefs, resolvers });
 const app = express();
 server.applyMiddleware({ app });
 
-app.listen({ port: 4000 }, () =>
-  console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`),
+const port = 4000;
+
+app.listen({ port }, () =>
+  console.log(`🚀 Server ready at http://localhost:${port}${server.graphqlPath}`),
 );
 ```
 
@@ -149,16 +151,51 @@ const path = '/graphql';
 server.use(query());
 server.applyMiddleware({ app, path });
 
-app.listen({ port: 4000 }, () =>
-  console.log(`🚀 Server ready at http://localhost:4000${server.graphqlPath}`),
+const port = 4000;
+
+app.listen({ port }, () =>
+  console.log(`🚀 Server ready at http://localhost:${port}${server.graphqlPath}`),
 );
 ```
 
 > Note; `qs-middleware` is only required if running outside of Meteor
 
+### Koa
+
+```js
+const koa = require('koa');
+const { ApolloServer, gql } = require('apollo-server-koa');
+
+// Construct a schema, using GraphQL schema language
+const typeDefs = gql`
+  type Query {
+    hello: String
+  }
+`;
+
+// Provide resolver functions for your schema fields
+const resolvers = {
+  Query: {
+    hello: () => 'Hello world!',
+  },
+};
+
+const server = new ApolloServer({ typeDefs, resolvers });
+
+const app = new Koa();
+server.applyMiddleware({ app });
+
+const port = 3000;
+const host = 'localhost';
+
+app.listen(port, host, () =>
+  console.log(`🚀 Server ready at http://${host}:${port}${server.graphqlPath}`),
+);
+```
+
 ### Hapi
 
-The code below requires Hapi 17 or higher.
+> The code below requires Hapi 17 or higher.
 
 ```js
 const { ApolloServer, gql } = require('apollo-server-hapi');

docs/source/essentials/data.md

@@ -11,7 +11,9 @@ Resolvers provide the instructions for turning a GraphQL operation into data. Re
 In order to respond to queries, a schema needs to have resolve functions for all fields. This collection of functions is called the "resolver map". This map relates the schema fields and types to a function.
 
 ```js
+
 const { gql } = require('apollo-server');
+const { find, filter } = require('lodash');
 
 const schema = gql`
 type Book {
@@ -53,7 +55,7 @@ The resolver parameters generally follow this naming convention and are describe
 1. `parent`: The object that contains the result returned from the resolver on the parent field, or, in the case of a top-level `Query` field, the `rootValue` passed from the [server configuration](./server.html). This argument enables the nested nature of GraphQL queries.
 2. `args`: An object with the arguments passed into the field in the query. For example, if the field was called with `query{ key(arg: "you meant") }`, the `args` object would be: `{ "arg": "you meant" }`.
 3. `context`: This is an object shared by all resolvers in a particular query, and is used to contain per-request state, including authentication information, dataloader instances, and anything else that should be taken into account when resolving the query. Read [this section](#context) for an explanation of when and how to use context.
-4. `info`: This argument contains information about the execution state of the query, including the field name, path to the field from the root, and more. It's only documented in the [GraphQL.js source code](https://github.com/graphql/graphql-js/blob/c82ff68f52722c20f10da69c9e50a030a1f218ae/src/type/definition.js#L489-L500), but is extended with additional functionality by other modules, like [`apollo-cache-control`](https://github.com/apollographql/apollo-cache-control-js).
+4. `info`: This argument contains information about the execution state of the query, including the field name, path to the field from the root, and more. It's only documented in the [GraphQL.js source code](https://github.com/graphql/graphql-js/blob/c82ff68f52722c20f10da69c9e50a030a1f218ae/src/type/definition.js#L489-L500), but is extended with additional functionality by other modules, like [`apollo-cache-control`](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-cache-control).
 
 In addition to returning GraphQL defined [scalars](./schema.html#scalar), you can return [custom scalars](../features/scalars-enums.html) for special use cases, such as JSON or big integers.
 

docs/source/features/errors.md

@@ -38,7 +38,7 @@ The response will return:
 
 ![Screenshot demonstrating an error stacktrace and additional](../images/features/error-stacktrace.png)
 
-> To disable stacktraces for production, pass `debug: false` to the Apollo server constructor or set the `NODE_ENV` environment variable to 'production' or 'test'
+> To disable stacktraces for production, pass `debug: false` to the Apollo server constructor or set the `NODE_ENV` environment variable to 'production' or 'test'. Note that this will make the stacktrace unavailable to your application. If you want to log the stacktrace, but not send it in the response to the client, see [Masking and logging errors](#masking-and-logging-errors) below.
 
 ## Codes
 
@@ -118,16 +118,19 @@ new ApolloError(message, code, additionalProperties);
 
 ## Masking and logging errors
 
-The Apollo server constructor accepts a `formatError` function that is run on each error passed back to the client. This can be used to mask errors as well as logging.
-This example demonstrates masking
+The Apollo server constructor accepts a `formatError` function that is run on each error passed back to the client. This can be used to mask errors as well as for logging.
+This example demonstrates masking (or suppressing the stacktrace):
 
-```js line=4-7
+```js line=4-10
 const server = new ApolloServer({
   typeDefs,
   resolvers,
   formatError: error => {
     console.log(error);
     return new Error('Internal server error');
+    // Or, you can delete the exception information
+    // delete error.extensions.exception;
+    // return error;
   },
 });
 

docs/source/migration-two-dot.md

@@ -193,15 +193,18 @@ app.listen({ port: 4000 }, () =>
 
 For many existing instances of Apollo Server, the schema is created at runtime before server startup, using `makeExecutableSchema` or `mergeSchemas`. Apollo Server 2 stays backwards compatible with these more complex schemas, accepting it as the `schema` field in the server constructor options. Additionally, Apollo Server 2 exports all of `graphql-tools`, so `makeExecutableSchema` and other functions can be imported directly from Apollo Server.
 
-> Note: the string to create these schema will not use the `gql` tag exported from apollo-server.
-
 ```js
-const { ApolloServer, makeExecutableSchema, gql } = require('apollo-server');
-
-//For developer tooling, such as autoformatting, use the following workaround
-const gql = String.raw;
-
-const typeDefs = gql`
+const {
+  ApolloServer,
+  makeExecutableSchema
+} = require('apollo-server');
+
+// The `typeDefs` passed into `makeExecutableSchema` are _intentionally_
+// passed in without using the `gql` tag since it requires a `String` and
+// the `gql` tag returns an AST.  When not using `makeExecutableSchema`
+// and passing `typeDefs` into the `ApolloServer` constructor, it's
+// recommended to use the `gql` tag.
+const typeDefs = `
   type Query {
     hello: String
   }