Dynamic extension of types

[kazekyo]

UPDATED: Document Transform has been released and I have reorganized and rewritten this post.

Purpose

When a tool (or user) adds a local-only field to GraphQL documents, I want it to give codegen the type information for that field to automatically treat it as type-safe.

Background

It is already possible to define a schema for local-only fields, as shown below:

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

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

However, users must manually add the necessary types to the schema. I want the tool to automatically add the type to the schema when a specific directive is included in documents or when a specific type is present in the schema.

Main Use Case

My use case is for implementing something like Relay's __id. The __id is a unique identifier assigned to a Connection when a user is using it, which is then used as a cache key when adding or removing elements from that Connection.

In my implementation, if a @pagination directive (an alias for @connection) is present in documents, a _connectionId (an alias for __id) type is added to a SomethingConnection.

extend type SomethingConnection {
  _connectionId: String!
}

Both documents and schema are required to generate the schema for this tool.

More generally, use cases involve adding local-only fields when a directive is used.
For example, assuming that there is a @iconInfo directive.

query MyQuery {
  user @iconInfo {
    id
    name
  }
}

And there is a document transform that automatically adds an iconUrl field and an iconDownloaded field when the @iconInfo directive is included, resulting in the following document:

query MyQuery {
  user {
    id
    name
    iconUrl # Added by the document transform
    iconDownloaded @client # Added by the document transform
  }
}

In this case, I want to add the type for the local-only field iconDownloaded automatically. However, although the field is automatically added by the document transform, the schema information must be manually added by the user, which is inconvenient.

Proposal of API

Several methods are possible.

Extending the schema field

To be able to add a function to the schema field that is executed after the documents and schema are read.

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

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

However, this will not work with YAML. It is also possible to specify the function's file name, but this may not be the best idea due to implementation complexity and user-friendliness because there are already many ways to specify strings. Also, users may not understand the order of loading, since this function must be executed after the loading of the other schemas.

Adding addToSchema to Document Transform

As far as I understand use cases, adding addToSchema to Document Transform seems reasonable as many use cases are closely related to Document Transform. Since plugins already have addToSchema, it should be easy to understand.

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

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

Document Transform can also be specified in YAML using file names.

Creating Schema Transform

It is possible to create a Schema Transform similar to Document Transform.

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

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

This mechanism is powerful as it allows not only adding types but also editing or deleting types in the schema. However, it may be over-engineering.

My opinion

Considering the necessary use cases at present, I think adding addToSchema to Document Transform is a good option.

[kazekyo]

@n1ru4l Please let me know if you have any feedback. 🙏
I will submit a pull request with addToSchema added again in a few days.