How to "officially" deprecate methods with Node.js utilities

If you maintain a Node.js library or framework that's consumed by people downstream, you know the pain of introducing breaking changes and deprecating existing functionality. People get mad very quickly and the only solution is to communicate very early that things might change or will disappear in a future version.

I've thought that the only way to communicate future deprecations is to mark methods as deprecated via TSDoc / JSDoc.

/**
 * Returns a string value.
 * @deprecated This function is deprecated and will be removed in a future version.
 * @returns {string} The string 'something'
 */
export const getSomething = () => {
  return 'something'
}

In this case, if someone imports the deprecated getSomething method, the editor (in my case it's VS Code) will make it very clear that they should look into not using the method.

VS Code's crossed out text is very convincing if you ask me but I don't know if every editor displays deprecation warnings as prominently.

If you really want to make sure people see your Node.js deprecation notice, today, I learned that Node.js provides a native deprecate method.

import { deprecate } from "node:util";

/**
 * Returns a string value.
 * @deprecated This function is deprecated and will be removed in a future version.
 * @returns {string} The string 'something'
 */
export const getSomething = deprecate(() => {
  return 'something'
}, 'watch out! something is deprecated!')

And if someone now uses deprecated methods, they will also get notified when they run the code via Node.js.

$ node index.ts

something
(node:21682) DeprecationWarning: watch out! something is deprecated!
(Use `node --trace-deprecation ...` to show where the warning was created)

Sweet!