node.extend

node.extend is a faithful port of jQuery's extend function that works reliably in Node.js environments. It enables developers to merge and clone JavaScript objects with support for both shallow and deep copying operations, addressing limitations found in other extend implementations available on npm.

Package Information

• Package Name: node.extend
• Package Type: npm
• Language: JavaScript
• Installation: npm install node.extend

Core Imports

const extend = require('node.extend');

For ES modules:

import extend from 'node.extend';

Basic Usage

const extend = require('node.extend');

// Shallow merge
const result = extend({}, { a: 1 }, { b: 2 });
// Result: { a: 1, b: 2 }

// Deep merge
const deep = extend(true, {}, { 
  nested: { a: 1 } 
}, { 
  nested: { b: 2 } 
});
// Result: { nested: { a: 1, b: 2 } }

// Clone an object
const original = { name: 'Alice', age: 30 };
const clone = extend({}, original);

Capabilities

Object Extend Function

Merges and clones JavaScript objects with support for shallow and deep copying.

/**
 * Extends objects with properties from source objects
 * @param {boolean} [deep] - If true, performs deep merge recursively
 * @param {any} target - The target object to extend (modified in-place)
 * @param {...any} sources - One or more source objects to merge into target
 * @returns {any} The modified target object with merged properties
 */
function extend([deep,] target, ...sources);

Parameters:

• deep (optional): Boolean - When true, performs recursive deep merge of nested objects and arrays
• target: Any - The target object to extend. Non-object values are converted to empty objects {}
• sources: Any - One or more source objects whose properties will be copied to the target

Return Value:

Returns the modified target object containing merged properties from all source objects.

Behavior Details:

1. Type Coercion: Non-object targets (strings, numbers, etc.) are converted to empty objects {}
2. String Handling: String sources are converted to object form with numeric keys (e.g., "abc" becomes {0: 'a', 1: 'b', 2: 'c'})
3. Array Handling: Arrays are treated as objects with numeric indices as keys
4. Deep Merge: When deep=true, recursively merges nested objects and arrays
5. Property Safety: Properly handles the __proto__ property using Object.defineProperty when available
6. Circular Reference Protection: Prevents infinite loops from objects that reference themselves
7. Undefined Values: Undefined values from sources are ignored and not copied to the target

Usage Examples:

const extend = require('node.extend');

// Basic shallow merge
const user = { name: 'Alice' };
const details = { age: 30, city: 'New York' };
const result = extend(user, details);
// user and result are: { name: 'Alice', age: 30, city: 'New York' }

// Multiple source objects
const config = extend({}, defaults, options, overrides);

// Deep merge for nested objects
const defaultConfig = {
  api: { timeout: 5000, retries: 3 },
  logging: { level: 'info' }
};
const userConfig = {
  api: { retries: 5 },
  logging: { level: 'debug', format: 'json' }
};
const finalConfig = extend(true, {}, defaultConfig, userConfig);
// Result: {
//   api: { timeout: 5000, retries: 5 },
//   logging: { level: 'debug', format: 'json' }
// }

// Cloning objects (shallow)
const original = { items: [1, 2, 3], meta: { count: 3 } };
const shallowClone = extend({}, original);
// shallowClone.items === original.items (same reference)

// Cloning objects (deep)
const deepClone = extend(true, {}, original);
// deepClone.items !== original.items (different reference)

// Working with arrays
const arr1 = [1, 2, 3];
const arr2 = ['a', 'b'];
const merged = extend(arr1, arr2);
// arr1 and merged are: ['a', 'b', 3]

// String sources are converted to objects
const target = extend({}, 'hello');
// Result: { 0: 'h', 1: 'e', 2: 'l', 3: 'l', 4: 'o' }

Error Handling:

The function gracefully handles edge cases without throwing errors:

• null or undefined sources are ignored
• Circular references are detected and prevented
• Type coercion ensures consistent behavior across different input types

Type Compatibility:

The function handles these type combinations:

• Object + Object → Merged object
• Array + Array → Merged array (properties by index)
• String + Any → Object form of string with additional properties
• Number + Object → Object (number ignored)
• Date + Object → Date with object properties attached
• Any + undefined/null → Target unchanged