GraphQL Artisan
Type safe GraphQL query generator for TypeScript. Works with
typescript@>=3.0
.
Installation
npm install graphql graphql-artisan
Usage
The library comes with a CLI that allows converting the GraphQL schema into a TypeScript GraphQL query generator API. Currently only .graphql
schema files are supported, but support for introspection JSON and GraphQL server endpoints is to be added later.
To convert a schema file into typescript, simply run:
graphql-artisan input.graphql output.ts
The output will also depend on the graphql-artisan
and graphql
libraries and can be imported to your program for dynamic query generation.
Examples
All the examples below are written using the following schema:
type User { id: ID! name: String! age: Int }interface Message { id: ID! createdBy: ID! title: String! }type Headline implements Message { id: ID! createdBy: ID! title: String! tags: [String] }type Article implements Message { id: ID! createdBy: ID! title: String! content: String }input UserEdit { id: ID! name: String age: Int } type Query { user(id: ID!): User userMessages(id: ID): [Message!]!}type Mutation { updateUser(user: UserEdit!): User}schema { query: Query mutation: Mutation}
Simple queries
You can create anonymous queries with a simple syntax:
schema.query.select Query.user.select User.id, User.name ;
This can be serialized into the following GraphQL query:
{ user(id: "123") { id name }}
This might not seem very interesting, but notice that you can also generate queries like this:
schema.query.selectusers1, 2, 3;
The query above will be serialized as:
{ user1: user(id: 1) { id name } user2: user(id: 2) { id name } user3: user(id: 3) { id name }}
All without any ugly string concatenations or unsafe operations.
Named queries
Just like above, you can also name your queries, which is required to be able to add directives:
schema.query"queryName".select Query.user.select User.id, User.name ;
The query name will be added to the serialized query as expected:
query queryName { user(id: "123") { id name }}
Queries with directives
Because @
sign is not allowed in JavaScript/TypeScript names, $
is used instead for directives. You can for example write the following query:
schema.query.select Query.user.select User.id$skip, User.name ;
It will result in the following query:
{ user(id: "123") { id @skip(if: true) name }}
Queries containing interfaces
If the query requires selecting an interface and you only want to select its interface fields, you can write the query as expected:
schema.query.select Query.userMessages.select Message.id, Message.createdBy, Message.title ;
The serialized version has no surprises either:
{ userMessages(id: "123") { id createdBy title }}
However, if you want to also query for some fields that implement that interface, you need to be able to use fragments. Don't worry, this is not difficult either:
schema.query.select Query.userMessages.select Message.id, Message.createdBy, Message.title, Headline$InlineFragment.select Headline.tags , Article$InlineFragment.select Article.content ;
The inline fragments will now be serialized into the query as specified:
{ userMessages(id: "123") { id createdBy title ... on Headline { tags } ... on Article { content } }}
Mutations
Mutations work just like queries and the arguments are also typed as expected. If doing multiple mutations you can also always rely that the order of the selections in code is the same as in the resulting query. An example mutation could go like this:
schema.mutation"mutationName".select Mutation.updateUser.select User.id, User.name ;
You will then get your mutation as a GraphQL query string when serialized:
mutation mutationName { updateUser(user: {id: "123", name: "John Doe"}) { id name }}
License
MIT