The contents of a source object is merged into the contents of the target object recursively.

EXAMPLE

var result = Uize.mergeInto (
  {foo:{bar:{hello:'world'}}},
  {foo:{bar:{boo:'yah'}}}
);

RESULT

{foo:{bar:{hello:'world',boo:'yah'}}}

Only the contents of plain objects are recursed, and non-plain objects are copied by reference.

EXAMPLE

function CustomObject (value) {this.value = value}

var
  customObject1 = new CustomObject (5),
  customObject2 = new CustomObject (42)
;
customObject1.foo = 'bar';
customObject2.hello = 'world';

var result = Uize.mergeInto (
  {prop:customObject1},
  {prop:customObject2}
);

In the above example, a constructor is created for a custom object called CustomObject. Then, we create two different instances of this object. To each instance, we add extra properties.

Now, when we use the Uize.mergeInto method to merge a source object into a target object, where the value of a prop property in the source object is customObject2 and the value of that same property in the target object is customObject1, the value of the prop property in the target object is simply overwritten with a reference to the customObject2 value contained in the source object - the contents of customObject2 are not merged into customObject1.

In other words, the merge process does not recurse into the properties of the CustomObject instances (or any non-plain objects, for that matter). The Uize.mergeInto method considers custom objects to be values rather than nodes of the object tree.

When the target object being recursed is missing a node, at any level of its structure, that is present in the source object, then the node from the source object is copied by reference - it is not cloned.

EXAMPLE

var
  targetObject = {foo:'bar'},
  sourceObject = {aMissingNode:{hello:'world'}}
;
Uize.mergeInto (targetObject,sourceObject);

alert (targetObject.aMissingNode === sourceObject.aMissingNode);  // alerts "true"

In the above example, the sourceObject object contains the property aMissingNode, whose value is a plain object and represent a node in the object structure that is not present in the targetObject object. When the source object is merged into the target object, this missing node is copied by reference - it is not cloned into the target object. Therefore, the expression target.aMissingNode is identical in a strict equality to sourceObject.aMissingNode.

This same rule applies if the target object contains the property that is contained in the source object, but the value of the property in the target object is not a plain object.

EXAMPLE

var
  targetObject = {someProperty:'foo'},
  sourceObject = {someProperty:{hello:'world'}}
;
Uize.mergeInto (targetObject,sourceObject);

alert (targetObject.someProperty === sourceObject.someProperty);  // alerts "true"

In the above example, the sourceObject object contains the property someProperty, which is also present in the targetObject object. However, the value of this property in the target object is a string, so this value is overwritten with a reference to the object value of the property obtained from the source object. Therefore, the expression target.someProperty is identical in a strict equality to sourceObject.someProperty.

As with the related Uize.copyInto method, specifying the values null or undefined for source object parameters results in those parameters simply being ignored - they contain nothing to merge into the target object.

EXAMPLE

Uize.mergeInto (
  {foo:'bar',junk:{hello:'world'}},
  null,
  {foo:'BAR'},
  undefined,
  {junk:{simple:'simon'}}
);

RESULT

{foo:'BAR',junk:{hello:'world',simple:'simon'}}