[major] respectArrayOrder

Author: omgaz

README.md

@@ -47,6 +47,54 @@ const difference = diffler(before, after);
 console.log(difference); // { location: { from: "London", to: "Melbourne" } }
 ```
 
+## Options
+
+> Experimental
+
+```shell
+npm i diffler@next
+```
+
+### `respectArrayOrder` defaults to `true`
+
+If you don't care about the order of an array you can disable like so:
+
+```js
+const diffler = require("diffler");
+
+const before = { name: "omgaz", locations: ["London", "Melbourne"] };
+const after = { name: "omgaz", locations: ["Melbourne", "London"] };
+
+const difference = diffler(before, after, { respectArrayOrder: false });
+console.log(difference); // {}
+```
+
+However, be aware that additions and removals change the overall shape of the array and so will be seen as an entire array change AFTER the addition and removal.
+
+```js
+const diffler = require("diffler");
+
+const before = { name: "omgaz", locations: ["London", "Hong Kong", "Melbourne"] };
+const after = { name: "omgaz", locations: ["London", "Melbourne", "Hong Kong" ] };
+
+const difference = diffler(before, after, { respectArrayOrder: false });
+console.log(difference); // { locations: { 1: { from: "Hong Kong", to: "Melbourne" }, 2: { from: "Melbourne", to: "Hong Kong" }
+```
+
+My advice is to use associative arrays if you do not care about order.
+
+```js
+const diffler = require("diffler");
+
+const before = { name: "omgaz", locations: { Melbourne: "Melbourne", London: "London" } };
+const after = { name: "omgaz", locations: { London: "London", Melbourne: "Melbourne" } };
+
+const difference = diffler(before, after, { respectArrayOrder: false });
+console.log(difference); // { }
+```
+
+Maybe in the future, diffler will do this internally and be able to return array new array indexes for these values, it is still my current belief that arrays are ordered and should preserve order.
+
 ## Tests
 
 [![Build Status](https://travis-ci.org/omgaz/diffler.svg?branch=master)](https://travis-ci.org/omgaz/diffler)

src/index.js

@@ -4,15 +4,16 @@
  */
 
 function isArray(toCheck) {
-  return typeof toCheck === 'object' && Boolean(toCheck.length);
+  return typeof toCheck === "object" && Boolean(toCheck.length);
 }
 
 function isPrimitive(toCheck) {
   return toCheck !== Object(toCheck);
 }
 
-function toPrimitive(val) {
-  return isPrimitive(val) ? val : JSON.stringify(val);
+function validate(val) {
+  if (isPrimitive(val)) return val;
+  throw new Error("Cannot ignore array ordering on non-primitive values");
 }
 
 var defaultOptions = {
@@ -33,7 +34,7 @@ function diffler(obj1, obj2, options = defaultOptions) {
 
   // Iterate over obj1 looking for removals and differences in existing values
   for (var key in obj1) {
-    if (obj1.hasOwnProperty(key) && typeof obj1[key] !== 'function') {
+    if (obj1.hasOwnProperty(key) && typeof obj1[key] !== "function") {
       var obj1Val = obj1[key],
         obj2Val = obj2[key];
 
@@ -46,14 +47,20 @@ function diffler(obj1, obj2, options = defaultOptions) {
       }
 
       // If property is an object then we need to recursively go down the rabbit hole
-      else if (typeof obj1Val === 'object') {
+      else if (typeof obj1Val === "object") {
         var obj1ValForDiff = obj1Val;
         var obj2ValForDiff = obj2Val;
-        if (!options.respectArrayOrder && isArray(obj1Val) && isArray(obj2Val)) {
-          obj1ValForDiff = obj1Val.map(toPrimitive).sort();
-          obj2ValForDiff = obj2Val.map(toPrimitive).sort();
+        if (isArray(obj1Val) && isArray(obj2Val)) {
+          // TODO: This is messy, but I've found a bug with arrays of mixed types
+          // I need to clean this up later.
+          obj1Val.map(validate);
+          obj2Val.map(validate);
+          if (!options.respectArrayOrder) {
+            obj1ValForDiff = obj1Val.sort();
+            obj2ValForDiff = obj2Val.sort();
+          }
         }
-        var tempDiff = diffler(obj1ValForDiff, obj2ValForDiff);
+        var tempDiff = diffler(obj1ValForDiff, obj2ValForDiff, options);
         if (Object.keys(tempDiff).length > 0) {
           if (tempDiff) {
             diff[key] = tempDiff;
@@ -73,7 +80,7 @@ function diffler(obj1, obj2, options = defaultOptions) {
 
   // Iterate over obj2 looking for any new additions
   for (key in obj2) {
-    if (obj2.hasOwnProperty(key) && typeof obj2[key] !== 'function') {
+    if (obj2.hasOwnProperty(key) && typeof obj2[key] !== "function") {
       var obj1Val = obj1[key],
         obj2Val = obj2[key];