merge-options

What is merge-options?

The merge-options npm package is a utility for deeply merging multiple objects into one. It is particularly useful for configurations and settings where default options need to be overridden by user inputs or other sources.

What are merge-options's main functionalities?

Deep Merging of Objects

This feature allows for the deep merging of objects. Properties from the second object will override those in the first object without replacing the entire structure, allowing for fine-grained updates.

const mergeOptions = require('merge-options');
const defaultOptions = { a: 1, b: { c: 2, d: 3 } };
const userOptions = { b: { c: 4 } };
const finalOptions = mergeOptions(defaultOptions, userOptions);
console.log(finalOptions); // Output: { a: 1, b: { c: 4, d: 3 } }

Merging Arrays and Functions

merge-options can also handle merging arrays and functions. By default, it replaces the original array or function entirely with the new one.

const mergeOptions = require('merge-options');
const opts1 = { arr: [1, 2], func: function() { return 'A'; } };
const opts2 = { arr: [3, 4], func: function() { return 'B'; } };
const result = mergeOptions(opts1, opts2);
console.log(result); // Output: { arr: [3, 4], func: [Function: func] }

Other packages similar to merge-options

lodash.merge

lodash.merge is a method from the Lodash library that provides a similar deep merging functionality. Unlike merge-options, lodash.merge is part of a larger utility library, which might be preferable for projects already using Lodash for other purposes.

deepmerge

deepmerge is another npm package that exclusively focuses on merging objects deeply. It offers more customization options compared to merge-options, such as array concatenation and custom merging functions, which can be useful for more complex merging scenarios.

README

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

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

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

mergeOptions({foo: 'bar'}, {foo: undefined})
//=> {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

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
Default: false

Concatenate arrays:

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
Default: false

Ignore undefined values:

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 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