|
1 | 1 | # graphql-utilities |
| 2 | +⚒ Utilities for GraphQL |
| 3 | + |
2 | 4 | [](https://badge.fury.io/js/graphql-utilities) [](https://travis-ci.org/bloveit/graphql-utilities) [](https://coveralls.io/github/bloveit/graphql-utilities?branch=master) |
3 | 5 |
|
4 | 6 | Inspired by [`graph.ql`](https://github.com/MatthewMueller/graph.ql), [`graphql-tools`](https://github.com/apollostack/graphql-tools), and [`graphql-helpers`](https://github.com/depop/graphql-helpers). |
5 | 7 |
|
6 | 8 | ## Why? |
7 | | -There are various libraries out there providing utilities for GraphQL and even the [reference implementation](https://github.com/graphql/graphql-js) itself is adding [new utilities](https://github.com/graphql/graphql-js/pull/471). So why do we need another one? |
| 9 | +If there are various libraries out there providing utilities for [GraphQL.js](https://github.com/graphql/graphql-js), why do we need another library? |
8 | 10 |
|
9 | | -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. |
| 11 | +None of those libraries let you build GraphQL types using the schema language. This prevents their gradual adoption and makes code separation and isolation a nightmare. |
10 | 12 |
|
11 | | -With `graphql-utilities` it's simple. `build` makes it extremely simple to build a GraphQL type. |
| 13 | +With `graphql-utilities`, it's simple. Here's how you can use [`build`](#build) to make a GraphQL type. |
12 | 14 |
|
13 | 15 | ```js |
14 | | -build(` |
15 | | - type Query { |
16 | | - ok: Boolean! |
| 16 | +const { User } = build(` |
| 17 | + type User { |
| 18 | + id: ID! |
| 19 | + email: String! |
| 20 | + # The user's full name. |
| 21 | + name: String! |
17 | 22 | } |
18 | | -`); |
| 23 | +`, { |
| 24 | + User: { |
| 25 | + name: ({ firstName, lastName }) => `${firstName} ${lastName}`, |
| 26 | + } |
| 27 | +}); |
19 | 28 |
|
20 | 29 | /* is equivalent to */ |
21 | 30 |
|
22 | | -new GraphQLObjectType({ |
23 | | - name: 'Query', |
| 31 | +const User = new GraphQLObjectType({ |
| 32 | + name: 'User', |
24 | 33 | fields: () => ({ |
25 | | - ok: { type: new GraphQLNonNull(GraphQLBoolean) }, |
| 34 | + id: { |
| 35 | + type: new GraphQLNonNull(GraphQLID), |
| 36 | + }, |
| 37 | + email: { |
| 38 | + type: new GraphQLNonNull(GraphQLString), |
| 39 | + }, |
| 40 | + name: { |
| 41 | + type: new GraphQLNonNull(GraphQLString), |
| 42 | + resolve: ({ firstName, lastName }) => `${firstName} ${lastName}`, |
| 43 | + description: 'The user\'s full name.' |
| 44 | + }, |
26 | 45 | }), |
27 | | -}) |
| 46 | +}); |
28 | 47 | ``` |
29 | 48 |
|
30 | | -## Installation |
| 49 | +## Getting Started |
| 50 | +### Installation |
31 | 51 | ``` |
32 | | -npm install --save graphql-utilities |
| 52 | +npm install --save graphql graphql-utilities |
33 | 53 | ``` |
34 | 54 |
|
35 | | -## Getting Started |
| 55 | +### Example |
| 56 | +Head over to the [example](https://github.com/bloveit/graphql-utilities/tree/master/example) folder to see an implementation of the GraphQL.js Star Wars example using `graphql-utilities`. |
| 57 | + |
| 58 | +### I want to use `.graphql` files |
36 | 59 | ```js |
37 | | -import { build } from 'graphql-utilities'; |
| 60 | +const makeFileBuilder = (fn) => (...args) => |
| 61 | + fn(fs.readFileSync(__dirname.replace(/\.js$/, '.graphql', 'utf-8')), ...args); |
38 | 62 |
|
39 | | -// you can build a type |
40 | | -const Record = build(` |
41 | | - interface Record { |
42 | | - id: ID! |
43 | | - } |
44 | | -`); |
| 63 | +const fileBuild = makeFileBuilder(build); |
| 64 | +const fileBuildType = makeFileBuilder(buildType); |
| 65 | +const fileBuildSchema = makeFileBuilder(buildSchema); |
| 66 | +``` |
| 67 | +```graphql |
| 68 | +# User.graphql |
45 | 69 |
|
46 | | -// or you can build a schema |
47 | | -const Schema = build(` |
48 | | - schema { |
49 | | - query: Query |
50 | | - } |
| 70 | +type User { |
| 71 | + id: ID! |
| 72 | + email: String! |
| 73 | + # The user's full name. |
| 74 | + name: String! |
| 75 | +} |
| 76 | +``` |
| 77 | +```js |
| 78 | +/* User.js */ |
51 | 79 |
|
52 | | - type Query { |
53 | | - ok: Boolean! |
54 | | - } |
55 | | -`); |
| 80 | +fileBuildType({ |
| 81 | + name: ({ firstName, lastName }) => `${firstName} ${lastName}`, |
| 82 | +}); |
56 | 83 | ``` |
57 | 84 |
|
58 | | -## TODO |
59 | | -- [ ] Add detailed API docs. |
60 | | -- [x] ~~Make `build` configuration interchangeable with types.~~ |
61 | | -- [x] ~~Allow `build` to accept a flag to skip inferred schema.~~ |
| 85 | +## API |
| 86 | +### build |
| 87 | +```js |
| 88 | +function build( |
| 89 | + source: string, |
| 90 | + configMap?: BuildConfigMap, |
| 91 | + typeDependencies?: GraphQLTypesThunk | Array<GraphQLType>, |
| 92 | +): GraphQLType | GraphQLSchema |
| 93 | +``` |
62 | 94 |
|
63 | 95 | ## License |
64 | | -MIT |
| 96 | +[MIT](https://github.com/bloveit/graphql-utilities/blob/master/LICENSE) |
0 commit comments