README.md

react-redux-uuid

A place to keep your disposable but application-related component state data

Why would you need this

Sometimes you write components that hold a state with data related to your application's data, in an ideal world you would like to keep all of your's app state in the redux state, but sometimes these components dont have an unique key in the redux state because there's an undefined number of instances of your component across the app.

Philosophy

The main goal is to register a unique sub-state for each component that needs it into the redux state, this happens when the component mounts/unmounts.

The data in this state, very much like the data in the component's local state, isn't persistent and is completely discarded in the unmount lifecycle.

Instead of initializing your component's state in its constructor you would do as you would with a redux reducer declaring its initial state in the reducer's definition.

Quick Example

// declaration of your Autocomplete.js component

const Autocomplete = ({ options }) => (
  ...
)

const mapStateToProps = (state /* this is the componet's unique state */) => {
  return {
    options: state.options
  }
}

export default connectUUID('autocomplete', mapStateToProps)(Autocomplete);

// using it somewhere else

<div>
  <Autocomplete />
  <Autocomplete />
  <Autocomplete />
</div>

// each of the Autocomplete components opens up a new key in your app's state

uuid: {
  autocomplete: {
    // autogenerated uuids by this lib
    'bc1de127-0962-43a6-a224-9cc4716da4b6': {...},
    'cc94ccb8-85a3-407a-9fc0-cc895459b422': {...},
    '41952137-e54c-4f9e-be08-07ffe11ee554': {...}
  }
}

API

createUUIDReducer(reducers)

Creates your UUID reducer, make sure to place its result state under state.uuid

Arguments

• reducers (Object<key, reducer>): An object map of reducers, where each <key> sets the reducer's name (see connectUUID(name, ...args))

Returns

A reducer that will filter out redux actions that go through it to the corresponding reducer

Example

const mainAppReducer = combineReducers({
  uuid: createUUIDReducer({
    counter: counterReducer,
    fizzbuzz: fizzbuzzReducer
  })
})

connectUUID(name, [mapStateToProps], [mapDispatchToProps])

Creates a HoC to connect your component to it's corresponding reducer state, its very similar to react-redux's connect. It will inject the uuid prop to the component as well.

• this.props.uuid (String): The component's uuid

Arguments

• name (String): The name of the corresponding reducer that this HoC will use from the reducer object map passed on to createUUIDReducer in the main reducer declaration
• [mapStateToProps]: See react-redux's docs
• [mapDispatchToProps]: See react-redux's docs

Returns

A higher-order React component that injects the inner state and wrapped action creators into your component.

IMPORTANT NOTE: if a component connected this way is provided an uuid prop then the component wont automatically generate its own UUID and it wont unregister the UUID when unmounted, this can be extremely useful when dealing with UUID states that are handled manually, see the examples in the repo to understand how this works

wrapActionCreators(actionCreator, name, [uuid])

Wraps calls to the given action creator, making it so it only applies to reducers within the given name, if the uuid parameter is passed then it will only apply to the only reducer matching the uuid (most times you wont need this).

Arguments

• actionCreator (Function|Object): The action creator to be wrapped, if an object of actions is passed it will wrap all the actions within instead.
• name (String): The name of the reducer that actions will apply to
• [uuid] (String): The name of the uuid of the reducer that the action will apply to, you wont need to use this parameter this most of the time.

Returns

A new action (or object of actions) that will do the same as the action before but it will only apply to reducers that match the criteria.

registerUUID(name, uuid)

An action creator for creating new sub-states into the given collection, useful when you wish to index objects using a custom key

Arguments

• name (String): The name of the collection you wish to register a new sub-state in
• uuid (String|Object<String, Any>): The UUID that matches the new sub-state, can also be an object where the keys are the new UUIDs and the values are the initial states for them

Returns

The action that once dispatched to the state would commit the change

unregisterUUID(name, uuid)

An action creator for removing the sub-states into from given collection

Arguments

• name (String): The name of the collection that contains the uuid
• uuid (String|Array<String>): The UUID that matches the sub-state, can also be an array for batch updates

Returns

The action that once dispatched to the state would commit the change

getUUIDState(state, name, uuid)

A helper for selecting a specific sub-state

Arguments

• state (Object): The whole redux state
• name (String): The name of the collection of sub-states
• uuid (String): The uuid you're looking for

Returns

The sub-state corresponding the query

getRegisteredUUIDs(state, name)

A helper for selecting an array of all the available keys in a collection

Arguments

• state (Object): The whole redux state
• name (String): The name of the collection of sub-states

Returns

An array of UUIDs that are currently registered into the collection