reselect-map

Selectors for mapping over collections.

Installation

1npm install reselect-map reselect

Usage

This package exposes a few special selector creators. They're mostly the same as reselect's createSelector, with one major difference: the first dependency gets mapped over.

To give you a better idea, here's an example of how a selector to multiply an array of numbers would look in basic reselect and then using reselect-map.

1import { createSelector } from "reselect";
2import { createArraySelector } from "reselect-map";
3
4const exampleState = {
5  numbers: [1, 2, 3],
6  multiplier: 5,
7};
8
9const numbers = (state) => state.numbers;
10const multiplier = (state) => state.multiplier;
11
12// reselect
13const mul1 = createSelector([numbers, multiplier], (numbers, multiplier) =>
14  numbers.map((n) => n * multiplier)
15);
16
17// reselect-map
18const mul2 = createArraySelector(
19  [numbers, multiplier],
20  (number, multiplier) => number * multiplier
21);
22
23// Result: [5, 10, 15]

Notice the second version uses number instead of numbers; the result function is passed each element of numbers instead of the whole thing, and then the results are reassembled into an array.

So why would you use this? The answer is that you probably shouldn't! However, in certain situations it may significantly improve performance. Learn more in the motivation section.

API

The only thing to know is that the first dependency/selector passed is the one that gets mapped over, and all other selectors work just like they do in reselect proper. Additionally, key-based selectors like createObjectSelector and createMapSelector pass the key as the final argument.

NOTICE: This package makes use of the builtin Set and Map. If you need to support environments without Set or Map, you are going to have to polyfill it.

createArraySelector

Takes in an array, runs each element through the result function, and returns the results in a new array.

1import { createArraySelector } from "reselect-map";
2
3const exampleState = {
4  numbers: [1, 2, 3],
5  multiplier: 5,
6};
7
8const mul = createArraySelector(
9  (state) => state.numbers,
10  (state) => state.multiplier,
11  (number, multiplier) => number * multiplier
12);
13
14console.log(mul(exampleState)); // [5, 10, 15]

createObjectSelector

Takes an object, runs the value at each key through the result function, and returns an object with the results. The key is passed as the last argument to the selector function.

1import { createObjectSelector } from "reselect-map";
2
3const exampleState = {
4  numbers: { a: 1, b: 2 },
5  multiplier: 5,
6};
7
8const mul = createObjectSelector(
9  (state) => state.numbers,
10  (state) => state.multiplier,
11  (number, multiplier, key) => `${key}:${number * multiplier}`
12);
13
14console.log(mul(exampleState)); // { a: 'a:5', b: 'b:10' }

createListSelector

Takes anything with an array-like map function, and returns whatever that returns. This conveniently makes it compatible with Immutable js collections and similar without erasing the input type.

1import { createListSelector } from "reselect-map";
2import Immutable from "immutable";
3
4const exampleState = {
5  numbers: Immutable.List([1, 2, 3]),
6  multiplier: 5,
7};
8
9const mul = createListSelector(
10  (state) => state.numbers,
11  (state) => state.multiplier,
12  (number, multiplier) => number * multiplier
13);
14
15console.log(String(mul(exampleState))); // List [5, 10, 15]

createMapSelector

Like the sequence selector, but it expects the map function to provide a second argument to the callback that represents the key. This key is passed as the last argument to the selector function. This is mostly to support Immutable's Collection.Keyed types.

1import { createMapSelector } from "reselect-map";
2import Immutable from "immutable";
3
4const exampleState = {
5  numbers: Immutable.Map({ a: 1, b: 2 }),
6  multiplier: 5,
7};
8
9const mul = createMapSelector(
10  (state) => state.numbers,
11  (state) => state.multiplier,
12  (number, multiplier, key) => `${key}:${number * multiplier}`
13);
14
15console.log(String(mul(exampleState))); // Map { "a": "a:5", "b": "b:10" }

Need more?

I'm hoping that what I've got here covers most common use cases, but it's not difficult to expand. Please let me know if there are any other selector types you'd like, or submit a pull request!

Motivation

When doing very expensive computations on elements of a collection, reselect might not give you the granularity of caching that you need. Imagine a selector that looks like this:

1import { createSelector } from "reselect";
2
3const expensiveSelector = createSelector(
4  (state) => state.largeArray,
5  (largeArray) => largeArray.map(expensiveFunction)
6);

Notice that every time largeArray is changed, every single element of the array will be run back through expensiveFunction. If largeArray is very large or expensiveFunction is very expensive, this could be very slow.

What would be better is if we only recomputed those elements that are new or have changed. That's what this package does. Your expensiveFunction only runs on the elements it needs to.

When shouldn't you use reselect-map

When you don't need it. If your selector takes an array and multiplies every element by five (like in all of the examples), this package will slow your code down. In situations where you're having performance issues with reselect and you're thinking about how to cache on an element level, this package is here for you.