mazeru (混ぜる) is a deep merging utility module, aimed at JSON-compatible arrays and objects.

const merge = require('mazeru');

merge({
	foo: true,
	bar: { a: 'foo', b: [0, 1] },
}, {
	bar: { a: 'bar', b: [2, 3, 4, 5], c: false },
	baz: [],
}, {
	arrays: 'append',
	excludeKeys: ['baz', 'c'],
});

// 	foo: true,
// 	bar: { a: 'bar', b: [0, 1, 2, 3, 4, 5] },

Features

• Merge complex nested objects & arrays
• Allow/exclude/filter keys
• Several merge strategies for arrays (replace, append, etc.)
• Doesn't break on cyclic references
• Written in TypeScript and well-tested

Installation

npm i mazeru

API

merge(base: JsonValue, mixed: JsonValue, options?: MergeOptions): JsonValue

Merge mixed into base.

If at least one of the passed value is a primitive, the return value will simply be mixed.

If both are arrays, the return value will depend on the arrays option (see below for more infos).

Finally, if both are objects, they will be merged recursively. In the case of as conflict between two keys at the same level with the same name, the value of the key in mixed will always prevail.

Options

arrays: 'replace' | 'append' | 'concat' | 'merge'

Default: 'replace'

The strategy used to handle two conflicting arrays:

• 'replace' (default): simply replace the first array with the second one
• 'append', 'concat': append the second array to the first one
• 'merge': merge each pair of matching items, adding any excess items at the end (this is only really useful when the items are arrays or objects themselves)

onlyCommonKeys: boolean

Default: false

Only keep the keys that present in both objects. This applies to nested objects as well.

excludeKeys: string[]

Default: []

Exclude the listed keys from the resulting merged object.

allowKeys: string[]

Default: undefined

Only allow the listed keys in the resulting merged object.

keysFilter: (key: string, baseValue?: JsonValue, mixedValue?: JsonValue) => boolean

Default: () => true

Filter keys in the resulting merged object using the provided sieve.

Acknowledgments

This module makes use of some types from the great type-fest package.

License

Copyright (c) 2021-present, cheap glitch

Permission to use, copy, modify, and/or distribute this software for any purpose
with or without fee is hereby  granted, provided that the above copyright notice
and this permission notice appear in all copies.

THE SOFTWARE  IS PROVIDED "AS IS"  AND THE AUTHOR DISCLAIMS  ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING  ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS.  IN NO  EVENT  SHALL THE  AUTHOR  BE LIABLE  FOR  ANY SPECIAL,  DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR  PROFITS, WHETHER IN AN ACTION OF  CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN  CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.