Nocturnal Prancing Mosquito

    iguazu-graphql

    1.3.0 • Public • Published

    Iguazu GraphQL - One Amex

    npm Health Check

    Iguazu GraphQL is a plugin for the Iguazu ecosystem that allows for GraphQL requests backed by a simple cache.

    👩‍💻 Hiring 👨‍💻

    Want to get paid for your contributions to iguazu-graphql?

    Send your resume to oneamex.careers@aexp.com

    📖 Table of Contents

    Features

    • Plugs into Iguazu
    • Easy dispatchable actions for querying and mutating GraphQL APIs
    • Simple caching of requests based on Query
    • Seamless integration in Redux

    How it works

    🤹‍ Usage

    Installation

    npm install --save iguazu-graphql

    Quick Setup

    You will need to add the graphqlReducer to your redux store (redux-thunk middleware is required):

    import { createStore, combineReducers, applyMiddleware } from 'redux';
    import { graphqlReducer, addGraphQLEndpoints } from 'iguazu-graphql';
    import thunk from 'redux-thunk';
    
    const store = createStore(
      combineReducers({
        iguazuGraphQL: graphqlReducer,
      }),
      applyMiddleware(thunk)
    );
    
    addGraphQLEndpoints([
      {
        name: 'example-endpoint',
        fetch: () => ({ url: 'https://example.com/graphql' }),
      },
      // other endpoints can be specified at the same time
      // they can also be added later
    ]);

    You may now call GraphQL using Iguazu's loadDataAsProps:

    Basic Usage

    /* MyContainer.jsx */
    import React from 'react';
    import { connectAsync } from 'iguazu';
    import { queryGraphQLData } from 'iguazu-graphql';
    
    function MyContainer({ isLoading, loadedWithErrors, myData }) {
      if (isLoading()) {
        return <div>Loading...</div>;
      }
    
      if (loadedWithErrors()) {
        return <div>Oh no! Something went wrong</div>;
      }
    
      return (
        <div>
          myData =
          {myData}
        </div>
      );
    }
    
    function loadDataAsProps({ store, ownProps }) {
      const { dispatch } = store;
      const endpointName = 'example-endpoint';
      const query = `
        query ($someParam: String) {
          path(someParam: $someParam) {
            to {
              data
            }
          }
        }
      `;
      const variables = { someParam: ownProps.someParam };
      return {
        myData: () => dispatch(queryGraphQLData({ endpointName, query, variables })),
      };
    }
    
    export default connectAsync({ loadDataAsProps })(MyContainer);

    Getting Data (Queries)

    The Iguazu GraphQL adapter follows the Iguazu pattern. The queryGraphQLData action creator handles the boilerplate of action forms (promise, status, error, and data properties) Iguazu expects, while providing a convenient way to query a GraphQL schema/endpoint. The queryGraphQLData action creator requires a query to send to the GraphQL server, and also accepts variables for that query.

    /* MyContainer.jsx */
    import React from 'react';
    import { connectAsync } from 'iguazu';
    import { queryGraphQLData } from 'iguazu-graphql';
    
    function MyContainer({ isLoading, loadedWithErrors, myData }) {
      if (isLoading()) {
        return <div>Loading...</div>;
      }
    
      if (loadedWithErrors()) {
        return <div>Oh no! Something went wrong</div>;
      }
    
      return (
        <div>
          myData =
          {myData}
        </div>
      );
    }
    
    function loadDataAsProps({ store, ownProps }) {
      const { dispatch } = store;
      const endpointName = 'example-endpoint';
      const query = `
        query ($someParam: String) {
          path(someParam: $someParam) {
            to {
              data
            }
          }
        }
      `;
      const variables = { someParam: ownProps.someParam };
      return {
        myData: () => dispatch(queryGraphQLData({ endpointName, query, variables })),
      };
    }
    
    export default connectAsync({ loadDataAsProps })(MyContainer);

    Changing Data (Mutations)

    To change data on the server, use mutateGraphQLData to send mutations. It is very similar to the queryGraphQLData action creator, using a mutation instead of a query:

    /* MyUpdatingComponent.jsx */
    import React, { Component, Fragment } from 'react';
    import { compose } from 'redux';
    import { connect } from 'react-redux';
    import { connectAsync } from 'iguazu';
    import { queryGraphQLData, mutateGraphQLData } from 'iguazu-graphql';
    
    const endpointName = 'sample-endpoint';
    
    const QUERY_DATA = `
      query ($someParam: String) {
        path(someParam: $someParam) {
          to {
            data
          }
        }
      }
    `;
    
    const MUTATE_DATA = `
      mutation ($someParam: String) {
        removeTodo(someParam: $someParam) {
          someFunIdentifier
        }
      }
    `;
    
    class MyUpdatingComponent extends Component {
      constructor(props) {
        super(props);
        this.state = { message: '' };
      }
    
      handleClick = () => {
        const { mutateData, queryData } = this.props;
        // Send mutateData request
        const { promise: mutatePromise } = mutateData({ someParam: 'someParam' });
        return mutatePromise
          .then(() => {
            // Refresh queryData to get new results
            // which retriggers loadDataAsProps on rerender to get new myData
            const { promise: queryPromise } = queryData({ someParam: 'someParam' });
            return queryPromise;
          })
          .then(() => {
            this.setState({ message: 'Success!' });
          });
      };
    
      render() {
        const { isLoading, loadedWithErrors, myData } = this.props;
        const { message } = this.state;
    
        if (isLoading()) {
          return <div>Loading...</div>;
        }
    
        if (loadedWithErrors()) {
          return <div>Oh no! Something went wrong</div>;
        }
    
        return (
          <Fragment>
            {message}
            <button type="button" onClick={this.handleClick}>Update</button>
            <h1>My Data</h1>
            {myData}
          </Fragment>
        );
      }
    }
    
    // Hook up action creator functions to props to call later
    function mapDispatchToProps(dispatch) {
      return {
        // Update some remote resource
        mutateData: ({ someParam }) => dispatch(
          mutateGraphQLData({ endpointName, mutation: MUTATE_DATA, variables: { someParam } })
        ),
        // Fetch some remote resource
        queryData: ({ someParam }) => dispatch(
          queryGraphQLData({ endpointName, query: QUERY_DATA, variables: { someParam } })
        ),
      };
    }
    
    // Hook up data dispatches on component load
    function loadDataAsProps({ store, ownProps }) {
      const { dispatch } = store;
      return {
        // Fetch some remote resource and inject it into props as myData
        myData: () => dispatch(
          queryGraphQLData({
            endpointName,
            query: QUERY_DATA,
            variables: { someParam: ownProps.someParam },
          })
        ),
      };
    }
    
    export default compose(
      connect(undefined, mapDispatchToProps),
      connectAsync({ loadDataAsProps })
    )(MyUpdatingComponent);

    Advanced Setup

    Modifying Fetch Client

    The fetch option must return an object with a url key, and optionally an opts key of options for the fetch call (the second argument). Note that the fetch option for the endpoint is given the redux state, allowing computation of the URL or other options that may be needed:

    import { addGraphQLEndpoints } from 'iguazu-graphql';
    
    addGraphQLEndpoints([
      {
        name: 'example-endpoint',
    
        fetch: (state) => ({
          // the first argument to `fetch`
          url: `https://${state.config.myDomainForData}/graphql`,
    
          // the second argument to `fetch`
          opts: {
            // the base headers of `content-type` and `accepts` remain as opts are deeply merged
            headers: { 'X-CSRF': state.config.csrfToken },
          },
        }),
    
        // can also provide static opts, but overridden (via merge) by the `opts` returned by `fetch`
        opts: {
          headers: { 'API-Token': 'twelve' },
        },
      },
    ]);

    The Iguazu GraphQL adapter can be further configured via configureIguazuGraphQL:

    import { configureIguazuGraphQL } from 'iguazu-graphql';
    
    configureIguazuGraphQL({
      // extend fetch with some added functionality
      baseFetch: fetchWith6sTimeout,
    
      // override state location, defaults to state.iguazuGraphQL
      getToState: (state) => state.iguazuGraphQL,
    
      // default overrides of the Iguazu GraphQL defaults, like using POST
      // the endpoint `opts` takes precedence, see `src/executeFetch.js getAsyncData()` for details
      defaultOpts: {
        method: 'GET',
      },
    });

    Note: The baseFetch option is overriden if fetchClient is set with Redux Thunk's withExtraArgument. (See Advanced Setup for details)

    Placing State in a Different Location

    If you have a different place you want to put the query cache, you can put the reducer in that location in the redux pattern and then tell Iguazu GraphQL where that is via the getToState key to configureIguazuGraphQL:

    import { createStore, combineReducers, applyMiddleware } from 'redux';
    import { graphqlReducer, configureIguazuGraphQL } from 'iguazu-graphql';
    import thunk from 'redux-thunk';
    
    const store = createStore(
      combineReducers({
        deep: combineReducers({
          deeper: combineReducers({
            deepEnough: graphqlReducer,
          }),
        }),
      }),
      applyMiddleware(thunk)
    );
    
    configureIguazuGraphQL({ getToState: (state) => state.deep.deeper.deepEnough });

    Selectors

    getStateOfQuery

    Retrieve the existing result of a query from Redux state.

    const queryState = getStateOfQuery({ endpointName, query, variables })(getState);
    if (queryState) {
      // do something with ...
      queryState.toJS();
    }

    🏆 Contributing

    We welcome Your interest in the American Express Open Source Community on Github. Any Contributor to any Open Source Project managed by the American Express Open Source Community must accept and sign an Agreement indicating agreement to the terms below. Except for the rights granted in this Agreement to American Express and to recipients of software distributed by American Express, You reserve all right, title, and interest, if any, in and to Your Contributions. Please fill out the Agreement.

    Please feel free to open pull requests and see CONTRIBUTING.md to learn how to get started contributing.

    🗝️ License

    Any contributions made under this project will be governed by the Apache License 2.0.

    🗣️ Code of Conduct

    This project adheres to the American Express Community Guidelines. By participating, you are expected to honor these guidelines.

    Install

    npm i iguazu-graphql

    DownloadsWeekly Downloads

    4

    Version

    1.3.0

    License

    Apache-2.0

    Unpacked Size

    66.4 kB

    Total Files

    17

    Last publish

    Collaborators

    • pixnbits
    • anescobar1991
    • jsmartfo
    • amexopensource