ra-data-graphcool

A GraphQL data provider for react-admin built with Apollo and tailored to target the GraphCool service.

• Installation
• Usage
• Options

Installation

Install with:

npm install --save graphql ra-data-graphcool

or

yarn add graphql ra-data-graphcool

Usage

This example assumes a Post type is defined in the graphcool schema.

// in App.js
import * as React from 'react';
import { Component } from 'react';
import buildGraphcoolProvider from 'ra-data-graphcool';
import { Admin, Resource, Delete } from 'react-admin';

import { PostCreate, PostEdit, PostList } from './posts';

class App extends Component {
    constructor() {
        super();
        this.state = { dataProvider: null };
    }
    componentDidMount() {
        buildGraphcoolProvider({ clientOptions: { uri: 'https://api.graph.cool/simple/v1/graphcool_id' }})
            .then(dataProvider => this.setState({ dataProvider }));
    }

    render() {
        const { dataProvider } = this.state;

        if (!dataProvider) {
            return <div>Loading</div>;
        }

        return (
            <Admin dataProvider={dataProvider}>
                <Resource name="Post" list={PostList} edit={PostEdit} create={PostCreate} remove={Delete} />
            </Admin>
        );
    }
}

export default App;

And that's it, buildGraphcoolProvider will create a default ApolloClient for you and run an introspection query on your graphcool endpoint, listing all potential resources.

This works with any GraphCool endpoint, or any GraphQL endpoint modeled after the GraphCool grammar:

Options

Customize the Apollo client

You can either supply the client options by calling buildGraphcoolProvider like this:

buildGraphcoolProvider({ clientOptions: { uri: 'https://api.graph.cool/simple/v1/graphcool_id', ...otherApolloOptions } });

Or supply your client directly with:

buildGraphcoolProvider({ client: myClient });

Overriding a specific query

The default behavior might not be optimized especially when dealing with references. You can override a specific query by wrapping the buildQuery function:

// in src/dataProvider.js
import buildGraphcoolProvider, { buildQuery } from 'ra-data-graphcool';

const myBuildQuery = introspection => (fetchType, resource, params) => {
    const builtQuery = buildQuery(introspection)(fetchType, resource, params);

    if (resource === 'Command' && fetchType === 'GET_ONE') {
        return {
            // Use the default query variables and parseResponse
            ...builtQuery,
            // Override the query
            query: gql`
                query Command($id: ID!) {
                    data: Command(id: $id) {
                        id
                        reference
                        customer {
                            id
                            firstName
                            lastName
                        }
                    }
                }`,
        };
    }

    return builtQuery;
}

export default buildGraphcoolProvider({ buildQuery: myBuildQuery })

Customize the introspection

These are the default options for introspection:

const introspectionOptions = {
    include: [], // Either an array of types to include or a function which will be called for every type discovered through introspection
    exclude: [], // Either an array of types to exclude or a function which will be called for every type discovered through introspection
}

// Including types
const introspectionOptions = {
    include: ['Post', 'Comment'],
};

// Excluding types
const introspectionOptions = {
    exclude: ['CommandItem'],
};

// Including types with a function
const introspectionOptions = {
    include: type => ['Post', 'Comment'].includes(type.name),
};

// Including types with a function
const introspectionOptions = {
    exclude: type => !['Post', 'Comment'].includes(type.name),
};

Note: exclude and include are mutually exclusives and include will take precedence.

Note: When using functions, the type argument will be a type returned by the introspection query. Refer to the introspection documentation for more information.

Pass the introspection options to the buildApolloProvider function:

buildApolloProvider({ introspection: introspectionOptions });

DELETE_MANY and UPDATE_MANY Optimizations

Graphcool does not allow multiple deletions or updates in a single query. This provider simply makes multiple requests to handle those. This is obviously not ideal but can be alleviated by supplying your own ApolloClient which could use the apollo-link-batch-http link. Indeed, Graphcool does support query batching.

Contributing

Run the tests with this command:

make test