Repository files navigation

A library for creating memoized "selector" functions. Commonly used with Redux, but usable with any plain JS immutable data as well.

• Selectors can compute derived data, allowingRedux to store the minimal possible state.
• Selectors are efficient. A selector is not recomputed unless one of its arguments changes.
• Selectors are composable. They can be used as input to other selectors.

TheRedux docs usage page onDeriving Data with Selectors covers the purpose and motivation for selectors, why memoized selectors are useful, typical Reselect usage patterns, and using selectors withReact-Redux.

While Reselect is not exclusive toRedux, it is already included by default inthe official Redux Toolkit package - no further installation needed.

import{createSelector}from'@reduxjs/toolkit'

For standalone usage, install thereselect package:

# NPMnpm install reselect# Yarnyarn add reselect

The Reselect docs are available athttps://reselect.js.org, and include usage guides and API references:

• Introduction
• How Does Reselect Work?
• API Reference:
  • createSelector
  • createSelectorCreator
  • createStructuredSelector
  • Development-Only Stability Checks
  • lruMemoize
  • weakMapMemoize
• FAQ

Reselect exports acreateSelector API, which generates memoized selector functions.createSelector accepts one or moreinput selectors, which extract values from arguments, and aresult function function that receives the extracted values and should return a derived value. If the generatedoutput selector is called multiple times, the output will only be recalculated when the extracted values have changed.

You can play around with the followingexample inthis CodeSandbox:

import{createSelector}from'reselect'interfaceRootState{todos:{id:number;completed:boolean}[]alerts:{id:number;read:boolean}[]}conststate:RootState={todos:[{id:0,completed:false},{id:1,completed:true}],alerts:[{id:0,read:false},{id:1,read:true}]}constselectCompletedTodos=(state:RootState)=>{console.log('selector ran')returnstate.todos.filter(todo=>todo.completed===true)}selectCompletedTodos(state)// selector ranselectCompletedTodos(state)// selector ranselectCompletedTodos(state)// selector ranconstmemoizedSelectCompletedTodos=createSelector([(state:RootState)=>state.todos],todos=>{console.log('memoized selector ran')returntodos.filter(todo=>todo.completed===true)})memoizedSelectCompletedTodos(state)// memoized selector ranmemoizedSelectCompletedTodos(state)memoizedSelectCompletedTodos(state)console.log(selectCompletedTodos(state)===selectCompletedTodos(state))//=> falseconsole.log(memoizedSelectCompletedTodos(state)===memoizedSelectCompletedTodos(state))//=> true

As you can see from the example above,memoizedSelectCompletedTodos does not run the second or third time, but we still get the same return value as last time.

In addition to skipping unnecessary recalculations,memoizedSelectCompletedTodos returns the existing result reference if there is no recalculation. This is important for libraries likeReact-Redux orReact that often rely on reference equality checks to optimize UI updates.

• Selector Function: A function that accepts one or more JavaScript values as arguments, and derives a result. When used withRedux, the first argument is typically the entire Redux store state.
• input selectors: Basic selector functions used as building blocks for creating a memoized selector. They are passed as the first argument(s) tocreateSelector, and are called with all selector arguments. They are responsible for extracting and providing necessary values to theresult function.
• Output Selector: The actual memoized selectors created bycreateSelector.
• Result Function: The function that comes after theinput selectors. It takes theinput selectors' return values as arguments and returns a result.
• Dependencies: Same asinput selectors. They are what theoutput selector "depends" on.

The below example serves as a visual aid:

constoutputSelector=createSelector([inputSelector1,inputSelector2,inputSelector3],// synonymous with `dependencies`.resultFunc// Result function)

Version 5.0.0 introduces several new features and improvements:

• Customization Enhancements:

  • Added the ability to pass an options object tocreateSelectorCreator, allowing for customizedmemoize andargsMemoize functions, alongside their respective options (memoizeOptions andargsMemoizeOptions).
  • ThecreateSelector function now supports direct customization ofmemoize andargsMemoize within its options object.

• Memoization Functions:

  • Introduced new experimental memoization functions:weakMapMemoize andunstable_autotrackMemoize.
  • Incorporatedmemoize andargsMemoize into theoutput selector fields for debugging purposes.

• TypeScript Support and Performance:

  • Discontinued support for TypeScript versions below 4.7, aligning with modern TypeScript features.
  • Significantly improved TypeScript performance for nestingoutput selectors. The nesting limit has increased from approximately 8 to around 30output selectors, greatly reducing the occurrence of the infamousType instantiation is excessively deep and possibly infinite error.

• Selector API Enhancements:

  • Removed the second overload ofcreateStructuredSelector due to its susceptibility to runtime errors.

• Additional Functionalities:

  • AddeddependencyRecomputations andresetDependencyRecomputations to theoutput selector fields. These additions provide greater control and insight overinput selectors, complementing the newargsMemoize API.
  • IntroducedinputStabilityCheck, a development tool that runs theinput selectors twice using the same arguments and triggers a warning If they return differing results for the same call.
  • IntroducedidentityFunctionCheck, a development tool that checks to see if theresult function returns its own input.

These updates aim to enhance flexibility, performance, and developer experience. For detailed usage and examples, refer to the updated documentation sections for each feature.

• Breaking Changes:

  • RemovedParametricSelector andOutputParametricSelector types. Their functionalities are now integrated intoSelector andOutputSelector respectively, which inherently support additional parameters.

MIT