# merge-options

> Merge Option Objects

Latest version **3.0.4** (published 2020-11-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install merge-options
pnpm add merge-options
yarn add merge-options
bun add merge-options
```

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.4 |
| Published | 2020-11-23 |
| First published | 2015-11-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=10 |
| Dependencies | 1 |
| Unpacked size | 10.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 69 |
| Author | Michael Mayer |
| Maintainers | schnittstabil |
| Keywords | merge, options, deep, plain, object, extend, clone |

## Links

- npm: https://www.npmjs.com/package/merge-options
- Repository: https://github.com/schnittstabil/merge-options
- Homepage: https://github.com/schnittstabil/merge-options#readme
- Issues: https://github.com/schnittstabil/merge-options/issues
- npm.io page: https://npm.io/package/merge-options

## Dependencies (1)

- [is-plain-obj](https://npm.io/package/is-plain-obj.md) ^2.1.0

## Recent versions

- 3.0.4 (latest) — 2020-11-23
- 3.0.3 — 2020-09-16
- 3.0.2 — 2020-09-11
- 3.0.1 — 2020-08-23
- 3.0.0 — 2020-08-23
- 2.0.0 — 2019-10-19
- 1.0.1 — 2018-04-30
- 1.0.0 — 2017-05-06
- 0.0.64 — 2016-02-25
- 0.0.42 — 2015-11-06

## README

# merge-options [![Build Status](https://travis-ci.org/schnittstabil/merge-options.svg?branch=master)](https://travis-ci.org/schnittstabil/merge-options) [![Coverage Status](https://coveralls.io/repos/schnittstabil/merge-options/badge.svg?branch=master&service=github)](https://coveralls.io/github/schnittstabil/merge-options?branch=master) [![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)


> Merge Option Objects

`merge-options` considers [plain objects](https://github.com/sindresorhus/is-plain-obj) as *Option Objects*, everything else as *Option Values*.

## Install

```
$ npm install --save merge-options
```

## Usage

```js
const mergeOptions = require('merge-options');

mergeOptions({foo: 0}, {bar: 1}, {baz: 2}, {bar: 3})
//=> {foo: 0, bar: 3, baz: 2}

mergeOptions({nested: {unicorns: 'none'}}, {nested: {unicorns: 'many'}})
//=> {nested: {unicorns: 'many'}}

mergeOptions({[Symbol.for('key')]: 0}, {[Symbol.for('key')]: 42})
//=> {Symbol(key): 42}
```

### Usage with custom config

```js
const mergeOptions = require('merge-options').bind({ignoreUndefined: true});

mergeOptions({foo: 'bar'}, {foo: undefined})
//=> {foo: 'bar'}
```

## API

### mergeOptions(option1, ...options)<br/>mergeOptions.call(config, option1, ...options)<br/>mergeOptions.apply(config, [option1, ...options])

`mergeOptions` recursively merges one or more *Option Objects* into a new one and returns that. The `options` are merged in order, thus *Option Values* of additional `options` take precedence over previous ones.

The merging does not alter the passed `option` arguments, taking roughly the following steps:
* recursively cloning<sup><a href="#note1">[1]</a></sup> *Option Objects* and [arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray) until reaching *Option Values*
* copying<sup><a href="#note1">[1]</a></sup> references to *Option Values* to the result object


```js
const defaultOpts = {
	fn:      () => false,                  // functions are Option Values
	promise: Promise.reject(new Error()),  // all non-plain objects are Option Values
	array:   ['foo'],                      // arrays are Option Values
	nested:  {unicorns: 'none'}            // {…} is plain, therefore an Option Object
};

const opts = {
	fn:      () => true,                   // [1]
	promise: Promise.resolve('bar'),       // [2]
	array:   ['baz'],                      // [3]
	nested:  {unicorns: 'many'}            // [4]
};

mergeOptions(defaultOpts, opts)
//=>
{
	fn:      [Function],                   // === [1]
	promise: Promise { 'bar' },            // === [2]
	array:   ['baz'],                      // !== [3] (arrays are cloned)
	nested:  {unicorns: 'many'}            // !== [4] (Option Objects are cloned)
}
```

#### config

Type: `object`

##### config.concatArrays

Type: `boolean`<br/>Default: `false`

Concatenate arrays:

```js
mergeOptions({src: ['src/**']}, {src: ['test/**']})
//=> {src: ['test/**']}

// Via call
mergeOptions.call({concatArrays: true}, {src: ['src/**']}, {src: ['test/**']})
//=> {src: ['src/**', 'test/**']}

// Via apply
mergeOptions.apply({concatArrays: true}, [{src: ['src/**']}, {src: ['test/**']}])
//=> {src: ['src/**', 'test/**']}
```

##### config.ignoreUndefined

Type: `boolean`<br/>Default: `false`

Ignore undefined values:

```js
mergeOptions({foo: 'bar'}, {foo: undefined})
//=> {foo: undefined}

// Via call
mergeOptions.call({ignoreUndefined: true}, {foo: 'bar'}, {foo: undefined})
//=> {foo: 'bar'}

// Via apply
mergeOptions.apply({ignoreUndefined: true}, [{foo: 'bar'}, {foo: undefined}])
//=> {foo: 'bar'}
```


## Related

* See [object-assign](https://github.com/sindresorhus/object-assign) if you need a ES2015 Object.assign() ponyfill
* See [deep-assign](https://github.com/sindresorhus/deep-assign) if you need to do Object.assign() recursively

## Notes

<ol>
	<li id="note1">copying and cloning take only enumerable own properties into account</li>
</ol>

## License

MIT © [Michael Mayer](http://schnittstabil.de)

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