Merge pull request #25 from darthrellimnad/ignore-branches

ignore mutation detection for specified branches

README.md

@@ -43,3 +43,26 @@ const store = createStore(
 ```
 
 Then if you're doing things correctly, you should see nothing different. But if you don't, that is, if you're mutating your data somewhere in your app either in a dispatch or between dispatches, an error will be thrown with a (hopefully) descriptive message.
+
+## API
+
+#### `immutableStateInvariantMiddleware({ isImmutable, ignore })`
+
+Middleware creation function and default export. Supports an optional `object` argument to customize middleware behavior with supported options.
+
+**Parameters**
+
+- **isImmutable** `function` - override default "isImmutable" implementation (see: `src/isImmutable.js`). function must accept a single argument and return `true` if the value should be considered immutable, `false` otherwise.
+
+    ```js
+    // example: use a custom `isImmutable` implementation
+    const mw = immutableStateInvariantMiddleware({ isImmutable: customIsImmutable })
+    ```
+- **ignore** `string[]` - specify branch(es) of state to ignore when detecting for mutations. elements of array should be dot-separated "path" strings that match named nodes from the root state.
+
+    ```js
+    // example: ignore mutation detection along the 'foo' & 'bar.thingsToIgnore' branches
+    const mw = immutableStateInvariantMiddleware({ ignore: ['foo', 'bar.thingsToIgnore'] })
+    ```
+
+Returns: `function` - the middleware function

src/index.js

@@ -15,8 +15,12 @@ const INSIDE_DISPATCH_MESSAGE = [
   '(http://redux.js.org/docs/Troubleshooting.html#never-mutate-reducer-arguments)'
 ].join(' ');
 
-export default function immutableStateInvariantMiddleware(isImmutable = isImmutableDefault) {
-  const track = trackForMutations.bind(null, isImmutable);
+export default function immutableStateInvariantMiddleware(options = {}) {
+  const {
+    isImmutable = isImmutableDefault,
+    ignore
+  } = options
+  const track = trackForMutations.bind(null, isImmutable, ignore);
 
   return ({getState}) => {
     let state = getState();

src/trackForMutations.js

@@ -1,26 +1,36 @@
-export default function trackForMutations(isImmutable, obj) {
-  const trackedProperties = trackProperties(isImmutable, obj);
+export default function trackForMutations(isImmutable, ignore, obj) {
+  const trackedProperties = trackProperties(isImmutable, ignore, obj);
   return {
     detectMutations() {
-      return detectMutations(isImmutable, trackedProperties, obj);
+      return detectMutations(isImmutable, ignore, trackedProperties, obj);
     }
   };
 }
 
-function trackProperties(isImmutable, obj) {
+function trackProperties(isImmutable, ignore = [], obj, path = []) {
   const tracked = { value: obj };
 
   if (!isImmutable(obj)) {
     tracked.children = {};
 
     for (const key in obj) {
-      tracked.children[key] = trackProperties(isImmutable, obj[key]);
+      const childPath = path.concat(key);
+      if (ignore.length && ignore.indexOf(childPath.join('.')) !== -1) {
+        continue;
+      }
+
+      tracked.children[key] = trackProperties(
+        isImmutable,
+        ignore,
+        obj[key],
+        childPath
+      );
     }
   }
   return tracked;
 }
 
-function detectMutations(isImmutable, trackedProperty, obj, sameParentRef = false, path = []) {
+function detectMutations(isImmutable, ignore = [], trackedProperty, obj, sameParentRef = false, path = []) {
   const prevObj = trackedProperty ? trackedProperty.value : undefined;
 
   const sameRef = prevObj === obj;
@@ -45,12 +55,18 @@ function detectMutations(isImmutable, trackedProperty, obj, sameParentRef = fals
   const keys = Object.keys(keysToDetect);
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i];
+    const childPath = path.concat(key);
+    if (ignore.length && ignore.indexOf(childPath.join('.')) !== -1) {
+      continue;
+    }
+
     const result = detectMutations(
       isImmutable,
+      ignore,
       trackedProperty.children[key],
       obj[key],
       sameRef,
-      path.concat(key)
+      childPath
     );
 
     if (result.wasMutated) {

test/index.spec.js

@@ -5,8 +5,8 @@ describe('immutableStateInvariantMiddleware', () => {
   let state;
   const getState = () => state;
 
-  function middleware(next) {
-    return immutableStateInvariantMiddleware()({getState})(next);
+  function middleware(options) {
+    return immutableStateInvariantMiddleware(options)({getState});
   }
 
   beforeEach(() => {
@@ -15,7 +15,7 @@ describe('immutableStateInvariantMiddleware', () => {
 
   it('sends the action through the middleware chain', () => {
     const next = action => ({...action, returned: true});
-    const dispatch = middleware(next);
+    const dispatch = middleware()(next);
 
     expect(dispatch({type: 'SOME_ACTION'})).toEqual({type: 'SOME_ACTION', returned: true});
   });
@@ -26,7 +26,7 @@ describe('immutableStateInvariantMiddleware', () => {
       return action;
     };
 
-    const dispatch = middleware(next);
+    const dispatch = middleware()(next);
 
     expect(() => {
       dispatch({type: 'SOME_ACTION'});
@@ -36,7 +36,7 @@ describe('immutableStateInvariantMiddleware', () => {
   it('throws if mutating between dispatches', () => {
     const next = action => action;
 
-    const dispatch = middleware(next);
+    const dispatch = middleware()(next);
 
     dispatch({type: 'SOME_ACTION'});
     state.foo.bar.push(5);
@@ -51,7 +51,7 @@ describe('immutableStateInvariantMiddleware', () => {
       return action;
     };
 
-    const dispatch = middleware(next);
+    const dispatch = middleware()(next);
 
     expect(() => {
       dispatch({type: 'SOME_ACTION'});
@@ -61,7 +61,7 @@ describe('immutableStateInvariantMiddleware', () => {
   it('does not throw if not mutating between dispatches', () => {
     const next = action => action;
 
-    const dispatch = middleware(next);
+    const dispatch = middleware()(next);
 
     dispatch({type: 'SOME_ACTION'});
     state = {...state, foo: {...state.foo, baz: 'changed!'}};
@@ -73,7 +73,7 @@ describe('immutableStateInvariantMiddleware', () => {
   it('works correctly with circular references', () => {
     const next = action => action;
 
-    const dispatch = middleware(next);
+    const dispatch = middleware()(next);
 
     let x = {};
     let y = {};
@@ -84,4 +84,31 @@ describe('immutableStateInvariantMiddleware', () => {
       dispatch({type: 'SOME_ACTION', x});
     }).toNotThrow();
   });
+
+  it('respects "isImmutable" option', function () {
+    const isImmutable = (value) => true
+    const next = action => {
+      state.foo.bar.push(5);
+      return action;
+    };
+
+    const dispatch = middleware({ isImmutable })(next);
+
+    expect(() => {
+      dispatch({type: 'SOME_ACTION'});
+    }).toNotThrow();
+  })
+
+  it('respects "ignore" option', () => {
+    const next = action => {
+      state.foo.bar.push(5);
+      return action;
+    };
+
+    const dispatch = middleware({ ignore: ['foo.bar'] })(next);
+
+    expect(() => {
+      dispatch({type: 'SOME_ACTION'});
+    }).toNotThrow();
+  })
 });

test/trackForMutations.spec.js

@@ -1,12 +1,14 @@
 import expect from 'expect';
-import isImmutable from '../src/isImmutable';
+import isImmutableDefault from '../src/isImmutable';
 import trackForMutations from '../src/trackForMutations';
 
 describe('trackForMutations', () => {
   function testCasesForMutation(spec) {
     it('returns true and the mutated path', () => {
       const state = spec.getState();
-      const tracker = trackForMutations(isImmutable, state);
+      const options = spec.middlewareOptions || {};
+      const { isImmutable = isImmutableDefault, ignore } = options;
+      const tracker = trackForMutations(isImmutable, ignore, state);
       const newState = spec.fn(state);
 
       expect(
@@ -18,7 +20,9 @@ describe('trackForMutations', () => {
   function testCasesForNonMutation(spec) {
     it('returns false', () => {
       const state = spec.getState();
-      const tracker = trackForMutations(isImmutable, state);
+      const options = spec.middlewareOptions || {};
+      const { isImmutable = isImmutableDefault, ignore } = options;
+      const tracker = trackForMutations(isImmutable, ignore, state);
       const newState = spec.fn(state);
 
       expect(
@@ -163,6 +167,36 @@ describe('trackForMutations', () => {
         return s;
       },
       path: ['foo']
+    },
+    'cannot ignore root state': {
+      getState: () => ({ foo: {} }),
+      fn: (s) => {
+        s.foo = {};
+        return s;
+      },
+      middlewareOptions: {
+        ignore: ['']
+      },
+      path: ['foo']
+    },
+    'catching state mutation in non-ignored branch': {
+      getState: () => ({
+        foo: {
+          bar: [1, 2]
+        },
+        boo: {
+          yah: [1, 2]
+        }
+      }),
+      fn: (s) => {
+        s.foo.bar.push(3);
+        s.boo.yah.push(3);
+        return s;
+      },
+      middlewareOptions: {
+        ignore: ['foo']
+      },
+      path: ['boo', 'yah', '2']
     }
   };
 
@@ -230,6 +264,53 @@ describe('trackForMutations', () => {
     'having a NaN in the state': {
       getState: () => ({ a:NaN, b: Number.NaN }),
       fn: (s) => s
+    },
+    'ignoring branches from mutation detection': {
+      getState: () => ({
+        foo: {
+          bar: 'bar'
+        },
+      }),
+      fn: (s) => {
+        s.foo.bar = 'baz'
+        return s;
+      },
+      middlewareOptions: {
+        ignore: ['foo']
+      },
+    },
+    'ignoring nested branches from mutation detection': {
+      getState: () => ({
+        foo: {
+          bar: [1, 2],
+          boo: {
+            yah: [1, 2]
+          }
+        },
+      }),
+      fn: (s) => {
+        s.foo.bar.push(3);
+        s.foo.boo.yah.push(3);
+        return s;
+      },
+      middlewareOptions: {
+        ignore: [
+          'foo.bar',
+          'foo.boo.yah',
+        ]
+      }
+    },
+    'ignoring nested array indices from mutation detection': {
+      getState: () => ({
+        stuff: [{a: 1}, {a: 2}]
+      }),
+      fn: (s) => {
+        s.stuff[1].a = 3
+        return s;
+      },
+      middlewareOptions: {
+        ignore: ['stuff.1']
+      }
     }
   };