Update isShallowEqual documentation and unit tests by deep comparison

packages/is-shallow-equal/README.md

@@ -29,6 +29,24 @@ import { isShallowEqualArrays } from '@wordpress/is-shallow-equal';
 import { isShallowEqualObjects } from '@wordpress/is-shallow-equal';
 ```
 
+Shallow comparison differs from deep comparison by the fact that it compares members from each as being strictly equal to the other, meaning that arrays and objects will be compared by their _references_, not by their values (see also [_Object Equality in JavaScript_.](http://adripofjavascript.com/blog/drips/object-equality-in-javascript.html)) In situations where nested objects must be compared by value, consider using [Lodash's `isEqual`](https://lodash.com/docs/4.17.11#isEqual) instead.
+
+```js
+import isShallowEqual from '@wordpress/is-shallow-equal';
+import { isEqual } from 'lodash'; // deep comparison
+
+let object = { a: 1 };
+
+isShallowEqual( [ { a: 1 } ], [ { a: 1 } ] );
+// ⇒ false
+
+isEqual( [ { a: 1 } ], [ { a: 1 } ] );
+// ⇒ true
+
+isShallowEqual( [ object ], [ object ] );
+// ⇒ true
+```
+
 ## Rationale
 
 Shallow equality utilities are already a dime a dozen. Since these operations are often at the core of critical hot code paths, the WordPress contributors had specific requirements that were found to only be partially satisfied by existing solutions.

packages/is-shallow-equal/test/index.js

@@ -84,6 +84,14 @@ describe( 'isShallowEqual', () => {
 		expect( isShallowEqual( b, a ) ).toBe( true );
 	} );
 
+	it( 'returns false on object deep-but-referentially-unequal values', () => {
+		const a = { foo: {} };
+		const b = { foo: {} };
+
+		expect( isShallowEqual( a, b ) ).toBe( false );
+		expect( isShallowEqual( b, a ) ).toBe( false );
+	} );
+
 	it( 'returns false if a array has more keys than b', () => {
 		const a = [ 1, 2 ];
 		const b = [ 1 ];