|
| 1 | +# GraphQL.js |
| 2 | + |
| 3 | +This is a technical preview of the JavaScript reference implementation for |
| 4 | +GraphQL, a query language created by Facebook for describing data requirements |
| 5 | +on complex application data models. |
| 6 | + |
| 7 | +## Technical Preview Contents |
| 8 | + |
| 9 | +This technical preview contains a [draft specification for GraphQL](https://github.com/facebook/graphql) |
| 10 | +and a reference implementation in JavaScript that implements that draft, |
| 11 | +GraphQL.js. |
| 12 | + |
| 13 | +The reference implemention provides base libraries in javascript that would |
| 14 | +provide the basis for full GraphQL implementations and tools. It is not a fully |
| 15 | +standalone GraphQL server that a client developer could use to start |
| 16 | +manipulating and querying data. Most importantly it provides no mapping to a |
| 17 | +functioning, production-ready backend. The only “backend” we have targeted for |
| 18 | +this early preview are in-memory stubs in test cases. |
| 19 | + |
| 20 | +We are releasing this now because after GraphQL was first discussed publically, |
| 21 | +many engineers used this information to implement the parts of the system that |
| 22 | +we discussed publically. We want to support those engineers by providing both a |
| 23 | +formal specification and a reference implementation for the system as a whole. |
| 24 | + |
| 25 | +To that end the target audience is not the client developer, but those who have |
| 26 | +or are actively interested in building their own GraphQL implementations and |
| 27 | +tools. Critically we also want feedback on system and to incorporate that |
| 28 | +feedback in our final release. |
| 29 | + |
| 30 | +In order to be broadly adopted GraphQL will have to target a wide |
| 31 | +variety of backends, frameworks, and languages, which will necessitate a |
| 32 | +collaborative effort across projects and organizations. This technical preview |
| 33 | +marks the beginning of that process. |
| 34 | + |
| 35 | +## Getting Started |
| 36 | + |
| 37 | +An overview of GraphQL in general is available in the |
| 38 | +[README](https://github.com/facebook/graphql/README) for the |
| 39 | +[Specification for GraphQL](https://github.com/facebook/graphql). That overview |
| 40 | +describes a simple set of GraphQL examples that exist as [tests](src/__tests__) |
| 41 | +in this repository. A good way to get started with this repository is to walk |
| 42 | +through that README and the corresponding tests in parallel. |
| 43 | + |
| 44 | +### Using GraphQL.js |
| 45 | + |
| 46 | +Install GraphQL.js from npm |
| 47 | + |
| 48 | +``` |
| 49 | +npm install graphql |
| 50 | +``` |
| 51 | + |
| 52 | +GraphQL.js provides two important capabilites: building a type schema, and |
| 53 | +serving queries against that type schema. |
| 54 | + |
| 55 | +First, build a GraphQL type schema which maps to your code base. |
| 56 | + |
| 57 | +```js |
| 58 | +var GraphQL = require('graphql'); |
| 59 | + |
| 60 | +var schema = new GraphQL.GraphQLSchema({ |
| 61 | + query: new GraphQL.GraphQLObjectType({ |
| 62 | + name: 'RootQueryType', |
| 63 | + fields: { |
| 64 | + hello: { |
| 65 | + type: GraphQL.GraphQLString, |
| 66 | + resolve: function() { return 'world'; } |
| 67 | + } |
| 68 | + } |
| 69 | + }) |
| 70 | +}); |
| 71 | +``` |
| 72 | + |
| 73 | +This defines a simple schema with one type and one field, that resolves |
| 74 | +to a fixed value. A more complex example is included in the top level |
| 75 | +[tests](src/__tests__) directory. |
| 76 | + |
| 77 | +Then, serve the result of a query against that type schema. |
| 78 | + |
| 79 | +```js |
| 80 | +var query = '{ hello }'; |
| 81 | + |
| 82 | +GraphQL.graphql(schema, query).then(function (result) { |
| 83 | + |
| 84 | + // Prints |
| 85 | + // { |
| 86 | + // data: { hello: "world" } |
| 87 | + // } |
| 88 | + console.log(result); |
| 89 | + |
| 90 | +}); |
| 91 | +``` |
| 92 | + |
| 93 | +This runs a query fetching the one field defined. The `graphql` function will |
| 94 | +first ensure the query is syntactically and semantically valid before executing |
| 95 | +it, reporting errors otherwise. |
| 96 | + |
| 97 | +```js |
| 98 | +var query = '{ boyhowdy }'; |
| 99 | + |
| 100 | +GraphQL.graphql(schema, query).then(function (result) { |
| 101 | + |
| 102 | + // Prints |
| 103 | + // { |
| 104 | + // errors: [ |
| 105 | + // { message: 'Cannot query field boyhowdy on RootQueryType', |
| 106 | + // locations: [ { line: 1, column: 3 } ] } |
| 107 | + // ] |
| 108 | + // } |
| 109 | + console.log(result); |
| 110 | + |
| 111 | +}); |
| 112 | +``` |
| 113 | + |
| 114 | +### Contributing |
| 115 | + |
| 116 | +After cloning this repo, ensure dependencies are installed by running: |
| 117 | + |
| 118 | +```sh |
| 119 | +npm install |
| 120 | +``` |
| 121 | + |
| 122 | +GraphQL is written in ES6 using [Babel](http://babeljs.io/), widely consumable |
| 123 | +JavaScript can be produced by running: |
| 124 | + |
| 125 | +```sh |
| 126 | +npm run build |
| 127 | +``` |
| 128 | + |
| 129 | +Once `npm run build` has run, you may `require()` directly from node. |
| 130 | + |
| 131 | +After developing, the full test suite can be evaluated by running: |
| 132 | + |
| 133 | +```sh |
| 134 | +npm test |
| 135 | +``` |
| 136 | + |
| 137 | +While actively developing, we recommend running |
| 138 | + |
| 139 | +```sh |
| 140 | +npm run watch |
| 141 | +``` |
| 142 | + |
| 143 | +in a terminal. This will watch the file system run lint, tests, and type |
| 144 | +checking automatically whenever you save a js file. |
| 145 | + |
| 146 | +To lint the JS files and type interface checks run `npm run lint`. |
0 commit comments