{"id":10870,"library":"fast-equals","title":"Fast Equality Comparison Utility","description":"fast-equals is a high-performance utility library designed for deep and shallow equality comparisons between JavaScript values, offering significant speed advantages and a small bundle size (~2KB minified and gzipped). Currently stable at version 6.0.0, the library maintains a steady release cadence with minor updates for bug fixes and features, and major versions for breaking changes and significant enhancements. It differentiates itself by providing a comprehensive suite of equality methods (deep, shallow, SameValue, SameValueZero, strict, and circular-aware comparisons), built-in support for a wide array of JavaScript types including Objects, Arrays, TypedArrays, Dates, RegExps, Maps, Sets, Promises, and custom class instances. Furthermore, it offers robust customization options through `createCustomEqual`, allowing developers to define comparison logic for specific types or use cases, all without any external dependencies.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/planttheidea/fast-equals","tags":["javascript","fast","equal","equals","deep-equal","equivalent","typescript"],"install":[{"cmd":"npm install fast-equals","lang":"bash","label":"npm"},{"cmd":"yarn add fast-equals","lang":"bash","label":"yarn"},{"cmd":"pnpm add fast-equals","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` is supported, ESM named imports are the preferred modern approach for `fast-equals`.","wrong":"const deepEqual = require('fast-equals');","symbol":"deepEqual","correct":"import { deepEqual } from 'fast-equals';"},{"note":"Use named imports for specific utilities. Direct access via a namespace import can be less efficient or lead to unexpected behavior in some bundlers.","wrong":"import * as FastEquals from 'fast-equals'; FastEquals.createCustomEqual;","symbol":"createCustomEqual","correct":"import { createCustomEqual } from 'fast-equals';"},{"note":"Import directly from the package root. Bundlers will resolve the correct module format (ESM/CJS). Avoid importing from deep paths unless absolutely necessary for specific optimizations.","wrong":"import shallowEqual from 'fast-equals/dist/es/shallowEqual.mjs';","symbol":"shallowEqual","correct":"import { shallowEqual } from 'fast-equals';"}],"quickstart":{"code":"import { deepEqual, shallowEqual, createCustomEqual, strictEqual } from 'fast-equals';\n\nconst objA = { a: 1, b: { c: 2 }, d: [3, 4] };\nconst objB = { a: 1, b: { c: 2 }, d: [3, 4] };\nconst objC = { a: 1, b: { c: 99 }, d: [3, 4] };\nconst arr1 = [1, { foo: 'bar' }, new Date('2023-01-01')];\nconst arr2 = [1, { foo: 'bar' }, new Date('2023-01-01')];\nconst arr3 = [1, { foo: 'baz' }, new Date('2023-01-01')];\n\nconsole.log('Deep equality (objects):', deepEqual(objA, objB)); // true\nconsole.log('Deep equality (objects with difference):', deepEqual(objA, objC)); // false\nconsole.log('Shallow equality (objects):', shallowEqual(objA, objB)); // false (nested objects/arrays are different references)\nconsole.log('Deep equality (arrays):', deepEqual(arr1, arr2)); // true\nconsole.log('Deep equality (arrays with difference):', deepEqual(arr1, arr3)); // false\n\nconst customEqual = createCustomEqual({ createComparator: () => (a, b) => a === b || a.value === b.value });\nconsole.log('Custom equality (simple values):', customEqual({ value: 1 }, { value: 1 })); // true\n\nconsole.log('Strict equality (same value, different reference):', strictEqual([1], [1])); // false\nconsole.log('Strict equality (same reference):', strictEqual(objA, objA)); // true\n","lang":"typescript","description":"This quickstart demonstrates the core `deepEqual`, `shallowEqual`, `strictEqual`, and `createCustomEqual` methods with various data types, illustrating their differing behaviors for object, array, and custom value comparisons."},"warnings":[{"fix":"Migrate your module imports to use standard ESM (`import ... from 'fast-equals'`) or CommonJS (`require('fast-equals')`) conventions. Ensure your build tooling is configured to correctly resolve these module formats.","message":"As of v6.0.0, `fast-equals` has dropped Universal Module Definition (UMD) support. Users relying on UMD bundles (e.g., via `<script>` tags in browsers or specific legacy bundler configurations) must update their import strategy to use either ESM or CommonJS builds.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Review your imports and rely only on the public API exposed directly from the `fast-equals` package root. Consult the official documentation for the current list of exported functions and types.","message":"Version 6.0.0 significantly reduced the number of directly exposed types and removed indirect methods from `equals.ts`. If you were previously importing specific internal types or methods directly from deep paths within the package, these imports will likely break.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Be aware of this specific behavior when comparing `Map` instances. If you require strict `SameValueZero` comparison for Map keys, you might need to implement a custom comparator using `createCustomEqual` that explicitly bypasses this deep comparison logic for Maps.","message":"When comparing `Map` objects, `fast-equals` performs a deep equality comparison for both keys and values, deviating from the `SameValueZero` spec for key lookups. This means `Map` instances with structurally identical but referentially different complex keys will be considered equal, which may not align with native `Map` behavior for key access.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refactor your code to use the public API functions (`deepEqual`, `shallowEqual`, `createCustomEqual`, etc.) instead of relying on internal indirect methods.","message":"The `equals.ts` indirect methods were removed in v6.0.0. While not broadly used, direct access to these internal mechanisms is no longer supported.","severity":"deprecated","affected_versions":">=6.0.0"},{"fix":"Use `strictEqual` specifically when you intend to compare for referential equality or primitive value equality. For comparing the content and structure of objects, arrays, or other complex types, use `deepEqual`.","message":"The `strictEqual` method, introduced in v6.0.0, performs a JavaScript strict equality comparison (`===`) on its inputs. It is crucial to understand that `strictEqual` will return `false` for two distinct objects or arrays that have identical content, as it compares references, not deep structure. It is distinct from `deepEqual`.","severity":"gotcha","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your import statements or bundler configuration to use the ESM (`import ... from 'fast-equals'`) or CommonJS (`require('fast-equals')`) builds. The default package entry point should resolve correctly.","cause":"Attempting to import from the UMD build path after upgrading to `fast-equals` v6.0.0, which removed UMD support.","error":"Error: Cannot find module 'fast-equals/dist/umd/index.js'"},{"fix":"Ensure you are using `import { deepEqual } from 'fast-equals';` for ESM environments and `const { deepEqual } = require('fast-equals');` for CommonJS environments. Verify your `tsconfig.json` and bundler settings (`moduleResolution`, `module`) are correctly configured for your target environment.","cause":"This error typically occurs when an ESM named export is incorrectly imported or accessed, often in environments with mixed module systems (CommonJS trying to import ESM, or vice-versa) or incorrect bundler configurations.","error":"TypeError: (0 , fast_equals_1.deepEqual) is not a function"},{"fix":"Review the official `fast-equals` documentation or source code for the current set of publicly exposed types. If a specific type is no longer available, consider if you truly need to import it, or if a more general type definition suffices.","cause":"As part of the v6.0.0 cleanup, the package reduced exposed types. You are likely attempting to import a type that is no longer part of the public API.","error":"TS2305: Module '\"fast-equals\"' has no exported member 'Equals'"}],"ecosystem":"npm"}