Registry / serialization / variable-diff

variable-diff

library2.0.2jsnpmunverified

variable-diff is a JavaScript/TypeScript library designed to generate a visual diff between two JavaScript variables, primarily objects or JSON structures. It focuses on presenting only the differences (additions, deletions, and modifications) in a human-readable, formatted output, making it easier to identify changes without sifting through identical data. The current stable version is 2.0.2. While there isn't an explicit release cadence, the project appears to be actively maintained, with recent updates introducing new features like an options argument in version 2.0.1. Its key differentiator is its emphasis on clear, colored, and indented output directly within the console or logs, making it particularly useful for debugging and comparing configuration objects or data states efficiently.

serialization testing

npm install variable-diff

github ↗package ↗

INSTALL

IMPORT

SIG · VARIABLE-DIFF

variable-diff

serializationjavascriptv2.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

diff

✓ import diff from 'variable-diff';

✗ 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.

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));

Debug

Known issues

gotchaWhen `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.

affects: >=1.0.0

gotchaFor 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');`.

affects: >=2.0.0

gotchaComparing 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: diff is not a function

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

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).

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/taylorhakes/variable-diff ↗

packagehttps://www.npmjs.com/package/variable-diff ↗