{"id":12333,"library":"utils-merge","title":"utils-merge","description":"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.","status":"maintenance","version":"1.0.1","language":"javascript","source_language":"en","source_url":"git://github.com/jaredhanson/utils-merge","tags":["javascript","util"],"install":[{"cmd":"npm install utils-merge","lang":"bash","label":"npm"},{"cmd":"yarn add utils-merge","lang":"bash","label":"yarn"},{"cmd":"pnpm add utils-merge","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports the `merge` function as the default CommonJS export.","wrong":"const { merge } = require('utils-merge');","symbol":"merge","correct":"const merge = require('utils-merge');"},{"note":"For ESM, `merge` is the default export. Named import syntax will result in undefined.","wrong":"import { merge } from 'utils-merge';","symbol":"merge","correct":"import merge from 'utils-merge';"},{"note":"While CommonJS `require` often defaults to `* as`, the type definition for `utils-merge` typically expects a default import for `merge`.","wrong":"import * as merge from 'utils-merge';","symbol":"merge (TypeScript)","correct":"import merge from 'utils-merge';"}],"quickstart":{"code":"const merge = require('utils-merge'); // CommonJS import for Node.js environments\n\n// Define initial objects\nlet userProfile = {\n  id: 'user123',\n  name: 'Jane Doe',\n  settings: {\n    theme: 'dark',\n    notifications: { email: true, sms: false }\n  }\n};\n\nlet defaultProfileSettings = {\n  language: 'en-US',\n  settings: {\n    notifications: { email: false, push: true }, // This will completely replace userProfile.settings.notifications\n    privacy: { dataSharing: false }\n  },\n  status: 'active'\n};\n\nconsole.log('Initial User Profile:', JSON.stringify(userProfile, null, 2));\nconsole.log('Default Settings to Merge:', JSON.stringify(defaultProfileSettings, null, 2));\n\n// Perform the merge operation\n// WARNING: utils-merge performs a shallow merge and mutates the destination object.\n// Nested objects from the source will replace the corresponding nested objects in the destination,\n// rather than merging their properties recursively.\nmerge(userProfile, defaultProfileSettings);\n\nconsole.log('\\nUser Profile After Shallow Merge (destination mutated):', JSON.stringify(userProfile, null, 2));\n\n// Example of shallow merge for nested objects:\nlet objA = { config: { timeout: 1000, retries: 3 } };\nlet objB = { config: { timeout: 5000, maxAttempts: 5 } };\n\nconsole.log('\\nBefore nested merge: objA =', JSON.stringify(objA));\nmerge(objA, objB);\nconsole.log('After nested merge (config from objB replaced objA.config): objA =', JSON.stringify(objA));\n\n// To create a new object without mutating the original 'userProfile' while using utils-merge:\n// First, create a shallow copy of 'userProfile' (or an empty object),\n// then merge the defaults into that copy.\nlet newMergedProfile = merge({}, userProfile);\nmerge(newMergedProfile, defaultProfileSettings); // Note: This example is illustrative. For true deep merge, other libs are needed.\n\nconsole.log('\\nNew merged profile (via cloning then merging):', JSON.stringify(newMergedProfile, null, 2));\n","lang":"javascript","description":"Demonstrates the shallow merging behavior and direct object mutation of `utils-merge`, showing how it combines properties and handles nested objects by replacement."},"warnings":[{"fix":"For deep merging behavior, consider using libraries like `lodash.merge`, `deepmerge`, or implementing a custom recursive merge function.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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);`.","message":"The `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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For CommonJS: `const merge = require('utils-merge');`. For ESM: `import merge from 'utils-merge';`.","cause":"Incorrect import statement; `utils-merge` exports its function as a default export, not a named export.","error":"TypeError: merge is not a function"},{"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)`).","cause":"Attempting to merge into a non-object destination (e.g., `merge(null, source)` or `merge(undefined, source)`), which is not supported.","error":"Uncaught TypeError: Cannot set properties of undefined (reading 'foo')"},{"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.","cause":"The `utils-merge` function performs a shallow merge, replacing entire nested objects rather than merging their individual properties.","error":"My nested object properties are gone after merging!"}],"ecosystem":"npm"}