Merge branch 'master' into master

.circleci/config.yml

@@ -0,0 +1,81 @@
+version: 2
+
+#
+# Reusable Snippets!
+#
+# These are re-used by the various tests below, to avoid repetition.
+#
+run_install_desired_npm: &run_install_desired_npm
+  run:
+    # Due to a bug, npm upgrades from the version of npm that ships with
+    # Node.js 6 (npm v3.10.10) go poorly and generally causes other problems
+    # with the environment.  Since yarn is already available here we can just
+    # use that to work-around the issue.  It's possible that npm cleanup might
+    # prevent this from being necessary, but this can be removed once Node 6 is
+    # no longer being built below.
+    name: Install npm@latest, but with yarn.
+    command: sudo yarn global add npm@latest
+
+# These are the steps used for each version of Node which we're testing
+# against.  Thanks to YAMLs inability to merge arrays (though it is able
+# to merge objects), every version of Node must use the exact same steps,
+# or these steps would need to be repeated in a version of Node that needs
+# something different.  Probably best to avoid that, out of principle, though.
+common_test_steps: &common_test_steps
+  steps:
+    - *run_install_desired_npm
+    - checkout
+    - run: npm --version
+    - run: npm install
+    - run: npm run travis
+
+# Important! When adding a new job to `jobs`, make sure to define when it
+# executes by also adding it to the `workflows` section below!
+jobs:
+
+  # Platform tests, each with the same tests but different platform or version.
+  # The docker tag represents the Node.js version and the full list is available
+  # at https://hub.docker.com/r/circleci/node/.
+  Node.js 4:
+    docker: [ { image: 'circleci/node:4' } ]
+    <<: *common_test_steps
+
+  Node.js 6:
+    docker: [ { image: 'circleci/node:6' } ]
+    <<: *common_test_steps
+
+  Node.js 8:
+    docker: [ { image: 'circleci/node:8' } ]
+    <<: *common_test_steps
+
+  Node.js 9:
+    docker: [ { image: 'circleci/node:9' } ]
+    <<: *common_test_steps
+
+  # Other tests, unrelated to typical code tests.
+  Linting:
+    docker: [ { image: 'circleci/node:8' } ]
+    steps:
+      # (speed) Intentionally omitted, unnecessary, run_install_desired_npm.
+      - checkout
+      # (speed) --ignore-scripts to skip unnecessary Lerna build during linting.
+      - run: npm install --ignore-scripts
+      - run: npm run lint
+  Docs:
+    docker: [ { image: 'circleci/node:8' } ]
+    steps:
+      # (speed) Intentionally omitted, unnecessary, run_install_desired_npm.
+      - checkout
+      # (speed) Ignore scripts to skip the Lerna build stuff for linting.
+      - run: npm install-test --prefix ./docs
+
+workflows:
+  version: 2
+  Build and Test:
+    jobs:
+      - Node.js 4
+      - Node.js 6
+      - Node.js 8
+      - Node.js 9
+      - Linting
+      - Docs

.github/ISSUE_TEMPLATE.md

@@ -5,6 +5,7 @@ While not necessary, you can help organize our issues by labeling this issue whe
 
 - [ ] has-reproduction
 - [ ] feature
+- [ ] docs
 - [ ] blocking
 - [ ] good first issue
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -16,10 +16,9 @@ TODO:
 
 While not necessary, you can help organize our pull requests by labeling this issue when you open it.  To add a label automatically, simply [x] mark the appropriate box below:
 
-- [ ] has-reproduction
 - [ ] feature
 - [ ] blocking
-- [ ] good first review
+- [ ] docs
 
 To add a label not listed above, simply place `/label another-label-name` on a line by itself.
 -->

CHANGELOG.md

@@ -4,7 +4,8 @@
 
 * Fix apollo-server-core runQuery breaks `async_hooks` tracking [PR #733](https://github.com/apollographql/apollo-server/pull/733)
 * Optimize one-time functions [PR# 821](https://github.com/apollographql/apollo-server/pull/821)
-* Add skipValidation option [PR #839](https://github.com/apollographql/apollo-server/pull/839)
+* The `GraphQLOptions` type is now exported from `apollo-server-express` in order to facilitate type checking when utilizing `graphqlExpress`, `graphiqlExpress`, `graphqlConnect` or `graphiqlConnect`. [PR #871](https://github.com/apollographql/apollo-server/pull/871)
+* Add `skipValidation` option [PR #839](https://github.com/apollographql/apollo-server/pull/839)
 
 ### v1.3.2
 

CONTRIBUTING.md

@@ -23,9 +23,9 @@ If you encounter a bug, please file an issue on GitHub via the repository of the
 
 While we will try to be as helpful as we can on any issue reported, please include the following to maximize the chances of a quick fix:
 
-1. **Intended outcome:** What you were trying to accomplish when the bug occurred, and as much code as possible related to the source of the problem.
-2. **Actual outcome:** A description of what actually happened, including a screenshot or copy-paste of any related error messages, logs, or other output that might be related. Places to look for information include your browser console, server console, and network logs. Please avoid non-specific phrases like “didn’t work” or “broke”.
-3. **How to reproduce the issue:** Instructions for how the issue can be reproduced by a maintainer or contributor. Be as specific as possible, and only mention what is necessary to reproduce the bug. If possible, try to isolate the exact circumstances in which the bug occurs and avoid speculation over what the cause might be.
+1.  **Intended outcome:** What you were trying to accomplish when the bug occurred, and as much code as possible related to the source of the problem.
+2.  **Actual outcome:** A description of what actually happened, including a screenshot or copy-paste of any related error messages, logs, or other output that might be related. Places to look for information include your browser console, server console, and network logs. Please avoid non-specific phrases like “didn’t work” or “broke”.
+3.  **How to reproduce the issue:** Instructions for how the issue can be reproduced by a maintainer or contributor. Be as specific as possible, and only mention what is necessary to reproduce the bug. If possible, try to isolate the exact circumstances in which the bug occurs and avoid speculation over what the cause might be.
 
 Creating a good reproduction really helps contributors investigate and resolve your issue quickly. In many cases, the act of creating a minimal reproduction illuminates that the source of the bug was somewhere outside the library in question, saving time and effort for everyone.
 
@@ -45,9 +45,9 @@ For a small bug fix change (less than 20 lines of code changed), feel free to op
 
 Most of the features in Apollo came from suggestions by you, the community! We welcome any ideas about how to make Apollo better for your use case. Unless there is overwhelming demand for a feature, it might not get implemented immediately, but please include as much information as possible that will help people have a discussion about your proposal:
 
-1. **Use case:** What are you trying to accomplish, in specific terms? Often, there might already be a good way to do what you need and a new feature is unnecessary, but it’s hard to know without information about the specific use case.
-2. **Could this be a plugin?** In many cases, a feature might be too niche to be included in the core of a library, and is better implemented as a companion package. If there isn’t a way to extend the library to do what you want, could we add additional plugin APIs? It’s important to make the case for why a feature should be part of the core functionality of the library.
-3. **Is there a workaround?** Is this a more convenient way to do something that is already possible, or is there some blocker that makes a workaround unfeasible?
+1.  **Use case:** What are you trying to accomplish, in specific terms? Often, there might already be a good way to do what you need and a new feature is unnecessary, but it’s hard to know without information about the specific use case.
+2.  **Could this be a plugin?** In many cases, a feature might be too niche to be included in the core of a library, and is better implemented as a companion package. If there isn’t a way to extend the library to do what you want, could we add additional plugin APIs? It’s important to make the case for why a feature should be part of the core functionality of the library.
+3.  **Is there a workaround?** Is this a more convenient way to do something that is already possible, or is there some blocker that makes a workaround unfeasible?
 
 Feature requests will be labeled as such, and we encourage using GitHub issues as a place to discuss new features and possible implementation designs. Please refrain from submitting a pull request to implement a proposed feature until there is consensus that it should be included. This way, you can avoid putting in work that can’t be merged in.
 
@@ -62,24 +62,24 @@ This includes:
 
 For significant changes to a repository, it’s important to settle on a design before starting on the implementation. This way, we can make sure that major improvements get the care and attention they deserve. Since big changes can be risky and might not always get merged, it’s good to reduce the amount of possible wasted effort by agreeing on an implementation design/plan first.
 
-1. **Open an issue.** Open an issue about your bug or feature, as described above.
-2. **Reach consensus.** Some contributors and community members should reach an agreement that this feature or bug is important, and that someone should work on implementing or fixing it.
-3. **Agree on intended behavior.** On the issue, reach an agreement about the desired behavior. In the case of a bug fix, it should be clear what it means for the bug to be fixed, and in the case of a feature, it should be clear what it will be like for developers to use the new feature.
-4. **Agree on implementation plan.** Write a plan for how this feature or bug fix should be implemented. What modules need to be added or rewritten? Should this be one pull request or multiple incremental improvements? Who is going to do each part?
-5. **Submit PR.** In the case where multiple dependent patches need to be made to implement the change, only submit one at a time. Otherwise, the others might get stale while the first is reviewed and merged. Make sure to avoid “while we’re here” type changes - if something isn’t relevant to the improvement at hand, it should be in a separate PR; this especially includes code style changes of unrelated code.
-6. **Review.** At least one core contributor should sign off on the change before it’s merged. Look at the “code review” section below to learn about factors are important in the code review. If you want to expedite the code being merged, try to review your own code first!
-7. **Merge and release!**
+1.  **Open an issue.** Open an issue about your bug or feature, as described above.
+2.  **Reach consensus.** Some contributors and community members should reach an agreement that this feature or bug is important, and that someone should work on implementing or fixing it.
+3.  **Agree on intended behavior.** On the issue, reach an agreement about the desired behavior. In the case of a bug fix, it should be clear what it means for the bug to be fixed, and in the case of a feature, it should be clear what it will be like for developers to use the new feature.
+4.  **Agree on implementation plan.** Write a plan for how this feature or bug fix should be implemented. What modules need to be added or rewritten? Should this be one pull request or multiple incremental improvements? Who is going to do each part?
+5.  **Submit PR.** In the case where multiple dependent patches need to be made to implement the change, only submit one at a time. Otherwise, the others might get stale while the first is reviewed and merged. Make sure to avoid “while we’re here” type changes - if something isn’t relevant to the improvement at hand, it should be in a separate PR; this especially includes code style changes of unrelated code.
+6.  **Review.** At least one core contributor should sign off on the change before it’s merged. Look at the “code review” section below to learn about factors are important in the code review. If you want to expedite the code being merged, try to review your own code first!
+7.  **Merge and release!**
 
 ### Code review guidelines
 
 It’s important that every piece of code in Apollo packages is reviewed by at least one core contributor familiar with that codebase. Here are some things we look for:
 
-1. **Required CI checks pass.** This is a prerequisite for the review, and it is the PR author's responsibility. As long as the tests don’t pass, the PR won't get reviewed.
-2. **Simplicity.** Is this the simplest way to achieve the intended goal? If there are too many files, redundant functions, or complex lines of code, suggest a simpler way to do the same thing. In particular, avoid implementing an overly general solution when a simple, small, and pragmatic fix will do.
-3. **Testing.** Do the tests ensure this code won’t break when other stuff changes around it? When it does break, will the tests added help us identify which part of the library has the problem? Did we cover an appropriate set of edge cases? Look at the test coverage report if there is one. Are all significant code paths in the new code exercised at least once?
-4. **No unnecessary or unrelated changes.** PRs shouldn’t come with random formatting changes, especially in unrelated parts of the code. If there is some refactoring that needs to be done, it should be in a separate PR from a bug fix or feature, if possible.
-5. **Code has appropriate comments.** Code should be commented, or written in a clear “self-documenting” way.
-6. **Idiomatic use of the language.** In TypeScript, make sure the typings are specific and correct. In ES2015, make sure to use imports rather than require and const instead of var, etc. Ideally a linter enforces a lot of this, but use your common sense and follow the style of the surrounding code.
+1.  **Required CI checks pass.** This is a prerequisite for the review, and it is the PR author's responsibility. As long as the tests don’t pass, the PR won't get reviewed.
+2.  **Simplicity.** Is this the simplest way to achieve the intended goal? If there are too many files, redundant functions, or complex lines of code, suggest a simpler way to do the same thing. In particular, avoid implementing an overly general solution when a simple, small, and pragmatic fix will do.
+3.  **Testing.** Do the tests ensure this code won’t break when other stuff changes around it? When it does break, will the tests added help us identify which part of the library has the problem? Did we cover an appropriate set of edge cases? Look at the test coverage report if there is one. Are all significant code paths in the new code exercised at least once?
+4.  **No unnecessary or unrelated changes.** PRs shouldn’t come with random formatting changes, especially in unrelated parts of the code. If there is some refactoring that needs to be done, it should be in a separate PR from a bug fix or feature, if possible.
+5.  **Code has appropriate comments.** Code should be commented, or written in a clear “self-documenting” way.
+6.  **Idiomatic use of the language.** In TypeScript, make sure the typings are specific and correct. In ES2015, make sure to use imports rather than require and const instead of var, etc. Ideally a linter enforces a lot of this, but use your common sense and follow the style of the surrounding code.
 
 ## New contributors
 

DESIGN.md

@@ -4,19 +4,19 @@ The goal of this project is to build a GraphQL server for Node.js that is simple
 
 GraphQL Server consists of three parts:
 
-1. Core
-2. Integrations
-3. Modules
+1.  Core
+2.  Integrations
+3.  Modules
 
 At the core of GraphQL Server is a function called `runQuery`, which handles parsing, validating and executing queries. Its interface is generic in order to allow for integrations with different Node.js server frameworks. Extensions provide useful functionality that can be shared between different integrations.
 
 ### Core
 
 The main goals of GraphQL Server are (in order of priority):
 
-1. Simplicity: GraphQL Server’s core API is very straight forward. It’s one function that does one thing really well (parsing, validating and executing GraphQL queries), and doesn’t do anything else.
-2. Flexibility: The core of GraphQL Server should be transport-agnostic (e.g. it doesn’t deal with HTTP or Websockets directly. This is will be handled in the wrappers for Express, Hapi, etc.)
-3. Performance: GraphQL server should be be tunable to make it fast in production. One example of this is that it should be able to take pre-stored queries to skip parsing and validation. It should also allow easy integration of profiling tools like Apollo Optics that help with debugging and optimizing server performance.
+1.  Simplicity: GraphQL Server’s core API is very straight forward. It’s one function that does one thing really well (parsing, validating and executing GraphQL queries), and doesn’t do anything else.
+2.  Flexibility: The core of GraphQL Server should be transport-agnostic (e.g. it doesn’t deal with HTTP or Websockets directly. This is will be handled in the wrappers for Express, Hapi, etc.)
+3.  Performance: GraphQL server should be be tunable to make it fast in production. One example of this is that it should be able to take pre-stored queries to skip parsing and validation. It should also allow easy integration of profiling tools like Apollo Optics that help with debugging and optimizing server performance.
 
 ### Integrations
 

docs/package.json

@@ -19,8 +19,8 @@
     "hexo-renderer-marked": "0.3.2",
     "hexo-server": "0.3.1",
     "lodash": "4.17.5",
-    "meteor-theme-hexo": "1.0.1",
-    "nodemon": "1.17.1",
+    "meteor-theme-hexo": "1.0.2",
+    "nodemon": "1.17.2",
     "showdown": "1.8.6"
   },
   "scripts": {

docs/source/example.md

@@ -1,5 +1,5 @@
 ---
-title: End-to-end example
+title: Quick start
 description: Copy and paste this code to have a GraphQL server running in 30 seconds.
 ---