UNPKG

4.13 kBMarkdownView Raw
1# GraphQL-tools: generate and mock GraphQL.js schemas
2
3[![npm version](https://badge.fury.io/js/graphql-tools.svg)](https://badge.fury.io/js/graphql-tools)
4[![Build Status](https://travis-ci.org/apollographql/graphql-tools.svg?branch=master)](https://travis-ci.org/apollographql/graphql-tools)
5[![Coverage Status](https://coveralls.io/repos/github/apollographql/graphql-tools/badge.svg?branch=master)](https://coveralls.io/github/apollographql/graphql-tools?branch=master)
6[![Get on Slack](https://img.shields.io/badge/slack-join-orange.svg)](http://www.apollostack.com/#slack)
7
8This package provides a few useful ways to create a GraphQL schema:
9
101. Use the GraphQL schema language to [generate a schema](https://www.apollographql.com/docs/graphql-tools/generate-schema.html) with full support for resolvers, interfaces, unions, and custom scalars. The schema produced is completely compatible with [GraphQL.js](https://github.com/graphql/graphql-js).
112. [Mock your GraphQL API](https://www.apollographql.com/docs/graphql-tools/mocking.html) with fine-grained per-type mocking
123. Automatically [stitch multiple schemas together](https://www.apollographql.com/docs/graphql-tools/schema-stitching.html) into one larger API
13
14## Documentation
15
16[Read the docs.](https://www.apollographql.com/docs/graphql-tools/)
17
18## Binding to HTTP
19
20If you want to bind your JavaScript GraphQL schema to an HTTP server, we recommend using [Apollo Server](https://github.com/apollographql/apollo-server/), which supports every popular Node HTTP server library including Express, Koa, Hapi, and more.
21
22JavaScript GraphQL servers are often developed with `graphql-tools` and `apollo-server-express` together: One to write the schema and resolver code, and the other to connect it to a web server.
23
24## Example
25
26[See and edit the live example on Launchpad.](https://launchpad.graphql.com/1jzxrj179)
27
28When using `graphql-tools`, you describe the schema as a GraphQL type language string:
29
30```js
31
32const typeDefs = `
33type Author {
34 id: ID! # the ! means that every author object _must_ have an id
35 firstName: String
36 lastName: String
37 """
38 the list of Posts by this author
39 """
40 posts: [Post]
41}
42
43type Post {
44 id: ID!
45 title: String
46 author: Author
47 votes: Int
48}
49
50# the schema allows the following query:
51type Query {
52 posts: [Post]
53}
54
55# this schema allows the following mutation:
56type Mutation {
57 upvotePost (
58 postId: ID!
59 ): Post
60}
61
62# we need to tell the server which types represent the root query
63# and root mutation types. We call them RootQuery and RootMutation by convention.
64schema {
65 query: Query
66 mutation: Mutation
67}
68`;
69
70export default typeDefs;
71```
72
73Then you define resolvers as a nested object that maps type and field names to resolver functions:
74
75```js
76const resolvers = {
77 Query: {
78 posts() {
79 return posts;
80 },
81 },
82 Mutation: {
83 upvotePost(_, { postId }) {
84 const post = find(posts, { id: postId });
85 if (!post) {
86 throw new Error(`Couldn't find post with id ${postId}`);
87 }
88 post.votes += 1;
89 return post;
90 },
91 },
92 Author: {
93 posts(author) {
94 return filter(posts, { authorId: author.id });
95 },
96 },
97 Post: {
98 author(post) {
99 return find(authors, { id: post.authorId });
100 },
101 },
102};
103
104export default resolvers;
105```
106
107At the end, the schema and resolvers are combined using `makeExecutableSchema`:
108
109```js
110import { makeExecutableSchema } from 'graphql-tools';
111
112const executableSchema = makeExecutableSchema({
113 typeDefs,
114 resolvers,
115});
116```
117
118This example has the entire type definition in one string and all resolvers in one file, but you can combine types and resolvers from multiple files and objects, as documented in the [modularizing the schema](https://www.apollographql.com/docs/graphql-tools/generate-schema.html#modularizing) section of the docs.
119
120## Contributions
121
122Contributions, issues and feature requests are very welcome. If you are using this package and fixed a bug for yourself, please consider submitting a PR!
123
124## Maintainers
125
126- [@hwillson](https://github.com/hwillson) (Apollo)
127- [@benjamn](https://github.com/benjamn) (Apollo)