node package manager
Loosely couple your services. Use Orgs to version and reuse your code. Create a free org »

supermixer

Build Status # Super Mixer

Mixes/merges/extends your object in multiple ways.

Unlike underscore/lodash utility methods this module allows you to:

  • mix or deep merge objects' prototype chain. Regular mixin/extend/assign implementations can't do that.
  • mix or deep merge unique properties only. I.e. data will not be overwritten if a property already exists.
  • filter each individual property by target value, source value, and key. See API.
  • transform each value by resulting value, source value, and key. See API.

Install

$ npm install supermixer
var mixer = require('supermixer');

API

NB! All functions always mutate the first argument.

supermixer(opts = {})

The opts:

 * @param {Object} opts
 * @param {Function} opts.filter Function which filters value and key.
 * @param {Function} opts.transform Function which transforms each value.
 * @param {Boolean} opts.chain Loop through prototype properties too.
 * @param {Boolean} opts.deep Deep looping through the nested properties.
 * @param {Boolean} opts.noOverwrite Do not overwrite any existing data (aka first one wins).

Usage:

const mix = supermixer({
  filter(sourceValue, targetValue, key) { return key[0] !== '_'; }, // do not copy "private" values 
  transform(resultValue, targetValue, key) { console.log(key); return resultValue; }, // log each key which gets set 
  chain: true,
  deep: true,
  noOverwrite: true
});
 
const johnStream = mix({}, new Stream(), { name: "John Stream"; })

Regular mixin, aka Object.assign, aka $.extend.

 // the regular Object.assign function 
var extend = supermixer();
// OR 
extend = supermixer.mixin;
 
extend({}, { a: 1 }, { b: 2 });
// { a: 1, b: 2 } 

Mixin functions only.

// assigns own functions only 
var functionMixer = supermixer({
  filter: function (sourceValue) { return typeof sourceValue === 'function'; }
});
// OR 
functionMixer = supermixer.mixinFunctions;
 
functionMixer({}, { a: "x" },  { b: function(){} });
// { b() } 

Mixin functions including prototype chain.

// assigns functions only, but traverse through the prototype chain 
var chainFunctionMixer = supermixer({
  filter: function (sourceValue) { return typeof sourceValue === 'function'; },
  chain: true
});
// OR 
chainFunctionMixer = supermixer.mixinChainFunctions;
 
chainFunctionMixer({}, new EventEmitter());
// { on(), off(), emit(), ... } 

Deep merge

// deep merge own properties 
var mergeDeep = supermixer({
  deep: true
});
// OR 
mergeDeep = supermixer.merge;
 
mergeDeep({ url: { host: "example.com" } }, { url: { port: 81 } });
// { url: { host: "example.com", port: 81 } } 

Deep merge but do not overwrite existing values.

// deep merge own properties 
var mergeDeep = supermixer({
  deep: true,
  noOverwrite: true
});
// OR 
mergeUnique = supermixer.mergeUnique;
 
mergeUnique({ url: { host: "example.com" } }, { url: { host: "evil.com" } });
// { url: { host: "example.com" } } 

Deep merge non functions including prototype chain.

// deeply merges data properties, traversing through prototype chain 
var mergeChainData =  supermixer({
  filter: function (sourceValue) { return typeof sourceValue !== 'function'; },
  deep: true,
  chain: true
});
// OR 
mergeChainData = supermixer.mergeChainNonFunctions;
 
EventEmitter.prototype.hello = "world";
mergeChainData({}, new EventEmitter());
// { hello: "world" } 

Want to contribute?

This project is Open Open Source. This means whoever submits an accepted PR will receive write permissions to the project.