gqlc

GraphQL IDL Compiler

gqlc is a compiler for the GraphQL IDL, as defined by the GraphQL spec. Current spec implementation: Current Working Draft

Table of Contents

• Getting Started
  • Installing
  • Compiling Your First Schema
• Support Languages
• Design
  • IDL packages
  • Code generation
• Contributing
  • Getting Started
    • Guidelines
    • Code Generators
• WIP

Getting Started

This section gives a brief intro to using gqlc.

Installing

You can either git clone this repo and build from source or download one of the prebuilt releases.

Compiling Your First Schema

To begin, lets use an abbreviated version of the schema used in the examples at graphql.org:

schema {
  query: Query,
  mutation: Mutation
}

type Query {
  "hero returns a character in an episode"
  hero(episode: Episode): Character
}

type Mutation {
  """
  addCharacter adds a new Character given their name and the episodes they appeared in.
  """
  addCharacter(name: String!, episodes: [Episode!]!): Character
}

"Episode represents the episodes of the Star Wars saga."
enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

"Character represents a character in any episode of Star Wars."
type Character {
  name: String!
  appearsIn: [Episode]!
}

Now, that we have the schema for our GraphQL service it's time to start implementing it. Typically, when implementing a GraphQL service you're thinking in terms of the IDL, but not writing in it; instead, you're writing in whatever language you have chosen to implement your service in. This is where gqlc comes in handy, by providing you with a tool that can "compile", or translate, your IDL definitions into source code definitions. To accomplish this, simply type the following into your shell:

gqlc --js_out . --doc_out . schema.gql

gqlc will then generate two files:

schema.js: The js generator will output Javascript types for the schema.

var {
  GraphQLSchema,
  GraphQLObjectType,
  GraphQLEnumType,
  GraphQLList,
  GraphQLNonNull,
  GraphQLString
} = require('graphql');

var Schema = new GraphQLSchema({
  query: Query,
  mutation: Mutation
});

var EpisodeType = new GraphQLEnumType({
  name: 'Episode',
  values: {
    NEWHOPE: {
      value: 'NEWHOPE'
    },
    EMPIRE: {
      value: 'EMPIRE'
    },
    JEDI: {
      value: 'JEDI'
    }
  }
});

var QueryType = new GraphQLObjectType({
  name: 'Query',
  fields: {
    hero: {
      type: Character,
      args: {
        episode: {
          type: Episode
        }
      },
      resolve() { /* TODO */ }
    }
  }
});

var MutationType = new GraphQLObjectType({
  name: 'Mutation',
  fields: {
    addCharacter: {
      type: Character,
      args: {
        name: {
          type: new GraphQLNonNull(GraphQLString)
        },
        episodes: {
          type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(Episode)))
        }
      },
      resolve() { /* TODO */ }
    }
  }
});

var CharacterType = new GraphQLObjectType({
  name: 'Character',
  fields: {
    name: {
      type: new GraphQLNonNull(GraphQLString),
      resolve() { /* TODO */ }
    },
    appearsIn: {
      type: new GraphQLNonNull(new GraphQLList(Episode)),
      resolve() { /* TODO */ }
    }
  }
});

schema.md: The doc generator will output CommonMark documentation for the schema.

# Documentation
*This was generated by gqlc.*

## Table of Contents
- [Schema](#Schema)
- [Objects](#Objects)
	* [Character](#Character)
	* [Mutation](#Mutation)
	* [Query](#Query)
- [Enums](#Enums)
	* [Episode](#Episode)

## Schema

*Root Operations*:
- query **([Query](#Query))**
- mutation **([Mutation](#Mutation))**

## Objects

### Character
Character represents a character in any episode of Star Wars.

*Fields*:
- name **(String!)**
- appearsIn **([[Episode](#Episode)]!)**

### Mutation

*Fields*:
- addCharacter **([Character](#Character))**

	  addCharacter adds a new Character
	*Args*:
	- name **(String!)**
	- episodes **([[Episode](#Episode)!]!)**

### Query

*Fields*:
- hero **([Character](#Character))**

	hero returns a character in an episode

	*Args*:
	- episode **([Episode](#Episode))**

## Enums

### Episode
Episode represents the episodes of the Star Wars saga.

*Values*:
- NEWHOPE
- EMPIRE
- JEDI

Now, all you have to do is fill in the resolvers and plug it into an http endpoint. All generators and the compiler, itself, support options to tweak the output.

Supported Languages

The currently supported languages by gqlc for generation are:

• Documentation (example)
• Go (example)
• Javascript (example)

Note: There will most likely be more to come. Check out the Code Generators section for more on this.

Design

The overall design of the compiler is heavily influenced by Google's Protocol Buffer compiler.

IDL Pacakges

Overall structure and "connected-ness" is heavily influenced by Go's go package for working with Go source files. The lexer and parser are implemented following the text/template/parse package and Rob Pike's talk on "Lexical Scanning in Go". The source for the lexer and parser can be found here: graphql

Code Generation and CLI

The code generation and CLI designs were both pulled from Google's Protocol Buffer compiler, in order to allow for extensibility and ease of maintainability. The source for internal compiler details and cli interfaces can be found here: compiler

Contributing

Thank you for wanting to help keep this project awesome!

Before diving straight into the WIP list or issues, here are a few things to help your contribution be accepted:

Guidelines

When making any sort of contribution remember to follow the Contribution guidelines.

Code Generators

Not every language can be supported directly, so please first create an issue and discuss adding support for your language there. If the community shows enough consensus that your language should be directly supported, then a @gqlc team member will initialize the repository for it and work can commence on implementing it.

If your desired language doesn't show enough support from the community to deem direct support in gqlc, then implementing a plugin is highly encouraged. Check out compiler/plugin for more information on how plugins are expected to behave when interacting with gqlc.

WIP

This is all current work desired to be completed in order to release v1.

• gqlc (cmd)
  • generator options flag
  • Plugin generator (plugin)
• Documentation generator (doc)
• Go generator (golang)
• Javascript generator (js)
• compiler
  • type checking
  • import resolution
• graphql
  • ast
  • lexer
  • parser
  • token