@jayoncode/object-diff API

---

@jayoncode/object-diff API

Classes

ObjectDiffError

Extends

• Error

Extended by

• CircularReferenceError
• InvalidOptionsError
• InvalidPatchError
• MaxDepthExceededError
• NotImplementedError
• PatchApplyError
• PluginError
• UnsupportedTypeError

Constructors

Constructor

new ObjectDiffError(
   message: string, 
   code: ObjectDiffErrorCode, 
   options?: ObjectDiffErrorOptions): ObjectDiffError;

Parameters

Parameter	Type
message	string
code	ObjectDiffErrorCode
options	ObjectDiffErrorOptions

Returns

ObjectDiffError

Overrides

Error.constructor

Properties

Property	Modifier	Type
code	readonly	ObjectDiffErrorCode
details	readonly	Readonly<PlainObject> | undefined

---

CircularReferenceError

Extends

• ObjectDiffError

Constructors

Constructor

new CircularReferenceError(message: string, options?: ObjectDiffErrorOptions): CircularReferenceError;

Parameters

Parameter	Type
message	string
options	ObjectDiffErrorOptions

Returns

CircularReferenceError

Overrides

ObjectDiffError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	ObjectDiffErrorCode	ObjectDiffError.code
details	readonly	Readonly<PlainObject> | undefined	ObjectDiffError.details

---

MaxDepthExceededError

Extends

• ObjectDiffError

Constructors

Constructor

new MaxDepthExceededError(message: string, options?: ObjectDiffErrorOptions): MaxDepthExceededError;

Parameters

Parameter	Type
message	string
options	ObjectDiffErrorOptions

Returns

MaxDepthExceededError

Overrides

ObjectDiffError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	ObjectDiffErrorCode	ObjectDiffError.code
details	readonly	Readonly<PlainObject> | undefined	ObjectDiffError.details

---

InvalidPatchError

Extends

• ObjectDiffError

Constructors

Constructor

new InvalidPatchError(message: string, options?: ObjectDiffErrorOptions): InvalidPatchError;

Parameters

Parameter	Type
message	string
options	ObjectDiffErrorOptions

Returns

InvalidPatchError

Overrides

ObjectDiffError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	ObjectDiffErrorCode	ObjectDiffError.code
details	readonly	Readonly<PlainObject> | undefined	ObjectDiffError.details

---

PatchApplyError

Extends

• ObjectDiffError

Constructors

Constructor

new PatchApplyError(message: string, options?: ObjectDiffErrorOptions): PatchApplyError;

Parameters

Parameter	Type
message	string
options	ObjectDiffErrorOptions

Returns

PatchApplyError

Overrides

ObjectDiffError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	ObjectDiffErrorCode	ObjectDiffError.code
details	readonly	Readonly<PlainObject> | undefined	ObjectDiffError.details

---

UnsupportedTypeError

Extends

• ObjectDiffError

Constructors

Constructor

new UnsupportedTypeError(message: string, options?: ObjectDiffErrorOptions): UnsupportedTypeError;

Parameters

Parameter	Type
message	string
options	ObjectDiffErrorOptions

Returns

UnsupportedTypeError

Overrides

ObjectDiffError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	ObjectDiffErrorCode	ObjectDiffError.code
details	readonly	Readonly<PlainObject> | undefined	ObjectDiffError.details

---

NotImplementedError

Extends

• ObjectDiffError

Constructors

Constructor

new NotImplementedError(message: string, options?: ObjectDiffErrorOptions): NotImplementedError;

Parameters

Parameter	Type
message	string
options	ObjectDiffErrorOptions

Returns

NotImplementedError

Overrides

ObjectDiffError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	ObjectDiffErrorCode	ObjectDiffError.code
details	readonly	Readonly<PlainObject> | undefined	ObjectDiffError.details

---

InvalidOptionsError

Extends

• ObjectDiffError

Constructors

Constructor

new InvalidOptionsError(message: string, options?: ObjectDiffErrorOptions): InvalidOptionsError;

Parameters

Parameter	Type
message	string
options	ObjectDiffErrorOptions

Returns

InvalidOptionsError

Overrides

ObjectDiffError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	ObjectDiffErrorCode	ObjectDiffError.code
details	readonly	Readonly<PlainObject> | undefined	ObjectDiffError.details

---

PluginError

Extends

• ObjectDiffError

Constructors

Constructor

new PluginError(message: string, options?: ObjectDiffErrorOptions): PluginError;

Parameters

Parameter	Type
message	string
options	ObjectDiffErrorOptions

Returns

PluginError

Overrides

ObjectDiffError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	ObjectDiffErrorCode	ObjectDiffError.code
details	readonly	Readonly<PlainObject> | undefined	ObjectDiffError.details

Interfaces

DiffRecord

A single recorded change between two values.

Properties

Property	Modifier	Type	Description
path	readonly	string	-
type	readonly	DiffType	-
previous?	readonly	unknown	-
current?	readonly	unknown	-
from?	readonly	string	Source display path when type is moved.

---

DiffMetadata

Metadata collected during a diff operation.

Properties

Property	Modifier	Type
durationMs	readonly	number
changeCount	readonly	number
addedCount	readonly	number
removedCount	readonly	number
changedCount	readonly	number
unchangedCount	readonly	number
movedCount	readonly	number

---

DiffResult

Result of a diff operation.

Properties

Property	Modifier	Type
changes	readonly	readonly DiffRecord[]
metadata	readonly	DiffMetadata

---

DiffOptions

Options for diff and filtered diff helpers.

Properties

Property	Modifier	Type	Description
maxDepth?	readonly	number	-
includeUnchanged?	readonly	boolean	-
detectMoves?	readonly	boolean	When true, pair equal removed+added values into moved records (and JSON Patch move ops).
circular?	readonly	CircularReferenceStrategy	-
customComparator?	readonly	CustomComparator	-
treatUndefinedAsMissing?	readonly	boolean	-
identityKey?	readonly	IdentityKey	Match array elements by identity instead of index.
ignore?	readonly	readonly string[]	Skip paths matching these patterns (*, ** supported).
include?	readonly	readonly string[]	Only emit/visit paths matching these patterns (ancestors still visited).

---

CompareOptions

Options for deep equality comparison.

Properties

Property	Modifier	Type
maxDepth?	readonly	number
circular?	readonly	CircularReferenceStrategy
customComparator?	readonly	CustomComparator

---

ResolvedDiffOptions

Normalized diff options used internally.

Properties

Property	Modifier	Type
maxDepth	readonly	number
includeUnchanged	readonly	boolean
detectMoves	readonly	boolean
circular	readonly	CircularReferenceStrategy
customComparator	readonly	CustomComparator | undefined
treatUndefinedAsMissing	readonly	boolean
identityKey	readonly	IdentityKey | undefined
ignore	readonly	readonly string[] | undefined
include	readonly	readonly string[] | undefined

---

ResolvedCompareOptions

Normalized compare options used internally.

Properties

Property	Modifier	Type
maxDepth	readonly	number
circular	readonly	CircularReferenceStrategy
customComparator	readonly	CustomComparator | undefined

---

PatchOperation

A single JSON Patch style operation.

Properties

Property	Modifier	Type
op	readonly	PatchOperationType
path	readonly	string
from?	readonly	string
value?	readonly	unknown

---

PatchOptions

Options for patch generation.

Properties

Property	Modifier	Type	Description
format?	readonly	PatchFormat	-
optimize?	readonly	boolean	Coalesce sequential replaces and drop no-op-friendly noise. Default false.

---

ApplyPatchOptions

Options for applying patches.

Properties

Property	Modifier	Type	Description
mutable?	readonly	boolean	-
validate?	readonly	boolean	Validate operations before apply. Default true.

---

ApplyPatchWithInverseResult

Result of applying a patch while recording a faithful inverse.

Type Parameters

Type Parameter
T

Properties

Property	Modifier	Type
value	readonly	T
inverse	readonly	Patch

---

SerializeOptions

Options for serialization.

Properties

Property	Modifier	Type	Description
title?	readonly	string	-
color?	readonly	boolean	When false, console format omits ANSI colors. Default true.

---

FormatterPlugin

Optional custom formatter registered via createSerializer (no import side effects).

Properties

Property	Modifier	Type
name	readonly	string

Methods

format()

format(result: DiffResult, options?: SerializeOptions): string;

Parameters

Parameter	Type
result	DiffResult
options?	SerializeOptions

Returns

string

Type Aliases

DiffType

type DiffType = "added" | "removed" | "changed" | "unchanged" | "moved";

Supported change kinds emitted by the difference engine.

---

PathSegment

type PathSegment = string | number;

Path segment used for nested value addressing.

---

Path

type Path = readonly PathSegment[];

Canonical path representation for a nested value.

---

CircularReferenceStrategy

type CircularReferenceStrategy = "error" | "skip";

How circular references are handled during traversal.

---

CustomComparator

type CustomComparator = (a: unknown, b: unknown, path: Path) => boolean | undefined;

Custom comparator hook. Return true if equal, false if unequal, undefined to use default.

Parameters

Parameter	Type
a	unknown
b	unknown
path	Path

Returns

boolean | undefined

---

IdentityKey

type IdentityKey = 
  | string
  | ((item: unknown, path: Path) => string | number | undefined);

Identity key for array element matching (Phase 2). String form reads a property; function form returns an id or undefined (positional leftover).

---

PatchOperationType

type PatchOperationType = "add" | "remove" | "replace" | "move" | "copy" | "test";

JSON Patch operation kinds (RFC 6902).

---

Patch

type Patch = readonly PatchOperation[];

A patch is an ordered list of operations.

---

PatchFormat

type PatchFormat = "json-patch" | "merge";

Patch generation format.

---

SerializeFormat

type SerializeFormat = "json" | "pretty" | "markdown" | "table" | "html" | "console" | "human";

Supported serializer output formats.

---

ValueKind

type ValueKind = 
  | "primitive"
  | "array"
  | "object"
  | "date"
  | "regexp"
  | "map"
  | "set"
  | "typed-array"
  | "function";

Internal value kind for traversal dispatch.

---

ComparisonOutcome

type ComparisonOutcome = "equal" | "unequal" | "type-mismatch";

Result of comparing two values at a path.

Functions

compare()

function compare(
   a: unknown, 
   b: unknown, 
   options?: CompareOptions): boolean;

Deep equality comparison for structured values.

Parameters

Parameter	Type
a	unknown
b	unknown
options?	CompareOptions

Returns

boolean

---

diff()

function diff(
   a: unknown, 
   b: unknown, 
   options?: DiffOptions): DiffResult;

Compare two values and return structured change records.

Parameters

Parameter	Type
a	unknown
b	unknown
options?	DiffOptions

Returns

DiffResult

---

hasChanges()

function hasChanges(
   a: unknown, 
   b: unknown, 
   options?: DiffOptions): boolean;

Fast boolean check for whether two values differ. Early-exits on the first allowed change; does not allocate a DiffResult.

Parameters

Parameter	Type
a	unknown
b	unknown
options?	DiffOptions

Returns

boolean

---

added()

function added(
   a: unknown, 
   b: unknown, 
   options?: DiffOptions): DiffRecord[];

Parameters

Parameter	Type
a	unknown
b	unknown
options?	DiffOptions

Returns

DiffRecord[]

---

removed()

function removed(
   a: unknown, 
   b: unknown, 
   options?: DiffOptions): DiffRecord[];

Parameters

Parameter	Type
a	unknown
b	unknown
options?	DiffOptions

Returns

DiffRecord[]

---

updated()

function updated(
   a: unknown, 
   b: unknown, 
   options?: DiffOptions): DiffRecord[];

Parameters

Parameter	Type
a	unknown
b	unknown
options?	DiffOptions

Returns

DiffRecord[]

---

unchanged()

function unchanged(
   a: unknown, 
   b: unknown, 
   options?: DiffOptions): DiffRecord[];

Parameters

Parameter	Type
a	unknown
b	unknown
options?	DiffOptions

Returns

DiffRecord[]

---

patch()

function patch(diffResult: DiffResult, options?: PatchOptions): Patch;

Generate a patch from a diff result.

Parameters

Parameter	Type
diffResult	DiffResult
options?	PatchOptions

Returns

Patch

---

applyPatch()

function applyPatch<T>(
   target: T, 
   patchOperations: Patch, 
   options?: ApplyPatchOptions): T;

Apply a patch to a target value. Returns a new value by default.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
target	T
patchOperations	Patch
options?	ApplyPatchOptions

Returns

T

---

applyPatchWithInverse()

function applyPatchWithInverse<T>(
   target: T, 
   patchOperations: Patch, 
options?: ApplyPatchOptions): ApplyPatchWithInverseResult<T>;

Apply a patch and return a faithful inverse patch (previous values captured).

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
target	T
patchOperations	Patch
options?	ApplyPatchOptions

Returns

ApplyPatchWithInverseResult<T>

---

revertPatch()

function revertPatch<T>(
   target: T, 
   patchOperations: Patch, 
   options?: ApplyPatchOptions): T;

Revert a previously applied patch. Prefer applyPatchWithInverse when you need faithful undo of replaces/removes. This helper inverts ops structurally; remove→add uses undefined unless values were journaled.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
target	T
patchOperations	Patch
options?	ApplyPatchOptions

Returns

T

---

optimizePatch()

function optimizePatch(patchOperations: Patch): Patch;

Optimize a patch: coalesce sequential replaces on the same path (keep last). Does not reorder independent operations.

Parameters

Parameter	Type
patchOperations	Patch

Returns

Patch

---

validatePatch()

function validatePatch(patchOperations: unknown): asserts patchOperations is Patch;

Validate a patch document. Throws InvalidPatchError on failure.

Parameters

Parameter	Type
patchOperations	unknown

Returns

asserts patchOperations is Patch

---

serialize()

function serialize(
   diff: DiffResult, 
   format: SerializeFormat, 
   options?: SerializeOptions): string;

Serialize a diff result to a supported built-in output format. Works with zero plugins (no import side effects).

Parameters

Parameter	Type
diff	DiffResult
format	SerializeFormat
options?	SerializeOptions

Returns

string