mongoose-patch

This module is responsible for transforming JSON merge patch objects to Mongoose update objects.

When to use mongoose-patch?

When implementing PATCH on Mongo resources with Mongoose update using the FC 7396 JSON Merge Patch.

How does mongoose-patch work?

Mongoose-patch flattens a JSON merge patch object into a single-depth object using the flat library.

It then iterates over the object's properties to determine which properties should be updated and which should be removed.

A property whose value is null is pushed into an $unset object, a property whose value is not null is pushed into a $set object.

Key concepts

• Deletion happens by setting a key to null. This inherently means that it isn’t possible to change a key’s value to null, since such modification cannot be described by a merge patch document.
• Objects cannot be fully replaced, only properties.
• A property's value cannot be set to an empty object by passing an empty object as its value. This is to avoid illegal updates which cannot be enforced using a schema validator.
• Array items cannot be individually patched. An array may only be replaced in full or removed.

Validation

• Mongoose-patch should be used only after the JSON merge patch object is validated using a schema validator. The schema validator should enforce which properties can be updated and which can be removed.

• Mongoose-patch does not allow updating a property's value to an empty object by passing an empty object as its value. The error EXAMPLE_KEY cannot be set to an empty object. To delete the property, pass null instead will be thrown. This is to avoid illegal updates which cannot be enforced using a schema validator.

Example

Given this input:

        that: {
          is: null,
          test: ['object', null, 'it'],
          must: [],
          be: true,
          very: {
            long: {
              even: 'longer',
              than: {
                that: 'ohyeah'
              }
            }
          }
        }

Mongoose-patch will return this output:

   {
         $set: {
           'that.test': ['object', null, 'it'],
           'that.must': [],
           'that.be': true,
           'that.very.long.even': 'longer',
           'that.very.long.than.that': 'ohyeah'
         },
         $unset: {
           'that.is': ''
         }
       };

A service's use of mongoose-patch may look like this:

const  { transformToMongoUpdateAndValidate } = require('mongoose-patch')

try {
  const patchObj = { exampleResource: req.body };
  mongoUpdateObj = transformToMongoUpdateAndValidate(patchObj);

  ExampleResourceFactory(orgName).findOneAndUpdate({ _id: '123456789' },
      mongoUpdateObj, { new: true }).exec();
} catch (err) {
  return errorResult(res, err, {
    error_message: err.message,
});