days
-7
0
hours
-1
-3
minutes
-1
-7
seconds
0
-3
search
The whys and the hows

Node.js Errors: Changes are coming!

Gabriela Motroc
Node.js

© Shutterstock / Pretty Vectors

Have you noticed the changes to Errors thrown by the Node.js runtime? They started appearing in the latest release [Node.js 8] and will continue to pour into Node.js 9. Why should you care? If your code parses the message strings, this change will surely interest you.

Michael Dawson, a Node.js Runtime Tech Dev at IBM, Node.js collaborator and CTC member announced in a post published on the Nodejs @ IBM blog that “changes are coming to Errors thrown by the Node.js runtime.” He explained that the changes started appearing in the latest Node.js version and that they will continue to pour into Node.js 9.

“Until recently, most of the Errors thrown by Node.js only had a message associated with them, Michael wrote. “If you wanted to have your code take a specific action based on the Error, you would have had to compare the message string to a known value.” This would be the result:

try { 
  // make a Node.js API call here
} catch (error) { 
  if (error.message === 'This is th message') { 
    // do something 
  } else { 
    // do something else  
  }
}

This shouldn’t happen very often because usually when you get an error from Node.js, “it is more likely that your code will simply log/display the message and then branch to a common recovery path. However, in the cases where it was necessary, you end up relying on the specific error message string.”

The message in the example above contains a typo — this also happens in the Node.js code base. When there’s a typo and you want to fix it, the change is marked as SemVer major. Therefore, the change will only be included in the next major release; it cannot be backported to older versions. Although a typo may not be such a big deal, if there’s a wrong or misleading message, that’s a problem.

SEE ALSO: Node.js 8 doesn’t come away empty-handed — Developers also receive npm@5

There’s another aspect that poses a challenge for internalization: the hard dependency on the message string. “If/when we want to take the next step and allow internationalization of the error messages returned by Node.js we need to allow the specific Error to be identified without using the message,” according to Michael. This needs to be done because once localized, the message itself could change based on the locale set for the user.

The changes being made are to add a ‘code’ to all of the error objects thrown by the Node.js APIs.

The codes are being documented in the API docs here.

Therefore, the example above could be rewritten like this:

try {
  // make a Node.js API call here
} catch (error) {
  if (error.code === 'ERR_INVALID_URL_SCHEME') {
    // do something
  } else {
    // do something else
  }
}

If/when the message changes in the future, the code will not be affected because it uses the code which remains the same.

The name of the Error is also set to include the error code.

For example, for the common errors:

  • Error [error-code]
  • TypeError [error-code]
  • RangeError [error-code]

The result is that the toString() for the error will be in the following format:

  • Error [error-code]: message
  • TypeError [error-code]: message
  • RangeError [error-code]: message

Once Error codes are in place, the idea is to be able to update message strings without having to mark the change as SemVer major.  Read more about it here.

SEE ALSO: Node.js 2017 user survey results: This is what users like about Node.js

Solution

  • For the code bases you maintain, look for instances where you are depending on the message string for Errors.
  • Remove instances where you depend on the message string content [if it’s not absolutely necessary].
  • As error codes are added, update your code base to use the error code instead of the message.  If you need to support multiple versions of Node.js you can do something like this:
try {
  // make a Node.js API call here
} catch (error) {
  if ((!error.code && (error.message === 'This is th message')) ||
      (error.code === 'ERR_INVALID_URL_SCHEME')
     ) {
    // do something 
  } else { 
    // do something else 
}

“The initial check to see if the error code exists is to make sure we only accept a match on the message if there is no code on the error,” Michael wrote. “This avoids any possibility of matching on a different error that might have the same message.”

 

They need your help so if you want to contribute, find a file that has not already been converted (checkbox checked) and for which no existing PR is listed for the file in https://github.com/nodejs/node/issues/11273 either in the main list or in the comments. You can also see if there are recent PRs covering the file you want to select because the main issue is not always up-to-date. After you’ve opened a PR, don’t forget to comment with the link in 11273 so that they can update the master list.

For more information about Errors, check out Michael Dawson’s post

Author
Gabriela Motroc
Gabriela Motroc is editor of JAXenter.com and JAX Magazine. Before working at Software & Support Media Group, she studied International Communication Management at the Hague University of Applied Sciences.