Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gqlc/gqlc
GraphQL IDL Compiler
https://github.com/gqlc/gqlc
go graphql graphql-idl-compiler graphql-schema graphql-tools javascript
Last synced: 3 months ago
JSON representation
GraphQL IDL Compiler
- Host: GitHub
- URL: https://github.com/gqlc/gqlc
- Owner: gqlc
- License: mit
- Created: 2018-11-08T01:21:26.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2023-01-23T05:28:14.000Z (almost 2 years ago)
- Last Synced: 2024-09-28T21:41:17.774Z (3 months ago)
- Topics: go, graphql, graphql-idl-compiler, graphql-schema, graphql-tools, javascript
- Language: Go
- Homepage:
- Size: 470 KB
- Stars: 24
- Watchers: 6
- Forks: 1
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-ccamel - gqlc/gqlc - GraphQL IDL Compiler (Go)
- awesome-list - gqlc
README
[](https://godoc.org/github.com/gqlc/gqlc)
[](https://goreportcard.com/report/github.com/gqlc/gqlc)
[](https://codecov.io/gh/gqlc/gqlc)
# GraphQL Compiler
`gqlc` is a compiler for the GraphQL IDL, as defined by the [GraphQL spec](http://facebook.github.io/graphql).
Current spec implementation: [Current Working Draft](https://graphql.github.io/graphql-spec/draft/)
# Table of Contents
- [Getting Started](#getting-started)
* [Installing](#installing)
* [Compiling Your First Schema](#compiling-your-first-schema)
- [Supported Languages](#supported-languages)
- [Contributing](#contributing)
* [Guidelines](#guidelines)
* [Code Generators](#code-generators)
## Getting Started
This section gives a brief intro to using gqlc. For more information, check the
docs at [gqlc.dev](https://gqlc.dev).
### Installing
You can either `git clone` this repo and build from source or download one of the prebuilt [releases](https://github.com/gqlc/gqlc/releases).
### Compiling Your First Schema
To begin, lets use an abbreviated version of the schema used in the examples at [graphql.org](https://graphql.org/learn/schema/):
```graphql
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:
```bash
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.
```javascript
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.
```commonmark
# 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](https://commonmark.org) ([example](https://gqlc.dev/generators/documentation.html))
* [Go](https://golang.org) ([example](https://gqlc.dev/generators/go.html))
* [Javascript](https://javascript.com) ([example](https://gqlc.dev/generators/javascript.html))
## 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](https://github.com/gqlc/gqlc/blob/master/CONTRIBUTING.md).
#### 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](https://gqlc.dev/plugin/) for more information on how plugins are expected to behave when interacting with gqlc.