API docs: use GraphQL types not JSONValue

[sqs]

I understand it is because "GraphQL has terrible support for recursive data structures: graphql/graphql-spec#91". But the API would be much easier to use IMO if it were GraphQL-typed and not just JSONValue. The GraphQL query can just request a capped depth (the UI probably only supports a couple levels of nesting anyway). This is what the comment graphql/graphql-spec#91 (comment) in reply to that issue also suggests.

(Just opening this up for discussion and to give 1 data point, it's obviously your call.)

[emidoots]

👋 (after-hours Stephen here, responding because I think it's interesting)

The UI really does support an infinite level of nesting, and needs to because LSIF indexers really could emit whatever structure they want. It's up to the UI to display that in some reasonable way.

I do think embedding JSON values into GraphQL is terrible, nasty, disgusting - and unpleasant to work with. But recursive GraphQL also is terrible, and I would argue worse in this context.

I do think it's super unfortunate, I just don't see any way around it. GraphQL can't do this.

[sqs]

Thanks for the reply. Although the UI supports an infinite level of nesting, it would probably be fine to cap it at N levels deep. You could change the N anytime by just changing the GraphQL query string literal in the TypeScript file. That would then let the GraphQL API be typed.

eg:

gql`
  documentationNode {
    ...CommonDocNodeFields
    children {
      ...CommonDocNodeFields
      children {
        ...CommonDocNodeFields
        children {
          ...CommonDocNodeFields
        }
      }
    }
  }
`

would fetch 4 levels deep.

[emidoots]

@sqs different question: do you actually want access to that API? Basically, I am wondering, what actually made you go to that API and what information were you hoping to get? I am wondering if we could expose nicer higher-level APIs and keep the current one as the "low level" one.