merge-options

Merge Option Objects

merge-options considers plain objects as Option Objects, everything else as Option Values.

Install

$ npm install --save merge-options

Usage

1const mergeOptions = require('merge-options');
2
3mergeOptions({foo: 0}, {bar: 1}, {baz: 2}, {bar: 3})
4//=> {foo: 0, bar: 3, baz: 2}
5
6mergeOptions({nested: {unicorns: 'none'}}, {nested: {unicorns: 'many'}})
7//=> {nested: {unicorns: 'many'}}
8
9mergeOptions({[Symbol.for('key')]: 0}, {[Symbol.for('key')]: 42})
10//=> {Symbol(key): 42}

Usage with custom config

1const mergeOptions = require('merge-options').bind({ignoreUndefined: true});
2
3mergeOptions({foo: 'bar'}, {foo: undefined})
4//=> {foo: 'bar'}

API

mergeOptions(option1, ...options)
mergeOptions.call(config, option1, ...options)
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^[1] Option Objects and arrays until reaching Option Values
• copying^[1] references to Option Values to the result object

1const defaultOpts = {
2	fn:      () => false,                  // functions are Option Values
3	promise: Promise.reject(new Error()),  // all non-plain objects are Option Values
4	array:   ['foo'],                      // arrays are Option Values
5	nested:  {unicorns: 'none'}            // {…} is plain, therefore an Option Object
6};
7
8const opts = {
9	fn:      () => true,                   // [1]
10	promise: Promise.resolve('bar'),       // [2]
11	array:   ['baz'],                      // [3]
12	nested:  {unicorns: 'many'}            // [4]
13};
14
15mergeOptions(defaultOpts, opts)
16//=>
17{
18	fn:      [Function],                   // === [1]
19	promise: Promise { 'bar' },            // === [2]
20	array:   ['baz'],                      // !== [3] (arrays are cloned)
21	nested:  {unicorns: 'many'}            // !== [4] (Option Objects are cloned)
22}

config

Type: object

config.concatArrays

Type: boolean
Default: false

Concatenate arrays:

1mergeOptions({src: ['src/**']}, {src: ['test/**']})
2//=> {src: ['test/**']}
3
4// Via call
5mergeOptions.call({concatArrays: true}, {src: ['src/**']}, {src: ['test/**']})
6//=> {src: ['src/**', 'test/**']}
7
8// Via apply
9mergeOptions.apply({concatArrays: true}, [{src: ['src/**']}, {src: ['test/**']}])
10//=> {src: ['src/**', 'test/**']}

config.ignoreUndefined

Type: boolean
Default: false

Ignore undefined values:

1mergeOptions({foo: 'bar'}, {foo: undefined})
2//=> {foo: undefined}
3
4// Via call
5mergeOptions.call({ignoreUndefined: true}, {foo: 'bar'}, {foo: undefined})
6//=> {foo: 'bar'}
7
8// Via apply
9mergeOptions.apply({ignoreUndefined: true}, [{foo: 'bar'}, {foo: undefined}])
10//=> {foo: 'bar'}

Related

• See object-assign if you need a ES2015 Object.assign() ponyfill
• See deep-assign if you need to do Object.assign() recursively

Notes

1. copying and cloning take only enumerable own properties into account

License

MIT © Michael Mayer