Skip to content
Tutorials Center
My learning

Topics

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").

NODE
import { deprecate } from "node:util";

export const oldName = deprecate(newName, "oldName() is deprecated, use newName()", "MYLIB001");

Try it

Node.js Warning once per code

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.

Node.js Deprecating a method on a class

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

NODE
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 a code, the code is the dedupe key.
  • Runtime flags control the output. --no-deprecation silences all deprecation warnings; --throw-deprecation turns them into thrown errors (useful in tests); --trace-deprecation prints a stack trace showing where the deprecated call came from. process.noDeprecation = true and process.throwDeprecation = true do the same from code.
  • Observe warnings with process.on("warning", ...); they are Error objects with name "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-deprecation in CI so your own code does not depend on deprecated APIs.