fast-equals

library6.0.0jsnpmunverified

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.

serialization

npm install fast-equals

github ↗package ↗

INSTALL

IMPORT

SIG · FAST-EQUALS

fast-equals

serializationjavascriptv6.0.0

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.

deepEqual

✓ import { deepEqual } from 'fast-equals';

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

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

createCustomEqual

✓ import { createCustomEqual } from 'fast-equals';

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

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

✓ import { shallowEqual } from 'fast-equals';

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

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.

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

Debug

Known issues

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

affects: >=6.0.0

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

affects: >=6.0.0

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

affects: >=1.0.0

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

affects: >=6.0.0

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

affects: >=6.0.0

Errors

Common errors & fixes

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

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

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'

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.

Upgrade

Version history

6.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/planttheidea/fast-equals ↗

packagehttps://www.npmjs.com/package/fast-equals ↗