@micimize/graphql-codegen-generators
v0.9.0-alpha.1
Published
GraphQL code generator predefined templates
Downloads
1
Readme
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:
$ yarn 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.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 withSINGLE_FILE
to declare the main entry point of the generated file, compiled with a merged object, containing allSchemaTemplateContext
andDocument
fields.type
: use withMULTIPLE_FILES
to declare that this template belongs to GraphQL schematype
, this template will compile with each type in your schema.inputType
: use withMULTIPLE_FILES
to declare that this template belongs to GraphQL schemainput
, this template will compile with each input type in your schema.union
: use withMULTIPLE_FILES
to declare that this template belongs to GraphQL schemaunion
, this template will compile with each union in your schema.scalar
: use withMULTIPLE_FILES
to declare that this template belongs to GraphQL schemascalar
, this template will compile with each scalar in your schema.enum
: use withMULTIPLE_FILES
to declare that this template belongs to GraphQL schemaenum
, this template will compile with each enum in your schema.interface
: use withMULTIPLE_FILES
to declare that this template belongs to GraphQL schemainterface
, this template will compile with each interface in your schema.operation
: use withMULTIPLE_FILES
to declare that this template belongs to GraphQL operation (query
/mutation
/subsription
), this template will compile withOperation
context.fragment
: use withMULTIPLE_FILES
to declare that this template belongs to GraphQLfragment
, this template will compile withFragment
context.schema
: use withMULTIPLE_FILES
to compile withSchemaTemplateContext
.documents
: use withMULTIPLE_FILES
to compile with all operations, the context will beDocument
.all
: same as toindex
.
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.