102 lines
3.4 KiB
Markdown
102 lines
3.4 KiB
Markdown
# merge-options [](https://travis-ci.org/schnittstabil/merge-options) [](https://coveralls.io/github/schnittstabil/merge-options?branch=master) [](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}
|
|
```
|
|
|
|
## 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/**']}
|
|
```
|
|
|
|
|
|
## 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)
|