preserve referential equality when possible

Author: kolodny

README.md

@@ -31,6 +31,11 @@ const withTax = update(state, {
 });
 assert(JSON.stringify(withTax) === JSON.stringify({ price: 221.4 });
 ```
+
+Note that `original` in the function above is the original object, so if you plan making a
+mutation, you must first shallow clone the object. Another option is to
+use `update` to make the change `return update(original, { foo: {$set: 'bar'} })`
+
 If you don't want to mess around with the globally exported `update` function you can make a copy and work with that copy:
 
 ```js

index.js

@@ -40,14 +40,21 @@ function newContext() {
       '$set'
     );
 
-    var newObject = copy(object);
+    var newObject = object;
     for (var key in spec) {
       if (hasOwnProperty.call(commands, key)) {
-        return commands[key](spec[key], newObject, spec);
+        return commands[key](spec[key], newObject, spec, object);
       }
     }
     for (var key in spec) {
-      newObject[key] = update(object[key], spec[key]);
+      var nextValueForKey = update(object[key], spec[key]);
+      if (nextValueForKey === object[key]) {
+        continue;
+      }
+      if (newObject === object) {
+        newObject = copy(object);
+      }
+      newObject[key] = nextValueForKey;
     }
     return newObject;
   }
@@ -63,24 +70,26 @@ var defaultCommands = {
     invariantPushAndUnshift(original, spec, '$unshift');
     return value.concat(original);
   },
-  $splice: function(value, original, spec) {
-    invariantSplices(original, spec);
+  $splice: function(value, newObject, spec, object) {
+    var originalValue = newObject === object ? copy(object) : newObject;
+    invariantSplices(originalValue, spec);
     value.forEach(function(args) {
       invariantSplice(args);
-      splice.apply(original, args);
+      splice.apply(originalValue, args);
     });
-    return original;
+    return originalValue;
   },
   $set: function(value, original, spec) {
     invariantSet(spec);
-    return value
+    return value;
   },
-  $merge: function(value, original, spec) {
-    invariantMerge(original, value);
+  $merge: function(value, newObject, spec, object) {
+    var originalValue = newObject === object ? copy(object) : newObject;
+    invariantMerge(originalValue, value);
     Object.keys(value).forEach(function(key) {
-      original[key] = value[key];
+      originalValue[key] = value[key];
     });
-    return original;
+    return originalValue;
   },
   $apply: function(value, original) {
     invariantApply(value);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "immutability-helper",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "mutate a copy of data without changing the original source",
   "main": "index.js",
   "scripts": {

test.js

@@ -103,6 +103,11 @@ describe('update', function() {
       update(obj, {$set: {c: 'd'}});
       expect(obj).toEqual({a: 'b'});
     });
+    it('keeps reference equality when possible', function() {
+      var original = {a: 1};
+      expect(update(original, {a: {$set: 1}})).toBe(original);
+      expect(update(original, {a: {$set: 2}})).toNotBe(original);
+    });
   });
 
   describe('$apply', function() {
@@ -122,38 +127,82 @@ describe('update', function() {
         'update(): expected spec of $apply to be a function; got 123.'
       );
     });
+    it('keeps reference equality when possible', function() {
+      var original = {a: {b: {}}};
+      function identity(val) {
+       return val;
+      }
+      expect(update(original, {a: {$apply: identity}})).toBe(original);
+      expect(update(original, {a: {$apply: applier}})).toNotBe(original);
+    });
   });
 
-  it('should support deep updates', function() {
-    expect(update({
-      a: 'b',
-      c: {
-        d: 'e',
-        f: [1],
-        g: [2],
-        h: [3],
-        i: {j: 'k'},
-        l: 4,
-      },
-    }, {
-      c: {
-        d: {$set: 'm'},
-        f: {$push: [5]},
-        g: {$unshift: [6]},
-        h: {$splice: [[0, 1, 7]]},
-        i: {$merge: {n: 'o'}},
-        l: {$apply: function(x) { return x * 2 } },
-      },
-    })).toEqual({
-      a: 'b',
-      c: {
-        d: 'm',
-        f: [1, 5],
-        g: [6, 2],
-        h: [7],
-        i: {j: 'k', n: 'o'},
-        l: 8,
-      },
+  describe('deep update', function() {
+    it('works', function() {
+      expect(update({
+        a: 'b',
+        c: {
+          d: 'e',
+          f: [1],
+          g: [2],
+          h: [3],
+          i: {j: 'k'},
+          l: 4,
+        },
+      }, {
+        c: {
+          d: {$set: 'm'},
+          f: {$push: [5]},
+          g: {$unshift: [6]},
+          h: {$splice: [[0, 1, 7]]},
+          i: {$merge: {n: 'o'}},
+          l: {$apply: function(x) { return x * 2; }},
+        },
+      })).toEqual({
+        a: 'b',
+        c: {
+          d: 'm',
+          f: [1, 5],
+          g: [6, 2],
+          h: [7],
+          i: {j: 'k', n: 'o'},
+          l: 8,
+        },
+      });
+    });
+    it('keeps reference equality when possible', function() {
+      var original = {a: {b: 1}, c: {d: {e: 1}}};
+
+      expect(update(original, {a: {b: {$set: 1}}})).toBe(original);
+      expect(update(original, {a: {b: {$set: 1}}}).a).toBe(original.a);
+
+      expect(update(original, {c: {d: {e: {$set: 1}}}})).toBe(original);
+      expect(update(original, {c: {d: {e: {$set: 1}}}}).c).toBe(original.c);
+      expect(update(original, {c: {d: {e: {$set: 1}}}}).c.d).toBe(original.c.d);
+
+      expect(update(original, {
+        a: {b: {$set: 1}},
+        c: {d: {e: {$set: 1}}},
+      })).toBe(original);
+      expect(update(original, {
+        a: {b: {$set: 1}},
+        c: {d: {e: {$set: 1}}},
+      }).a).toBe(original.a);
+      expect(update(original, {
+        a: {b: {$set: 1}},
+        c: {d: {e: {$set: 1}}},
+      }).c).toBe(original.c);
+      expect(update(original, {
+        a: {b: {$set: 1}},
+        c: {d: {e: {$set: 1}}},
+      }).c.d).toBe(original.c.d);
+
+      expect(update(original, {a: {b: {$set: 2}}})).toNotBe(original);
+      expect(update(original, {a: {b: {$set: 2}}}).a).toNotBe(original.a);
+      expect(update(original, {a: {b: {$set: 2}}}).a.b).toNotBe(original.a.b);
+
+      expect(update(original, {a: {b: {$set: 2}}}).c).toBe(original.c);
+      expect(update(original, {a: {b: {$set: 2}}}).c.d).toBe(original.c.d);
     });
   });
 
@@ -188,6 +237,16 @@ describe('update', function() {
       expect(myUpdate(5, {$addtax: 0.10})).toEqual(5.5);
     });
 
+    it('gets the original object (so be careful about mutations)', function() {
+      var obj = {};
+      var passedOriginal;
+      myUpdate.extend('$foobar', function(prop, original) {
+        passedOriginal = original;
+      });
+      myUpdate(obj, {$foobar: null});
+      expect(obj).toBe(passedOriginal);
+    });
+
     it("doesn't touch the original update", function() {
       myUpdate.extend('$addtax', function(tax, original) {
         return original + (tax * original);