Registry / serialization / utils-merge

utils-merge

JSON →
library1.0.1jsnpmunverified

The `utils-merge` package offers a singular utility function, `merge(destination, source)`, which facilitates the shallow combination of properties from a source object into a destination object. It operates by copying enumerable own properties from the source directly onto the destination, overwriting any existing properties with matching keys. The package is currently at version 1.0.1, reflecting a stable and mature, though minimally maintained, codebase since its last updates around 2017. Its core differentiator is its simplicity and direct mutable merging, suitable for scenarios where a lightweight, shallow merge is explicitly desired and object mutation is an acceptable side effect, rather than requiring deep cloning or immutability features found in more complex merging libraries.

npm install utils-merge
INSTALL
IMPORT
SIG · UTILS-MERGE
U
utils-merge
serializationjavascriptv1.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

merge
const merge = require('utils-merge');
const { merge } = require('utils-merge');
The package exports the `merge` function as the default CommonJS export.
merge
import merge from 'utils-merge';
import { merge } from 'utils-merge';
For ESM, `merge` is the default export. Named import syntax will result in undefined.
merge (TypeScript)
import merge from 'utils-merge';
import * as merge from 'utils-merge';
While CommonJS `require` often defaults to `* as`, the type definition for `utils-merge` typically expects a default import for `merge`.

Demonstrates the shallow merging behavior and direct object mutation of `utils-merge`, showing how it combines properties and handles nested objects by replacement.

const merge = require('utils-merge'); // CommonJS import for Node.js environments // Define initial objects let userProfile = { id: 'user123', name: 'Jane Doe', settings: { theme: 'dark', notifications: { email: true, sms: false } } }; let defaultProfileSettings = { language: 'en-US', settings: { notifications: { email: false, push: true }, // This will completely replace userProfile.settings.notifications privacy: { dataSharing: false } }, status: 'active' }; console.log('Initial User Profile:', JSON.stringify(userProfile, null, 2)); console.log('Default Settings to Merge:', JSON.stringify(defaultProfileSettings, null, 2)); // Perform the merge operation // WARNING: utils-merge performs a shallow merge and mutates the destination object. // Nested objects from the source will replace the corresponding nested objects in the destination, // rather than merging their properties recursively. merge(userProfile, defaultProfileSettings); console.log('\nUser Profile After Shallow Merge (destination mutated):', JSON.stringify(userProfile, null, 2)); // Example of shallow merge for nested objects: let objA = { config: { timeout: 1000, retries: 3 } }; let objB = { config: { timeout: 5000, maxAttempts: 5 } }; console.log('\nBefore nested merge: objA =', JSON.stringify(objA)); merge(objA, objB); console.log('After nested merge (config from objB replaced objA.config): objA =', JSON.stringify(objA)); // To create a new object without mutating the original 'userProfile' while using utils-merge: // First, create a shallow copy of 'userProfile' (or an empty object), // then merge the defaults into that copy. let newMergedProfile = merge({}, userProfile); merge(newMergedProfile, defaultProfileSettings); // Note: This example is illustrative. For true deep merge, other libs are needed. console.log('\nNew merged profile (via cloning then merging):', JSON.stringify(newMergedProfile, null, 2));
Debug
Known issues
gotchaThe `merge` function performs a shallow merge. This means that if both source and destination objects contain nested objects with the same key, the nested object from the source will completely overwrite the one in the destination, rather than recursively merging their properties.
fix
For deep merging behavior, consider using libraries like `lodash.merge`, `deepmerge`, or implementing a custom recursive merge function.
affects: >=1.0.0
gotchaThe `merge` function mutates the destination object directly. It does not return a new object with the merged properties. If you need to preserve the original destination object, you must explicitly clone it before calling `merge`.
fix
To avoid mutation, create a new empty object and merge into it, e.g., `const newObject = {}; merge(newObject, originalDestination); merge(newObject, source);` or first clone the destination: `const clonedDestination = { ...originalDestination }; merge(clonedDestination, source);`.
affects: >=1.0.0
gotchaThe package is minimally maintained since around 2017 (as indicated by copyright dates and last known updates). While stable for its intended simple use case, it may not receive updates for new JavaScript features, bug fixes, or security patches relevant to complex object manipulation.
fix
Evaluate if the package's limited scope and maintenance status align with your project's long-term requirements. For active development or complex needs, consider more actively maintained alternatives.
affects: >=1.0.0
gotchaThe package is primarily designed for CommonJS (Node.js) environments, as shown in its usage examples. While modern bundlers can handle it in ESM projects, direct `import` syntax might require specific configuration or careful usage if not properly transpiled, especially in older environments.
fix
Ensure your build toolchain (Webpack, Rollup, Vite, etc.) is configured to correctly handle CommonJS modules when importing `utils-merge` into an ESM project. Use `import merge from 'utils-merge';` and verify behavior.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: merge is not a function
Incorrect import statement; `utils-merge` exports its function as a default export, not a named export.
fix
For CommonJS: `const merge = require('utils-merge');`. For ESM: `import merge from 'utils-merge';`.
Uncaught TypeError: Cannot set properties of undefined (reading 'foo')
Attempting to merge into a non-object destination (e.g., `merge(null, source)` or `merge(undefined, source)`), which is not supported.
fix
Ensure the first argument passed to `merge` is always a valid object (or an empty object literal if you intend to create a new one, e.g., `merge({}, source)`).
My nested object properties are gone after merging!
The `utils-merge` function performs a shallow merge, replacing entire nested objects rather than merging their individual properties.
fix
This is expected behavior for `utils-merge`. If deep merging is required, use a dedicated deep merge library or manually implement a recursive merge.
Upgrade
Version history
1.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources