Visual Variable Diff

Common errors

• TypeError: diff is not a function

  cause This error commonly occurs when `variable-diff` is imported incorrectly. In CommonJS, trying `require('variable-diff').diff` or in ESM, using `import { diff } from 'variable-diff';` will cause this because `diff` is a default export.
  fix Correct the import statement: for CommonJS, use `const diff = require('variable-diff');`; for ES Modules, use `import diff from 'variable-diff';`.

• ReferenceError: chalk is not defined

  cause If you copy the `wrap` function example from the library's `defaultOptions` snippet (which implicitly uses the `chalk` library for coloring) into your options without having `chalk` installed in your project, this error will occur.
  fix To resolve, either install `chalk` as a dependency (`npm install chalk`) if you intend to use its coloring features, or remove the `wrap` function from your options to let `variable-diff` use its default color handling (or no colors if `color: false` is set).

Warnings

• gotcha When `color: true` (the default) or a custom `wrap` function (e.g., using `chalk`) is utilized, the output relies on ANSI escape codes for coloring. These codes may not render correctly in all environments, potentially showing raw escape sequences instead of colors (e.g., some non-TTY output streams or basic text editors).
  Fix: To ensure universal readability, set `color: false` in the options object if the output target does not support ANSI colors. If using a custom `wrap` function, ensure the coloring library is installed and compatible with the target environment, or provide a fallback without colors.
• gotcha For ES Module environments, `variable-diff` uses a default export for its primary `diff` function. Incorrectly attempting a named import (`import { diff } from 'variable-diff';`) will lead to `diff` being `undefined`.
  Fix: Always use `import diff from 'variable-diff';` for ES Modules. For CommonJS, use `const diff = require('variable-diff');`.
• gotcha Comparing objects with circular references (where an object directly or indirectly references itself) might lead to infinite loops or unexpected behavior, as the library's diffing algorithm may not inherently detect and handle all such cases gracefully.
  Fix: Before diffing, preprocess objects to break circular references, for example, by serializing and deserializing (`JSON.parse(JSON.stringify(obj))`) if possible, or by explicitly removing properties that cause circularity.

Install

• npm install variable-diff npm
• yarn add variable-diff yarn
• pnpm add variable-diff pnpm

Imports

• diff
  wrong:

  import { diff } from 'variable-diff';

  correct:

  import diff from 'variable-diff';

  The primary `diff` function is exported as a default export in ES Module (ESM) contexts. Using a named import will result in `undefined` for `diff`.
• diff (CommonJS)

  const diff = require('variable-diff');

  This is the standard CommonJS import pattern, as shown in the library's README examples for Node.js environments.
• DiffOptions (Type)

  import type { DiffOptions } from 'variable-diff';

  For TypeScript users, the `DiffOptions` interface can be imported to type the options object passed to the `diff` function, providing type safety for configuration.

Quickstart

Demonstrates the basic usage of `variable-diff` to visually compare two TypeScript objects (simulated user profiles), highlighting changes with custom indentation and color options, and also showing how to check if changes were detected programmatically.

import diff from 'variable-diff';

interface UserProfile {
  id: string;
  name: string;
  email: string;
  preferences?: {
    theme: 'dark' | 'light';
    notifications: boolean;
    language: string;
  };
  roles: string[];
}

const oldProfile: UserProfile = {
  id: 'user_123',
  name: 'Alice Smith',
  email: 'alice@example.com',
  preferences: {
    theme: 'dark',
    notifications: true,
    language: 'en-US'
  },
  roles: ['user', 'editor']
};

const newProfile: UserProfile = {
  id: 'user_123',
  name: 'Alice Johnson',
  email: 'alice.johnson@example.com',
  preferences: {
    theme: 'light',
    notifications: false,
    language: 'en-GB'
  },
  roles: ['user', 'admin']
};

const diffOptions = {
  indent: '  ', // 2 spaces for indentation
  newLine: '\n', // Newline character
  color: true // Enable colored output, set to false for plain text
};

console.log('--- Profile Changes ---\n');
const result = diff(oldProfile, newProfile, diffOptions);
console.log(result.text);

if (result.changed) {
  console.log('\nDetected changes in profile data.');
} else {
  console.log('\nNo changes detected in profile data.');
}

// Accessing programmatic changes (raw object)
// console.log('\nRaw changes object:', JSON.stringify(result.changes, null, 2));