util: `util.deprecate` improvement #1892

thefourtheye · 2015-06-04T06:15:41Z

Follow up of #1883.

Changes included in this PR are

Making the deprecation messages consistent. The messages will be in
the following format
```
x is deprecated. Use y instead.
```
If there is no alternative for x, then the Use y instead. part
will not be there in the message.
All the internal deprecation messages are printed with the prefix
(node), except when the --trace-deprecation flag is set.

silverwind · 2015-06-04T13:22:50Z

Regarding [node]: There is this one (and presumably only) case where we print with a (node) prefix. I have no preference for a parens style, but we should keep it consistent.

thefourtheye · 2015-06-04T13:26:36Z

@silverwind Oh, shall I change [node]s to (node)s?

silverwind · 2015-06-04T13:27:53Z

Yeah, probably best of you'd change that.

silverwind · 2015-06-04T13:36:39Z

lib/util.js

  function deprecated() {
+    var location = (new Error()).stack.match(/.*?\n.*\n.*?\((.*?:\d+):/)[1];


This doesn't seem to match the correct line of the call. Here's a random test I put into an app of mine:

Stack:

Error at startListeners (/Users/silverwind/git/droppy/server/server.js:121:18) at /Users/silverwind/git/droppy/server/server.js:77:45 at /Users/silverwind/git/droppy/node_modules/async/lib/async.js:695:13 at iterate (/Users/silverwind/git/droppy/node_modules/async/lib/async.js:256:13) at doNTCallback0 (node.js:408:9) at process._tickCallback (node.js:337:13)

Output of your regex:

/Users/silverwind/git/droppy/node_modules/async/lib/async.js:256

You should try matching the first line here (server.js:121).

I haven't tested this with a real deprecate yet, so maybe I'm wrong 😅

@silverwind You are correct, I am rebasing now. I ll fix it in that. I didn't know that we will get lines like

at /Users/silverwind/git/droppy/server/server.js:77:45

this in the trace. Probably, I ll split the stack, take the second line and then parse it.

@silverwind Do you have the change which landed today? This should ideally have an entry for deprecated. Are you doing only new Error().stack?

That line above was produced by just

console.log(stack.match(/.*?\n.*\n.*?\((.*?:\d+):/)[1]);

I think the lines without parens are anonymous functions.

@silverwind For anonymous functions, I am getting Object.<anonymous>. The lines without parens are for the calls directly from the modules, I think.

silverwind · 2015-06-04T13:41:44Z

Also, apparently your branch is outdated and the PR needs a rebase already.

vkurchatkin · 2015-06-04T14:33:27Z

If we actually want this it makes sense to use internal wrapper that prepends (node) automatically

silverwind · 2015-06-04T14:36:36Z

@vkurchatkin not a huge fan of a wrapper. Maybe there's a way to detect an internal call to deprecate and prepend (node) in that case?

thefourtheye · 2015-06-04T14:39:55Z

@silverwind @vkurchatkin Why don't we accept the prefix as a parameter?

vkurchatkin · 2015-06-04T14:40:03Z

@silverwind why not? just use require('internal/util').deprecate

@thefourtheye concatenating strings is something that users can do on their own

silverwind · 2015-06-04T15:05:06Z

@vkurchatkin guess I could live with something like internal/util 👍

thefourtheye · 2015-06-04T15:07:35Z

You guys mean, deprecate function in 'internal/util will add (node)? Can you please explain this a bit more?

silverwind · 2015-06-04T15:14:10Z

Add a wrapper function in lib/internal/util.js that uses util.deprecate and prepends (node) to the message string. Afterwards include it through require('internal/util').deprecate in all files that do deprecations and use it.

thefourtheye · 2015-06-04T16:11:26Z

@silverwind @vkurchatkin Thanks for the suggestions :-) I updated the PR. Please review.

thefourtheye · 2015-06-04T18:20:23Z

lib/util.js



-exports.pump = exports.deprecate(function(readStream, writeStream, callback) {
+exports.pump = internalUtil.deprecate(function(readStream, writeStream, cb) {


I had to change this because of the line length restriction

thefourtheye · 2015-06-04T18:26:51Z

@silverwind I think I addressed all the comments and included a test with parenthesis in the file name. Please check now.

targos · 2015-06-04T19:17:21Z

lib/smalloc.js

@@ -3,4 +3,4 @@
 const util = require('internal/util');

 module.exports = require('internal/smalloc');
-util.printDeprecationMessage('smalloc is deprecated.');
+util.deprecate('smalloc is deprecated. Use typed arrays.');


I don't think it will work here. The idea is to print a deprecation message when this line is executed.
printDeprecationMessage should stay but we have a problem with the --trace-deprecation flag. The actual caller location is where require('smalloc') is done.

@targos Oh, you are correct. printDeprecationMessage should stay. But, in case of require, we can print only once. So, --trace-deprecation cannot do much here, right?

silverwind · 2015-06-06T03:19:34Z

Is there a test yet to assert file and line numbers are correct? I can see this getting broken easily when the call stack to deprecate ever changes, so I think such a test is necessary.

thefourtheye · 2015-06-06T15:25:57Z

@silverwind Oh yeah. You are correct. I updated one of the tests to include the checks. Please check now.

silverwind · 2015-06-07T20:31:36Z

test/sequential/test-deprecation-flags.js

+  assert.equal(stack.pop(), '\'This is deprecated\'');
+  console.log('trace ok');
+});
+


Very minor, But one newline is enough here :)

@silverwind Only line 114 is left empty, right? I thought that it would improve readability.

I'm talking about the final line of this file. git apply also complains: new blank line at EOF

silverwind · 2015-06-07T20:43:19Z

Gave it a try, seems the file and line number isn't always correct:

$ >t.js
require("smalloc")
^C
$ ./iojs t.js
(node) smalloc is deprecated. Use typed arrays.
Used at: node.js:937

Strangely, --trace-deprecation doesn't show anything in this simple test.

Also, I'd prefer a single-line style. Maybe just cut out the path and use only the filename to keep it short:

(node) in node.js:937: smalloc is deprecated. Use typed arrays.

or postfix, I have no preference:

(node) smalloc is deprecated. Use typed arrays. (node.js:937)

thefourtheye · 2015-06-08T00:56:49Z

Ah, that is a corner case where we skip the util.deprecate and directly call printDeprecationMessage. I ll fix it by adding a flag in the parameter.

thefourtheye · 2015-06-17T05:22:29Z

@silverwind Why don't we change the newly landed deprecate to _deprecate? Its used in only one place.

silverwind · 2015-06-17T05:28:42Z

That could work too, just seems a bit confusing at first glance that _deprecate is the one used by public code. It's not much of an issue and I'd be fine if you chose to do so.

thefourtheye · 2015-06-17T08:07:46Z

@brendanashworth Thanks for the heads up :-)

@silverwind I renamed it to _internalDeprecate and removed the util dependency.

silverwind · 2015-06-17T12:15:18Z

lib/internal/util.js

@@ -10,7 +18,7 @@ exports.printDeprecationMessage = function(msg, warned) {
  if (process.throwDeprecation)
    throw new Error(msg);
  else if (process.traceDeprecation)
-    console.trace(msg);
+    console.trace(msg.replace(new RegExp(`^\\(${prefix}\\) `), ''));


Not sure I understand why this double escaping is needed. Wouldn't a literal like /^$${prefix}$ / work?

@silverwind Will the string substitution work in RegEx literals also?

Of course:

> '(node) something'.replace(/$node$ /,'') 'something'

This is not substitution right? I stored node in a variable. How can that be substituted in the RegEx literal?

Oh, right. Template string substitution won't work inside a regex literal, so this is fine.

@silverwind Actually, the ES6 proposal had re Quasi literal function though :-)

silverwind · 2015-06-17T12:19:28Z

Sorry, but still not totally satisfied yet. Here's what I suggest to fix the remaining issues:

_internalDeprecate isn't really clear either for the purpose, let's just call it _deprecate.
Add a _printDeprecationMessage that does not prefix
Change printDeprecationMessage to add the prefix and call into _printDeprecationMessage
Remove all remaining prefixes from printDeprecationMessage calls.

silverwind · 2015-06-17T12:20:09Z

Also, I think you should squash into a single commit now. I can't apply this PR on top of master because of previous patches that don't apply anymore.

thefourtheye · 2015-06-18T13:25:12Z

@silverwind I updated the PR with the review comments. Please review now.

Changes included in this commit are 1. Making the deprecation messages consistent. The messages will be in the following format x is deprecated. Use y instead. If there is no alternative for `x`, then the ` Use y instead.` part will not be there in the message. 2. All the internal deprecation messages are printed with the prefix `(node) `, except when the `--trace-deprecation` flag is set.

silverwind · 2015-06-28T15:25:23Z

Sorry for the delay. LGTM

mscdex · 2015-06-28T17:49:29Z

Would it make more sense to have a deprecate() that automatically includes the boilerplate text? Like:

exports.deprecate = function(oldValue, newValue) {
  // using whatever appropriate internal util function instead of `console.log` of course
  console.log('%s is deprecated. Use %s instead.', oldValue, newValue);
};

silverwind · 2015-06-28T17:58:52Z

I see some use in something like that (primarily the part of forcing the maintainer to point to an alternative). But remember this is public API which would force a semver-major.

mscdex · 2015-06-28T18:38:27Z

Well, there could be a conditional to check if arguments.length === 1 and if so, only log the %s is deprecated. part.

thefourtheye · 2015-06-29T11:54:02Z

What if the users want to give a custom message? Let's say "Feature X is deprecated and removed in version 1.0.0. Use Y instead"

silverwind · 2015-06-29T12:22:00Z

I'm feeling more inclined to leave it as is with a simple string for flexibility.

thefourtheye · 2015-06-29T12:35:35Z

@silverwind What if we use @mscdex's suggestion for the internal deprecations?

silverwind · 2015-06-29T16:59:26Z

I'd decide against it. We can just make sure the future deprecation messages follow this scheme. No hand-holding needed there imho :)

silverwind · 2015-07-02T21:27:13Z

I'll most likely land this tomorrow, unless further objections are made.

thefourtheye · 2015-07-02T21:49:50Z

OSM :-)

Changes included in this commit are 1. Making the deprecation messages consistent. The messages will be in the following format x is deprecated. Use y instead. If there is no alternative for `x`, then the ` Use y instead.` part will not be there in the message. 2. All the internal deprecation messages are printed with the prefix `(node) `, except when the `--trace-deprecation` flag is set. Fixes: #1883 PR-URL: #1892 Reviewed-By: Roman Reiss <me@silverwind.io>

silverwind · 2015-07-03T14:36:00Z

Landed in 9cd44bb

Changes included in this commit are 1. Making the deprecation messages consistent. The messages will be in the following format x is deprecated. Use y instead. If there is no alternative for `x`, then the ` Use y instead.` part will not be there in the message. 2. All the internal deprecation messages are printed with the prefix `(node) `, except when the `--trace-deprecation` flag is set. Fixes: nodejs#1883 PR-URL: nodejs#1892 Reviewed-By: Roman Reiss <me@silverwind.io>

thefourtheye force-pushed the deprecate-improvement branch from f7e2ba5 to 08e57b4 Compare June 4, 2015 06:17

brendanashworth added the util Issues and PRs related to the built-in util module. label Jun 4, 2015

silverwind reviewed Jun 4, 2015
View reviewed changes

thefourtheye force-pushed the deprecate-improvement branch from 08e57b4 to 0570e40 Compare June 4, 2015 16:09

thefourtheye force-pushed the deprecate-improvement branch from 0570e40 to 2aa754e Compare June 4, 2015 18:18

thefourtheye reviewed Jun 4, 2015
View reviewed changes

thefourtheye force-pushed the deprecate-improvement branch from 2aa754e to 876ff26 Compare June 4, 2015 18:26

targos reviewed Jun 4, 2015
View reviewed changes

thefourtheye force-pushed the deprecate-improvement branch from 876ff26 to 6d4a717 Compare June 4, 2015 19:39

thefourtheye force-pushed the deprecate-improvement branch from 6d4a717 to a24698a Compare June 6, 2015 15:24

thefourtheye force-pushed the deprecate-improvement branch from a24698a to 5e165c5 Compare June 7, 2015 16:17

silverwind reviewed Jun 7, 2015
View reviewed changes

silverwind reviewed Jun 17, 2015
View reviewed changes

thefourtheye force-pushed the deprecate-improvement branch 5 times, most recently from 9825c35 to 416a134 Compare June 18, 2015 13:23

rvagg force-pushed the master branch from 9d21135 to 628a3ab Compare June 25, 2015 09:18

silverwind closed this Jul 3, 2015

thefourtheye deleted the deprecate-improvement branch July 3, 2015 17:21

thefourtheye mentioned this pull request Jul 12, 2015

crypto: add sync methods, deprecate optional callbacks #632

Closed

1 task

		function deprecated() {
		var location = (new Error()).stack.match(/.?\n.\n.?\((.?:\d+):/)[1];



		exports.pump = exports.deprecate(function(readStream, writeStream, callback) {
		exports.pump = internalUtil.deprecate(function(readStream, writeStream, cb) {

util: util.deprecate improvement #1892

util: util.deprecate improvement #1892

Conversation

thefourtheye commented Jun 4, 2015

silverwind commented Jun 4, 2015

thefourtheye commented Jun 4, 2015

silverwind commented Jun 4, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

silverwind commented Jun 4, 2015

vkurchatkin commented Jun 4, 2015

silverwind commented Jun 4, 2015

thefourtheye commented Jun 4, 2015

vkurchatkin commented Jun 4, 2015

silverwind commented Jun 4, 2015

thefourtheye commented Jun 4, 2015

silverwind commented Jun 4, 2015

thefourtheye commented Jun 4, 2015

Choose a reason for hiding this comment

thefourtheye commented Jun 4, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

silverwind commented Jun 6, 2015

thefourtheye commented Jun 6, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

silverwind commented Jun 7, 2015

thefourtheye commented Jun 8, 2015

thefourtheye commented Jun 17, 2015

silverwind commented Jun 17, 2015

thefourtheye commented Jun 17, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

silverwind commented Jun 17, 2015

silverwind commented Jun 17, 2015

thefourtheye commented Jun 18, 2015

silverwind commented Jun 28, 2015

mscdex commented Jun 28, 2015

silverwind commented Jun 28, 2015

mscdex commented Jun 28, 2015

thefourtheye commented Jun 29, 2015

silverwind commented Jun 29, 2015

thefourtheye commented Jun 29, 2015

silverwind commented Jun 29, 2015

silverwind commented Jul 2, 2015

thefourtheye commented Jul 2, 2015

silverwind commented Jul 3, 2015

util: `util.deprecate` improvement #1892

util: `util.deprecate` improvement #1892