[client-preset] support explicit type annotation

[revero-doug]

Background

Due to Typescript limitations, tagged template literals don't work with overrides, making inferring the correct TypedDocumentNode type impossible using the following idiomatic syntax (see #8584):

import { gql } from './generated'
const fooQuery = gql`
query Foo {
  bar {
    baz
  }
}
`

Instead, the currently supported syntax looks as follows:

import { graphql } from './generated'
const fooQuery = graphql(/* GraphQL */`
query Foo {
  bar {
    baz
  }
}
`)

Proposed syntax / workflow

The following has the benefit of being more explicit without requiring any more effort than the current approach, while still supporting the more idiomatic tagged template literal syntax people are likely to be using prior to adopting client-preset:

import { gql } from '@apollo/client/core'
import { Foo } from './generated'

const fooQuery: Foo = gql`
query Foo {
  bar {
    baz
  }
}
`

Note that in typical usage, the developer would start with an untyped document, npm run codegen (or wait for generation if it's running in watch mode), then add : Foo to the fooQuery declaration, and the IDE would autoimport the generated type.

Also note that a very close analog of this workflow / syntax is already supported when using typed-document-node and related plugins instead of the preset, only one would have to write const fooQuery: typeof FooDocument = // . . .; this prior art should provide a quick and easy implementation path.

[charlypoly]

Hi @revero-doug,

Thank you for your proposal; however, the point of the client-preset is to not manipulate generated types.
We already have plugins that provide such developer experience.

If you are willing to use gql with a tagged template approach, I encourage you to use the typed-document-nodes plugin instead of the client-preset while we work on improving it: https://www.the-guild.dev/graphql/codegen/plugins/typescript/typed-document-node

[revero-doug]

@charlypoly I would encourage you to reconsider and perhaps solicit feedback from the broader community of maintainers and users, as I believe this feature is aligned with the stated high level goals of client preset and could be an additional interface supported alongside the existing graphql(/* . . . */) interface with little development effort or maintenance cost.

I recognize and support the goal of coalescing on a common community configuration for typing graphql documents, and I'd suggest that additionally supporting this more conventional syntax would serve to increase rather than hamper adoption of this standard configuration without adding significant complexity. I don't think that the boilerplate of declaring and importing the types (note there's no assertion or other manipulation required) is any better or worse than the boilerplate of importing and applying a graphql(/* . . . */) function call, and it has the benefit of broader tooling compatibility and greater compatibility with existing code without requiring anything more than exporting types which are already being generated in the current implementation.

Feature-wise, this goes a step further than existing plugins as it would export a type alias with the exact name of the document rather than a copy of the document or 3 types which must be combined (2 passed as type parameters to the 3rd), yielding a cleaner interface; this is worth mentioning, though I don't want to lose sight of the fact that the primary aim is to gain support for this pattern in the standard/recommended configuration.

[nandorojo]

The question I'm wondering is, is there any hope for typescript supporting the template syntax?