From 1029dd36861d7ab592d4e219362706d2c161839a Mon Sep 17 00:00:00 2001
From: Ruben Bridgewater <ruben@bridgewater.de>
Date: Fri, 9 Mar 2018 15:03:44 +0100
Subject: util: show Weak(Set|Map) entries in inspect

This adds support for WeakMap and WeakSet entries in `util.inspect`.
The output is limited to a maximum entry length of `maxArrayLength`.

PR-URL: https://github.com/nodejs/node/pull/19259
Fixes: https://github.com/nodejs/node/issues/19001:
Reviewed-By: Yosuke Furukawa <yosuke.furukawa@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api/util.md | 37 ++++++++++++++++++++++++++++++++-----
 1 file changed, 32 insertions(+), 5 deletions(-)

(limited to 'doc/api/util.md')

diff --git a/doc/api/util.md b/doc/api/util.md
index 8a4e6a0960..9253d46351 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -345,6 +345,9 @@ stream.write('With ES6');
 <!-- YAML
 added: v0.3.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/19259
+    description: WeakMap and WeakSet entries can now be inspected as well.
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/17907
     description: The `depth` default changed to Infinity.
@@ -369,7 +372,8 @@ changes:
 * `object` {any} Any JavaScript primitive or Object.
 * `options` {Object}
   * `showHidden` {boolean} If `true`, the `object`'s non-enumerable symbols and
-    properties will be included in the formatted result. Defaults to `false`.
+    properties will be included in the formatted result as well as [`WeakMap`][]
+    and [`WeakSet`][] entries. Defaults to `false`.
   * `colors` {boolean} If `true`, the output will be styled with ANSI color
     codes. Defaults to `false`. Colors are customizable, see
     [Customizing `util.inspect` colors][].
@@ -378,10 +382,14 @@ changes:
   * `showProxy` {boolean} If `true`, then objects and functions that are
     `Proxy` objects will be introspected to show their `target` and `handler`
     objects. Defaults to `false`.
-  * `maxArrayLength` {number} Specifies the maximum number of array and
-    `TypedArray` elements to include when formatting. Defaults to `100`. Set to
-    `null` or `Infinity` to show all array elements. Set to `0` or negative to
-    show no array elements.
+    <!--
+    TODO(BridgeAR): Deprecate `maxArrayLength` and replace it with
+                    `maxEntries`.
+    -->
+  * `maxArrayLength` {number} Specifies the maximum number of `Array`,
+    [`TypedArray`][], [`WeakMap`][] and [`WeakSet`][] elements to include when
+    formatting. Defaults to `100`. Set to `null` or `Infinity` to show all
+    elements. Set to `0` or negative to show no elements.
   * `breakLength` {number} The length at which an object's keys are split
     across multiple lines. Set to `Infinity` to format an object as a single
     line. Defaults to 60 for legacy compatibility.
@@ -501,6 +509,25 @@ console.log(util.inspect(o, { compact: false, breakLength: 80 }));
 // chunks.
 ```
 
+Using the `showHidden` option allows to inspect [`WeakMap`][] and [`WeakSet`][]
+entries. If there are more entries than `maxArrayLength`, there is no guarantee
+which entries are displayed. That means retrieving the same ['WeakSet'][]
+entries twice might actually result in a different output. Besides this any item
+might be collected at any point of time by the garbage collector if there is no
+strong reference left to that object. Therefore there is no guarantee to get a
+reliable output.
+
+```js
+const { inspect } = require('util');
+
+const obj = { a: 1 };
+const obj2 = { b: 2 };
+const weakSet = new WeakSet([obj, obj2]);
+
+console.log(inspect(weakSet, { showHidden: true }));
+// WeakSet { { a: 1 }, { b: 2 } }
+```
+
 Please note that `util.inspect()` is a synchronous method that is mainly
 intended as a debugging tool. Some input values can have a significant
 performance overhead that can block the event loop. Use this function
-- 
cgit v1.2.3