Skip to content

Commit 57a7b93

Browse files
ishon19aduh95
authored andcommitted
doc: WeakSet and WeakMap comparison details
PR-URL: #56648 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 4202045 commit 57a7b93

File tree

1 file changed

+60
-24
lines changed

1 file changed

+60
-24
lines changed

doc/api/assert.md

+60-24
Original file line numberDiff line numberDiff line change
@@ -804,8 +804,10 @@ are recursively evaluated also by the following rules.
804804
* [`Map`][] keys and [`Set`][] items are compared unordered.
805805
* Recursion stops when both sides differ or both sides encounter a circular
806806
reference.
807-
* [`WeakMap`][] and [`WeakSet`][] comparison does not rely on their values. See
808-
below for further details.
807+
* [`WeakMap`][] and [`WeakSet`][] instances are **not** compared structurally.
808+
They are only equal if they reference the same object. Any comparison between
809+
different `WeakMap` or `WeakSet` instances will result in inequality,
810+
even if they contain the same entries.
809811
* [`RegExp`][] lastIndex, flags, and source are always compared, even if these
810812
are not enumerable properties.
811813

@@ -882,23 +884,40 @@ assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 });
882884
// }
883885

884886
const weakMap1 = new WeakMap();
885-
const weakMap2 = new WeakMap([[{}, {}]]);
886-
const weakMap3 = new WeakMap();
887-
weakMap3.unequal = true;
887+
const weakMap2 = new WeakMap();
888+
const obj = {};
888889

890+
weakMap1.set(obj, 'value');
891+
weakMap2.set(obj, 'value');
892+
893+
// Comparing different instances fails, even with same contents
889894
assert.deepStrictEqual(weakMap1, weakMap2);
890-
// OK, because it is impossible to compare the entries
895+
// AssertionError: Values have same structure but are not reference-equal:
896+
//
897+
// WeakMap {
898+
// <items unknown>
899+
// }
900+
901+
// Comparing the same instance to itself succeeds
902+
assert.deepStrictEqual(weakMap1, weakMap1);
903+
// OK
891904

892-
// Fails because weakMap3 has a property that weakMap1 does not contain:
893-
assert.deepStrictEqual(weakMap1, weakMap3);
905+
const weakSet1 = new WeakSet();
906+
const weakSet2 = new WeakSet();
907+
weakSet1.add(obj);
908+
weakSet2.add(obj);
909+
910+
// Comparing different instances fails, even with same contents
911+
assert.deepStrictEqual(weakSet1, weakSet2);
894912
// AssertionError: Expected inputs to be strictly deep-equal:
895913
// + actual - expected
896914
//
897-
// WeakMap {
898-
// + [items unknown]
899-
// - [items unknown],
900-
// - unequal: true
901-
// }
915+
// + WeakSet { <items unknown> }
916+
// - WeakSet { <items unknown> }
917+
918+
// Comparing the same instance to itself succeeds
919+
assert.deepStrictEqual(weakSet1, weakSet1);
920+
// OK
902921
```
903922

904923
```cjs
@@ -974,23 +993,40 @@ assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 });
974993
// }
975994

976995
const weakMap1 = new WeakMap();
977-
const weakMap2 = new WeakMap([[{}, {}]]);
978-
const weakMap3 = new WeakMap();
979-
weakMap3.unequal = true;
996+
const weakMap2 = new WeakMap();
997+
const obj = {};
980998

999+
weakMap1.set(obj, 'value');
1000+
weakMap2.set(obj, 'value');
1001+
1002+
// Comparing different instances fails, even with same contents
9811003
assert.deepStrictEqual(weakMap1, weakMap2);
982-
// OK, because it is impossible to compare the entries
1004+
// AssertionError: Values have same structure but are not reference-equal:
1005+
//
1006+
// WeakMap {
1007+
// <items unknown>
1008+
// }
1009+
1010+
// Comparing the same instance to itself succeeds
1011+
assert.deepStrictEqual(weakMap1, weakMap1);
1012+
// OK
9831013

984-
// Fails because weakMap3 has a property that weakMap1 does not contain:
985-
assert.deepStrictEqual(weakMap1, weakMap3);
1014+
const weakSet1 = new WeakSet();
1015+
const weakSet2 = new WeakSet();
1016+
weakSet1.add(obj);
1017+
weakSet2.add(obj);
1018+
1019+
// Comparing different instances fails, even with same contents
1020+
assert.deepStrictEqual(weakSet1, weakSet2);
9861021
// AssertionError: Expected inputs to be strictly deep-equal:
9871022
// + actual - expected
9881023
//
989-
// WeakMap {
990-
// + [items unknown]
991-
// - [items unknown],
992-
// - unequal: true
993-
// }
1024+
// + WeakSet { <items unknown> }
1025+
// - WeakSet { <items unknown> }
1026+
1027+
// Comparing the same instance to itself succeeds
1028+
assert.deepStrictEqual(weakSet1, weakSet1);
1029+
// OK
9941030
```
9951031

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

0 commit comments

Comments
 (0)