Deep Value Equality Comparison

Common errors

• TypeError: (0 , value_equal__WEBPACK_IMPORTED_MODULE_0__.default) is not a function

  cause Incorrect ES module import syntax for a default export. This error typically occurs when attempting to use a named import (`import { valueEqual } from 'value-equal'`) for a module that only provides a default export.
  fix Use the correct default import syntax: `import valueEqual from 'value-equal';`

• ReferenceError: valueEqual is not defined

  cause The `valueEqual` function was not properly imported or made available in the current JavaScript scope. This can happen if the module is not imported at all, or if the UMD build is used in a browser without accessing it via `window.valueEqual`.
  fix Ensure the module is imported correctly using `import valueEqual from 'value-equal';` (ESM) or `const valueEqual = require('value-equal');` (CommonJS). If using the UMD build in a browser, ensure the script tag is present and you are accessing it via `window.valueEqual`.

Warnings

• gotcha This library performs deep value equality, meaning it compares the contents of objects and arrays recursively. It does *not* perform strict reference equality (`obj1 === obj2`). Users should be aware that `value-equal` may not handle circular references gracefully, potentially leading to infinite loops or stack overflows on extremely deep or interconnected structures, as this is not explicitly addressed in its API.
  Fix: Understand that `valueEqual` provides structural equality, not reference equality. For reference checks, use `===`. If dealing with objects that might contain circular references, consider a more robust deep equality library (e.g., `lodash.isequal` or `fast-equals`) that explicitly handles such cases, or implement custom logic to detect and break cycles.
• gotcha The package is primarily designed for primitive values, plain JavaScript objects, and arrays. Its comparison relies on `Object.prototype.valueOf` and direct property iteration, which might not yield expected results for custom class instances, built-in complex objects like `Map`, `Set`, `Date`, `RegExp`, or instances with non-enumerable properties. For example, `Date` objects with the same time value may be considered unequal if their internal representations differ, or if `valueOf` returns a primitive but other properties are ignored.
  Fix: Thoroughly test `valueEqual`'s behavior with any custom object types or complex built-in objects you need to compare. For specialized types like `Date` or `RegExp`, you might need to pre-process them (e.g., convert `Date` to `getTime()`) or use a more comprehensive deep equality library that offers specific handling for these types.
• deprecated This package (v1.0.1) has not been updated since its last publish 7 years ago, indicating it is in maintenance mode or potentially unmaintained. While its core functionality remains valid for its intended simple use cases, it might not receive updates for new JavaScript features, performance optimizations, or potential security vulnerabilities discovered in its (currently zero) dependencies or underlying JavaScript runtime. The `README.md` itself was last updated in 2017.
  Fix: Assess if the package meets your current needs without active development. For projects requiring active maintenance, modern JavaScript feature support, or robust handling of all JavaScript types and edge cases, consider actively maintained alternatives like `lodash.isequal`, `fast-equals`, or `is-equal`, which often provide broader compatibility and better performance for complex scenarios.

Install

• npm install value-equal npm
• yarn add value-equal yarn
• pnpm add value-equal pnpm

Imports

• valueEqual
  wrong:

  import { valueEqual } from 'value-equal';

  correct:

  import valueEqual from 'value-equal';

  The package exports a default function. Named imports will result in a TypeError at runtime if 'type': 'module' is used in package.json or if imported in an ESM context.
• valueEqual
  wrong:

  const { valueEqual } = require('value-equal');

  correct:

  const valueEqual = require('value-equal');

  The package exports a default function in CommonJS. Attempting to destructure it will result in `valueEqual` being undefined.
• valueEqual

  console.log(window.valueEqual(1, 1));

  When included via a `<script>` tag from a CDN like unpkg, the `valueEqual` function is available as a global on the `window` object.

Quickstart

Demonstrates basic deep equality comparisons for primitives, strings, plain objects, and arrays.

import valueEqual from 'value-equal';

// Primitive values
console.log('Primitives:');
console.log(valueEqual(1, 1)); // true
console.log(valueEqual('hello', 'hello')); // true
console.log(valueEqual(true, false)); // false
console.log(valueEqual(null, null)); // true
console.log(valueEqual(undefined, undefined)); // true

// String objects vs primitives
console.log('\nStrings:');
console.log(valueEqual('asdf', new String('asdf'))); // true

// Plain objects
console.log('\nObjects:');
console.log(valueEqual({ a: 'a', b: 1 }, { a: 'a', b: 1 })); // true
console.log(valueEqual({ a: 'a' }, { a: 'b' })); // false
console.log(valueEqual({ c: 3, a: 1 }, { a: 1, c: 3 })); // true (order of keys doesn't matter for deep equality)

// Arrays
console.log('\nArrays:');
console.log(valueEqual([1, 2, 3], [1, 2, 3])); // true
console.log(valueEqual([1, 2, { a: 1 }], [1, 2, { a: 1 }])); // true (nested objects)
console.log(valueEqual([1, 2, 3], [2, 3, 4])); // false

// Mixed types
console.log('\nMixed Types:');
console.log(valueEqual({ a: 1 }, [1])); // false