transform documents hooks #8723

kazekyo · 2022-12-12T10:21:50Z

Description

I have a preset to transform user-defined documents.
I want to use the new client preset, so I want to be able to transform documents with a plugin.

Plugin will have the following functions:

module.exports = {
  plugin: () => {
    return 'hello'
  },
  transformDocuments: (_schema, documents) => {
    // Make some changes to the documents    
    return documents;
  },
  validateBeforeTransformDocuments: () => {
    // Raises an error if necessary
  },
};

Use it as follows:

import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
   schema: 'https://localhost:4000/graphql',
   documents: ['src/**/*.tsx'],
   generates: {
      './src/gql/': {
        preset: 'client',
        documentTransformPlugins: ['./my-plugin.js'],
        plugins: ['./my-plugin.js']
      }
   }
}
export default config

One of the main uses of this feature is to add fields.
For example, assuming that there is a @useIcon directive that adds fields related to an icon:

query exampleQuery {
  user @useIcon {
    name
    email
  }
}

If the plugin transforms the document, we can get the following document:

query exampleQuery {
  user {
    name
    email
    iconUrl # Added by plugin
    iconFileName # Added by plugin
  }
}

New feature (non-breaking change which adds functionality)
This change requires a documentation update

Screenshots/Sandbox (if appropriate/relevant):

Please see unit tests for usage.

How Has This Been Tested?

I added tests to the spec file.

Checklist:

I have followed the CONTRIBUTING(https://github.com/the-guild-org/Stack/blob/master/CONTRIBUTING.md) doc and the style guidelines of this project
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
Any dependent changes have been merged and published in downstream modules

Further comments

About validation

No validation of documents is executed before transforming.
Because I understand that validation before transforming often leads to errors when this feature is needed.
This decision will allow future use of plugins such as relay-operation-optimizer without the skipDocumentsValidation flag.

About relay-operation-optimizer

We can probably remove the special implementation for relay-operation-optimizer and replace it with the document transform plugin.
But I did not include that changes in this pull request. If there is no problem, I will do that next.

…xecuting plugins.

changeset-bot · 2022-12-12T10:21:53Z

🦋 Changeset detected

Latest commit: 2a8e14f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@graphql-codegen/cli	Minor
@graphql-codegen/core	Minor
@graphql-codegen/plugin-helpers	Minor
@graphql-codegen/client-preset	Minor
@graphql-codegen/gql-tag-operations-preset	Minor
@graphql-codegen/graphql-modules-preset	Minor
@graphql-cli/codegen	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

kazekyo · 2022-12-12T10:38:10Z

@saihaj @n1ru4l Could you please review this?
#8593 (reply in thread)

.changeset/short-toes-relax.md

packages/graphql-codegen-cli/tests/codegen.spec.ts

kazekyo · 2022-12-21T15:51:19Z

@n1ru4l I have added a page to the documentation. I'm concerned about the quality of my texts as I don't usually use English.
Please feel free to point it out 🙏

…xecuting plugins.

n1ru4l · 2023-02-03T12:22:00Z

website/src/pages/docs/custom-codegen/document-transform.mdx

+const { visit, print } = require('graphql')
+
+module.exports = {
+  plugin(schema, documents, config) {


I am not really sure if we need this hook/function. What benefit is it trying to solve?

could this file not simply be the following?

module.exports = function transformDocuments (...args) => { }

In terms of the current implementation, I'm using Plugin mechanism to executetransformDocuments. Currently, we get the transformDocuments function from Plugin.

Regarding your question, are you suggesting we create a plugin without the plugin function?
Currently, the plugin function is not optional, but I can change it to be optional. However, I have concerns that making the plugin function optional may confuse users and may not be a desirable change to the API. 🤔

Another option would be not to use the Plugin mechanism at all. Instead, we could introduce a new concept called something like DocumentTransform that works independently of Plugin. Just as Preset is a separate concept from Plugin, DocumentTransform is separate from Plugin.
This would be a slightly over-engineered solution, and most implementations would probably be copies of Plugin, but it would make API cleaner. ✨
If this design is acceptable, I will implement it. 🚀

I think the new DocumentTransform concept is definitely what we should do here! Can you please adjust this?

Fixed #8723 (comment)

website/src/pages/docs/custom-codegen/document-transform.mdx

n1ru4l · 2023-02-03T12:24:07Z

Hey @kazekyo, sorry for letting this PR untouched for so long. I just rebased your PR and I have some questions for you:

With the client-preset we are aiming for a relay-compiler-like experience. Features we want to implement there include the following:

fragment masking (done)
fragment arguments (pending)
operation document optimization (pending)

Our goal would be that all new projects using GraphQL Code Generator would pick the client-preset over other presets/plugin combinations.

This feature would kind of allow implementation fragment arguments and operation document optimization as you already pointed out. This is great as it would work nicely with this change 😍. See this client-preset artifact as an example.

Would you be interested in helping out by having fragment arguments and document optimization built into the client preset? Of course not part of this pull request!

Here is some more feedback that I noticed while playing around with it.

Right now it is impossible only possible to reference documentTransforms via a file.

// eslint-disable-next-line import/no-extraneous-dependencies
import { type CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: './src/yoga.ts',
  documents: ['src/**/*.ts'],
  generates: {
    './src/gql/': {
      plugins: [],
      preset: 'client-preset',
      documentTransforms: ['./foo.js'],
    },
  },
};

export default config;

Should we also allow inline functions?

// eslint-disable-next-line import/no-extraneous-dependencies
import { type CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: './src/yoga.ts',
  documents: ['src/**/*.ts'],
  generates: {
    './src/gql/': {
      plugins: [],
      preset: 'client-preset',
      documentTransforms: [{
        tarnsformDocuments() {}
      }],
    },
  },
};

export default config;

Let me know what you think!

…ql-code-generator into document_transform

kazekyo · 2023-02-04T10:23:52Z

@n1ru4l Thanks for reviewing this pull request!

Would you be interested in helping out by having fragment arguments and document optimization built into the client preset? Of course not part of this pull request!

Of course, I'd be happy to help! It seems that some of our goals overlap. 😃
Please guide me to the relevant issues, discussions, Discord threads, etc., to discuss these tasks.

As for this PR, I am unsure whether it can be used as part of your project or should be re-implemented in the client-preset. I'll keep developing it if it can be used, but if you have a different opinion, feel free to close it. 🙏

Should we also allow inline functions?

// eslint-disable-next-line import/no-extraneous-dependencies
import { type CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: './src/yoga.ts',
  documents: ['src/**/*.ts'],
  generates: {
    './src/gql/': {
      plugins: [],
      preset: 'client-preset',
      documentTransforms: [{
        tarnsformDocuments() {}
      }],
    },
  },
};

export default config;

It's great to allow inline functions. It would make it easier for users to experiment.

Just to confirm, Plugin cannot be written as inline functions, correct?

import { type CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: './src/yoga.ts',
  documents: ['src/**/*.ts'],
  generates: {
    './src/gql/': {
      plugins: [{
        plugin() {}
      }],
      preset: 'client-preset',
    },
  },
};

export default config;

Currently, I use Plugin to execute transformDocuments, so it would be necessary to allow Plugin to write functions inline. I think a separate pull request for this would be appropriate. 🤔
If we don't use Plugin for transformDocuments, I will implement it in this pull request! 💪

n1ru4l · 2023-02-16T15:41:29Z

Currently, #8723 (comment), so it would be necessary to allow Plugin to write functions inline. I think a separate pull request for this would be appropriate. 🤔
If we don't use Plugin for transformDocuments, I will implement it in this pull request! 💪

As discussed here: #8723 (comment), let's allow passing a function.

That would then allow you to do something like the following:

import { type CodegenConfig } from '@graphql-codegen/cli';
import { addTypenameFieldSelections, addIdFieldSelection, inlineFragments } from '@wherever'

const config: CodegenConfig = {
  schema: './src/yoga.ts',
  documents: ['src/**/*.ts'],
  generates: {
    './src/gql/': {
      preset: 'client',
      transformDocuments: [addTypenameFieldSelections, addIdFieldSelection, inlineFragments]
    },
  },
};

export default config;

n1ru4l

Sorry, for the delayed answer. I added some comments, I am excited to get this close to getting merged!

kazekyo · 2023-02-19T09:29:29Z

@n1ru4l
I have introduced the concept of Document Transform and made changes to enable document transformation without using plugins. 🎉
In addition, I implemented the addToSchema function to resolve #8724.
Please refer to the documentation for details on how to use it.

Regarding the designs, please let me know if you have any feedback on the following points:

documentTransforms is specified with objects and file names. It is also possible to implement a more simplified way of specifying it by directly writing the transform function, but I did not implement it as I did not need it. If you think it is necessary to make it more user-friendly, please let me know your feedback.

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      documentTransforms: [
        ({ documents }) => { // Specify only the function
          return documents;
        },
      ],
    },
  },
};
export default config;

The transform function and the addToSchema function have completely different required arguments depending on the case, so I am using destructured arguments to extract only the necessary arguments. Therefore, the addToSchema function has the same name as the function in the plugin, but the arguments are different. I chose to use the same function name to make it easier to understand how to use it, but if it causes confusion, I can change the function name to something like extendSchema.

If you notice anything else, please let me know. I'm confident the designs have improved through our discussions, and I welcome further feedback! 😃

n1ru4l · 2023-02-20T08:46:14Z

@kazekyo Can you give more context for the use case of addToSchema/extendSchema?

What is the use-case of coupling the schema transform with a specific document transform?

I think this is redundant with the following:

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: ['https://localhost:4000/graphql', `extend type Query { foo: String }`], // see here
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
    },
  },
};
export default config;

Would be happy, if we could immediately merge the already discussed stuff without the addToSchema part and then in a follow-up PR/issue discuss the necessity and use-cases for addToSchema. I want to ship the documentTransforms as soon as possible as we also want to use them. 😇

kazekyo · 2023-02-20T09:18:59Z

@n1ru4l

@kazekyo Can you give more context for the use case of addToSchema/extendSchema?

What is the use-case of coupling the schema transform with a specific document transform?

I think this is redundant with the following:
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: ['https://localhost:4000/graphql', `extend type Query { foo: String }`], // see here
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
    },
  },
};
export default config;

My use case is to implement Relay's __id. To do that, I need the addToSchema function which takes documents and schema as arguments. This is not possible with the current functionality. You can find more details in #8724.

Would be happy, if we could immediately merge the already discussed stuff without the addToSchema part and then in a follow-up PR/issue discuss the necessity and use-cases for addToSchema. I want to ship the documentTransforms as soon as possible as we also want to use them. 😇

If after reading the information I just provided, you still have additional discussion or questions regarding addToSchema, I will immediately remove addToSchema.
Afterward, I will either open another pull request or we can discuss further at #8724 if more discussion is needed!

n1ru4l · 2023-02-20T14:22:58Z

@kazekyo Let's keep addToSchema out of scope of this PR!

kazekyo · 2023-02-21T00:24:52Z

@n1ru4l I have removed addToSchema! 🚀

I don't think the failing test algolia/algolia-records-check is a problem with the code but please check it out if you need.

n1ru4l · 2023-02-21T08:54:32Z

Thank you @kazekyo 🎉

Add document transform. Document transform changes documents before e…

8f82a02

…xecuting plugins.

kazekyo added 2 commits December 12, 2022 19:22

Merge branch 'master' into document_transform

6b6e396

Create changesets

a0daebe

kazekyo marked this pull request as ready for review December 12, 2022 10:34

saihaj requested review from saihaj and n1ru4l December 12, 2022 22:04

n1ru4l reviewed Dec 18, 2022

View reviewed changes

.changeset/short-toes-relax.md Outdated Show resolved Hide resolved

n1ru4l reviewed Dec 18, 2022

View reviewed changes

packages/graphql-codegen-cli/tests/codegen.spec.ts Outdated Show resolved Hide resolved

kazekyo added 4 commits December 21, 2022 16:10

Rename documentTransformPlugins to documentTransforms

c9b298f

Add more information to changesets

175f437

Add document-transform.mdx

5a1e155

Fix the changeset

613dd93

saihaj requested a review from n1ru4l December 26, 2022 16:57

kazekyo added 6 commits February 3, 2023 12:42

Add document transform. Document transform changes documents before e…

e045aba

…xecuting plugins.

Create changesets

6d0d3bd

Rename documentTransformPlugins to documentTransforms

85adec5

Add more information to changesets

95d5710

Add document-transform.mdx

ed3ef46

Fix the changeset

f16fc4c

n1ru4l force-pushed the document_transform branch from 613dd93 to f16fc4c Compare February 3, 2023 11:42

n1ru4l reviewed Feb 3, 2023

View reviewed changes

website/src/pages/docs/custom-codegen/document-transform.mdx Outdated Show resolved Hide resolved

Merge branch 'document_transform' of https://github.com/kazekyo/graph…

d06ad5f

…ql-code-generator into document_transform

Remove validateBeforeTransformDocuments function to simplify API

483d1e5

kazekyo removed the request for review from saihaj February 12, 2023 08:13

kazekyo requested a review from n1ru4l February 12, 2023 08:13

n1ru4l requested changes Feb 16, 2023

View reviewed changes

kazekyo added 2 commits February 18, 2023 15:28

Merge branch 'master' into document_transform

6f57c11

Rewrite to not use plugin

64e8376

kazekyo requested a review from n1ru4l February 19, 2023 09:47

Remove addToSchema in document transform

2a8e14f

n1ru4l approved these changes Feb 21, 2023

View reviewed changes

n1ru4l changed the title ~~Add a feature to transform documents~~ transform documents hooks Feb 21, 2023

n1ru4l merged commit a3309e6 into dotansimha:master Feb 21, 2023

This was referenced Feb 21, 2023

Upcoming Release Changes #8909

Merged

Upcoming Release Changes danielo515/graphql-code-generator#243

Open

kazekyo deleted the document_transform branch February 22, 2023 06:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

transform documents hooks #8723

transform documents hooks #8723

kazekyo commented Dec 12, 2022 •

edited

Loading

changeset-bot bot commented Dec 12, 2022 •

edited

Loading

kazekyo commented Dec 12, 2022

kazekyo commented Dec 21, 2022

n1ru4l Feb 3, 2023 •

edited

Loading

kazekyo Feb 4, 2023

n1ru4l Feb 16, 2023

kazekyo Feb 19, 2023

n1ru4l commented Feb 3, 2023

kazekyo commented Feb 4, 2023

n1ru4l commented Feb 16, 2023 •

edited

Loading

n1ru4l left a comment

kazekyo commented Feb 19, 2023 •

edited

Loading

n1ru4l commented Feb 20, 2023 •

edited

Loading

kazekyo commented Feb 20, 2023

n1ru4l commented Feb 20, 2023

kazekyo commented Feb 21, 2023

n1ru4l commented Feb 21, 2023

transform documents hooks #8723

transform documents hooks #8723

Conversation

kazekyo commented Dec 12, 2022 • edited Loading

Description

Type of change

Screenshots/Sandbox (if appropriate/relevant):

How Has This Been Tested?

Checklist:

Further comments

About validation

About relay-operation-optimizer

changeset-bot bot commented Dec 12, 2022 • edited Loading

🦋 Changeset detected

kazekyo commented Dec 12, 2022

kazekyo commented Dec 21, 2022

n1ru4l Feb 3, 2023 • edited Loading

Choose a reason for hiding this comment

kazekyo Feb 4, 2023

Choose a reason for hiding this comment

n1ru4l Feb 16, 2023

Choose a reason for hiding this comment

kazekyo Feb 19, 2023

Choose a reason for hiding this comment

n1ru4l commented Feb 3, 2023

kazekyo commented Feb 4, 2023

n1ru4l commented Feb 16, 2023 • edited Loading

n1ru4l left a comment

Choose a reason for hiding this comment

kazekyo commented Feb 19, 2023 • edited Loading

n1ru4l commented Feb 20, 2023 • edited Loading

kazekyo commented Feb 20, 2023

n1ru4l commented Feb 20, 2023

kazekyo commented Feb 21, 2023

n1ru4l commented Feb 21, 2023

kazekyo commented Dec 12, 2022 •

edited

Loading

changeset-bot bot commented Dec 12, 2022 •

edited

Loading

n1ru4l Feb 3, 2023 •

edited

Loading

n1ru4l commented Feb 16, 2023 •

edited

Loading

kazekyo commented Feb 19, 2023 •

edited

Loading

n1ru4l commented Feb 20, 2023 •

edited

Loading