feat: graphql test client headers

Question

closes #900

BREAKING CHANGE:

This introduces a new API for the test client.

Before:

ts
ctx.app.query

Now:

ts
ctx.client.send

Part of the motivation for a client namespace is for additional API surface area, like the purpose of this PR, headers:

ts
ctx.client.headers.set('foo', 'bar')

Also while ctx.app.query is very literate in a sense, its arguably better to treat client as a peer property to the thing its interacting with than a nested property.

The reason we don't use ctx.client.query is that such naming overloads query too much. Query is also a kind of operation graphql clients can send to GraphQL servers. Interestingly I noted in a recent Apollo webcast that they made an effort to use the term "operation" instead of query. Also there is some new spec work going in the GraphQL working group to greatly de-overload query and be more precise about how that word is used.

TODO

• [x] docs
• [x] tests

该提问来源于开源项目：prisma-labs/graphql-framework-experiment

Answer 1

Passionate overkill dx thrad here...

I started playing with what an ideal headers experience looks like.

I think this could be something externalized.

This is above an beyond to say the least, (#900 could be solved in ~1 minute with a "whatever" solution) but it pushes my typescript knowledge and might be good learning for other future API surface area.

I'm working from the docs at https://en.wikipedia.org/wiki/List_of_HTTP_header_fields.

Some results so far:

highlights:

• drop down to raw string if working with custom headers
• value type can be specialized to kind of header
• vscode ui allows cycling overload sigs, but its frankly a bit annoying to use, but still much cooler than nothing
• vscode ui also focuses to the sig doc after selecting a param autocomplete. This experience is pretty good, though one thing sucks here which is, sigs only focus after selecting a param autocomplete. It would be great if as I arrow key scroll through param autocompletes the sig docs change so I can read about different headers etc.

open questions/problems

• We'd want many of the overloads (including their doc) duplicated for other methods, e.g. set and append share many. I have no idea how to do that... (my current thinking is its impossible).

• an alternative api is headers.accept.{set,append,get,delete}, better?

  • custom headers in this api would be headers.custom.set('foo', 'bar')

• being able to encode new custom headers would be really nice polish, e.g.:

  ts
  headers.define({
    name: 'x-foo',
    value(value:{abba:string}) { return value.abba === 2 : 'a' : 'b' },
    jsDoc: '...',
  })
  <p>// later</p>
  <p>headers.set('x-foo', { abba: 4 }) // autocomplete for all of this
  </p>

  But I have no idea how global interface merging technique could work with function overloads... I fear no such thing exists.

  Therefore the typegen would have to be going more custom and actually injecting new overloads into the types.