README.md

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) => 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: (sourceValue) => 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: (sourceValue) => 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: (sourceValue) => 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.