|
1 | | -# deep-eql [](https://travis-ci.org/chaijs/deep-eql) [](https://coveralls.io/r/chaijs/deep-eql?branch=master) |
2 | | - |
3 | | -> Improved deep equality testing for Node.js and the browser. |
| 1 | +<h1 align=center> |
| 2 | + <a href="http://chaijs.com" title="Chai Documentation"> |
| 3 | + <img alt="ChaiJS" src="http://chaijs.com/img/chai-logo.png"/> deep-eql |
| 4 | + </a> |
| 5 | +</h1> |
| 6 | + |
| 7 | +<p align=center> |
| 8 | + Improved deep equality testing for [node](http://nodejs.org) and the browser. |
| 9 | +</p> |
| 10 | + |
| 11 | +<p align=center> |
| 12 | + <a href="./LICENSE"> |
| 13 | + <img |
| 14 | + alt="license:mit" |
| 15 | + src="https://img.shields.io/badge/license-mit-green.svg?style=flat-square" |
| 16 | + /> |
| 17 | + </a><a href="https://github.com/chaijs/deep-eql/releases"> |
| 18 | + <img |
| 19 | + alt="tag:?" |
| 20 | + src="https://img.shields.io/github/tag/chaijs/deep-eql.svg?style=flat-square" |
| 21 | + /> |
| 22 | + </a><a href="https://travis-ci.org/chaijs/deep-eql"> |
| 23 | + <img |
| 24 | + alt="build:?" |
| 25 | + src="https://img.shields.io/travis/chaijs/deep-eql/master.svg?style=flat-square" |
| 26 | + /> |
| 27 | + </a><a href="https://coveralls.io/r/chaijs/deep-eql"> |
| 28 | + <img |
| 29 | + alt="coverage:?" |
| 30 | + src="https://img.shields.io/coveralls/chaijs/deep-eql/master.svg?style=flat-square" |
| 31 | + /> |
| 32 | + </a><a href="https://www.npmjs.com/packages/deep-eql"> |
| 33 | + <img |
| 34 | + alt="code quality:?" |
| 35 | + src="https://img.shields.io/codacy/6de187aa62274dbea6e69a3c27e798da.svg?style=flat-square" |
| 36 | + /> |
| 37 | + </a><a href="https://www.npmjs.com/packages/deep-eql"> |
| 38 | + <img |
| 39 | + alt="dependencies:?" |
| 40 | + src="https://img.shields.io/npm/dm/deep-eql.svg?style=flat-square" |
| 41 | + /> |
| 42 | + </a><a href=""> |
| 43 | + <img |
| 44 | + alt="devDependencies:?" |
| 45 | + src="https://img.shields.io/david/chaijs/deep-eql.svg?style=flat-square" |
| 46 | + /> |
| 47 | + </a> |
| 48 | + <br/> |
| 49 | + <a href="https://saucelabs.com/u/chaijs-deep-eql"> |
| 50 | + <img |
| 51 | + alt="Selenium Test Status" |
| 52 | + src="https://saucelabs.com/browser-matrix/chaijs-deep-eql.svg" |
| 53 | + /> |
| 54 | + </a> |
| 55 | + <br> |
| 56 | + <a href="https://chai-slack.herokuapp.com/"> |
| 57 | + <img |
| 58 | + alt="Join the Slack chat" |
| 59 | + src="https://img.shields.io/badge/slack-join%20chat-E2206F.svg?style=flat-square" |
| 60 | + /> |
| 61 | + </a> |
| 62 | + <a href="https://gitter.im/chaijs/deep-eql"> |
| 63 | + <img |
| 64 | + alt="Join the Gitter chat" |
| 65 | + src="https://img.shields.io/badge/gitter-join%20chat-D0104D.svg?style=flat-square" |
| 66 | + /> |
| 67 | + </a> |
| 68 | +</p> |
| 69 | + |
| 70 | +## What is Deep-Eql? |
| 71 | + |
| 72 | +Deep Eql is a module which you can use to determine if two objects are "deeply" equal - that is, rather than having referential equality (`a === b`), this module checks an object's keys recursively, until it finds primitives to check for referential equality. For more on equality in JavaScript, read [the comparison operators article on mdn](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators). |
| 73 | + |
| 74 | +As an example, take the following: |
| 75 | + |
| 76 | +```js |
| 77 | +1 === 1 // These are primitives, they hold the same reference - they are strictly equal |
| 78 | +1 == '1' // These are two different primitives, through type coercion they hold the same value - they are loosely equal |
| 79 | +{ a: 1 } !== { a: 1 } // These are two different objects, they hold different references and so are not strictly equal - even though they hold the same values inside |
| 80 | +{ a: 1 } != { a: 1 } // They have the same type, meaning loose equality performs the same check as strict equality - they are still not equal. |
| 81 | + |
| 82 | +deepEql({ a: 1 }, { a: 1 }) === true // deepEql can determine that they share the same keys and those keys share the same values, therefore they are deeply equal! |
| 83 | +``` |
4 | 84 |
|
5 | 85 | ## Installation |
6 | 86 |
|
|
10 | 90 |
|
11 | 91 | $ npm install deep-eql |
12 | 92 |
|
13 | | -### Component |
14 | | - |
15 | | -`deep-eql` is available as a [component](https://github.com/component/component). |
16 | | - |
17 | | - $ component install chaijs/deep-eql |
18 | | - |
19 | 93 | ## Usage |
20 | 94 |
|
| 95 | +The primary export of `deep-eql` is function that can be given two objects to compare. It will always return a boolean which can be used to determine if two objects are deeply equal. |
| 96 | + |
21 | 97 | ### Rules |
22 | 98 |
|
23 | 99 | - Strict equality for non-traversable nodes according to [egal](http://wiki.ecmascript.org/doku.php?id=harmony:egal). |
|
26 | 102 | - Arguments are not Arrays: |
27 | 103 | - `eql([], arguments).should.be.false;` |
28 | 104 | - `eql([], Array.prototype.slice.call(arguments)).should.be.true;` |
29 | | - |
30 | | -## License |
31 | | - |
32 | | -(The MIT License) |
33 | | - |
34 | | -Copyright (c) 2013 Jake Luer <jake@alogicalparadox.com> |
35 | | - |
36 | | -Permission is hereby granted, free of charge, to any person obtaining a copy |
37 | | -of this software and associated documentation files (the "Software"), to deal |
38 | | -in the Software without restriction, including without limitation the rights |
39 | | -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
40 | | -copies of the Software, and to permit persons to whom the Software is |
41 | | -furnished to do so, subject to the following conditions: |
42 | | - |
43 | | -The above copyright notice and this permission notice shall be included in |
44 | | -all copies or substantial portions of the Software. |
45 | | - |
46 | | -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
47 | | -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
48 | | -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
49 | | -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
50 | | -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
51 | | -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN |
52 | | -THE SOFTWARE. |
|
0 commit comments