GraphQL 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
• Supported Languages
• Contributing
  • Guidelines
  • Code Generators

Getting Started

This section gives a brief intro to using gqlc. For more information, check the docs at gqlc.dev.

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)

Contributing

Thank you for wanting to help keep this project awesome!

Before diving right in, 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 the plugin docs for more information on how plugins are expected to behave when interacting with gqlc.