Value Comparison

The main diff function handles any JavaScript values by detecting types and routing to appropriate comparison methods. It provides automatic serialization, type checking, and colorized output.

Capabilities

Main Diff Function

Compares any two JavaScript values and returns formatted diff string with automatic type detection and routing.

/**
 * Generate a string that will highlight the difference between two values
 * with green and red coloring (similar to how GitHub does code diffing)
 * @param a - First value to compare (any type)
 * @param b - Second value to compare (any type)  
 * @param options - Optional formatting configuration
 * @returns Formatted diff string or null if no meaningful diff
 */
function diff(a: any, b: any, options?: DiffOptions): string | null;

Behavior by Type:

• Identical values: Returns "Compared values have no visual difference." message
• Different types: Returns type mismatch message with expected vs received types
• Strings: Uses line-by-line comparison with escaped control characters
• Primitives (boolean, number): Uses pretty-format with line comparison
• Maps: Converts to sorted object format for comparison
• Sets: Converts to sorted array format for comparison
• Objects: Uses pretty-format serialization with fallback handling

Usage Examples:

import { diff } from "jest-diff";

// Object comparison
const user1 = { name: "Alice", age: 25, active: true };
const user2 = { name: "Alice", age: 26, active: false };
console.log(diff(user1, user2));

// Array comparison  
const arr1 = [1, 2, 3];
const arr2 = [1, 3, 4];
console.log(diff(arr1, arr2));

// Primitive comparison
console.log(diff(42, 43));
console.log(diff(true, false));

// Type mismatch
console.log(diff("string", 123));
// Output: "Comparing two different types of values. Expected string but received number."

// No difference
console.log(diff("same", "same"));
// Output: "Compared values have no visual difference."

Special Handling:

• Asymmetric Matchers: Supports Jest asymmetric matchers with proper type detection
• Control Characters: Automatically escapes control characters in strings for visibility
• Serialization Fallback: Uses fallback formatting without toJSON when primary serialization fails
• Map/Set Sorting: Automatically sorts Maps and Sets for consistent comparison