Fast Equality Comparison Utility

Common errors

• Error: Cannot find module 'fast-equals/dist/umd/index.js'

  cause Attempting to import from the UMD build path after upgrading to `fast-equals` v6.0.0, which removed UMD support.
  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.

• TypeError: (0 , fast_equals_1.deepEqual) is not a function

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

• TS2305: Module '"fast-equals"' has no exported member 'Equals'

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

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• deprecated 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.
  Fix: Refactor your code to use the public API functions (`deepEqual`, `shallowEqual`, `createCustomEqual`, etc.) instead of relying on internal indirect methods.
• gotcha 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`.
  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`.

Install

• npm install fast-equals npm
• yarn add fast-equals yarn
• pnpm add fast-equals pnpm

Imports

• deepEqual
  wrong:

  const deepEqual = require('fast-equals');

  correct:

  import { deepEqual } from 'fast-equals';

  While CommonJS `require` is supported, ESM named imports are the preferred modern approach for `fast-equals`.
• createCustomEqual
  wrong:

  import * as FastEquals from 'fast-equals'; FastEquals.createCustomEqual;

  correct:

  import { createCustomEqual } from 'fast-equals';

  Use named imports for specific utilities. Direct access via a namespace import can be less efficient or lead to unexpected behavior in some bundlers.
• shallowEqual
  wrong:

  import shallowEqual from 'fast-equals/dist/es/shallowEqual.mjs';

  correct:

  import { shallowEqual } from 'fast-equals';

  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.

Quickstart

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.

import { deepEqual, shallowEqual, createCustomEqual, strictEqual } from 'fast-equals';

const objA = { a: 1, b: { c: 2 }, d: [3, 4] };
const objB = { a: 1, b: { c: 2 }, d: [3, 4] };
const objC = { a: 1, b: { c: 99 }, d: [3, 4] };
const arr1 = [1, { foo: 'bar' }, new Date('2023-01-01')];
const arr2 = [1, { foo: 'bar' }, new Date('2023-01-01')];
const arr3 = [1, { foo: 'baz' }, new Date('2023-01-01')];

console.log('Deep equality (objects):', deepEqual(objA, objB)); // true
console.log('Deep equality (objects with difference):', deepEqual(objA, objC)); // false
console.log('Shallow equality (objects):', shallowEqual(objA, objB)); // false (nested objects/arrays are different references)
console.log('Deep equality (arrays):', deepEqual(arr1, arr2)); // true
console.log('Deep equality (arrays with difference):', deepEqual(arr1, arr3)); // false

const customEqual = createCustomEqual({ createComparator: () => (a, b) => a === b || a.value === b.value });
console.log('Custom equality (simple values):', customEqual({ value: 1 }, { value: 1 })); // true

console.log('Strict equality (same value, different reference):', strictEqual([1], [1])); // false
console.log('Strict equality (same reference):', strictEqual(objA, objA)); // true