graphql-artisan

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({ id: "123" }).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:

function users(...userIds: number[]) {
  return userIds.map(id =>
    Query.user({ id }).select(
      User.id(),
      User.name()
    ).as(`user${id}`)
  );
}
schema.query().select(users(1, 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({ id: "123" }).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({ id: "123" }).select(
    User.id($skip({ if: true })),
    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({ id: "123" }).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({ id: "123" }).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({
    user: {
      id: "123",
      name: "John Doe"
    }
  }).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