Create a GraphQL operation (query/mutation) object-oriented builder based on the GraphQL schema

[MurzNN]

Is your feature request related to a problem? Please describe.

For now, the GraphQL Code Generator tool covers only the results of the GraphQL operations, providing types for them, as I understand.

But composing the GraphQL operations (query/mutation) still happens as a plain string, instead of a structured or typed object, which leads to a bad developer experience.

So, would be great to extend the GraphQL Code Generator project by providing a convenient object-oriented builder of GraphQL operations (query/mutation/etc), that operates with the operation fields, attributes and other items as objects, not just as a string.

Describe the solution you'd like

The idea is to create a tool that allows composing a GraphQL operation, providing not a plain text string with the GraphQL operation text, but an object that can be converted to a string.

So, instead of a code like this:

const postsQueryDocument = /* GraphQL */ `
  query Posts {
    posts {
      id
      title
      author {
        id
        firstName
        lastName
      }
    }
  }
`

have the same structure, but as an object, like this:

const postsQueryDocument: GraphqlOperation = {
  query: {
    Posts: {
      posts: {
        id: true,
        title: true,
        author: {
          id: true,
          firstName: true,
          lastName: true,
        },
      },
    },
  },
};

that can be converted to a string by a utility function.

This approach can provide native Typescript type checking with highlighting all the errors in the operation structure, field and attribute names, etc.

Additionally, users will be able to get a base operation and modify it, without using a regexp magic, something like this:

const postsQueryDocumentWithBody = structuredClone(postsQueryDocument);
// Adds a "body" field to the already existing posts query.
postsQueryDocumentWithBody.query.Posts.posts.body = true;
// Deletes the "author" field from the query.
delete postsQueryDocumentWithBody.query.Posts.posts.author;

Provided examples are for JavaScript, but we can have a similar developer experience in all other languages.

What do you think about this idea?

Describe alternatives you've considered

There is a separate project, implementing this idea, already exists here https://github.com/john-yuan/graphql-toolkit/tree/main/packages/generate-graphql-query

It is able to generate Typescript types in a similar way that the codegen project does, but the format is slightly different. Therefore, users can't reuse the generated Typescript types from codegen and have to manage two separate Typescript files (and the mess with a lot of similar type names in the files) to use both libraries at once.

So, the alternative can be adapting the generate-graphql-query project to work directly with the codegen-generated types.

Any additional important details?

If this is already possible now with the current version of the tool or a plugin, could you please provide an example?

[MurzNN]

Here john-yuan/graphql-toolkit#3 (comment) is an example how we can achieve typed GraphQL query with the existing Typescript types from the schema.

[eddeee888]

Hi @MurzNN ,
Thanks for proposing the idea!

AFAIK, it's common to do one of these in these approaches when sending the request:

• send the GraphQL doc
• send the converted AST (from the doc using gql tags)

I'm curious if there are GraphQL clients that could already consume the object-oriented style?

---

But composing the GraphQL operations (query/mutation) still happens as a plain string, instead of a structured or typed object, which leads to a bad developer experience.

A side note: there are extensions that can provide better developer experience (e.g. syntax highlighting, intellisense) when working with GraphQL documents (maybe you already tried them?) 🙂:

• https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql
• https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql-syntax

[MurzNN]

I'm curious if there are GraphQL clients that could already consume the object-oriented style?

There is no need for GraphQL clients to accept the operation as an object, as they should send it to the GraphQL endpoint as a string anyway 😉

The main benefit of this object-oriented GraphQL query approach happens before the query is sent to the GraphQL client: developers can manipulate parts of the query as objects, eg add new fields, delete, modify existing ones, run some checks, etc.

A side note: there are extensions that can provide better developer experience (e.g. syntax highlighting, intellisense) when working with GraphQL documents

About extensions that provide syntax highlighting and intellisense - yes, I tried them, but they just colorize the string in the editor, but the string still stays as a string! 😉 So they don't improve manipulations with the queries at all.

For example, you have this GraphQL query as string:

const postsQueryDocument = `
  query Posts {
    posts {
      id
      title
      author {
        id
        firstName
        lastName
      }
    }
  }
`

And need to do some simple things:

1. Check if the posts.author.id field is added to the query.
2. Add the "body" field to the "posts" field.

How would you do this? Only regexp magic, right?

Or some library that parses this query to an object, does the manipulations, and then stringifies it back to the string.

And my suggestion is exactly to make this library, reusing the already existing power and types of the Codegen project. At least, the "stringify" part. And get native Typescript type checking for GraphQL queries out of the box in any IDE without any extensions as a bonus! 😜

Does it sound more valuable now?

[MurzNN]

There is a great generate-graphql-query library that implements exactly what is described here, and it works very well for me!

But it works with its own format of the generated GraphQL Schema types, not compatible with the Codegen format, and managing two schema types in a single project is a pain for developers!

So, would be great to implement the same library in the scope of the Codegen project, maybe as a plugin, or even better - collaborate with the author of that library @john-yuan to join forces and create a single product that works for both approaches.

[eddeee888]

Thanks for the explanation @MurzNN !

And need to do some simple things:
Check if the posts.author.id field is added to the query.
Add the "body" field to the "posts" field.

To be honest, I haven't seen these needs whilst writing GraphQL documents before. The documents are usually static, and say, if we need to check if a field is in the query, maybe writing tests could help with that? 🤔
It'd be good to understand what GraphqlOperation looks like too. I can imagine it being quite complex.

---

But don't let my limited understanding of this use case stop you! Feel free to create a plugin to try it out for yourself, either in your own repo or our community repo (if it'd used by others in the community) 🙂