Skip to content
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

doc: note util.isError() @@toStringTag limitations #5414

Merged
merged 1 commit into from
Feb 25, 2016
Merged

doc: note util.isError() @@toStringTag limitations #5414

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
16 changes: 16 additions & 0 deletions doc/api/util.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -335,6 +335,22 @@ util.isError({ name: 'Error', message: 'an error occurred' })
// false
```

Note that this method relies on `Object.prototype.toString()` behavior. It is
possible to obtain an incorrect result when the `object` argument manipulates
`@@toStringTag`.

```js
// This example requires the `--harmony-tostring` flag
Copy link
Contributor

Choose a reason for hiding this comment

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

Should we even document something based on a feature which is behind a flag?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Normally, I'd say no. But this is already possible with things like babel-node, and is only a matter of time until it's possible without a flag (http://v8project.blogspot.com/2016/01/v8-release-49.html).

Copy link
Contributor

Choose a reason for hiding this comment

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

Aren't we deprecating all these functions with #1301 (hopefully by v6.0)?

Copy link
Member

Choose a reason for hiding this comment

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

@thefourtheye asks:

Aren't we deprecating all these functions with #1301 (hopefully by v6.0)?

Deprecated functions still need to be accurately documented. In this particular case, if the additional material provided here makes it clear that the function is not bullet-proof, then we're doing people a favor. (I'm not actually sure how likely it is that someone will run across the problem described here, but it's an awfully big ecosystem out there...)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes. They are already deprecated in the docs. I think the warning is still worthwhile until they are no longer exposed from core.

Copy link
Contributor

Choose a reason for hiding this comment

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

Okay, in that case, this particular thing is applicable to few other functions in util. Can we put this as a separate section and link it in all the relevant function descriptions?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It should only still be applicable to isError(). The others were moved to checks at the C++ level.

Copy link
Contributor

Choose a reason for hiding this comment

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

Oops, sorry. I should have checked that first.

const util = require('util');
const obj = { name: 'Error', message: 'an error occurred' };

util.isError(obj);
// false
obj[Symbol.toStringTag] = 'Error';
util.isError(obj);
// true
```

## util.isFunction(object)

Stability: 0 - Deprecated
Expand Down