1# react-fast-compare 2 3The fastest deep equal comparison for React. Really fast general-purpose deep comparison. 4Great for`shouldComponentUpdate`. This is a fork of the brilliant 5[fast-deep-equal](https://github.com/epoberezkin/fast-deep-equal) with some 6extra handling for React. 7 8[![Travis Status][trav_img]][trav_site] 9[![AppVeyor Status][appveyor_img]][appveyor_site] 10[![npm version][npm_img]][npm_site] 11[![size_minzip][size_minzip]][size_site] 12[![size_min][size_min]][size_site] 13 14![benchmark chart](assets/benchmarking.png "benchmarking chart") 15 16(Check out the [benchmarking details](#benchmarking-this-library).) 17 18## Install 19 20```sh 21$ yarn add react-fast-compare 22# or 23$ npm install react-fast-compare 24``` 25 26## Highlights 27 28* ES5 compatible; works in node.js (0.10+) and browsers (IE9+) 29* deeply compares any value (besides objects with circular references) 30* handles React-specific circular references, like elements 31* checks equality Date and RegExp objects 32* should be just as fast as [fast-deep-equal](https://github.com/epoberezkin/fast-deep-equal) for general use, and faster for React use 33* small: under 600 bytes minified+gzipped 34 35## Usage 36 37```jsx 38const isEqual = require("react-fast-compare"); 39 40// general usage 41console.log(isEqual({ foo: "bar" }, { foo: "bar" })); // true 42 43// react usage 44class ExpensiveRenderer extends React.Component { 45 shouldComponentUpdate(nextProps) { 46 return !isEqual(this.props, nextProps); 47 } 48 render() { 49 // ... 50 } 51} 52``` 53 54## Do I Need `shouldComponentUpdate`? 55 56> What's faster than a really fast deep comparison? No deep comparison at all. 57 58—This Readme 59 60Deep checks in React's `shouldComponentUpdate` should not be used blindly. 61First, see if a 62[PureComponent](https://reactjs.org/docs/react-api.html#reactpurecomponent) 63would work for you. If it won't (if you need deep checks), it's wise to make 64sure you've correctly indentified the bottleneck in your application by 65[profiling the performance](https://reactjs.org/docs/optimizing-performance.html#profiling-components-with-the-chrome-performance-tab). 66After you've determined that you _do_ need deep equality checks and you've 67identified the minimum number of places to apply them, then this library may 68be for you! For more information about making your app faster, check out the 69[Optimizing Performance](https://reactjs.org/docs/optimizing-performance.html) 70section of the React docs. 71 72## Benchmarking this Library 73 74All tests carried out locally on a MacBook. The absolute values are much less 75important than the relative differences between packages. 76 77Benchmarking source can be found 78[here](https://github.com/FormidableLabs/react-fast-compare/blob/master/node/tests.js). 79Each "operation" consists of running all relevant tests. The React benchmark 80uses both the generic tests and the react tests; these runs will be slower 81simply because there are more tests in each operation. 82 83### Generic Data 84 85``` 86react-fast-compare x 207,503 ops/sec ±0.54% (92 runs sampled) 87fast-deep-equal x 195,006 ops/sec ±0.70% (91 runs sampled) 88lodash.isEqual x 43,778 ops/sec ±0.55% (91 runs sampled) 89nano-equal x 198,036 ops/sec ±0.37% (95 runs sampled) 90shallow-equal-fuzzy x 173,023 ops/sec ±0.59% (95 runs sampled) 91 fastest: react-fast-compare 92``` 93 94`react-fast-compare` and `fast-deep-equal` should be the same speed for these 95tests; any difference is just noise. `react-fast-compare` won't be faster than 96`fast-deep-equal`, because it's based on it. 97 98### React and Generic Data 99 100``` 101react-fast-compare x 187,628 ops/sec ±0.58% (93 runs sampled) 102fast-deep-equal x 477 ops/sec ±0.55% (91 runs sampled) 103lodash.isEqual x 35,100 ops/sec ±0.16% (95 runs sampled) 104nano-equal x 468 ops/sec ±0.53% (94 runs sampled) 105shallow-equal-fuzzy x 684 ops/sec ±0.43% (92 runs sampled) 106 fastest: react-fast-compare 107``` 108 109Three of these packages cannot handle comparing React elements (which are 110circular): `fast-deep-equal`, `nano-equal`, and `shallow-equal-fuzzy`. 111 112### Running Benchmarks 113 114```sh 115$ yarn install 116$ yarn run benchmark 117``` 118 119## fast-deep-equal Versioning 120 121react-fast-compare@2.0.0 tracks fast-deep-equal@2.0.1 122 123## License 124 125[MIT](https://github.com/FormidableLabs/react-fast-compare/blob/readme/LICENSE) 126 127## Contributing 128 129Please see our [contributions guide](./CONTRIBUTING.md). 130 131[trav_img]: https://api.travis-ci.org/FormidableLabs/react-fast-compare.svg 132[trav_site]: https://travis-ci.org/FormidableLabs/react-fast-compare 133[cov_img]: https://img.shields.io/coveralls/FormidableLabs/react-fast-compare.svg 134[cov_site]: https://coveralls.io/r/FormidableLabs/react-fast-compare 135[npm_img]: https://badge.fury.io/js/react-fast-compare.svg 136[npm_site]: http://badge.fury.io/js/react-fast-compare 137[appveyor_img]: https://ci.appveyor.com/api/projects/status/github/formidablelabs/react-fast-compare?branch=master&svg=true 138[appveyor_site]: https://ci.appveyor.com/project/FormidableLabs/react-fast-compare 139[size_min]: https://img.shields.io/bundlephobia/min/react-fast-compare.svg 140[size_minzip]: https://img.shields.io/bundlephobia/minzip/react-fast-compare.svg 141[size_site]: https://bundlephobia.com/result?p=react-fast-compare 142