Shallow Equality Check

3.1.0 · active · verified Sun Apr 19

The `shallow-equal` library provides minimalistic, TypeScript-compatible utilities for performing shallow equality checks on arrays and objects. It currently stands at version 3.1.0, offering highly optimized functions like `shallowEqualArrays` and `shallowEqualObjects` for specific data types, alongside a generic `shallowEqual` function that includes runtime type checking. The project emphasizes being super light with no external dependencies, ensuring a small footprint. Its release cadence is stable, focusing on minor enhancements and maintenance rather than frequent, large-scale breaking changes, typical for foundational utility packages. A key differentiator is its explicit separation of array and object equality functions, allowing developers to choose the most performant option when the type is known, avoiding the overhead of runtime type inference inherent in more generic solutions.

Common errors

```
TypeError: shallowEqualArrays is not a function
```
cause Attempting to destructure a CommonJS `require`'s default export when the library provides named ESM exports, or incorrect module interoperability configuration.

fix Ensure you are using `import { shallowEqualArrays } from 'shallow-equal';` for ESM. If strictly using CommonJS, check if the package provides a CJS entry point that you can `require('shallow-equal').shallowEqualArrays;`.
```
Property 'shallowEqualObjects' does not exist on type 'typeof import("shallow-equal")'.
```
cause This TypeScript error indicates that the type checker cannot find the named export, often due to an incorrect import statement (e.g., `import * as shallowEqual from 'shallow-equal';` then trying `shallowEqual.shallowEqualObjects`) or mismatched `tsconfig.json` module settings.

fix Use a named import: `import { shallowEqualObjects } from 'shallow-equal';`. Verify your `tsconfig.json`'s `module` and `moduleResolution` settings are compatible with how your bundler or Node.js resolves modules.

Warnings

gotcha The generic `shallowEqual` function performs runtime type checking (to determine if inputs are arrays or objects), which introduces a slight performance overhead. For maximum performance when the type is known, prefer `shallowEqualArrays` or `shallowEqualObjects`.
Fix: Use `shallowEqualArrays` for arrays and `shallowEqualObjects` for objects when the input type is statically known.
gotcha This library performs *shallow* equality checks. This means that for arrays or objects containing other objects or arrays, only the references of the nested structures are compared, not their contents recursively. For example, `shallowEqualArrays([{a:1}], [{a:1}])` will return `false` because `({a:1}) !== ({a:1})`.
Fix: Understand the distinction between shallow and deep equality. For deep comparisons, you will need a different library (e.g., `lodash.isequal` or a custom recursive comparison).
gotcha While the package provides TypeScript types, incorrect import syntax (e.g., using CommonJS `require` in a TypeScript project configured for ESM) can lead to type inference issues or runtime errors, particularly in modern Node.js or bundler setups.
Fix: Ensure your project's `tsconfig.json` `module` and `moduleResolution` settings align with your runtime environment (e.g., `"module": "esnext", "moduleResolution": "bundler"` for modern setups) and consistently use `import` statements.

Install

npm install shallow-equal npm
yarn add shallow-equal yarn
pnpm add shallow-equal pnpm

Imports

shallowEqualArrays
wrong:
```
const { shallowEqualArrays } = require('shallow-equal');
```
correct:
```
import { shallowEqualArrays } from 'shallow-equal';
```
Primarily designed for ESM usage. CommonJS `require` can lead to bundling or runtime issues in pure ESM environments.
shallowEqualObjects
wrong:
```
const shallowEqualObjects = require('shallow-equal').shallowEqualObjects;
```
correct:
```
import { shallowEqualObjects } from 'shallow-equal';
```
Ensure your environment supports ESM imports. Direct CommonJS access might work but is not the recommended pattern.
shallowEqual
wrong:
```
import shallowEqual from 'shallow-equal';
```
correct:
```
import { shallowEqual } from 'shallow-equal';
```
`shallowEqual` is a named export, not a default export. Using the generic `shallowEqual` function introduces a small runtime performance penalty due to internal type checking compared to `shallowEqualArrays` or `shallowEqualObjects`.

Quickstart

Demonstrates how to use `shallowEqualArrays` and `shallowEqualObjects` for efficient shallow comparisons, clarifying that nested non-primitives are compared by reference, not recursively.

import { shallowEqualArrays, shallowEqualObjects } from "shallow-equal";

// Demonstrates shallow equality for arrays. Nested objects are compared by reference.
const arr1 = [1, 2, { id: 1 }];
const arr2 = [1, 2, { id: 1 }];
console.log("shallowEqualArrays(arr1, arr2):", shallowEqualArrays(arr1, arr2)); // Expected: false (because {id:1} !== {id:1})

const arr3 = [1, 2, 3];
const arr4 = [1, 2, 3];
console.log("shallowEqualArrays(arr3, arr4):", shallowEqualArrays(arr3, arr4)); // Expected: true

// Demonstrates shallow equality for objects. Nested objects are compared by reference.
const obj1 = { a: 5, b: "abc", c: { id: 1 } };
const obj2 = { a: 5, b: "abc", c: { id: 1 } };
console.log("shallowEqualObjects(obj1, obj2):", shallowEqualObjects(obj1, obj2)); // Expected: false (because {id:1} !== {id:1})

const obj3 = { a: 5, b: "abc" };
const obj4 = { a: 5, b: "abc" };
console.log("shallowEqualObjects(obj3, obj4):", shallowEqualObjects(obj3, obj4)); // Expected: true

view raw JSON →