Redux Resource
  • Home
  • Introduction
    • Motivation
    • Core Concepts
    • Similar Projects
    • Examples
  • Resources
    • Resource Reducers
    • Resource Objects
    • Meta
    • Lists
    • Modifying Resources
  • Requests
    • Request Objects
    • Keys
    • Names
    • Statuses
    • Request Actions
      • Updating Lists
      • Reading Resources
      • Updating Resources
      • Creating Resources
      • Deleting Resources
  • Other Guides
    • Usage With React
    • Tracking Request Statuses
    • Using Request Statuses
    • Custom Action Types
    • Migration Guides
  • Recipes
    • Forms
    • Canceling Requests
    • Unauthorized Responses
    • User Feedback
    • Related Resources
    • Caching
  • Ecosystem Extras
    • Redux Resource Action Creators
    • Redux Resource XHR
    • Redux Resource Prop Types
    • Redux Resource Plugins
      • HTTP Status Codes
      • Selection
      • Reset
      • Included Resources
  • FAQ
    • General
    • State Tree
    • Actions
    • Lists
  • API Reference
    • resourceReducer
    • getStatus
    • getResources
    • upsertResources
    • setResourceMeta
    • actionTypes
    • requestStatuses
Powered by GitBook
On this page
  • Other Guides
  • Installation
  • Usage
  • crudRequest( crudAction, options )
  • Arguments
  • Returns
  • Example
  • xhr( options )
  • Customizing Query String Serialization
  • Example
  • Tips
  1. Ecosystem Extras

Redux Resource XHR

PreviousRedux Resource Action CreatorsNextRedux Resource Prop Types

Last updated 5 years ago

Redux Resource XHR is an action creator that simplifies CRUD operations.

More information about CRUD actions in Redux Resource can be found in the guide and the four guides on CRUD:

We recommend familiarizing yourself with the content in those guides before using this library.

Other Guides

Old Documentation

Migration Guides

Installation

Install redux-resource-xhr from npm:

npm install redux-resource-xhr --save

Then, import the crudRequest action creator in your application:

import { crudRequest } from 'redux-resource-xhr';

Usage

crudRequest( crudAction, options )

An action creator for CRUD requests.

Arguments

  1. options (Object): Options to configure the CRUD request.

    • [onPending]: (Function) An optional function that allows you to modify the "pending" action, as well as control when it is dispatched. It is called with one argument: action. When this function is provided, you will be responsible for dispatching the action.

    • [onAborted]: (Function) An optional function that allows you to modify the "aborted" action, as well as control when it is dispatched. It is called with arguments (action, res). When this function is provided, you will be responsible for dispatching the action.

    • [onFailed]: (Function) An optional function that allows you to modify the "failed" action, as well as control when it is dispatched. It is called with arguments (action, err, res). When this function is provided, you will be responsible for dispatching the action.

    • [onSucceeded]: (Function) An optional function that allows you to modify the "succeeded" action, as well as control when it is dispatched. It is called with arguments (action, res, body). When this function is provided, you will be responsible for dispatching the action.

      If all that you need to do is transform the resources that your backend returns, then you should use transformData instead of onSuceeded.

Returns

Example

import { crudRequest } from 'redux-resource-xhr';
import store from './store';

const xhrOptions = {
  method: 'GET',
  json: true,
  url: '/books',
  qs: {
    user: 'someone@example.com'
  }
};

const xhr = crudRequest('read', {
  dispatch: store.dispatch,
  actionDefaults: {
    resourceType: 'books',
    requestKey: 'getHomePageBooks',
    list: 'homePageBooks',
    mergeListIds: false
  },
  xhrOptions
});

// Cancel the request if you need to
xhr.abort();

xhr( options )

On top of that, it adds several new features:

Customizing Query String Serialization

You can change how the query string is serialized using two options:

  • qsStringify - a function with the signature (qs, options). It should return the string to be appended to the URI.

  • qsStringifyOptions - an object that is passed as the second argument to the qsStringify method.

For instance, if you wish to use the qs library, you might do this:

import { xhr } from 'redux-resource-xhr';
import qs from 'qs';

xhr('/books', {
  method: 'GET',
  qs: {
    pageSize: 10,
    pageNumber: 0,
    publishers: ['goldenBooks', 'penguinBooks']
  },
  qsStringify: qs.stringify,
  qsStringifyOptions: { arrayFormat: 'brackets' }
}, cb);

Example

import { xhr } from 'redux-resource-xhr';

const booksSearch = xhr.get('/books', {
  // Pass a `qs` option, and it will be stringified and appended to the URL
  // for you
  qs: {
    bookName: 'brilliance of the moon'
  },
  json: true
}, (err, res, body) => {
  console.log('Got some books', body);
});

// Later, you can abort the request:
booksSearch.abort();

// Omit a callback to get a native Promise. This can be useful sometimes, but the
// tradeoff is that you cannot cancel Promises.
xhr.get('/books/24')
  .then(
    (res) => console.log('got a book', res),
    (err) => console.log('there was an error', err)
  );

Tips

  • The onSucceeded and onFailed options can also be used for chaining requests. You can make a second (or third, or fourth!) HTTP request in these callbacks. This is useful when you need to make multiple requests to get all of the data that your interface needs.

  • import { crudRequest } from 'redux-resource-xhr';
    
    function readManyBooks({ pageNumber }) {
      return (dispatch) => {
        const xhrOptions = {
          method: 'GET',
          json: true,
          url: '/books',
          qs: { pageNumber }
        };
    
        return crudRequest('read', {
          actionDefaults: {
            resourceType: 'books',
            requestKey: 'getHomePageBooks',
            list: 'homePageBooks',
            mergeListIds: false,
          },
          xhrOptions,
          dispatch
        });
      };
    }

    Then, in your view layer, you can call readManyBooks({ pageNumber: 5 }).

This library has two exports: an action creator for CRUD operations, crudRequest, and the library used for making the HTTP requests, .

crudAction: (String) The CRUD operation being performed. One of "create", "read", "update", or "delete". This determines the that are dispatched.

actionDefaults: (Object) Properties that will be included on each dispatched action. All of are supported, such as resourceType and resources.

dispatch: (Function) The dispatch function of a Redux store. If you're using , this will be the first argument of the thunk.

xhrOptions: (Object) Options to pass to the library. You must pass an url (or uri) option. You will typically also want to pass json: true, which will serialize your request body into JSON, as well as parse the response body as JSON. For more, see the examples below and .

[transformData]: (Function) An optional function to transform the data received by the server. It receives one argument, body, which is the response from the server, parsed as JSON. Return a transformed list of resources. This can be used to format the server response into a Redux Resource-compatible format. For more, see the guide on .

(XMLHttpRequest): An instance of a . Typically, you'll use this object to abort the request (should you need to) by calling myXhr.abort().

This is the library used to make HTTP requests. It is a thin wrapper around the library , and supports all of the same options and signatures.

Support for query string serialization (similar to the library).

Omitting the callback will return a native .

If you pass a qs object, then the object will be serialized into a query parameter using the library. This library supports basic serialization, but we don't expect it to work for every API that you interface with.

The onSucceeded option of crudRequest can be useful if your backend returns in a single request.

A good pattern for using this collection is to make your own action creators that "wrap" these action creators using . That way, your view layer doesn't need to concern itself with all of the configuration necessary to use these action creators. For instances, an action creator for reading books in your application may look like the following:

CRUD Action types
the Request Action options
redux-thunk
Resource objects
XMLHttpRequest
xhr
request
Promise
querystringify
related resources
redux-thunk
xhr
the xhr documentation
xhr
Request Actions
Reading resources
Updating resources
Creating resources
Deleting resources
2.x documentation
3.x documentation
v2 to v3
v3 to v4
npm version
gzip size