generate-graphql-code

generate-graphql-code

Generate TypeScript code from GraphQL introspection.

This module will do the following for you:

• Generate all types found in the schema.
• Generate a factory function which you can use to create your GraphQL client.

To get started, checkout the example directory or take a look at the generated files.

Table of contents:

• Installation
• Preview
• Usage
• Configuration file format
• How to get introspection?

Installation

# with pnpm
pnpm i generate-graphql-code -D

# or with npm
npm i generate-graphql-code --save-dev

Preview

In the following preview, the client is created with the factory function generated by generate-graphql-code.

When creating your GraphQL client with the factory function, you can use the generate-query module to convert the parameters to GraphQL code that you will send to the server. For more details, please check the example file.

Usage

With the command:

npx generate-graphql-code --config ./config.json

An example configuration file:

{
  "files": [
    {
      "filename": "./graphql/example-introspection.json",
      "output": "./generated/example.ts"
    },
    {
      "endpoint": { "url": "https://countries.trevorblades.com/" },
      "output": "./generated/countries.ts"
    }
  ]
}

Or you can use the generate function programmatically:

import generate from 'generate-graphql-code'

generate({
  files: [
    {
      filename: './graphql/example-introspection.json',
      output: './generated/example.ts'
    },
    {
      endpoint: { url: 'https://countries.trevorblades.com/' },
      output: './generated/countries.ts'
    }
  ]
})

Configuration file format

export interface ConfigurationFile {
  /**
   * Global options. Default options for every schema files.
   */
  options?: Options

  /**
   * Schema files.
   */
  files?: SchemaFile[]
}

export interface SchemaFile {
  /**
   * The output path of the generated typescript file.
   * The path is relative the configuration file.
   */
  output: string

  /**
   * The filename of the schema introspection json file.
   * The path is relative the configuration file.
   */
  filename?: string

  /**
   * The endpoint to fetch the schema. If `filename` is defined,
   * `endpoint` will be ignored.
   */
  endpoint?: {
    /**
     * The url to fetch schema.
     */
    url: string

    /**
     * The headers to add when requesting schema.
     */
    headers?: Record<string, any>

    /**
     * Path to a json file. The json value will be used as `headers`.
     * The path is relative the configuration file.
     */
    headersFile?: string
  }

  /**
   * The options of the current schema file. If a option of `options` is
   * not set or set to `null`, the corresponding option in global options
   * will be used.
   */
  options?: Options

  /**
   * By default, `options.scalarTypes` will extend the `scalarTypes`
   * defined in the global options. You can set `skipGlobalScalarTypes`
   * to avoid this.
   */
  skipGlobalScalarTypes?: boolean

  /**
   * Skip this file.
   */
  skip?: boolean
}

export interface Options {
  /**
   * Specify scalar type mapping. The default mapping is:
   *
   * - Int: number
   * - Float: number
   * - String: string
   * - Boolean: boolean
   * - ID: string
   *
   * Example value:
   *
   * - `{ "Int": "number", "ID": "string" }`
   * - `[ ["Int", "number"], ["ID", "string"] ]`
   *
   * If the a scalar type is not specified, it will be mapped to `unknown`.
   */
  scalarTypes?: Record<string, string> | [string, string][]

  /**
   * The suffix of args types. Default: "Args".
   */
  argsSuffix?: string

  /**
   * The suffix of fields types. Default: "Fields".
   */
  fieldsSuffix?: string

  /**
   * Skip generating comments for disabling lint.
   */
  skipLintComments?: boolean

  /**
   * Skip generating warning tip.
   */
  skipWarningTip?: boolean

  /**
   * Skip wrapping enum in the args as `{ $enum: EnumType }`.
   */
  skipWrappingArgsEnum?: boolean

  /**
   * Skip generating `xxxArgs` types. If this option is
   * `true`, the factory function will not be generated too.
   */
  skipArgs?: boolean

  /**
   * Skip generating `xxxFields` types. If this option is
   * `true`, the factory function will not be generated too.
   */
  skipFields?: boolean

  /**
   * Skip generating factory function.
   */
  skipFactory?: boolean

  /**
   * Skip generating query method.
   */
  skipQuery?: boolean

  /**
   * Skip generating queries object.
   */
  skipQueries?: boolean

  /**
   * Skip generating mutation method.
   */
  skipMutation?: boolean

  /**
   * Skip generating mutations object.
   */
  skipMutations?: boolean

  /**
   * The file headers.
   */
  headers?: string[]

  /**
   * The file footers.
   */
  footers?: string[]
}

How to get introspection?

Open your GraphiQL page, paste the following GraphQL code to query the introspection:

query IntrospectionQuery {
  __schema {
    queryType {
      name
    }
    mutationType {
      name
    }
    subscriptionType {
      name
    }
    types {
      ...FullType
    }
    directives {
      name
      description
      locations
      args {
        ...InputValue
      }
    }
  }
}

fragment FullType on __Type {
  kind
  name
  description
  fields(includeDeprecated: true) {
    name
    description
    args {
      ...InputValue
    }
    type {
      ...TypeRef
    }
    isDeprecated
    deprecationReason
  }
  inputFields {
    ...InputValue
  }
  interfaces {
    ...TypeRef
  }
  enumValues(includeDeprecated: true) {
    name
    description
    isDeprecated
    deprecationReason
  }
  possibleTypes {
    ...TypeRef
  }
}

fragment InputValue on __InputValue {
  name
  description
  type {
    ...TypeRef
  }
  defaultValue
}

fragment TypeRef on __Type {
  kind
  name
  ofType {
    kind
    name
    ofType {
      kind
      name
      ofType {
        kind
        name
        ofType {
          kind
          name
          ofType {
            kind
            name
            ofType {
              kind
              name
              ofType {
                kind
                name
              }
            }
          }
        }
      }
    }
  }
}