# equal-array

Make the === operator compare arrays by values instead of references.

## Stats

StarsIssuesVersionUpdatedCreatedSize
equal-array
101.0.77 years ago7 years ago

equal-array

equal-array lets the strict equality operator `===` compare arrays by values instead of references. Comparison can be either shallow or deeper.

## Purpose

It is mainly useful with an es6 Map or Set, because arrays, used as keys, are compared by references. For example :
``````const map = new Map();
map.set([1, 2 ,3], 'a');
map.set([1, 2 ,3], 'b'); // the map will consider [1, 2 ,3] as a new key
map.size; // returns 2 - with equal-array: returns 1
map.has([1, 2, 3]); // returns false - with equal-array: returns true``````

## Installation

``npm install equal-array``

## Usage

``````import EqualArray from 'equal-array';
// ES5: var EqualArray = require('equal-array').default;

const eq = new EqualArray();
// eq is a function

eq([1, 2, 3]) === eq([1, 2, 3]); //returns true

const map = new Map();
map.set(eq([1, 2 ,3]), 'a');
map.set(eq([1, 2 ,3]), 'b');
map.size; // returns 1
map.has(eq([1, 2, 3])); // returns true``````

## Options

``````const eq = new EqualArray({
returnArray: false,
conversion: true
})``````

#### `returnArray`

accepted values: `false` (default) or `true`
If `returnArray` is `true`, the `eq` function returns a cloned array, otherwise a unique integer. The default is `false` to maximize performances.

#### `conversion`

accepted values: `true` (default), `false`, or a callback
Apply a conversion to the array elements in order to make the comparison. This is important if the array contains objects.
If `conversion` is `false` then :
``eq([1, 2, new Date(1995, 10)]) !== eq([1, 2, new Date(1995, 10)])``

If `conversion` is `true` then :
``eq([1, 2, new Date(1995, 10)]) === eq([1, 2, new Date(1995, 10)])``
Setting `conversion` to `true` means that `EqualArray` will call the `valueOf()` function on each element (when applicable).
The `conversion` option also accepts a callback which takes as a parameter an element of an array and returns the value to be compared:
``````const obj1 = {dummy: 1};
const obj2 = {dummy: 1};
const obj3 = {dummy: 99};
const callback = element => element.dummy;
const eq = new EqualArray({conversion: callback});
eq([obj1]) === eq([obj2]); // true
eq([obj1]) === eq([obj3]); // false``````