Skip to content

util: deprecate obj.inspect for custom inspection #15631

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Trott wants to merge 2 commits into from
+15 −18
Closed

util: deprecate obj.inspect for custom inspection #15631

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7b5864e
util: deprecate obj.inspect for custom inspection
Trott Sep 26, 2017
1a791e8
squash: suggestion from addaleax
Trott Sep 29, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
util: deprecate obj.inspect for custom inspection 
The existence of `obj.inspect()` for custom inspection can cause people
to unintentionally break `console.log()` and friends. This is a
documentation-only deprecation that can hopefully land in 8.x.

Refs: #15549
  • Loading branch information
@Trott
Trott committed Sep 29, 2017
commit 7b5864e20228518dacc86f44d1c5680f7a5149a0
11 changes: 11 additions & 0 deletions doc/api/deprecations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -700,6 +700,15 @@ Type: Runtime

`REPLServer.turnOffEditorMode()` was removed from userland visibility.

<a id="DEP00XX"></a>
### DEP00XX: Custom inspection function on Objects via .inspect()

Type: Documentation-only

Using a property named `inspect` on an object to specify a custom inspection
function for [`util.inspect()`][] is deprecated. Use [`util.inspect.custom`][]
instead.
Copy link
Copy Markdown
Member

@addaleax addaleax Sep 29, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be helpful to note that, if compatibility is desired, having the method present under both names is always going to work?

Copy link
Copy Markdown
Member Author

@Trott Trott Sep 29, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea but I'm struggling with how to word it in a way that doesn't encourage people to use both if they're only using the Symbol. We don't want to create more messages if/when we move to a runtime deprecation. Suggestions welcome.

Copy link
Copy Markdown
Member

@addaleax addaleax Sep 29, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Trott The thing is, even if we move to a runtime deprecation, the symbol property will be the first one that’s detected, and the string property ignored – so if both are present, the runtime deprecation won’t be emitted… or am I misunderstanding what you’re saying?

Copy link
Copy Markdown
Member Author

@Trott Trott Sep 29, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@addaleax Good point. I've added some text in a separate commit.


[`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
[`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
[`Buffer.from(buffer)`]: buffer.html#buffer_class_method_buffer_from_buffer
Expand Down Expand Up @@ -738,6 +747,8 @@ Type: Runtime
[`util._extend()`]: util.html#util_util_extend_target_source
[`util.debug()`]: util.html#util_util_debug_string
[`util.error()`]: util.html#util_util_error_strings
[`util.inspect()`]: util.html#util_util_inspect_object_options
[`util.inspect.custom`]: util.html#util_util_inspect_custom
[`util.isArray()`]: util.html#util_util_isarray_object
[`util.isBoolean()`]: util.html#util_util_isboolean_object
[`util.isBuffer()`]: util.html#util_util_isbuffer_object
Expand Down
21 changes: 3 additions & 18 deletions doc/api/util.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -377,8 +377,8 @@ terminals.
<!-- type=misc -->

Objects may also define their own `[util.inspect.custom](depth, opts)`
(or, equivalently `inspect(depth, opts)`) function that `util.inspect()` will
invoke and use the result of when inspecting the object:
(or the equivalent but deprecated `inspect(depth, opts)`) function that
`util.inspect()` will invoke and use the result of when inspecting the object:

```js
const util = require('util');
Expand All @@ -388,7 +388,7 @@ class Box {
this.value = value;
}

inspect(depth, options) {
[util.inspect.custom](depth, options) {
if (depth < 0) {
return options.stylize('[Box]', 'special');
}
Expand Down Expand Up @@ -427,21 +427,6 @@ util.inspect(obj);
// Returns: "{ bar: 'baz' }"
```

A custom inspection method can alternatively be provided by exposing
an `inspect(depth, opts)` method on the object:

```js
const util = require('util');

const obj = { foo: 'this will not show up in the inspect() output' };
obj.inspect = function(depth) {
return { bar: 'baz' };
};

util.inspect(obj);
// Returns: "{ bar: 'baz' }"
```

### util.inspect.custom
<!-- YAML
added: v6.6.0
Expand Down