migueloller / graphql-utilities

Build GraphQL types using the schema language.

graphql-utilities

Inspired by graph.ql, graphql-tools, and graphql-helpers.

Why?

There are various libraries out there providing utilities for GraphQL and even the reference implementation itself is adding new utilities. So why do we need another one?

None of those libraries let you build GraphQL types using the schema language. This prevents gradual adoption of the tools and makes code separation and isolation a nightmare.

With graphql-utilities it's simple. build makes it extremely simple to build a GraphQL type.

build(`
  type Query {
    ok: Boolean!
  }
`);

/* is equivalent to */

new GraphQLObjectType({
  name: 'Query',
  fields: () => ({
    ok: { type: new GraphQLNonNull(GraphQLBoolean) },
  }),
})

Installation

npm install --save graphql-utilities

Getting Started

import { build } from 'graphql-utilities';

// you can build a type
const Record = build(`
  interface Record {
    id: ID!
  }
`);

// or you can build a schema
const Schema = build(`
  schema {
    query: Query
  }

  type Query {
    ok: Boolean!
  }
`);

TODO

• Add detailed API docs.
• Make build configuration interchangeable with types.
• Allow build to accept a flag to skip inferred schema.

License

MIT

graphql-utilities's Issues

Restructure `build` for building GraphQLSchema

There are various problems when trying to build a schema that make the API more confusing.

• Inferring a schema comes with the problem of it not being intuitive where build will check for the operations. Can they all be type dependencies? Do they all have to be in the AST?
• Schema must declare directives and types and these cannot be lazily evaluated, meaning that for this particular use case build wouldn't support thunks for type dependencies. This is inconsistent.
• Finally, because a GraphQL schema does not have a name, it's impossible to deterministically set the schema config via the config argument of build.

Perhaps it would be best to delegate schema creation to a separate function and use build only for types. While it adds an extra function it reduces complexity by separating concerns.

Add resolve function later

Would it be possible to provide an API to add the resolve functions onto the build output at a later point in time. I would prefer to keep my data type specification separate from the details of resolution.

Expose functionality for passing custom directives

buildSchema does seem to support it while, build doesn't

export default function buildSchema(schemaAST, { types, directives } = {}, typeDeps) {
...
}

Inferring a schema from a Query doesn't allow config shortcut

build(`
  type Query {
    status: Boolean!
  }
`, { status: () => true });

The code above will throw an error when attempting to query status.

Error messages for better developer experience

Warning the developer or throwing errors early (e.g, when passing undefined as a type dependency) can avoid many headaches.

Detailed API Docs

GraphQLInputObjectType default values aren't working for non-named types (i.e., GraphQLList)

This schema won't behave as expected. The default value for friends ends up being null.

input InsertUserInput {
  id: ID!
  name: String!
  friends: [ID!] = []
}

`mapNameToValue` for GraphQL enums

It would be useful to be able to apply a transform to enum values (e.g., camelcase)

Flow Type Annotations

Using Flow will greatly reduce various bugs and it should be easy to implement given that GraphQL.js is written with it.

GraphQL Custom Types

The next utility after build should be custom GraphQL types, mostly scalars, that facilitate validation. Potential types include GraphQLURL, GraphQLJSON, GraphQLEmail, GraphQLUnsignedInt, and many more!

Explore exporting buildType and buildSchema functions

build is very useful and convenient in that it can produce any number of types. Sometimes it might be inconvenient to get a type map though.

If we export the internal buildSchema and buildType functions then the developer could potentially use these to build a single type (or schema) and expect a GraphQLType or GraphQLSchema as an output instead of a map of those 2 things.

Would love to hear people's thoughts on adding these to the public API.

Add support for imports

We should add support to import files from .graphql files. You could import another .graphql file or a .js file that has a build config for it.

Integration Tests

To ensure we're catching edge cases for most use cases we should have an integration test suite.