In the context of a property comparer function, a property profile is either...

When the property profile is an object value, it will be of the form...

{
  key:keySTR,     // the name of the property
  value:valueSTR  // the value of the property
}

There are a few things to note about the property profile that is returned by the property comparer function...

In order to obtain the values for all properties that have been added or modified in the second object, the following property comparer function can be used...

function (obj1PropProfile,obj2PropProfile) {
  return (
    obj2PropProfile && (!obj1PropProfile || obj2PropProfile.value !== obj1PropProfile.value)
      ? obj2PropProfile
      : undefined
  );
}

In order to obtain a summary of just the differences between two objects, the following property comparer function can be used...

function (obj1PropProfile,obj2PropProfile) {
  return {
    obj1PropProfile && !obj2PropProfile
      ? {value:'removed'}
      : !obj1PropProfile && obj2PropProfile
        ? {value:'added'}
        : obj1PropProfile.value === obj2PropProfile.value
          ? undefined
          : {value:'modified'}
  };
}

If the above property compater function is used when comparing two objects and the object returned by the Uize.Data.Diff.diff method is empty, then the objects being compared can be considered identical.

In order to obtain a summary of just the structural differences between two objects, the following property comparer function can be used...

function (obj1PropProfile,obj2PropProfile) {
  return {
    obj1PropProfile && !obj2PropProfile
      ? {value:'removed'}
      : !obj1PropProfile && obj2PropProfile
        ? {value:'added'}
        : undefined
  };
}

If the above property compater function is used when comparing two objects and the object returned by the Uize.Data.Diff.diff method is empty, then the objects being compared can be considered to have identical structure - even if the values of the properties may differ between the two objects.

In order to obtain a summary of just the structural and type differences between two objects, the following property comparer function can be used...

function (obj1PropProfile,obj2PropProfile) {
  return {
    obj1PropProfile && !obj2PropProfile
      ? {value:'removed'}
      : !obj1PropProfile && obj2PropProfile
        ? {value:'added'}
        : typeof obj1PropProfile.value !== typeof obj2PropProfile.value
          ? {value:'type mismatch'}
          : undefined
  };
}

If the above property compater function is used when comparing two objects and the object returned by the Uize.Data.Diff.diff method is empty, then the objects being compared can be considered to have identical structure and type. This can be a useful way of testing if an object conforms to the structure and type requirements of some reference object.

In order to obtain the values for all properties that are identical in the objects being compared, the following property comparer function can be used...

function (obj1PropProfile,obj2PropProfile) {
  return (
    obj1PropProfile && obj2PropProfile && obj1PropProfile.value === obj2PropProfile.value
      ? obj1PropProfile
      : undefined
  );
}

In order to conditionally merge all properties of a second object with all properties of a first object, so that a property from the second object is only merged in if it doesn't exist in the first object, the following property comparer function can be used...

function (obj1PropProfile,obj2PropProfile) {
  return obj1PropProfile || obj2PropProfile;
}

EXAMPLE

Uize.Data.Diff.diff (
  {
    foo:'foo',
    bar:{
      baz:'baz'
    }
  },
  {
    foo:'FOO',
    bar:{
      baz:'BAZ',
      qux:'QUX'
    }
  },
  function (obj1PropProfile,obj2PropProfile) {
    return obj1PropProfile || obj2PropProfile;
  }
);

RESULT

{
  foo:'foo',
  bar:{
    baz:'baz',
    qux:'QUX'
  }
}

The Uize.Data.Diff.diff method can be used in a less conventional way to create an initialized clone of a source object using the following approach...

EXAMPLE

Uize.Data.Diff.diff (
  {
    foo:'foo',
    bar:{baz:{qux:'qux'}}
  },
  {},
  function () {return {value:''}}
);

RESULT

{
  foo:'',
  bar:{baz:{qux:''}}
}

The Uize.Data.Diff.diff method can be used to recursively iterate over all the leaf nodes of an object.

EXAMPLE

Uize.Data.Diff.diff (
  sourceObj,  // the object you wish to iterate over
  {},         // specify an empty object for the second object
  function (propertyProfile) {
    // do something for each leaf node
  }
);

When using the Uize.Data.Diff.diff method as essentially an object iterator, the first argument can be used for specifying the object you wish to iterate over, and an empty object can be specified for the second object.

Then, in the property comparer function that you specify, the information about the leaf node property currently being iterated over can be accessed from the first property profile argument, and the second argument can be ignored.

The Uize.Data.Diff.diff method can be used to map values for all the leaf nodes of an object.

EXAMPLE

var remappedValuesObj = Uize.Data.Diff.diff (
  sourceObj,  // the object you wish to iterate over
  {},         // specify an empty object for the second object
  function (propertyProfile) {
    // modify the value property of the propertyProfile argument
    return propertyProfile;
  }
);

When using the Uize.Data.Diff.diff method as a value mapper for object properties, the first argument can be used for specifying the object you wish to map, and an empty object can be specified for the second object.

Then, in the property comparer function that you specify, the information about the leaf node property currently being iterated over can be accessed from the first property profile argument, and the second argument can be ignored. In order to map the value for a property, simply modify the value property of the property profile object and return this modified object as the result.

EXAMPLE

Uize.Data.Diff.diff (
  {
    foo:'foo',
    bar:{baz:{qux:'qux'}}
  },
  {},
  function (propertyProfile) {
    propertyProfile.value = propertyProfile.value.toUpperCase ();
    return propertyProfile;
  }
);

RESULT

{
  foo:'FOO',
  bar:{baz:{qux:'QUX'}}
}

The Uize.Data.Diff.diff method can be used to rename keys for all the leaf nodes of an object.

EXAMPLE

var renamedKeysObj = Uize.Data.Diff.diff (
  sourceObj,  // the object you wish to iterate over
  {},         // specify an empty object for the second object
  function (propertyProfile) {
    // modify the key property of the propertyProfile argument
    return propertyProfile;
  }
);

When using the Uize.Data.Diff.diff method as a key renamer for object leaf node properties, the first argument can be used for specifying the source object, and an empty object can be specified for the second object.

Then, in the property comparer function that you specify, the information about the leaf node property currently being iterated over can be accessed from the first property profile argument, and the second argument can be ignored. In order to rename the key for a property, simply modify the key property of the property profile object and return this modified object as the result.

EXAMPLE

Uize.Data.Diff.diff (
  {
    foo:'foo',
    bar:{baz:{qux:'qux'}}
  },
  {},
  function (propertyProfile) {
    propertyProfile.key = propertyProfile.key.toUpperCase ();
    return propertyProfile;
  }
);

RESULT

{
  FOO:'foo',
  bar:{baz:{QUX:'qux'}}
}

Notice from the above example that not all keys have been renamed - only the keys for the leaf node properties. This is because the property comparer function is only called for leaf node properties.

A boolean, specifying whether or not a structural skeleton will be returned at a minimum when two objects are compared that either have empty nodes or where the property comparer function returns undefined for all compared properties.

EXAMPLE

Uize.Data.Diff.diff (
  {
    address:{
      mailing:{
        line1:'123 Strange Blvd',
        line2:'Apt 6',
        city:'Strangeville',
        state:'CA',
        zip:'12345'
      }
    },
    contact:{
      phoneNumbers:{
        home:'(555) 123-4567',
        cell:'(555) 555-5555',
        work:'(555) 999-9999'
      }
    }
  },
  {
    address:{
      shipping:{
        line1:'456 Work Plaze',
        line2:'Suite 400',
        city:'Workville',
        state:'CA',
        zip:'67890'
      }
    },
    contact:{
      other:{
        email:'[email protected]',
        IRC:'mstrange'
      }
    }
  },
  function () {return undefined},
  {skeleton:true}
);

In the above example, two objects are being compared that have similar but slightly differing structures. The custom property comparer function that is being specified always returns the value undefined. Normally, this would mean that the comparison result object would be empty. But, because the value true is being specified for the skeleton option, the method returns a skeleton object that is the union of the structures of the two objects being compared, as shown below...

RESULT

{
  address:{
    mailing:{},
    shipping:{}
  },
  contact:{
    phoneNumbers:{},
    other:{}
  }
}