# supermixer

> Mix JS objects deep, shallow, traversing prototypes, selectively, etc.

Latest version **1.0.5** (published 2020-08-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install supermixer
pnpm add supermixer
yarn add supermixer
bun add supermixer
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2020-08-20 |
| First published | 2015-05-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 9.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 20 |
| Author | koresar |
| Maintainers | koresar |
| Keywords | merge, extend, assign, deep |

## Links

- npm: https://www.npmjs.com/package/supermixer
- Repository: https://github.com/stampit-org/supermixer
- Homepage: https://github.com/stampit-org/supermixer#readme
- Issues: https://github.com/stampit-org/supermixer/issues
- npm.io page: https://npm.io/package/supermixer

## Dependencies (1)

- [lodash](https://npm.io/package/lodash.md) ^4.17.20

## Recent versions

- 1.0.5 (latest) — 2020-08-20
- 1.0.4 — 2020-08-20
- 1.0.3 — 2016-07-29
- 1.0.2 — 2015-06-13
- 1.0.1 — 2015-06-13
- 1.0.0 — 2015-06-13
- 0.4.0 — 2015-05-31
- 0.3.1 — 2015-05-24
- 0.3.0 — 2015-05-07
- 0.2.1 — 2015-05-07
- 0.2.0 — 2015-05-07
- 0.1.2 — 2015-05-07
- 0.1.1 — 2015-05-07
- 0.1.0 — 2015-05-07

## README

[![Build Status](https://travis-ci.org/stampit-org/supermixer.svg?branch=master)](https://travis-ci.org/stampit-org/supermixer)
# 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
```sh
$ npm install supermixer
```

```js
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:
```js
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`.
```js
 // the regular Object.assign function
var extend = supermixer();
// OR
extend = supermixer.mixin;

extend({}, { a: 1 }, { b: 2 });
// { a: 1, b: 2 }
```

### Mixin functions only.
```js
// 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.
```js
// 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
```js
// 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.
```js
// 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.
```js
// 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.

---
_Source: https://npm.io/package/supermixer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._