Merge

Merge provides comprehensive object merging utilities for JavaScript and TypeScript applications. It enables developers to merge objects with optional deep cloning and recursive merging capabilities, featuring built-in prototype pollution protection and flexible API patterns.

Package Information

• Package Name: merge
• Package Type: npm
• Language: TypeScript
• Installation: npm install merge

Core Imports

import merge from "merge";

For CommonJS:

const merge = require("merge");

Named imports (alternative approach):

import { merge, recursive, clone, isPlainObject } from "merge";

Basic Usage

import merge from "merge";

// Basic shallow merge using default export
const result1 = merge({ a: 1 }, { b: 2 });
// Result: { a: 1, b: 2 }

// Merge with cloning (first parameter true)
const original = { a: 1 };
const result2 = merge(true, original, { b: 2 });
// Result: { a: 1, b: 2 }, original unchanged

// Recursive merge using namespace property
const result3 = merge.recursive(
  { level: { value: 1 } }, 
  { level: { str: 'hello' } }
);
// Result: { level: { value: 1, str: 'hello' } }

// Deep clone using namespace property
const cloned = merge.clone({ a: { b: 1 } });

// Alternative: using named imports
import { merge as mergeFunc, recursive, clone } from "merge";
const result4 = mergeFunc({ a: 1 }, { b: 2 });
const result5 = recursive({ a: { b: 1 } }, { a: { c: 2 } });
// result4: { a: 1, b: 2 }
// result5: { a: { b: 1, c: 2 } }

Capabilities

Main Function (Default Export)

The primary merge function exported as default. Identical to the named merge function but also provides namespace access to other functions.

function main(clone: boolean, ...items: any[]): any;
function main(...items: any[]): any;

When the first parameter is true, objects are cloned before merging to prevent mutation of input objects. Otherwise, the first object in the arguments is mutated and returned.

Parameters:

• clone (boolean, optional): When true, clones objects before merging
• ...items (any[]): Objects to merge together

Returns: Merged object

Namespace Properties:

• main.clone - Reference to clone function
• main.isPlainObject - Reference to isPlainObject function
• main.recursive - Reference to recursive function

Basic Merge

Performs shallow merging of objects with optional cloning.

function merge(clone: boolean, ...items: any[]): any;
function merge(...items: any[]): any;

When the first parameter is true, objects are cloned before merging to prevent mutation of input objects. Otherwise, the first object in the arguments is mutated and returned.

Parameters:

• clone (boolean, optional): When true, clones objects before merging
• ...items (any[]): Objects to merge together

Returns: Merged object

Recursive Merge

Performs deep/recursive merging of nested objects with optional cloning. Available as both a named export and as a namespace property on the main function.

function recursive(clone: boolean, ...items: any[]): any;
function recursive(...items: any[]): any;

Recursively merges nested objects instead of replacing them entirely. Automatically filters dangerous prototype pollution keys (__proto__, constructor, prototype).

Parameters:

• clone (boolean, optional): When true, clones objects before merging
• ...items (any[]): Objects to recursively merge

Returns: Recursively merged object

Clone

Deep clones objects and arrays, preserving nested structures. Available as both a named export and as a namespace property on the main function.

function clone<T>(input: T): T;

Creates a deep copy of the input, handling nested objects and arrays recursively. Primitive values are returned as-is.

Parameters:

• input (any): Object, array, or primitive to clone

Returns: Deep cloned copy of the input

Plain Object Check

Checks if input is a plain object (not array, null, or primitive). Available as both a named export and as a namespace property on the main function.

function isPlainObject(input: any): input is Object;

Type predicate function that determines if the input is a plain object suitable for merging operations.

Parameters:

• input (any): Value to check

Returns: true if input is a plain object, false otherwise

Types

For TypeScript users, the package includes complete type definitions:

// Main function with overloads
declare function main(clone: boolean, ...items: any[]): any;
declare function main(...items: any[]): any;

// Named export functions
declare function merge(clone: boolean, ...items: any[]): any;
declare function merge(...items: any[]): any;
declare function recursive(clone: boolean, ...items: any[]): any;
declare function recursive(...items: any[]): any;
declare function clone<T>(input: T): T;
declare function isPlainObject(input: any): input is Object;

// Main function namespace properties
declare namespace main {
  var clone: typeof clone;
  var isPlainObject: typeof isPlainObject;
  var recursive: typeof recursive;
}

Security Features

The merge package includes built-in protection against prototype pollution attacks:

• Automatically filters dangerous keys: __proto__, constructor, prototype
• Safe for use with user-provided data and JSON payloads
• Protection applies to both shallow and recursive merge operations

Error Handling

The package gracefully handles invalid inputs:

• Non-objects are filtered out during merging
• null, undefined, arrays, and primitives are ignored
• Empty arguments return an empty object {}
• No exceptions are thrown for invalid inputs