doc: `WeakSet` and `WeakMap` comparison details · nodejs/node@9782639

* [`Map`][] keys and [`Set`][] items are compared unordered.

* Recursion stops when both sides differ or both sides encounter a circular

reference.

* [`WeakMap`][] and [`WeakSet`][] comparison does not rely on their values. See

below for further details.

* [`WeakMap`][] and [`WeakSet`][] instances are **not** compared structurally.

They are only equal if they reference the same object. Any comparison between

different `WeakMap` or `WeakSet` instances will result in inequality,

even if they contain the same entries.

* [`RegExp`][] lastIndex, flags, and source are always compared, even if these

are not enumerable properties.

// }

const weakMap1 = new WeakMap();

const weakMap2 = new WeakMap([[{}, {}]]);

const weakMap3 = new WeakMap();

weakMap3.unequal = true;

const weakMap2 = new WeakMap();

const obj = {};

weakMap1.set(obj, 'value');

weakMap2.set(obj, 'value');

// Comparing different instances fails, even with same contents

assert.deepStrictEqual(weakMap1, weakMap2);

// OK, because it is impossible to compare the entries

// AssertionError: Values have same structure but are not reference-equal:

//

// WeakMap {

// <items unknown>

// }

// Comparing the same instance to itself succeeds

assert.deepStrictEqual(weakMap1, weakMap1);

// OK

// Fails because weakMap3 has a property that weakMap1 does not contain:

assert.deepStrictEqual(weakMap1, weakMap3);

const weakSet1 = new WeakSet();

const weakSet2 = new WeakSet();

weakSet1.add(obj);

weakSet2.add(obj);

// Comparing different instances fails, even with same contents

assert.deepStrictEqual(weakSet1, weakSet2);

// AssertionError: Expected inputs to be strictly deep-equal:

// + actual - expected

//

// WeakMap {

// + [items unknown]

// - [items unknown],

// - unequal: true

// }

// + WeakSet { <items unknown> }

// - WeakSet { <items unknown> }

// Comparing the same instance to itself succeeds

assert.deepStrictEqual(weakSet1, weakSet1);

// OK

```

```cjs

// }

const weakMap1 = new WeakMap();

const weakMap2 = new WeakMap([[{}, {}]]);

const weakMap3 = new WeakMap();

weakMap3.unequal = true;

const weakMap2 = new WeakMap();

const obj = {};

weakMap1.set(obj, 'value');

weakMap2.set(obj, 'value');

// Comparing different instances fails, even with same contents

assert.deepStrictEqual(weakMap1, weakMap2);

// OK, because it is impossible to compare the entries

// AssertionError: Values have same structure but are not reference-equal:

//

// WeakMap {

// <items unknown>

// }

// Comparing the same instance to itself succeeds

assert.deepStrictEqual(weakMap1, weakMap1);

// OK

// Fails because weakMap3 has a property that weakMap1 does not contain:

assert.deepStrictEqual(weakMap1, weakMap3);

const weakSet1 = new WeakSet();

const weakSet2 = new WeakSet();

weakSet1.add(obj);

weakSet2.add(obj);

// Comparing different instances fails, even with same contents

assert.deepStrictEqual(weakSet1, weakSet2);

// AssertionError: Expected inputs to be strictly deep-equal:

// + actual - expected

//

// WeakMap {

// + [items unknown]

// - [items unknown],

// - unequal: true

// }

// + WeakSet { <items unknown> }

// - WeakSet { <items unknown> }

// Comparing the same instance to itself succeeds

assert.deepStrictEqual(weakSet1, weakSet1);

// OK

```

If the values are not equal, an [`AssertionError`][] is thrown with a `message`