v0.1.0

[migueloller]

We're going to start to implement the changes required to release v0.1.0 so I'm opening this PR to keep track of the progress.

Goals

With v0.1.0 we plan to make the first official release of graphql-utilities. Here are the goals of this release:

• Provide the ability yo build any GraphQL.js construct using the schema language.
• Enforce a convention that if it can be built using the schema language, then it should be built using the schema language. (e.g., the deprecation reason should be passed via the @deprecated directive and not the config object)
• Maintain full feature parity with the changes suggested in [RFC] GraphQL Schema Definition Language (SDL) graphql/graphql-spec#90.

Features

The main features to be supported are:

• Ability to build GraphQLSchema. The schema will be inferred if the default root types are named appropriately as required by the spec.
• Ability to build GraphQLScalar. It will be possible to build a new scalar using a previous GraphQLScalar as a starting point (this is currently implemented).
• Ability to build GraphQLObject. It will be possible to shortcut field resolve functions to minimize boilerplate (this is currently implemented).
• Ability to build GraphQLInterface. It will share the similar resolve shortcut as GraphQLObject (this is currently implemented).
• Ability to build GraphQLUnion.
• Ability to build GraphQLEnum. By default, it will use the field names as their values. It will also allow to pass a function to map field names to values.
• Ability to build GraphQLInputObject.
• Ability to build types using type extensions.
• Ability to build GraphQLDirective.

API

The API will expose the following functions:

• buildSchema
• buildType
• buildDirective
• build
• extend

buildSchema, buildType, buildDirective, and extend will all return GraphQL.js objects. build will return a map of these objects with their names as keys. For schema (which don't have a name), the key __schema will be used due to it being an invalid GraphQL name and it already being used for GraphQL introspection.

To Do

• Implement new changes to the API.
• Add Flow types.
• Comment the source code.
• Refactor some of the functions to be organized parallel to GraphQL AST definitions.
• Implement SWAPI integration tests.
• Add detailed API docs.
• Implement detailed error messages.

This PR resolves #2, #3, #4, #5, #6, #7, #8, #10 and #13.

[migueloller]

I accidentally closed the PR by force pushing the branch after removing all commits.

[coveralls]

Coverage remained the same at 100.0% when pulling 2ab639e on v0.1.0 into aee4754 on master.

[coveralls]

Coverage remained the same at 100.0% when pulling 30c4948 on v0.1.0 into aee4754 on master.

[coveralls]

Coverage remained the same at 100.0% when pulling d40858d on v0.1.0 into aee4754 on master.

[jakelacey2012]

I'm interested in this, excuse my naivety but how does this differ to using makeExecutableSchema from apollo?

[migueloller]

@jakelacey2012, great question!

The main difference from Apollo's makeExecutableSchema is that you can only make a schema and that's it. With graphql-utilities you can build intermediate GraphQL.js types. This is desirable for a couple of raesons. First, you can gradually adopt this library by simply changing some of your types to use it and keeping some other types without it. Also, it could be used by any other library builders that are building custom types - it's simply a more terse way of making GraphQL.js types. Finally, it lets you isolate your types in a way that makes sense. With Apollo you normally have your resolvers and type definitions in separate directories (if you keep them in the same you have to do import gymnastics), but logically you would want resolvers of your User type to live together with the type definition. With graphql-utilities you can have your types live in a single file, or you could even have a directory structure like this:

types/
  |-- User/
  |    |- User.graphql
  |    |- User.js
  |-- Comment/
  |    |- ...
  `-- Post/
       `- ...

Where your schema definition lives in the *.graphql files and then your JS lives in the *.js files. You could really have any structure you want.

Anyway, in summary, the goal is to let you build GraphQL.js types (not just schema) in a more terse way.