deepMerge

Recursively merges two objects into a new object. Nested plain objects are merged deeply, while arrays and other types are overwritten by the source value.

Import

import { deepMerge } from "1o1-utils";

import { deepMerge } from "1o1-utils/deep-merge";

Signature

function deepMerge({ target, source }: DeepMergeParams): Record<string, unknown>

Parameters

Name	Type	Required	Description
target	Record<string, unknown>	Yes	The base object
source	Record<string, unknown>	Yes	The object to merge into target

Returns

Record<string, unknown> — A new merged object (neither input is mutated).

Examples

deepMerge({
  target: { a: 1, b: { x: 10 } },
  source: { b: { y: 20 }, c: 3 },
});
// => { a: 1, b: { x: 10, y: 20 }, c: 3 }

Edge Cases

• Throws if target is not a plain object.
• Throws if source is not a plain object.
• Only merges plain objects recursively; arrays and other types are overwritten.
• Uses a stack-based (non-recursive) algorithm to avoid stack overflow on deeply nested objects.

Also known as

merge objects, recursive merge, combine objects, extend deep

Prompt suggestion

I'm using 1o1-utils (npm: https://www.npmjs.com/package/1o1-utils, GitHub: https://github.com/pedrotroccoli/1o1-utils, LLM context: https://pedrotroccoli.github.io/1o1-utils/llms.txt). Show me how to use deepMerge to merge user settings with defaults