@@ -419,51 +419,48 @@ changes: |
419 | 419 |
|
420 | 420 | * `object` {any} Any JavaScript primitive or `Object`. |
421 | 421 | * `options` {Object} |
422 | | - * `showHidden` {boolean} If `true`, the `object`'s non-enumerable symbols and |
423 | | - properties will be included in the formatted result as well as [`WeakMap`][] |
424 | | - and [`WeakSet`][] entries. **Default:** `false`. |
| 422 | + * `showHidden` {boolean} If `true`, `object`'s non-enumerable symbols and |
| 423 | + properties are included in the formatted result. [`WeakMap`][] and |
| 424 | + [`WeakSet`][] entries are also included. **Default:** `false`. |
425 | 425 | * `depth` {number} Specifies the number of times to recurse while formatting |
426 | | - the `object`. This is useful for inspecting large complicated objects. To |
427 | | - make it recurse up to the maximum call stack size pass `Infinity` or `null`. |
| 426 | + `object`. This is useful for inspecting large objects. To recurse up to |
| 427 | + the maximum call stack size pass `Infinity` or `null`. |
428 | 428 | **Default:** `2`. |
429 | | - * `colors` {boolean} If `true`, the output will be styled with ANSI color |
430 | | - codes. Colors are customizable, see [Customizing `util.inspect` colors][]. |
| 429 | + * `colors` {boolean} If `true`, the output is styled with ANSI color |
| 430 | + codes. Colors are customizable. See [Customizing `util.inspect` colors][]. |
431 | 431 | **Default:** `false`. |
432 | | - * `customInspect` {boolean} If `false`, then |
433 | | - `[util.inspect.custom](depth, opts)` functions will not be called. |
| 432 | + * `customInspect` {boolean} If `false`, |
| 433 | + `[util.inspect.custom](depth, opts)` functions are not invoked. |
434 | 434 | **Default:** `true`. |
435 | | - * `showProxy` {boolean} If `true`, then objects and functions that are |
436 | | - `Proxy` objects will be introspected to show their `target` and `handler` |
437 | | - objects. **Default:** `false`. |
| 435 | + * `showProxy` {boolean} If `true`, `Proxy` inspection includes |
| 436 | + the [`target` and `handler`][] objects. **Default:** `false`. |
438 | 437 | * `maxArrayLength` {integer} Specifies the maximum number of `Array`, |
439 | 438 | [`TypedArray`][], [`WeakMap`][] and [`WeakSet`][] elements to include when |
440 | 439 | formatting. Set to `null` or `Infinity` to show all elements. Set to `0` or |
441 | 440 | negative to show no elements. **Default:** `100`. |
442 | 441 | * `breakLength` {integer} The length at which an object's keys are split |
443 | 442 | across multiple lines. Set to `Infinity` to format an object as a single |
444 | 443 | line. **Default:** `60` for legacy compatibility. |
445 | | - * `compact` {boolean} Setting this to `false` changes the default indentation |
446 | | - to use a line break for each object key instead of lining up multiple |
447 | | - properties in one line. It will also break text that is above the |
448 | | - `breakLength` size into smaller and better readable chunks and indents |
449 | | - objects the same as arrays. Note that no text will be reduced below 16 |
| 444 | + * `compact` {boolean} Setting this to `false` causes each object key to |
| 445 | + be displayed on a new line. It will also add new lines to text that is |
| 446 | + longer than `breakLength`. Note that no text will be reduced below 16 |
450 | 447 | characters, no matter the `breakLength` size. For more information, see the |
451 | 448 | example below. **Default:** `true`. |
452 | 449 | * `sorted` {boolean|Function} If set to `true` or a function, all properties |
453 | | - of an object and Set and Map entries will be sorted in the returned string. |
454 | | - If set to `true` the [default sort][] is going to be used. If set to a |
455 | | - function, it is used as a [compare function][]. |
456 | | - * `getters` {boolean|string} If set to `true`, getters are going to be |
457 | | - inspected as well. If set to `'get'` only getters without setter are going |
458 | | - to be inspected. If set to `'set'` only getters having a corresponding |
459 | | - setter are going to be inspected. This might cause side effects depending on |
460 | | - the getter function. **Default:** `false`. |
461 | | -* Returns: {string} The representation of passed object |
| 450 | + of an object, and `Set` and `Map` entries are sorted in the resulting |
| 451 | + string. If set to `true` the [default sort][] is used. If set to a function, |
| 452 | + it is used as a [compare function][]. |
| 453 | + * `getters` {boolean|string} If set to `true`, getters are inspected. If set |
| 454 | + to `'get'`, only getters without a corresponding setter are inspected. If |
| 455 | + set to `'set'`, only getters with a corresponding setter are inspected. |
| 456 | + This might cause side effects depending on the getter function. |
| 457 | + **Default:** `false`. |
| 458 | +* Returns: {string} The representation of `object`. |
462 | 459 |
|
463 | 460 | The `util.inspect()` method returns a string representation of `object` that is |
464 | 461 | intended for debugging. The output of `util.inspect` may change at any time |
465 | 462 | and should not be depended upon programmatically. Additional `options` may be |
466 | | -passed that alter certain aspects of the formatted string. |
| 463 | +passed that alter the result. |
467 | 464 | `util.inspect()` will use the constructor's name and/or `@@toStringTag` to make |
468 | 465 | an identifiable tag for an inspected value. |
469 | 466 |
|
@@ -491,7 +488,7 @@ const util = require('util'); |
491 | 488 | console.log(util.inspect(util, { showHidden: true, depth: null })); |
492 | 489 | ``` |
493 | 490 |
|
494 | | -The following example highlights the difference with the `compact` option: |
| 491 | +The following example highlights the effect of the `compact` option: |
495 | 492 |
|
496 | 493 | ```js |
497 | 494 | const util = require('util'); |
@@ -548,13 +545,11 @@ console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 })); |
548 | 545 | // chunks. |
549 | 546 | ``` |
550 | 547 |
|
551 | | -Using the `showHidden` option allows to inspect [`WeakMap`][] and [`WeakSet`][] |
552 | | -entries. If there are more entries than `maxArrayLength`, there is no guarantee |
553 | | -which entries are displayed. That means retrieving the same [`WeakSet`][] |
554 | | -entries twice might actually result in a different output. Besides this any item |
555 | | -might be collected at any point of time by the garbage collector if there is no |
556 | | -strong reference left to that object. Therefore there is no guarantee to get a |
557 | | -reliable output. |
| 548 | +The `showHidden` option allows [`WeakMap`][] and [`WeakSet`][] entries to be |
| 549 | +inspected. If there are more entries than `maxArrayLength`, there is no |
| 550 | +guarantee which entries are displayed. That means retrieving the same |
| 551 | +[`WeakSet`][] entries twice may result in different output. Furthermore, entries |
| 552 | +with no remaining strong references may be garbage collected at any time. |
558 | 553 |
|
559 | 554 | ```js |
560 | 555 | const { inspect } = require('util'); |
@@ -567,8 +562,8 @@ console.log(inspect(weakSet, { showHidden: true })); |
567 | 562 | // WeakSet { { a: 1 }, { b: 2 } } |
568 | 563 | ``` |
569 | 564 |
|
570 | | -The `sorted` option makes sure the output is identical, no matter of the |
571 | | -properties insertion order: |
| 565 | +The `sorted` option ensures that an object's property insertion order does not |
| 566 | +impact the result of `util.inspect()`. |
572 | 567 |
|
573 | 568 | ```js |
574 | 569 | const { inspect } = require('util'); |
@@ -595,11 +590,9 @@ assert.strict.equal( |
595 | 590 | ); |
596 | 591 | ``` |
597 | 592 |
|
598 | | -Please note that `util.inspect()` is a synchronous method that is mainly |
599 | | -intended as a debugging tool. Its maximum output length is limited to |
600 | | -approximately 128 MB and input values that result in output bigger than that |
601 | | -will not be inspected fully. Such values can have a significant performance |
602 | | -overhead that can block the event loop for a significant amount of time. |
| 593 | +`util.inspect()` is a synchronous method intended for debugging. Its maximum |
| 594 | +output length is approximately 128 MB. Inputs that result in longer output will |
| 595 | +be truncated. |
603 | 596 |
|
604 | 597 | ### Customizing `util.inspect` colors |
605 | 598 |
|
@@ -2209,6 +2202,7 @@ Deprecated predecessor of `console.log`. |
2209 | 2202 | [`assert.deepStrictEqual()`]: assert.html#assert_assert_deepstrictequal_actual_expected_message |
2210 | 2203 | [`console.error()`]: console.html#console_console_error_data_args |
2211 | 2204 | [`console.log()`]: console.html#console_console_log_data_args |
| 2205 | +[`target` and `handler`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy#Terminology |
2212 | 2206 | [`util.format()`]: #util_util_format_format_args |
2213 | 2207 | [`util.inspect()`]: #util_util_inspect_object_options |
2214 | 2208 | [`util.promisify()`]: #util_util_promisify_original |
|