@defer & @stream experimental usage & docs

[Banou26]

Issue Description

When trying to follow the instructions for running @defer & @stream (as per #6827), tried using both the graphql 17.0.0-alpha.2 & 17.0.0-alpha.1, the server always return Unknown directive \"@defer\". as response.

I did also try 16.0.0-experimental-stream-defer.5, in which case, it didn't throw the Unknown directive \"@defer\". error but instead just returned an empty result from the http server.

Using the 16.0.0-experimental-stream-defer.5 experimental version did allow me to get a response from the executeOperation api, even thought it did not conform to the specs documented in #6827 and returned a body.singleResult looking like

{
  next: [Function: next],
  return: [Function: return],
  throw: [Function: throw],
  errors: undefined,
  [Symbol(Symbol.asyncIterator)]: [Function: [Symbol.asyncIterator]]
}

I'd really like to have some more documentation on how to use these features.

Link to Reproduction

https://github.com/Banou26/apollo-server-issue-7279

Reproduction Steps

accessing the sandbox and sending this request

  query GetBooks {
    books {
      title
      author
      ... @defer {
        test {
          foo
        }
      }
    }
  }

will result in a Unknown directive \"@defer\". error

[trevor-scheer]

Hey @Banou26 - thanks for the reproduction. I've opened #7281 to add some documentation which will help you get past the error you're seeing.

[Banou26]

@trevor-scheer little side question, would you happen to know if it's possible to force the package.lock to accept using "graphql": "^17.0.0-alpha.2", with @apollo/client@3.7.3, right now npm i fails because @apollo/client only accepts graphql@"^14.0.0 || ^15.0.0 || ^16.0.0" and that forces me to npm i --force which isn't possible on CIs, or maybe could ^17.0.0 be added to the @apollo/client accepted versions?

[trevor-scheer]

Hey @Banou26, this is a common problem for now - tools don't really support v17 in their peer dependencies. We work around this in our CI using the --legacy-peer-deps flag. I went looking for docs on that flag to link you to, but didn't find any. Best I've got is this StackOverflow post. Hope that's helpful!

apollo-server/.circleci/config.yml

Line 66 in 610f930

- run: npm i --legacy-peer-deps graphql@17.0.0-alpha.1.canary.pr.3361.04ab27334641e170ce0e05bc927b972991953882