graphql-codegen-generators

graphql-code-generators

This packages includes the built-in generators for GraphQL Codegen.

Currently includes:

• TypeScript single file
• TypeScript multiple files

Build process

The build process of this package is based on Webpack with awesome-typescript-loader to compile TypeScript source code, and raw-loader to load the handlebars templates as string.

The purpose of the build process is to eliminate the need to use fs.readFile for the template files, and integrate the template files into the compiles JS files as strings.

To build this package and the generators template, start by installing the package dependencies:

   $ npm install
   // Or, with Yarn
   $ yarn

Then, you can use the existing NPM scripts to build the package:

    $ npm run build
    // Or, with Yarn
    $ yarn build

Adding a new generator

To add a new generator, start by adding a new directory under ./src/ of this directory, with the name of the generator.

Then, create a file called config.ts.

Your config file should use default export, and export a config variable that implements the GeneratorConfig interface, for example:

import { EInputType, GeneratorConfig } from '../types';

const config: GeneratorConfig = {
  inputType: EInputType.MULTIPLE_FILES,
  templates: {
    // Your templates here
  },
  flattenTypes: true,
  primitives: {
    String: 'string',
    Int: 'number',
    Float: 'number',
    Boolean: 'boolean',
    ID: 'string'
  },
};

export default config;

Next, make sure to import your template files and add them to your templates, for example:

import * as index from './template.handlebars';
import * as type from './type.handlebars';
import * as schema from './schema.handlebars';
import * as documents from './documents.handlebars';
import * as selectionSet from './selection-set.handlebars';
import { EInputType, GeneratorConfig } from '../types';

const config: GeneratorConfig = {
  inputType: EInputType.SINGLE_FILE,
  templates: {
    index,
    type,
    schema,
    documents,
    selectionSet,
  },
  flattenTypes: true,
  primitives: {
    String: 'string',
    Int: 'number',
    Float: 'number',
    Boolean: 'boolean',
    ID: 'string'
  },
  outFile: 'types.d.ts',
};

export default config;

inputType

Allowed values: EInputType.SINGLE_FILE, EInputType.MULTIPLE_FILES

inputType defined the template input type of the generator, and also declares the generator output.

For example, we have TypeScript generators for both single and multiple files.

The input type field effects the rest of the fields:

SINGLE_FILE

When using SINGLE_FILE, you must specify the main template name, with a key called index, and this will be the root of your app.

You also need to specify the outFile of the package, which is the default file name in case of output filename was not specified through the CLI.

MULTIPLE_FILES

When using MULTIPLE_FILES, you need to specify a template for each available compilation context (refer to templates section for the list of available contexts).

You also need to specify the filesExtension for the generated files.

templates

templates field should contains an object, where the key is the name of the template, and the value is a string.

There are special context types for templates, and each type of templates will compile with a different context:

• index: use with SINGLE_FILE to declare the main entry point of the generated file, compiled with a merged object, containing all SchemaTemplateContext and Document fields.
• type: use with MULTIPLE_FILES to declare that this template belongs to GraphQL schema type, this template will compile with each type in your schema.
• inputType: use with MULTIPLE_FILES to declare that this template belongs to GraphQL schema input, this template will compile with each input type in your schema.
• union: use with MULTIPLE_FILES to declare that this template belongs to GraphQL schema union, this template will compile with each union in your schema.
• scalar: use with MULTIPLE_FILES to declare that this template belongs to GraphQL schema scalar, this template will compile with each scalar in your schema.
• enum: use with MULTIPLE_FILES to declare that this template belongs to GraphQL schema enum, this template will compile with each enum in your schema.
• interface: use with MULTIPLE_FILES to declare that this template belongs to GraphQL schema interface, this template will compile with each interface in your schema.
• operation: use with MULTIPLE_FILES to declare that this template belongs to GraphQL operation (query/mutation/subsription), this template will compile with Operation context.
• fragment: use with MULTIPLE_FILES to declare that this template belongs to GraphQL fragment, this template will compile with Fragment context.
• schema: use with MULTIPLE_FILES to compile with SchemaTemplateContext.
• documents: use with MULTIPLE_FILES to compile with all operations, the context will be Document.
• all: same as to index.

Also, all templates specified under templates will be loaded as Handlebars template partials, so you can use it any time inside other templates, for example, the following templates definitions:

const config = {
  // ... 
  templates: {
    index: '{{>selectionSet}}',
    selectionSet: 'Hello',
  },
  // ... 
};

The index template loads selectionSet template, and it can also provide a context for the specific partial:

const config = {
  // ... 
  templates: {
    index: '{{>selectionSet types}}',
    selectionSet: '{{#each this }} Type name: {{ name }}{{/each}}',
  },
  // ... 
};

You can also load a template from itself, and create a recursive generation of the template.

flattenTypes

Type flattening is a useful feature when generation a template, when true is specified, the generator will return a flatten version of the GraphQL selection set when using inner types.

For example, let's take a look in the following GraphQL schema and query:

type NameFields {
    firstName: String
    lastName: String
}

type User {
    name: NameFields
    email: String
    age: Int
}

type Query {
    me: User
}

schema {
    query: Query
}

query myQuery {
  user {
    me {
      firstName
      lastName
    }
  }
}

This query uses multiple levels of selection set (user > name > firstName), but when adding flattenTypes: true, the generator will append a new field to the operation/fragment context, called innerModels, and it this case it will contains the following:

[
    {
        schemaBaseType: 'User',
        modelType: 'Me',
        fields: [ ... ] // Original SelectionSetFieldNode from the operation
        // .. more fields
    },
    {
        schemaBaseType: 'NameFields',
        modelType: 'Name',
        fields: [ ... ] // Original SelectionSetFieldNode from the operation
        // .. more fields
    }
]

So the two available levels of selection set were flatten into a single level, so you can generate you whole selection set in a single iteration.

The modelType becomes the name of the selection set field, because we use only part of the available fields (for example, the query only asks for part of the User fields), so we can't use the actual GraphQL type from the schema - so each selection set creates new "types", and the usage in the selection set also changes, so the type of me is not User - it's Me.

The actual compilation context when using flattenTypes: true is available here.

primitives

Specify primitives object map to replace the original GraphQL built-in types to a language-specific primitives.

For example, GraphQL type of String is actually a string in TypeScript.

outFile

Use with SINGLE_FILE, specify the default filename for the generated file.

filesExtension

Use with MULTIPLE_FILES, specify the file extension for the generated files.

customHelpers

With customHelpers you can add custom helpers that executes with your custom templates.

Provide an object with key as the name of the helper, and a Function for the helper execution.