feat: option to exclude certain paths

* Added excludes option
* Added deep removal of excluded paths in json-patch-operations
* Moved filtering inside condition to get a little performance if 'excludes' option is not used
* Extracted ambiguous functionality from getArrayFromPath()
* Reworked some property names. Extraced methods for better readability.
* Moved some comments.
* Added documentation examples
* Added link to excludes chapter

Author: vinerich

README.md

@@ -14,7 +14,7 @@ To use **mongoose-patch-history** for an existing mongoose schema you can simply
 
 ```javascript
 import mongoose, { Schema } from 'mongoose'
-import patchHistory from 'mongoose-patch-history' 
+import patchHistory from 'mongoose-patch-history'
 
 /* or the following if not running your app with babel:
 const patchHistory = require('mongoose-patch-history').default;
@@ -148,8 +148,8 @@ post.rollback(patches[1].id, {}, false)
 
 The `rollback` method will throw an Error when invoked with an ObjectId that is
 
-* not a patch of the document
-* the latest patch of the document
+- not a patch of the document
+- the latest patch of the document
 
 ## Options
 
@@ -160,17 +160,19 @@ PostSchema.plugin(patchHistory, {
 })
 ```
 
-* `mongoose` :pushpin: _required_ <br/>
+- `mongoose` :pushpin: _required_ <br/>
   The mongoose instance to work with
-* `name` :pushpin: _required_ <br/>
+- `name` :pushpin: _required_ <br/>
   String where the names of both patch model and patch collection are generated from. By default, model name is the pascalized version and collection name is an undercore separated version
-* `removePatches` <br/>
+- `removePatches` <br/>
   Removes patches when origin document is removed. Default: `true`
-* `transforms` <br/>
+- `transforms` <br/>
   An array of two functions that generate model and collection name based on the `name` option. Default: An array of [humps](https://github.com/domchristie/humps).pascalize and [humps](https://github.com/domchristie/humps).decamelize
-* `includes` <br/>
+- `includes` <br/>
   Property definitions that will be included in the patch schema. Read more about includes in the next chapter of the documentation. Default: `{}`
-* `trackOriginalValue` <br/>
+- `excludes` <br/>
+  Property paths that will be excluded in patches. Read more about excludes in the [excludes chapter of the documentation](https://github.com/codepunkt/mongoose-patch-history#excludes). Default: `[]`
+- `trackOriginalValue` <br/>
   If enabled, the original value will be stored in the change patches under the attribute `originalValue`. Default: `false`
 
 ### Includes
@@ -203,7 +205,7 @@ There is an additional option that allows storing information in the patch docum
 
 ```javascript
 // save user as _user in versioned documents
-PostSchema.virtual('user').set(function(user) {
+PostSchema.virtual('user').set(function (user) {
   this._user = user
 })
 
@@ -262,3 +264,36 @@ Post.findOneAndUpdate(
   { _user: mongoose.Types.ObjectId() }
 )
 ```
+
+### Excludes
+
+```javascript
+PostSchema.plugin(patchHistory, {
+  mongoose,
+  name: 'postPatches',
+  excludes: [
+    '/path/to/hidden/property',
+    '/path/into/array/*/property',
+    '/path/to/one/array/1/element',
+  ],
+})
+
+// Properties
+// /path/to/hidden:                   included
+// /path/to/hidden/property:          excluded
+// /path/to/hidden/property/nesting:  excluded
+
+// Array element properties
+// /path/into/array/0:                included
+// /path/into/array/345345/property:  excluded
+// /path/to/one/array/0/element:      included
+// /path/to/one/array/1/element:      excluded
+```
+
+This will exclude the given properties and _all nested_ paths. Excluding `/` however will not work, since then you can just disable the plugin.
+
+- If a property is `{}` or `undefined` after processing all excludes statements, it will _not_ be included in the patch.
+- Arrays work a little different. Since json-patch-operations work on the array index, array elements that are `{}` or `undefined` are still added to the patch. This brings support for later `remove` or `replace` operations to work as intended.<br/>
+  The `ARRAY_WILDCARD` `*` matches every array element.
+
+If there are any bugs experienced with the `excludes` feature please write an issue so we can fix it!

lib/index.js

@@ -5,12 +5,17 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.RollbackError = undefined;
 
+var _typeof = typeof Symbol === "function" && typeof Symbol.iterator === "symbol" ? function (obj) { return typeof obj; } : function (obj) { return obj && typeof Symbol === "function" && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; };
+
 exports.default = function (schema, opts) {
   var options = (0, _lodash.merge)({}, defaultOptions, opts);
 
   // get _id type from schema
   options._idType = schema.tree._id.type;
 
+  // transform excludes option
+  options.excludes = options.excludes.map(getArrayFromPath);
+
   // validate parameters
   (0, _assert2.default)(options.mongoose, '`mongoose` option must be defined');
   (0, _assert2.default)(options.name, '`name` option must be defined');
@@ -122,6 +127,16 @@ exports.default = function (schema, opts) {
     var ref = document._id;
 
     var ops = _fastJsonPatch2.default.compare(document.isNew ? {} : document._original || {}, toJSON(document.data()));
+    if (options.excludes.length > 0) {
+      ops = ops.filter(function (op) {
+        var pathArray = getArrayFromPath(op.path);
+        return !options.excludes.some(function (exclude) {
+          return isPathContained(exclude, pathArray);
+        }) && options.excludes.every(function (exclude) {
+          return deepRemovePath(op, exclude);
+        });
+      });
+    }
 
     // don't save a patch when there are no changes to save
     if (!ops.length) {
@@ -330,14 +345,118 @@ var createPatchModel = function createPatchModel(options) {
 
 var defaultOptions = {
   includes: {},
+  excludes: [],
   removePatches: true,
   transforms: [_humps.pascalize, _humps.decamelize],
   trackOriginalValue: false
+};
+
+var ARRAY_INDEX_WILDCARD = '*';
+
+/**
+ * Splits a json-patch-path of form `/path/to/object` to an array `['path', 'to', 'object']`.
+ * Note: `/` is returned as `[]`
+ *
+ * @param {string} path Path to split
+ */
+var getArrayFromPath = function getArrayFromPath(path) {
+  return path.replace(/^\//, '').split('/');
+};
+
+/**
+ * Checks the provided `json-patch-operation` on `excludePath`. This check joins the `path` and `value` property of the `operation` and removes any hit.
+ *
+ * @param {import('fast-json-patch').Operation} patch operation to check with `excludePath`
+ * @param {String[]} excludePath Path to property to remove from value of `operation`
+ *
+ * @return `false` if `patch.value` is `{}` or `undefined` after remove, `true` in any other case
+ */
+var deepRemovePath = function deepRemovePath(patch, excludePath) {
+  var operationPath = sanitizeEmptyPath(getArrayFromPath(patch.path));
+
+  if (isPathContained(operationPath, excludePath)) {
+    var value = patch.value;
+
+    // because the paths overlap start at patchPath.length
+    // e.g.: patch: { path:'/object', value:{ property: 'test' } }
+    // pathToExclude: '/object/property'
+    // need to start at array idx 1, because value starts at idx 0
+
+    var _loop = function _loop(i) {
+      if (excludePath[i] === ARRAY_INDEX_WILDCARD && Array.isArray(value)) {
+        // start over with each array element and make a fresh check
+        // Note: it can happen that array elements are rendered to: {}
+        //         we need to keep them to keep the order of array elements consistent
+        value.forEach(function (elem) {
+          deepRemovePath({ path: '/', value: elem }, excludePath.slice(i + 1));
+        });
+
+        // If the patch value has turned to {} return false so this patch can be filtered out
+        if (Object.keys(patch.value).length === 0) return {
+            v: false
+          };
+        return {
+          v: true
+        };
+      }
+      value = value[excludePath[i]];
+
+      if (typeof value === 'undefined') return {
+          v: true
+        };
+    };
+
+    for (var i = operationPath.length; i < excludePath.length - 1; i++) {
+      var _ret = _loop(i);
+
+      if ((typeof _ret === 'undefined' ? 'undefined' : _typeof(_ret)) === "object") return _ret.v;
+    }
+    if (typeof value[excludePath[excludePath.length - 1]] === 'undefined') return true;else {
+      delete value[excludePath[excludePath.length - 1]];
+      // If the patch value has turned to {} return false so this patch can be filtered out
+      if (Object.keys(patch.value).length === 0) return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Sanitizes a path `['']` to be used with `isPathContained()`
+ * @param {String[]} path
+ */
+var sanitizeEmptyPath = function sanitizeEmptyPath(path) {
+  return path.length === 1 && path[0] === '' ? [] : path;
+};
+
+// Checks if 'fractionPath' is contained in fullPath
+// Exp. 1: fractionPath '/path/to',              fullPath '/path/to/object'       => true
+// Exp. 2: fractionPath '/arrayPath/*/property', fullPath '/arrayPath/1/property' => true
+var isPathContained = function isPathContained(fractionPath, fullPath) {
+  return fractionPath.every(function (entry, idx) {
+    return entryIsIdentical(entry, fullPath[idx]) || matchesArrayWildcard(entry, fullPath[idx]);
+  });
+};
+
+var entryIsIdentical = function entryIsIdentical(entry1, entry2) {
+  return entry1 === entry2;
+};
+
+var matchesArrayWildcard = function matchesArrayWildcard(entry1, entry2) {
+  return isArrayIndexWildcard(entry1) && isIntegerGreaterEqual0(entry2);
+};
+
+var isArrayIndexWildcard = function isArrayIndexWildcard(entry) {
+  return entry === ARRAY_INDEX_WILDCARD;
+};
+
+var isIntegerGreaterEqual0 = function isIntegerGreaterEqual0(entry) {
+  return Number.isInteger(Number(entry)) && Number(entry) >= 0;
+};
 
-  // used to convert bson to json - especially ObjectID references need
-  // to be converted to hex strings so that the jsonpatch `compare` method
-  // works correctly
-};var toJSON = function toJSON(obj) {
+// used to convert bson to json - especially ObjectID references need
+// to be converted to hex strings so that the jsonpatch `compare` method
+// works correctly
+var toJSON = function toJSON(obj) {
   return JSON.parse(JSON.stringify(obj));
 };
 

src/index.js

@@ -35,11 +35,95 @@ const createPatchModel = options => {
 
 const defaultOptions = {
   includes: {},
+  excludes: [],
   removePatches: true,
   transforms: [pascalize, decamelize],
   trackOriginalValue: false,
 }
 
+const ARRAY_INDEX_WILDCARD = '*'
+
+/**
+ * Splits a json-patch-path of form `/path/to/object` to an array `['path', 'to', 'object']`.
+ * Note: `/` is returned as `[]`
+ *
+ * @param {string} path Path to split
+ */
+const getArrayFromPath = path => path.replace(/^\//, '').split('/')
+
+/**
+ * Checks the provided `json-patch-operation` on `excludePath`. This check joins the `path` and `value` property of the `operation` and removes any hit.
+ *
+ * @param {import('fast-json-patch').Operation} patch operation to check with `excludePath`
+ * @param {String[]} excludePath Path to property to remove from value of `operation`
+ *
+ * @return `false` if `patch.value` is `{}` or `undefined` after remove, `true` in any other case
+ */
+const deepRemovePath = (patch, excludePath) => {
+  const operationPath = sanitizeEmptyPath(getArrayFromPath(patch.path))
+
+  if (isPathContained(operationPath, excludePath)) {
+    let value = patch.value
+
+    // because the paths overlap start at patchPath.length
+    // e.g.: patch: { path:'/object', value:{ property: 'test' } }
+    // pathToExclude: '/object/property'
+    // need to start at array idx 1, because value starts at idx 0
+    for (let i = operationPath.length; i < excludePath.length - 1; i++) {
+      if (excludePath[i] === ARRAY_INDEX_WILDCARD && Array.isArray(value)) {
+        // start over with each array element and make a fresh check
+        // Note: it can happen that array elements are rendered to: {}
+        //         we need to keep them to keep the order of array elements consistent
+        value.forEach(elem => {
+          deepRemovePath({ path: '/', value: elem }, excludePath.slice(i + 1))
+        })
+
+        // If the patch value has turned to {} return false so this patch can be filtered out
+        if (Object.keys(patch.value).length === 0) return false
+        return true
+      }
+      value = value[excludePath[i]]
+
+      if (typeof value === 'undefined') return true
+    }
+    if (typeof value[excludePath[excludePath.length - 1]] === 'undefined')
+      return true
+    else {
+      delete value[excludePath[excludePath.length - 1]]
+      // If the patch value has turned to {} return false so this patch can be filtered out
+      if (Object.keys(patch.value).length === 0) return false
+    }
+  }
+  return true
+}
+
+/**
+ * Sanitizes a path `['']` to be used with `isPathContained()`
+ * @param {String[]} path
+ */
+const sanitizeEmptyPath = path =>
+  path.length === 1 && path[0] === '' ? [] : path
+
+// Checks if 'fractionPath' is contained in fullPath
+// Exp. 1: fractionPath '/path/to',              fullPath '/path/to/object'       => true
+// Exp. 2: fractionPath '/arrayPath/*/property', fullPath '/arrayPath/1/property' => true
+const isPathContained = (fractionPath, fullPath) =>
+  fractionPath.every(
+    (entry, idx) =>
+      entryIsIdentical(entry, fullPath[idx]) ||
+      matchesArrayWildcard(entry, fullPath[idx])
+  )
+
+const entryIsIdentical = (entry1, entry2) => entry1 === entry2
+
+const matchesArrayWildcard = (entry1, entry2) =>
+  isArrayIndexWildcard(entry1) && isIntegerGreaterEqual0(entry2)
+
+const isArrayIndexWildcard = entry => entry === ARRAY_INDEX_WILDCARD
+
+const isIntegerGreaterEqual0 = entry =>
+  Number.isInteger(Number(entry)) && Number(entry) >= 0
+
 // used to convert bson to json - especially ObjectID references need
 // to be converted to hex strings so that the jsonpatch `compare` method
 // works correctly
@@ -65,6 +149,9 @@ export default function(schema, opts) {
   // get _id type from schema
   options._idType = schema.tree._id.type
 
+  // transform excludes option
+  options.excludes = options.excludes.map(getArrayFromPath)
+
   // validate parameters
   assert(options.mongoose, '`mongoose` option must be defined')
   assert(options.name, '`name` option must be defined')
@@ -167,10 +254,20 @@ export default function(schema, opts) {
   // added to the associated patch collection
   function createPatch(document, queryOptions = {}) {
     const { _id: ref } = document
-    const ops = jsonpatch.compare(
+    let ops = jsonpatch.compare(
       document.isNew ? {} : document._original || {},
       toJSON(document.data())
     )
+    if (options.excludes.length > 0) {
+      ops = ops.filter(op => {
+        const pathArray = getArrayFromPath(op.path)
+        return (
+          !options.excludes.some(exclude =>
+            isPathContained(exclude, pathArray)
+          ) && options.excludes.every(exclude => deepRemovePath(op, exclude))
+        )
+      })
+    }
 
     // don't save a patch when there are no changes to save
     if (!ops.length) {