{"id":12343,"library":"value-equal","title":"Deep Value Equality Comparison","description":"The `value-equal` package provides a lightweight utility function designed to determine if two JavaScript values are deeply equal based on their content, rather than strict reference equality. It intelligently compares primitive values, arrays, and plain objects by recursively checking their `valueOf` representations. Currently at stable version 1.0.1 (published 7 years ago), the package demonstrates a mature and reliable API. Its release cadence is likely infrequent due to its focused scope and stable implementation, with updates typically limited to critical bug fixes. This package serves as a practical alternative for scenarios where deep value comparison is essential, such as normalizing data for `localStorage` or comparing `window.history.state` values, where objects need to be treated as equal if their contents match. Unlike strict equality (`===`) or more feature-rich libraries, `value-equal` offers a streamlined approach specifically for these use cases without additional overhead.","status":"maintenance","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/mjackson/value-equal","tags":["javascript"],"install":[{"cmd":"npm install value-equal","lang":"bash","label":"npm"},{"cmd":"yarn add value-equal","lang":"bash","label":"yarn"},{"cmd":"pnpm add value-equal","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { valueEqual } from 'value-equal';","symbol":"valueEqual","correct":"import valueEqual from 'value-equal';"},{"note":"The package exports a default function in CommonJS. Attempting to destructure it will result in `valueEqual` being undefined.","wrong":"const { valueEqual } = require('value-equal');","symbol":"valueEqual","correct":"const valueEqual = require('value-equal');"},{"note":"When included via a `<script>` tag from a CDN like unpkg, the `valueEqual` function is available as a global on the `window` object.","symbol":"valueEqual","correct":"console.log(window.valueEqual(1, 1));"}],"quickstart":{"code":"import valueEqual from 'value-equal';\n\n// Primitive values\nconsole.log('Primitives:');\nconsole.log(valueEqual(1, 1)); // true\nconsole.log(valueEqual('hello', 'hello')); // true\nconsole.log(valueEqual(true, false)); // false\nconsole.log(valueEqual(null, null)); // true\nconsole.log(valueEqual(undefined, undefined)); // true\n\n// String objects vs primitives\nconsole.log('\\nStrings:');\nconsole.log(valueEqual('asdf', new String('asdf'))); // true\n\n// Plain objects\nconsole.log('\\nObjects:');\nconsole.log(valueEqual({ a: 'a', b: 1 }, { a: 'a', b: 1 })); // true\nconsole.log(valueEqual({ a: 'a' }, { a: 'b' })); // false\nconsole.log(valueEqual({ c: 3, a: 1 }, { a: 1, c: 3 })); // true (order of keys doesn't matter for deep equality)\n\n// Arrays\nconsole.log('\\nArrays:');\nconsole.log(valueEqual([1, 2, 3], [1, 2, 3])); // true\nconsole.log(valueEqual([1, 2, { a: 1 }], [1, 2, { a: 1 }])); // true (nested objects)\nconsole.log(valueEqual([1, 2, 3], [2, 3, 4])); // false\n\n// Mixed types\nconsole.log('\\nMixed Types:');\nconsole.log(valueEqual({ a: 1 }, [1])); // false","lang":"javascript","description":"Demonstrates basic deep equality comparisons for primitives, strings, plain objects, and arrays."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use the correct default import syntax: `import valueEqual from 'value-equal';`","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.","error":"TypeError: (0 , value_equal__WEBPACK_IMPORTED_MODULE_0__.default) is not a function"},{"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`.","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`.","error":"ReferenceError: valueEqual is not defined"}],"ecosystem":"npm"}