ngraph.merge

1.0.0 · abandoned · verified Sun Apr 19

ngraph.merge is a minimalist JavaScript utility designed to extend target objects with properties from source objects without introducing external dependencies. It primarily operates as a shallow merge. Its key differentiator is a specific, somewhat unconventional, conflict resolution strategy: properties from the source will overwrite existing target properties only if their types differ. If the target already contains a property with the same name and type, it is *not* overwritten by the source property. The package is currently at version 1.0.0, with its last commit in 2017, indicating it is no longer actively maintained and has an abandoned release cadence. Its zero-dependency footprint makes it suitable for environments where bundle size and dependency chain control are critical, though its unique merge logic requires careful consideration.

Common errors

```
TypeError: require is not a function
```
cause Attempting to use `require` in an ES module context or a browser environment without a CommonJS bundler.

fix This package is CommonJS-only. If you are in an ES module environment (e.g., `"type": "module"` in package.json), you may need to use `import merge from 'ngraph.merge';` (which will likely fail if a CJS wrapper is not provided) or revert to a CJS environment. Alternatively, use a bundler that handles CJS modules in an ESM project.
```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use `import merge from 'ngraph.merge';` in a CommonJS context.

fix This package is CommonJS-only. Use `const merge = require('ngraph.merge');` instead of `import` statements.
```
Property value not updated as expected during merge.
```
cause Misunderstanding of `ngraph.merge`'s specific overwrite logic: it only overwrites if the types of the source and target properties differ. If types are the same, the target property is retained.

fix Review the documentation and examples. If this behavior is not desired, consider using a different merge utility with standard overwrite behavior.

Warnings

gotcha Properties are only overwritten if the target object's existing property has a *different* type than the source property. If the types are the same, the existing property in the target object is preserved.
Fix: Be aware of this specific merge logic. If you need a standard deep merge or consistent overwrite behavior, consider an alternative utility like `lodash.merge` or `deepmerge`.
gotcha This utility performs a shallow merge. Nested objects within the source will not be deeply merged into nested objects in the target; instead, they will be assigned by reference or entirely replaced if types differ.
Fix: For deep merging of nested objects, you will need to use a different utility specifically designed for deep merges.
deprecated The package has not been updated since 2017 and is considered abandoned. It uses older CommonJS modules and Travis CI for builds, which are indicators of inactivity. There will likely be no further updates or security patches.
Fix: For new projects or if active maintenance is required, consider modern, actively maintained alternatives that support ES Modules and have more conventional merge behaviors.

Install

npm install ngraph.merge npm
yarn add ngraph.merge yarn
pnpm add ngraph.merge pnpm

Imports

merge
wrong:
```
import merge from 'ngraph.merge';
```
correct:
```
const merge = require('ngraph.merge');
```
This package is CommonJS-only and does not provide ES module exports. Direct ESM imports will fail.

Quickstart

This quickstart demonstrates basic usage and highlights the specific shallow merge logic and overwrite behavior based on type matching.

const merge = require('ngraph.merge');

const defaults = {
  name: 'Guest',
  age: 30,
  isActive: true,
  settings: { theme: 'dark' }
};

const userOptions = {
  name: 'Alice',       // Same type as default, will not overwrite
  age: 'thirty',      // Different type (string vs number), will overwrite
  isAdmin: false,
  settings: { debug: true } // New property for settings, will overwrite entire settings object if it's not a deep merge
};

const finalOptions = {};
merge(finalOptions, defaults);
console.log('1. After merging with defaults:', finalOptions);
// Expected: { name: 'Guest', age: 30, isActive: true, settings: { theme: 'dark' } }

merge(finalOptions, userOptions);
console.log('2. After merging with user options:', finalOptions);
// Expected: { name: 'Guest', age: 'thirty', isActive: true, isAdmin: false, settings: { theme: 'dark' } }
// Note: `name` remains 'Guest' because types match. `age` becomes 'thirty' due to type mismatch.
// `settings` in `userOptions` will not overwrite because the `settings` property in `finalOptions` already exists and has the same object type.

console.log('Final Name:', finalOptions.name);     // Expected: 'Guest'
console.log('Final Age:', finalOptions.age);       // Expected: 'thirty'
console.log('Final Is Admin:', finalOptions.isAdmin); // Expected: false
console.log('Final Settings:', finalOptions.settings); // Expected: { theme: 'dark' } - not affected by userOptions.settings because it's a shallow merge and type match.

view raw JSON →