|
1 | 1 | <a href="https://gramps.js.org/"><img src="https://gramps.js.org/assets/img/gramps-banner.png" alt="GrAMPS · An easier way to manage the data sources powering your GraphQL server" width="450"></a> |
2 | 2 |
|
3 | 3 | # GrAMPS GraphQL Data Source Base |
4 | | -[](https://travis-ci.org/gramps-graphql/data-source-base) [](https://codeclimate.com/github/gramps-graphql/data-source-base/maintainability) [](https://codeclimate.com/github/gramps-graphql/data-source-base/test_coverage) [](https://www.npmjs.com/package/@gramps/data-source-base) [](https://greenkeeper.io/) |
5 | 4 |
|
6 | | -This is a minimal example and boilerplate for a GrAMPS data source. Inside, you’ll find: |
| 5 | +[](https://travis-ci.org/gramps-graphql/data-source-base) [](https://codeclimate.com/github/gramps-graphql/data-source-base/maintainability) [](https://codeclimate.com/github/gramps-graphql/data-source-base/test_coverage) [](https://www.npmjs.com/package/@gramps/data-source-base) [](https://greenkeeper.io/) |
7 | 6 |
|
8 | | - - **Context** — an object with methods to retrieve/modify data from the data |
9 | | - source (e.g. a CRUD wrapper) |
10 | | - - **Schema** — type definitions for GraphQL to interpret the data (see the |
11 | | - [GraphQL docs on schemas](http://graphql.org/learn/schema/)) |
12 | | - - **Resolvers** — functions to map the results of calls to model methods to |
13 | | - the schema |
14 | | - - **Mock Resolvers** — mock functions for offline development |
15 | | - |
16 | | -Each file contains a `TODO` comment explaining the changes you’ll need to make to create a working data source. |
17 | | - |
18 | | -The goal of this repo is to provide enough code to allow a working example of a data source and its related tests, but to limit how much boilerplate needs to be edited to get your own data source implemented. |
19 | | - |
20 | | -## Code Quality and Continuous Integration |
21 | | - |
22 | | -To help ensure a reliable, easy-to-maintain data source, this example also includes: |
23 | | - |
24 | | - - Configuration for Travis CI (for automated testing) and Code Climate |
25 | | - (for quality analysis) |
26 | | - - Starts you off right with test coverage at 💯 |
27 | | - - Provides testing helpers for common resolver testing patterns |
28 | | - - Comes with docs! https://ibm.biz/graphql-data-source |
| 7 | +A boilerplate and minimal example for a [GrAMPS data source](https://gramps.js.org/data-source/data-source-overview/). |
29 | 8 |
|
30 | 9 | ## Quickstart |
31 | 10 |
|
32 | | -**NOTE:** Replace all instances of `YOUR_DATA_SOURCE_NAME` with the actual name you want to use (e.g. `data-source-companyname-datatype`). |
| 11 | +Set up a local data source in seconds with: |
33 | 12 |
|
34 | | -```sh |
35 | | -# Get a copy of the data source |
36 | | -npx degit gramps-graphql/data-source-base data-source-YOUR_DATA_SOURCE_NAME |
37 | | - |
38 | | -# Move into it |
39 | | -cd data-source-YOUR_DATA_SOURCE_NAME/ |
| 13 | +```bash |
| 14 | +# 💥 zero dependencies! no global installs! create a new data source |
| 15 | +npx graphql-cli create -b gramps-graphql/data-source-base data-source-mydata |
40 | 16 |
|
41 | | -# IMPORTANT: Make sure to edit the name, description, contributors, and |
42 | | -# repository fields in package.json |
| 17 | +# 📂 move into the newly-created data source |
| 18 | +cd $_ |
43 | 19 |
|
44 | | -# Install dependencies |
45 | | -yarn |
46 | | - |
47 | | -# Start the dev server |
| 20 | +# 🚀 start the GraphQL Playground with your spankin’ new data source |
48 | 21 | yarn dev |
49 | 22 | ``` |
50 | 23 |
|
51 | | -You'll see a message with URLs for the GraphQL gateway and the [GraphQL Playground](https://github.com/graphcool/graphql-playground). Open the Playground link (usually http://localhost:8080/playground if you don’t already have something running on port 8080), then run a query: |
| 24 | +> **NOTE:** We recommend prefixing data source projects with `data-source-` for clarity and the eventual support of CLI tools to add data sources to your gateway. So if you’re creating a user management data source for the Acme company, we recommend `data-source-acme-users` or `data-source-acmeusers` as a directory/repo name. |
| 25 | +
|
| 26 | +> **ALSO NOTE:** `$_` is a handy shortcut for using the last argument passed to the previous command. It [also does other stuff](https://unix.stackexchange.com/questions/280453/understand-the-meaning-of), but that's a rabbit hole for another time. |
| 27 | +
|
| 28 | +After running `yarn dev`, you’ll see a message with URLs for the GraphQL gateway and the [GraphQL Playground](https://github.com/graphcool/graphql-playground). Open the Playground link (usually http://localhost:8080/playground if you don’t already have something running on port 8080), then run a query: |
52 | 29 |
|
53 | 30 | ```graphql |
54 | 31 | { |
55 | | - getById(id: 123) { |
56 | | - id |
57 | | - name |
58 | | - lucky_numbers |
59 | | - } |
| 32 | + getById(id: 123) { |
| 33 | + id |
| 34 | + name |
| 35 | + lucky_numbers |
| 36 | + } |
60 | 37 | } |
61 | 38 | ``` |
62 | 39 |
|
63 | 40 | ### To Develop with Mock Data |
64 | 41 |
|
65 | | -Start the app with the following command: |
| 42 | +Add the `--mock` flag to enable mock data, which is helpful for working offline. |
66 | 43 |
|
67 | 44 | ```sh |
68 | 45 | # Start the gateway with mock data |
69 | 46 | yarn dev --mock |
70 | 47 | ``` |
71 | 48 |
|
| 49 | +See `src/mocks.js` to modify your mock resolvers. |
| 50 | + |
| 51 | +> **NOTE:** For more information on the GrAMPS CLI and its available options, [check out the docs](https://gramps.js.org/cli/cli-overview/). |
| 52 | +
|
| 53 | +### To Run the Tests |
| 54 | + |
| 55 | +GrAMPS data sources start you off with 100% test coverage so you can build high-reliability GraphQL servers without a bunch of setup work. |
| 56 | + |
| 57 | +Run the tests with: |
| 58 | + |
| 59 | +```bash |
| 60 | +yarn test |
| 61 | +``` |
| 62 | + |
| 63 | +## What's Inside? |
| 64 | + |
| 65 | +Inside, you’ll find: |
| 66 | + |
| 67 | +* **Schema** — type definitions for GraphQL to interpret the data (see the |
| 68 | + [GraphQL docs on schemas](http://graphql.org/learn/schema/)) |
| 69 | +* **Resolvers** — functions to map the results of calls to model methods to |
| 70 | + the schema |
| 71 | +* **Mock Resolvers** — mock functions for offline development |
| 72 | +* **Context** — an object with methods to interact with data that is passed to resolver functions |
| 73 | + |
| 74 | +Each file contains a `TODO` comment explaining the changes you’ll need to make to create a working data source. |
| 75 | + |
| 76 | +The goal of this repo is to provide enough code to allow a working example of a data source and its related tests, but to limit how much boilerplate needs to be edited to get your own data source implemented. |
| 77 | + |
| 78 | +## Code Quality and Continuous Integration |
| 79 | + |
| 80 | +To help ensure a reliable, easy-to-maintain data source, this example also includes: |
| 81 | + |
| 82 | +* Configuration for Travis CI (for automated testing) and Code Climate |
| 83 | + (for quality analysis) |
| 84 | +* Starts you off right with test coverage at 💯 |
| 85 | +* Provides testing helpers for common resolver testing patterns |
| 86 | +* Comes with docs! https://gramps.js.org/data-source/data-source-overview/ |
| 87 | + |
72 | 88 | ### Notes for Developers |
73 | 89 |
|
74 | 90 | Currently, there is no watch capability (PRs welcome!), so the service needs to be stopped (`control` + `C`) and restarted (`yarn dev`) to reflect new changes to the data source. |
0 commit comments