Name	Name	Last commit message	Last commit date
parent directory ..
src	src
.babelrc	.babelrc
.eslintrc.json	.eslintrc.json
.gitignore	.gitignore
LICENSE	LICENSE
README.md	README.md
package.json	package.json

redux-source

< Back to Project WebCube

Using GraphQL schema and query language to access any data source (eg. RESTful APIs) and automatically generate reducers, actions and normalized state

npm install --save redux-source

For Immutable.js store: redux-source-immutable

Examples
Get Started

Examples

webcube-examples

Get Started

For example, suppose we have a CRUD (create, read, update, delete) API for managing shops

Create A Data Source

`createSource`

Create a data source instance

// shopManageApp/apis/shops/index.js
import { createSource } from 'redux-source';
// for Immutable.js store:
// import { createSource } from 'redux-source-immutable';
import schema from './schema/index.gql';
import resolvers from './resolvers';

export const source = createSource({
  schema,
  resolvers,
});

TIPS
Add raw-loader to your webpack.config.js for importing .gql file
{
  test: /\.(txt|gql)$/,
  use: 'raw-loader',
},

Schema

# shopManageApp/apis/shops/schema/index.gql
type Shop {
  id: ID!
  name: String
  address: String
  deliveryEnabled: Boolean!
  services: [Service!]
  orders: [JSON!]
  position: Position
}
type Service {
  id: ID!
  name: String!
  price: Float!
}
type Query {
  shops: [Shop!]
}
type Mutation {
  updateShop(shopId: String!, shopData: JSON!): [Shop!]
  deleteShop(shopId: String!): [Shop!]
}

TIPS

Syntax highlighting for GraphQL schema language and query language

GraphQL for VSCode

GraphQL schema language

Schemas and Types

Generating a schema

JSON type is built-in and defined by graphql-type-json ("field type for object with dynamic keys")

Other built-in scalar types: Date, Time, DateTime (graphql-iso-date)

You can define your own custom scalar

If you want to automatically normalize (see below) the data of a field, its field name must be plural (for the above example, the field names for Service type and Shop type are services and shops) or 'xxxx_$list' when its type is a List and must be singular or uncountable when its type is not a List.

Resolvers

// shopManageApp/apis/shops/resolvers/index.js
import hifetch from 'hifetch';

const resolvers = {
  Query: {
    shops: () => hifetch({
      url: `https://example.com/api/shops`,
    }).send().then(response => response.shops),
  },
  Mutation: {
    updateShop: (_, { shopId, shopData }) =>
      hifetch({
        url: `https://example.com/api/shops/${shopId}`,
        method: 'post',
        data: shopData,
      }).send().then(response => [response.shop]),
    deleteShop: (_, { shopId }) =>
      hifetch({
        url: `https://example.com/api/shops/${shopId}`,
        method: 'delete',
      }).send().then(response => [response.shop]),
  },
  Shop {
    services: shop => hifetch({
      url: `https://example.com/api/shops/${shop.id}/services`,
    }).send().then(response => [response.services]),
  },
};

export default resolvers;

TIPS

createSource's schema and resolvers options are the same as graphql-tools's makeExecutableSchema

Writing resolvers with graphql-tools

For more complex query or mutation operations, you can use composition libraries such as graphql-resolvers.

Examples: react-redux-restapi-app/common/apis/shops/resolvers

Examples of how to modularize the above code: react-redux-restapi-app/common/apis

Create A Data Source Query

Queries

Use GraphQL query language to automatically generate reducers, actions and normalized state:

// shopManageApp/ducks/shops.js
import gql from 'graphql-tag';
import { source } from '../apis/shops';

export const shopsSource = source(
  gql`
    query fetchShops {
      __config__ {
        combineResult: replace
      }
      shops {
        ...shopFields
      }
    }

    mutation addShop($id: ID!, $data: JSON!) {
      shops: updateShop(shopId: $id, shopData: $data) {
        ...shopFields
      }
    }

    mutation updateShop($id: ID!, $data: JSON!) {
      shops: updateShop(shopId: $id, shopData: $data) {
        ...shopFields
      }
    }

    mutation deleteShop($id: ID!) {
      __config__ {
        combineResult: crop
      }
      shops: deleteShop(shopId: $id) {
        ...shopFields
      }
    }

    fragment shopFields on Shop {
      id
      name
      address
      deliveryEnabled
      services {
        id
        name
        price
      }
      orders
      position {
        latitude
        longitude
      }
    }
  `,
);

// use `shopsSource` to generate reducer function and action creators

export {
  reducer,
  actions,
  types,
}

TIPS

GraphQL query language

Queries and Mutations

__config__ is an extended syntax supported by redux-source

combineResult is used to indicate how the autogenerated reducer to change the state, its value can be merge (default), replace, or crop

Examples: CRUD API demo in react-source-sample

Reducers, Actions and States

The output of source query:

console.log(shopsSource.actions)
// {
//   'REDUX_SOURCE/FETCH_SHOPS': asyncActionCreator,
//   'REDUX_SOURCE/FETCH_SHOPS_PENDING': actionCreator,
//   'REDUX_SOURCE/FETCH_SHOPS_SUCCESS': actionCreator,
//   'REDUX_SOURCE/FETCH_SHOPS_ERROR': actionCreator,
//   'REDUX_SOURCE/ADD_SHOP': asyncActionCreator,
//   'REDUX_SOURCE/ADD_SHOP_PENDING': actionCreator,
//   'REDUX_SOURCE/ADD_SHOP_SUCCESS': actionCreator,
//   'REDUX_SOURCE/ADD_SHOP_ERROR': actionCreator,
//   'REDUX_SOURCE/UPDATE_SHOP': asyncActionCreator,
//   'REDUX_SOURCE/UPDATE_SHOP_PENDING': actionCreator,
//   'REDUX_SOURCE/UPDATE_SHOP_ERROR': actionCreator,
//   'REDUX_SOURCE/UPDATE_SHOP_SUCCESS': actionCreator,
//   'REDUX_SOURCE/DELETE_SHOP': asyncActionCreator,
//   'REDUX_SOURCE/DELETE_SHOP_PENDING': actionCreator,
//   'REDUX_SOURCE/DELETE_SHOP_ERROR': actionCreator,
//   'REDUX_SOURCE/DELETE_SHOP_SUCCESS': actionCreator,
// }

console.log(shopsSource.reducerMap)
// {
//   'REDUX_SOURCE/FETCH_SHOPS_PENDING': reducer,
//   'REDUX_SOURCE/FETCH_SHOPS_SUCCESS': reducer,
//   'REDUX_SOURCE/FETCH_SHOPS_ERROR': reducer,
//   'REDUX_SOURCE/ADD_SHOP_PENDING': reducer,
//   'REDUX_SOURCE/ADD_SHOP_SUCCESS': reducer,
//   'REDUX_SOURCE/ADD_SHOP_ERROR': reducer,
//   'REDUX_SOURCE/UPDATE_SHOP_PENDING': reducer,
//   'REDUX_SOURCE/UPDATE_SHOP_ERROR': reducer,
//   'REDUX_SOURCE/UPDATE_SHOP_SUCCESS': reducer,
//   'REDUX_SOURCE/DELETE_SHOP_PENDING': reducer,
//   'REDUX_SOURCE/DELETE_SHOP_ERROR': reducer,
//   'REDUX_SOURCE/DELETE_SHOP_SUCCESS': reducer,
// }

console.log(shopsSource.initialState)
// {
//   source: {
//     result: {},
//     entities: {},
//     isPending: false,
//     errors: [],
//   }
// }

TIPS

How to compile GraphQL queries at the build time

babel-plugin-graphql-tag

How to use the output of source query (like shopsSource) with redux-cube

New docs coming soon! (based on the new createCube API and webcube's SSR feature)

Example: redux-source-sample

How will the action creators (shopsSource.actions) and reducers (shopsSource.reducerMap) change the state slice (shopsSource.initialState):

shopsSource.actions.reduxSource.fetchShops()
// state slice:
// {
//   source: {
//     result: {
//       shops: ['shop-id-0001', 'shop-id-0002'],
//     },
//     entities: {
//       shop: {
//         'shop-id-0001': {
//           id: 'shop-id-0001',
//           name: 'Shop A',
//           services: ['service-id-0001', 'serivce-id-0001'],
//           position: {
//             latitude: '...',
//             longitude: '...',
//           },
//           ...
//         },
//         'shop-id-0002': {
//           id: 'shop-id-0002',
//           name: 'Shop B',
//           services: ['shop-id-0002', 'shop-id-0003'],
//           position: {
//             latitude: '...',
//             longitude: '...',
//           },
//           ...
//         },
//       },
//       service: {
//         'service-id-0001': {
//           name: 'Service A',
//           ...
//         },
//         'service-id-0002': {
//           ...
//         },
//         'service-id-0003': {
//           ...
//         },
//       },
//     },
//     isPending: false,
//     errors: [],
//   }
// }

shopsSource.actions.reduxSource.addShop({
  id: 'shop-id-0003',
  data: {
    name: 'Shop C',
    services: [{
      id: 'shop-id-0004',
      name: 'Service D',
      // ...
    }],
    // ...
  },
})
// state slice:
// {
//   source: {
//     result: {
//       shops: ['shop-id-0001', 'shop-id-0002', 'shop-id-0003'],
//     },
//     entities: {
//       shop: {
//         'shop-id-0001': {
//           ...
//         },
//         'shop-id-0002': {
//           ...
//         },
//         'shop-id-0003': {
//           id: 'shop-id-0003',
//           name: 'Shop C',
//           ...
//         },
//       },
//       service: {
//         'service-id-0001': {
//           ...
//         },
//         'service-id-0002': {
//           ...
//         },
//         'service-id-0003': {
//           ...
//         },
//         'service-id-0004': {
//           name: 'Service D',
//           ...
//         },
//       },
//     },
//     isPending: false,
//     errors: [],
//   }
// }

shopsSource.actions.reduxSource.updateShop({
  id: 'shop-id-0001',
  data: {
    name: 'Shop A (modified)',
    // ...
  },
})
// state slice:
// {
//   source: {
//     result: {
//       shops: ['shop-id-0001', 'shop-id-0002', 'shop-id-0003'],
//     },
//     entities: {
//       shop: {
//         'shop-id-0001': {
//           id: 'shop-id-0001',
//           name: 'Shop A (modified)',
//           ...
//         },
//         'shop-id-0002': {
//           ...
//         },
//         'shop-id-0003': {
//           ...
//         },
//       },
//       service: {
//         ...
//       },
//     },
//     isPending: false,
//     errors: [],
//   }
// }

shopsSource.actions.reduxSource.deleteShop({
  id: 'shop-id-0002',
})
// state slice:
// {
//   source: {
//     result: {
//       shops: ['shop-id-0001', 'shop-id-0003'],
//     },
//     entities: {
//       shop: {
//         'shop-id-0001': {
//           ...
//         },
//         'shop-id-0002': {
//           ...
//         },
//         'shop-id-0003': {
//           ...
//         },
//       },
//       service: {
//         'service-id-0001': {
//           ...
//         },
//         'service-id-0002': {
//           ...
//         },
//         'service-id-0003': {
//           ...
//         },
//         'service-id-0004': {
//           ...
//         },
//       },
//     },
//     isPending: false,
//     errors: [],
//   }
// }

TIPS

redux-source can automatically generate the schema definition for normalizr and automatically normalize the output of GraphQL resolvers (equal to shopsSource.normalize(outputOfAllResolvers))

The position field in the result is not normalized because it does not contain an id field

The name of the id field can be customized by idAttribute option (see below)

How To Customize

const shopsSource = source(
  gql`
    ...
  `,
  {
    // for normalize
    // default value is 'id'
    idAttribute: 'otherId',
    // for state slice
    stateName: 'shopsSource',
    // for action types
    namespace: 'SHOPS_NAMESPACE',
    // for action types
    delimiter: '|',
  }
})

console.log(shopsSource.actions)
// {
//   'SHOPS_NAMESPACE|FETCH_SHOPS': asyncActionCreator,
//   'SHOPS_NAMESPACE|FETCH_SHOPS_PENDING': actionCreator,
//   'SHOPS_NAMESPACE|FETCH_SHOPS_SUCCESS': actionCreator,
//   'SHOPS_NAMESPACE|FETCH_SHOPS_ERROR': actionCreator,
//   ...
//   'SHOPS_NAMESPACE|DELETE_SHOP_SUCCESS': actionCreator,
// }

console.log(shopsSource.initialState)
// {
//   shopsSource: {
//     result: {},
//     entities: {},
//     isPending: false,
//     errors: [],
//   }
// }

Higher-order Components

Connect To React Components

New docs coming soon! (based on the new createCube API and webcube's SSR feature)

See redux-source-connect

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

redux-source

redux-source

README.md

redux-source

Examples

Get Started

Create A Data Source

`createSource`

Schema

Resolvers

Create A Data Source Query

Queries

Reducers, Actions and States

How To Customize

Higher-order Components

Connect To React Components

Notification

Block UI

Immutable.js Store

Files

redux-source

Directory actions

More options

Directory actions

More options

Latest commit

History

redux-source

Folders and files

parent directory

README.md

redux-source

Examples

Get Started

Create A Data Source

createSource

Schema

Resolvers

Create A Data Source Query

Queries

Reducers, Actions and States

How To Customize

Higher-order Components

Connect To React Components

Notification

Block UI

Immutable.js Store

`createSource`