merg v2.0.0

merg

Define object schema, validate and merge objects in different context

Installation

$ npm install merg -S

Usage

var Merg = require('merg');
var V    = require('node-veee');
var v    = V.scaffold(); // using [node-veee](https://github.com/node-veee/veee) for validations

// options is optional, below are the default handlers being used internally
var options = {
  // handler for formatting target object
  formatObject: function(value, context, cb) {
    return cb(null, value);
  },
  // handler for validating value-to-merge with schema field type
  validateField: function(value, type, context, cb) {
    return cb(null, value)
  },
  // handler for resolving field(s) not defined in schema
  onMissingField: function(fieldName, oldVal, newVal, context, cb) {
    return cb(null, newValue);
  }
};

var mergeOpts = new Merg({
  opt1: { type: v.string() },
  opt2: { type: v.number() }
});

var merge = new Merg({
  limit: { 
    type: v.number().positive()
  },
  offset: {
    type: v.number().nonNegative().default(10),
    // optional resolve function to decide what to merge
    resolve: function(oldVal, newVal, context, cb) {
      if (context.trusted) {
        return cb(null, newVal);
      } else {
        return cb(null, oldVal);
      }
    }
  },
  includeDeleted: {
    type: v.boolean().default(false),
    resolve: function(oldVal, newVal, context, cb) {
      if (context.user.role === 'admin') {
        return cb(null, newVal);
      } else {
        return cb(null, oldVal);
      }
    }
  },
  // nested merg
  opts: mergeOpts
}, options);

merge(old, { limit: 10, offset: 0 }, function(err, merged) {
  
});

merge(old, [{ limit: 1000, offset: -5 }, ...], { trusted: false }, function(err, merged) {
  
});

API

Merg(schema, options)

create a new merger with a given schema (the resulting merger is a pure function, target won't not be mutated)

possible option(s):

• formatObject transformation to be done, it's being executed before everything
• validateField function to validate value-to-merge with the type in schema, plug your favourite validation module in, or use node-veee
• onMissingField resolve function for fields that are not defined in schema

var Merg = require('merg');

var schema = {
  name: { type: v.string().required() } 
}

var options = {
  onMissingField: function(fieldName, oldVal, newVal, context, callback) {
    if (fieldName !== 'password') {
      return callback(null, newVal);
    }
  }
}

var merge = new Merg(schema, options);

merge(target, sources, callback)

merge objects

var schema = {
  name: { type: v.string() }
};

var options = {
  onMissingField: function(fieldName, oldVal, newVal, context, callback) {
    return callback(); // dont assign any missing fields
  }
}

var merge = Merg(schema, options);

var target = { name: 'John' };

merge(target, [{ name: 'Peter', age: 25 }, { name: 'Derek' }], function(err, result) {
  console.log(target); // { name: 'John' }
  console.log(err);    // null;
  console.log(result); // { name: 'Derek' }
});

Schema

// valid schema
var schema = { name: { type: v.string().required() } };

// also a valid schema
var mergeName = new Merg({ ... });
var schema = { name: mergeName };

Schema fields:

• type: anything, whatever could be used to validate the value-to-merge, being used in validateField function
• resolve: function that will be used for merging (optional)
• format: function to transform the value-to-merge before validateField & resolve

{
  name: {
    type: v.object().keys({
      first: v.string().required(),
      last: v.string().required()
    }),
    resolve: function(oldValue, newValue, context, cb) {
      cb(null, {
        first: newValue.first,
        last: newValue.last
      });
    },
    format: function(value, context, cb) {
      cb(null, value);
    }
  }
}

Nesting

Same as above

var nameMerg = new Merg({
  first: { type: v.string().required() },
  last: { type: v.string().required() }
});

var personMerg = new Merg({
  name: nameMerg
});

Author

Marvin Lam lam@seedalpha.net

Vladimir Popov vlad@seedalpha.net

License

MIT