or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

extend

extend is a port of jQuery's classic extend() method for Node.js and the browser. It provides reliable object merging and cloning functionality with support for both shallow and deep copying, making it ideal for configuration management, object composition, and data transformation tasks.

Package Information

Package Name: extend
Package Type: npm
Language: JavaScript
Installation: npm install extend

Core Imports

const extend = require('extend');

For ES modules (via bundlers):

import extend from 'extend';

Basic Usage

const extend = require('extend');

// Shallow merging
const target = { a: 1, b: 2 };
const source = { b: 3, c: 4 };
const result = extend(target, source);
// result: { a: 1, b: 3, c: 4 }
// Note: target is modified and returned

// Deep merging
const deepTarget = { 
  config: { debug: false, port: 3000 },
  features: { auth: true }
};
const deepSource = { 
  config: { debug: true, host: 'localhost' },
  features: { logging: true }
};
const deepResult = extend(true, deepTarget, deepSource);
// Result: {
//   config: { debug: true, port: 3000, host: 'localhost' },
//   features: { auth: true, logging: true }
// }

Capabilities

Object Merging and Cloning

The extend function merges properties from one or more source objects into a target object, with optional deep cloning support.

/**
 * Merge properties from source objects into target object
 * @param {boolean} [deep] - If true, performs deep/recursive merge
 * @param {object} target - The object to extend (will be modified)
 * @param {object} object1 - Object containing properties to merge
 * @param {...object} [objectN] - Additional objects to merge
 * @returns {object} The modified target object
 */
function extend([deep], target, object1, ...objectN);

Key Behaviors:

Target Modification: The first object argument (target) is modified in place and returned
Deep vs Shallow: Pass true as first argument for deep/recursive merging
Type Handling: Handles objects, arrays, strings, numbers, dates, and other types
Security: Safely handles __proto__ property to prevent prototype pollution
Undefined Values: Skips undefined properties during merge
Circular References: Prevents infinite loops from circular object references

Usage Examples:

// Multiple object merging
const config = extend(
  { server: { port: 3000 } },
  { server: { host: 'localhost' } },
  { database: { url: 'mongodb://localhost' } }
);
// Result: {
//   server: { host: 'localhost' },  // shallow merge overwrites
//   database: { url: 'mongodb://localhost' }
// }

// Deep merging preserves nested properties
const deepConfig = extend(true,
  { server: { port: 3000, ssl: false } },
  { server: { host: 'localhost' } }
);
// Result: {
//   server: { port: 3000, ssl: false, host: 'localhost' }
// }

// Array merging (shallow)
const arrayResult = extend([1, 2, 3], [4, 5]);
// Result: [4, 5, 3] (array elements are overwritten by index)

// Deep array merging
const deepArrayResult = extend(true, [1, [2, 3]], [4, [5]]);
// Result: [4, [5, 3]] (nested arrays are merged)

// Cloning objects (target as empty object)
const original = { a: 1, nested: { b: 2 } };
const shallowClone = extend({}, original);  // shallow clone
const deepClone = extend(true, {}, original);  // deep clone

// Handle edge cases
extend(null, { a: 1 });          // Returns { a: 1 }
extend(undefined, { a: 1 });     // Returns { a: 1 }  
extend({ a: 1 });                // Returns { a: 1 } (single argument)
extend();                        // Returns {} (no arguments)

Type Conversion Examples:

// String to object conversion
extend('hello', { 0: 'H' });  // Result: { 0: 'H', 1: 'e', 2: 'l', 3: 'l', 4: 'o' }

// Number becomes empty object
extend(42, { a: 1 });  // Result: { a: 1 }

// Function becomes empty object (then gets properties)
extend(function() {}, { a: 1 });  // Result: { a: 1 }

// Date object behavior
extend(new Date(), { custom: 'prop' });  // Adds custom property to date

// Special property handling (constructor, isPrototypeOf)
extend({}, { constructor: 'fake', isPrototypeOf: 'not a function' });
// Result: { constructor: 'fake', isPrototypeOf: 'not a function' }

Security Considerations:

// Safe __proto__ handling
const malicious = { __proto__: { evil: true } };
const target = {};
extend(target, malicious);
// target.__proto__ is set as own property, doesn't affect prototype chain

Browser Compatibility

Node.js: All supported versions
Browsers: IE9+ and all modern browsers
Dependencies: Zero runtime dependencies
Module Systems: CommonJS (native), ES modules (via bundlers), UMD (via bundlers)

Performance Notes

Shallow merging is faster than deep merging
Deep merging creates new objects/arrays rather than sharing references
Large nested objects may impact performance with deep merging
Gracefully handles environments without Array.isArray (falls back to toString check)
Consider Object.assign() for simple shallow merging in modern environments (though it lacks deep merge capability)