or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

customization.mdimmutable-merging.mdindex.mdmutable-merging.mdutilities.md
tile.json

tessl/npm-deepmerge-ts

Deeply merge 2 or more objects respecting type information.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/deepmerge-ts@6.0.x

To install, run

npx @tessl/cli install tessl/npm-deepmerge-ts@6.0.0

index.mddocs/

Deepmerge TS

Deepmerge TS provides high-performance, type-safe deep merging of 2 or more objects, arrays, Maps, and Sets with full TypeScript type inference. It offers both immutable merging (creating new objects) and mutable merging (updating objects in place), with extensive customization options for different data structures.

Package Information

  • Package Name: deepmerge-ts
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install deepmerge-ts or pnpm add deepmerge-ts or yarn add deepmerge-ts

Core Imports

import { deepmerge, deepmergeCustom, deepmergeInto, deepmergeIntoCustom } from "deepmerge-ts";

For CommonJS:

const { deepmerge, deepmergeCustom, deepmergeInto, deepmergeIntoCustom } = require("deepmerge-ts");

Basic Usage

import { deepmerge } from "deepmerge-ts";

// Basic object merging
const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 }, e: 4 };
const merged = deepmerge(obj1, obj2);
// Result: { a: 1, b: { c: 2, d: 3 }, e: 4 }

// Array merging
const arr1 = [1, 2, 3];
const arr2 = [4, 5, 6];
const mergedArrays = deepmerge(arr1, arr2);
// Result: [1, 2, 3, 4, 5, 6]

// Map and Set merging
const map1 = new Map([["key1", "value1"]]);
const map2 = new Map([["key2", "value2"]]);
const mergedMaps = deepmerge(map1, map2);
// Result: Map with both key-value pairs

const set1 = new Set([1, 2]);
const set2 = new Set([2, 3]);
const mergedSets = deepmerge(set1, set2);
// Result: Set with [1, 2, 3]

Architecture

Deepmerge TS is built around several key architectural patterns:

  • Dual API Pattern: Provides both immutable (deepmerge) and mutable (deepmergeInto) merging approaches
  • Type Inference System: Uses Higher-Kinded Types (HKT) and URI mapping for compile-time type inference
  • Smart Merging Algorithm: Looks ahead to optimize performance by avoiding sequential merge patterns
  • Customizable Merge Functions: Supports custom merge strategies for objects, arrays, Maps, Sets, and other types
  • Metadata System: Extensible metadata support for advanced merge customization
  • Action-Based Control: Uses symbols to control merge behavior (skip, default merge)

Capabilities

Immutable Deep Merging

Core immutable merging functionality that creates new objects while preserving the original inputs. Perfect for functional programming patterns and state management.

function deepmerge<Ts extends Readonly<ReadonlyArray<unknown>>>(
  ...objects: readonly [...Ts]
): DeepMergeHKT<Ts, DeepMergeMergeFunctionsDefaultURIs, DeepMergeBuiltInMetaData>;

function deepmergeCustom<
  BaseTs = unknown,
  PMF extends Partial<DeepMergeMergeFunctionsURIs> = {},
>(
  options: DeepMergeOptions<DeepMergeBuiltInMetaData, DeepMergeBuiltInMetaData>
): <Ts extends ReadonlyArray<BaseTs>>(
  ...objects: Ts
) => DeepMergeHKT<Ts, GetDeepMergeMergeFunctionsURIs<PMF>, DeepMergeBuiltInMetaData>;

Immutable Merging

Mutable Deep Merging

High-performance mutable merging that modifies target objects in place. Ideal for performance-critical applications and large data processing.

function deepmergeInto<T extends object>(
  target: T,
  ...objects: ReadonlyArray<T>
): void;

function deepmergeIntoCustom<BaseTs = unknown>(
  options: DeepMergeIntoOptions<DeepMergeBuiltInMetaData, DeepMergeBuiltInMetaData>
): <Target extends object, Ts extends ReadonlyArray<BaseTs>>(
  target: Target,
  ...objects: Ts
) => void;

Mutable Merging

Utility Functions

Helper functions for object type detection and property manipulation.

function getObjectType(object: unknown): ObjectType;
function getKeys(objects: ReadonlyArray<object>): Set<PropertyKey>;
function objectHasProperty(object: object, property: PropertyKey): boolean;
function getIterableOfIterables<T>(
  iterables: ReadonlyArray<Readonly<Iterable<T>>>
): Iterable<T>;

type ObjectType = 0 | 1 | 2 | 3 | 4 | 5; // const enum values

Utilities

Merge Customization

Advanced customization options including custom merge functions for different data types and metadata handling.

interface DeepMergeOptions<M, MM extends Readonly<Record<PropertyKey, unknown>>> {
  mergeRecords?: DeepMergeMergeFunctions<M, MM>["mergeRecords"] | false;
  mergeArrays?: DeepMergeMergeFunctions<M, MM>["mergeArrays"] | false;
  mergeMaps?: DeepMergeMergeFunctions<M, MM>["mergeMaps"] | false;
  mergeSets?: DeepMergeMergeFunctions<M, MM>["mergeSets"] | false;
  mergeOthers?: DeepMergeMergeFunctions<M, MM>["mergeOthers"];
  metaDataUpdater?: (previousMeta: M | undefined, metaMeta: Readonly<Partial<MM>>) => M;
  enableImplicitDefaultMerging?: boolean;
}

// Note: Special action symbols are available within custom merge functions
// but are not exported from the main package interface

Customization

Core Types

// Higher-Kinded Type for merge result inference
type DeepMergeHKT<
  Ts extends ReadonlyArray<unknown>,
  MF extends DeepMergeMergeFunctionsURIs,
  M
>;

// Built-in metadata type
type DeepMergeBuiltInMetaData = Readonly<Record<PropertyKey, unknown>>;

// Reference wrapper for mutable operations
type Reference<T> = { value: T };

// Default merge function URIs
type DeepMergeMergeFunctionsDefaultURIs = Readonly<{
  DeepMergeRecordsURI: "DeepMergeRecordsDefaultURI";
  DeepMergeArraysURI: "DeepMergeArraysDefaultURI";
  DeepMergeSetsURI: "DeepMergeSetsDefaultURI";
  DeepMergeMapsURI: "DeepMergeMapsDefaultURI";
  DeepMergeOthersURI: "DeepMergeLeafURI";
}>;

// Type alias for mutable merging default functions
type DeepMergeMergeIntoFunctionsDefaults = {
  mergeRecords: typeof mergeRecords;
  mergeArrays: typeof mergeArrays;
  mergeSets: typeof mergeSets;
  mergeMaps: typeof mergeMaps;
  mergeOthers: typeof mergeOthers;
};

// Type alias for immutable merging default functions  
type DeepMergeMergeFunctionsDefaults = {
  mergeRecords: typeof mergeRecords;
  mergeArrays: typeof mergeArrays;
  mergeSets: typeof mergeSets;
  mergeMaps: typeof mergeMaps;
  mergeOthers: typeof mergeOthers;
};