deep-diff-value

One-directional deep structural diff — returns only the changed parts of a value

Install

npm install @voxpelli/deep-diff-value

Usage

import { getDeepDifference } from '@voxpelli/deep-diff-value';

getDeepDifference({ a: 1, b: 2 }, { a: 1, b: 3 });
// => { b: 3 }

getDeepDifference({ a: 1 }, { a: 1 });
// => undefined

getDeepDifference([1, 2, 3], [1, 9, 3]);
// => [9]

API

getDeepDifference(valueA, valueB)

Compares valueB against valueA and returns only the parts of valueB that differ. Returns undefined when the two values are equal.

Syntax

getDeepDifference(valueA, valueB) => ValueB | DeepPartial<ValueB> | undefined

Arguments

• valueA — ValueA | undefined — the base value to compare against
• valueB — ValueB | undefined — the new value; must be assignable to ValueA | DeepPartial<ValueA>

Returns

• undefined when valueA and valueB are equal (by reference or deep equality)
• For plain objects: a new object containing only the keys whose values changed, recursively diffed
• For arrays: a new array containing only the elements that changed, recursively diffed
• For primitives and other values: valueB directly

Throws if a circular reference is detected or the structure exceeds 20 levels of depth.

DeepPartial<T>

A utility type that recursively makes all properties of an object type optional. Arrays become Array<DeepPartial<T[number]>>. Primitives are returned as-is.

type DeepPartial<T> =
  T extends Record<PropertyKey, unknown>
    ? { [Key in keyof T]?: DeepPartial<T[Key]> }
    : T extends unknown[]
      ? Array<DeepPartial<T[number]>>
      : T;