Node.js Reference ยท util, assert and the Test Runner
Node.js util.deprecate() function
Reference for util.deprecate() in Node.js: wrap a function so it warns once on first use, deprecation codes, --no-deprecation flags and the warning event.
util.deprecate(fn, message, code) returns a wrapper around fn that behaves exactly like fn but prints a deprecation warning the first time it is called. It is how a library tells its users "this still works, but stop using it" without breaking anything.
The warning is emitted through the process warning system, so it appears on stderr as (node:PID) [CODE] DeprecationWarning: message, can be silenced or turned into an error with command-line flags, and can be observed with process.on("warning").
import { deprecate } from "node:util"; export const oldName = deprecate(newName, "oldName() is deprecated, use newName()", "MYLIB001");
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
util.deprecate<T extends Function>(fn: T, msg: string, code?: string): T
| Name | Description |
|---|---|
fn |
The function to wrap. It is called with the same this and arguments, and its return value is passed through. |
msg |
The warning text. |
code |
Optional identifier such as "DEP0001" or your own "MYLIB001". It is shown in brackets and available as warning.code. |
Returns: a function that wraps fn. The wrapper keeps the original's length but is itself named deprecated, so stack traces and fn.name no longer show the original name. Used with new, it constructs normally.
Errors / edge cases: a non-function first argument throws ERR_INVALID_ARG_TYPE. A given code is warned about only once per process, even across different wrapped functions, so give each deprecation its own code.
Usage notes
- Warn once, not on every call. Without a
code, each wrapped function warns on its first call only. With acode, the code is the dedupe key. - Runtime flags control the output.
--no-deprecationsilences all deprecation warnings;--throw-deprecationturns them into thrown errors (useful in tests);--trace-deprecationprints a stack trace showing where the deprecated call came from.process.noDeprecation = trueandprocess.throwDeprecation = truedo the same from code. - Observe warnings with
process.on("warning", ...); they areErrorobjects withname"DeprecationWarning". - Deprecate properties by wrapping the getter or setter in an accessor property, since
util.deprecate()only wraps functions. - Keep the replacement obvious. A good message names the new API and the version in which the old one will be removed.
- Not a security or removal mechanism. The wrapped function still runs; nothing is blocked.
- Tests: run the code with
--throw-deprecationin CI so your own code does not depend on deprecated APIs.