feat(extend): optionally deep-extend when last parameter is true

src/Angular.js

@@ -333,27 +333,43 @@ function setHashKey(obj, h) {
  * Extends the destination object `dst` by copying own enumerable properties from the `src` object(s)
  * to `dst`. You can specify multiple `src` objects. If you want to preserve original objects, you can do so
  * by passing an empty object as the target: `var object = angular.extend({}, object1, object2)`.
- * Note: Keep in mind that `angular.extend` does not support recursive merge (deep copy).
  *
  * @param {Object} dst Destination object.
  * @param {...Object} src Source object(s).
+ * @param {boolean=} deep if the last parameter is set to `true`, objects are recursively merged
+ *    (deep copy). Defaults to `false`.
  * @returns {Object} Reference to `dst`.
  */
 function extend(dst) {
   var h = dst.$$hashKey;
+  var argsLength = arguments.length;
+  var isDeep = false;
+  if (argsLength >= 3) {
+    var maybeIsDeep = arguments[argsLength - 1];
+    // Secret code to use deep extend without adding hash keys to destination object properties!
+    if (maybeIsDeep === true || maybeIsDeep === 0xFACECAFE) isDeep = maybeIsDeep;
+  }
+
+  if (isDeep) --argsLength;
 
-  for (var i = 1, ii = arguments.length; i < ii; i++) {
+  for (var i = 1; i < argsLength; i++) {
     var obj = arguments[i];
-    if (obj) {
-      var keys = Object.keys(obj);
-      for (var j = 0, jj = keys.length; j < jj; j++) {
-        var key = keys[j];
-        dst[key] = obj[key];
+    if (!isObject(obj) && !isFunction(obj)) continue;
+    var keys = Object.keys(obj);
+    for (var j = 0, jj = keys.length; j < jj; j++) {
+      var key = keys[j];
+      var src = obj[key];
+
+      if (isDeep && isObject(src)) {
+        if (!isObject(dst[key])) dst[key] = isArray(src) ? [] : {};
+        extend(dst[key], src, 0xFACECAFE);
+      } else {
+        dst[key] = src;
       }
     }
   }
 
-  setHashKey(dst, h);
+  if (isDeep !== 0xFACECAFE) setHashKey(dst, h);
   return dst;
 }
 

test/AngularSpec.js

@@ -223,6 +223,69 @@ describe('angular', function() {
       // make sure we retain the old key
       expect(hashKey(dst)).toEqual(h);
     });
+
+    it('should perform deep extend when last argument is true', function() {
+      var src = { foo: { bar: 'foobar' }},
+          dst = { foo: { bazz: 'foobazz' }};
+      extend(dst, src, true);
+      expect(dst).toEqual({
+        foo: {
+          bar: 'foobar',
+          bazz: 'foobazz'
+        }
+      });
+      expect(dst.foo.$$hashKey).toBeUndefined();
+    });
+
+
+    it('should replace primitives with objects when deep extending', function() {
+      var dst = { foo: "bloop" };
+      var src = { foo: { bar: { baz: "bloop" }}};
+      extend(dst, src, true);
+      expect(dst).toEqual({
+        foo: {
+          bar: {
+            baz: "bloop"
+          }
+        }
+      });
+    });
+
+
+    it('should replace null values with objects when deep extending', function() {
+      var dst = { foo: null };
+      var src = { foo: { bar: { baz: "bloop" }}};
+      extend(dst, src, true);
+      expect(dst).toEqual({
+        foo: {
+          bar: {
+            baz: "bloop"
+          }
+        }
+      });
+    });
+
+
+    it('should not deep extend function-valued sources when deep extending', function() {
+      function fn() {}
+      var dst = { foo: 1 };
+      var src = { foo: fn };
+      extend(dst, src, true);
+      expect(dst).toEqual({
+        foo: fn
+      });
+    });
+
+
+    it('should create a new array if destination property is a non-object and source property is an array when deep-extending', function() {
+      var dst = { foo: NaN };
+      var src = { foo: [1,2,3] };
+      extend(dst, src, true);
+      expect(dst).toEqual({
+        foo: [1,2,3]
+      });
+      expect(dst.foo).not.toBe(src.foo);
+    });
   });
 
   describe('shallow copy', function() {