utils-merge

Common errors

• TypeError: merge is not a function

  cause 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')

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

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

Warnings

• gotcha 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.
  Fix: For deep merging behavior, consider using libraries like `lodash.merge`, `deepmerge`, or implementing a custom recursive merge function.
• gotcha 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`.
  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);`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install utils-merge npm
• yarn add utils-merge yarn
• pnpm add utils-merge pnpm

Imports

• merge
  wrong:

  const { merge } = require('utils-merge');

  correct:

  const merge = require('utils-merge');

  The package exports the `merge` function as the default CommonJS export.
• merge
  wrong:

  import { merge } from 'utils-merge';

  correct:

  import merge from 'utils-merge';

  For ESM, `merge` is the default export. Named import syntax will result in undefined.
• merge (TypeScript)
  wrong:

  import * as merge from 'utils-merge';

  correct:

  import merge from 'utils-merge';

  While CommonJS `require` often defaults to `* as`, the type definition for `utils-merge` typically expects a default import for `merge`.

Quickstart

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