redux-reorder/README.md

Higher-order reducer that tracks order fluctuation within iterable state

# redux-reorder

> Higher-order reducer that tracks order fluctuation within iterable state

[![npm version](https://img.shields.io/npm/v/redux-reorder.svg?style=flat-square)](https://www.npmjs.com/package/redux-reorder)
[![Build Status](https://img.shields.io/travis/nonnontrivial/redux-reorder/master.svg?style=flat-square)](https://travis-ci.org/nonnontrivial/redux-reorder)

## The Problem
You have a reducer that holds on to [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable) state. Its order periodically updates.

You would like to know how the order has changed _relative_ to a previous order.

This package appends a given reducer with a representation of how its new order has changed from a previous order.

## A use case
> Showing the evolution of a leaderboard.

Let's say your application monitors the (daily) exchange rates of cryptocurrencies. A useful thing.
Occasionally, one currency jumps ahead in value of another, and your state changes to reflect this.

You now want to show the extent of this change in your UI.

### The implementation
#### Reducer wrapping

`./reducers/index.js`
```js
import { combineReducers } from 'redux'
import grokReorders from 'redux-reorder'

import currencies from './currencies'

export default combineReducers({
  ...otherReducers,
  // We'll pass a reducer that manages iterable state to grokReorders.
  // It takes a config object as the second argument, where the number of calls
  // (= step) to the reducer initiated by a specified action type (= reorderType)
  // required before fluctuation is recalculated can be specificed.
  currencies: grokReorders(currencies, { step: 1, reorderType: 'RECEIVE_CURRENCIES' })
  // state.currencies will now look like: { iterable: <Iterable>, fluctuationMap: <Array> }
})
```

#### Connecting to React

`./components/Leaderboard.js`
```js
import React, { Component } from 'react'
import { connect } from 'react-redux'

// A component which we imagine can display the order delta for a given item in a list.
import FluctuationIcon from './FluctuationIcon'

class Leaderboard extends Component {
  render() {
    // Recall that grokReorders changes the shape of the reducer it accepts as
    // an argument.

    // Now, with currencies.iterable we have access to the iterable as
    // originally returned by the reducer that was passed to grokReorders. With
    // currencies.fluctuationMap we have an array of integers which 'say' how 'far'
    // each element has moved from its last 'known' position.

    // For example, if currencies.fluctuationMap looks like [-1,1,0,0], then the
    // first element in currencies.iterable has moved 'up' one index from where it
    // last was, the second has moved 'down' one index, and so forth.
    const { currencies: { iterable, fluctuationMap } } = this.props
    return (
      <div>
        {iterable.map(({ name, valueInUSD }, i) => (
          <div>
            // We can now pass the appropriate indication of fluctuation to our
            // icon component.
            <FluctuationIcon delta={fluctuationMap[i]} />
            <p>{name}: {valueInUSD}</p>
          </div>
        ))}
      </div>
    )
  }
}

function mapStateToProps(state) {
  return {
    currencies: state => state.currencies
  }
}

// Inject the part of state we care about as a prop in Leaderboard.
export default connect(mapStateToProps)(Leaderboard)
```

## Installation
```console
npm i -S redux-reorder
```

or

```console
yarn add redux-reorder
```