{ "source": "doc/api/deprecations.md", "introduced_in": "v7.7.0", "miscs": [ { "textRaw": "Deprecated APIs", "name": "Deprecated APIs", "introduced_in": "v7.7.0", "type": "misc", "desc": "
Node.js may deprecate APIs when either: (a) use of the API is considered to be\nunsafe, (b) an improved alternative API has been made available, or (c)\nbreaking changes to the API are expected in a future major release.
\nNode.js utilizes three kinds of Deprecations:
\nA Documentation-only deprecation is one that is expressed only within the\nNode.js API docs. These generate no side-effects while running Node.js.\nSome Documentation-only deprecations trigger a runtime warning when launched\nwith --pending-deprecation
flag (or its alternative,\nNODE_PENDING_DEPRECATION=1
environment variable), similarly to Runtime\ndeprecations below. Documentation-only deprecations that support that flag\nare explicitly labeled as such in the\nlist of Deprecated APIs.
A Runtime deprecation will, by default, generate a process warning that will\nbe printed to stderr
the first time the deprecated API is used. When the\n--throw-deprecation
command-line flag is used, a Runtime deprecation will\ncause an error to be thrown.
An End-of-Life deprecation is used to identify code that either has been\nremoved or will soon be removed from Node.js.
\n", "miscs": [ { "textRaw": "Revoking deprecations", "name": "revoking_deprecations", "desc": "Occasionally, the deprecation of an API may be reversed. In such situations,\nthis document will be updated with information relevant to the decision.\nHowever, the deprecation identifier will not be modified.
\n", "type": "misc", "displayName": "Revoking deprecations" }, { "textRaw": "List of Deprecated APIs", "name": "list_of_deprecated_apis", "desc": "\n", "modules": [ { "textRaw": "DEP0001: http.OutgoingMessage.prototype.flush", "name": "dep0001:_http.outgoingmessage.prototype.flush", "desc": "Type: Runtime
\nThe OutgoingMessage.prototype.flush()
method is deprecated. Use\nOutgoingMessage.prototype.flushHeaders()
instead.
Type: End-of-Life
\nThe _linklist
module is deprecated. Please use a userland alternative.
Type: Runtime
\nThe _writableState.buffer
property is deprecated. Use the\n_writableState.getBuffer()
method instead.
Type: Documentation-only
\nThe CryptoStream.prototype.readyState
property is deprecated and should not\nbe used.
Type: Runtime (supports --pending-deprecation
)
The Buffer()
function and new Buffer()
constructor are deprecated due to\nAPI usability issues that can potentially lead to accidental security issues.
As an alternative, use of the following methods of constructing Buffer
objects\nis strongly recommended:
Buffer.alloc(size[, fill[, encoding]])
- Create a Buffer
with\ninitialized memory.Buffer.allocUnsafe(size)
- Create a Buffer
with\nuninitialized memory.Buffer.allocUnsafeSlow(size)
- Create a Buffer
with uninitialized\n memory.Buffer.from(array)
- Create a Buffer
with a copy of array
Buffer.from(arrayBuffer[, byteOffset[, length]])
-\nCreate a Buffer
that wraps the given arrayBuffer
.Buffer.from(buffer)
- Create a Buffer
that copies buffer
.Buffer.from(string[, encoding])
- Create a Buffer
\nthat copies string
.As of v10.0.0, a deprecation warning is printed at runtime when\n--pending-deprecation
is used or when the calling code is\noutside node_modules
in order to better target developers, rather than users.
Type: Runtime
\nWithin the child_process
module's spawn()
, fork()
, and exec()
\nmethods, the options.customFds
option is deprecated. The options.stdio
\noption should be used instead.
Type: End-of-Life
\nIn an earlier version of the Node.js cluster
, a boolean property with the name\nsuicide
was added to the Worker
object. The intent of this property was to\nprovide an indication of how and why the Worker
instance exited. In Node.js\n6.0.0, the old property was deprecated and replaced with a new\nworker.exitedAfterDisconnect
property. The old property name did not\nprecisely describe the actual semantics and was unnecessarily emotion-laden.
Type: Documentation-only
\nThe constants
module has been deprecated. When requiring access to constants\nrelevant to specific Node.js builtin modules, developers should instead refer\nto the constants
property exposed by the relevant module. For instance,\nrequire('fs').constants
and require('os').constants
.
Type: End-of-Life
\nUse of the crypto.pbkdf2()
API without specifying a digest was deprecated\nin Node.js 6.0 because the method defaulted to using the non-recommended\n'SHA1'
digest. Previously, a deprecation warning was printed. Starting in\nNode.js 8.0.0, calling crypto.pbkdf2()
or crypto.pbkdf2Sync()
with an\nundefined digest
will throw a TypeError
.
Type: Runtime
\nThe crypto.createCredentials()
API is deprecated. Please use\ntls.createSecureContext()
instead.
Type: Runtime
\nThe crypto.Credentials
class is deprecated. Please use tls.SecureContext
\ninstead.
Type: End-of-Life
\nDomain.dispose()
has been removed. Recover from failed I/O actions\nexplicitly via error event handlers set on the domain instead.
Type: End-of-Life
\nCalling an asynchronous function without a callback throws a TypeError
\nin Node.js 10.0.0 onwards. (See https://github.com/nodejs/node/pull/12562.)
Type: End-of-Life
\nThe fs.read()
legacy String
interface is deprecated. Use the Buffer
\nAPI as mentioned in the documentation instead.
Type: End-of-Life
\nThe fs.readSync()
legacy String
interface is deprecated. Use the\nBuffer
API as mentioned in the documentation instead.
Type: Runtime
\nThe GLOBAL
and root
aliases for the global
property have been deprecated\nand should no longer be used.
Type: End-of-Life
\nIntl.v8BreakIterator
was a non-standard extension and has been removed.\nSee Intl.Segmenter
.
Type: Runtime
\nUnhandled promise rejections are deprecated. In the future, promise rejections\nthat are not handled will terminate the Node.js process with a non-zero exit\ncode.
\n\n", "type": "module", "displayName": "DEP0018: Unhandled promise rejections" }, { "textRaw": "DEP0019: require('.') resolved outside directory", "name": "dep0019:_require('.')_resolved_outside_directory", "desc": "Type: Runtime
\nIn certain cases, require('.')
may resolve outside the package directory.\nThis behavior is deprecated and will be removed in a future major Node.js\nrelease.
Type: Runtime
\nThe Server.connections
property is deprecated. Please use the\nServer.getConnections()
method instead.
Type: Runtime
\nThe Server.listenFD()
method is deprecated. Please use\nServer.listen({fd: <number>})
instead.
Type: Runtime
\nThe os.tmpDir()
API is deprecated. Please use os.tmpdir()
instead.
Type: Runtime
\nThe os.getNetworkInterfaces()
method is deprecated. Please use the\nos.networkInterfaces
property instead.
Type: End-of-Life
\nThe REPLServer.prototype.convertToContext()
API is deprecated and should\nnot be used.
Type: Runtime
\nThe sys
module is deprecated. Please use the util
module instead.
Type: Runtime
\nThe util.print()
API is deprecated. Please use console.log()
\ninstead.
Type: Runtime
\nThe util.puts()
API is deprecated. Please use console.log()
instead.
Type: Runtime
\nThe util.debug()
API is deprecated. Please use console.error()
\ninstead.
Type: Runtime
\nThe util.error()
API is deprecated. Please use console.error()
\ninstead.
Type: Documentation-only
\nThe SlowBuffer
class has been deprecated. Please use\nBuffer.allocUnsafeSlow(size)
instead.
Type: Documentation-only
\nThe ecdh.setPublicKey()
method is now deprecated as its inclusion in the\nAPI is not useful.
Type: Documentation-only
\nThe domain
module is deprecated and should not be used.
Type: Documentation-only
\nThe EventEmitter.listenerCount(emitter, eventName)
API has been\ndeprecated. Please use emitter.listenerCount(eventName)
instead.
Type: Documentation-only
\nThe fs.exists(path, callback)
API has been deprecated. Please use\nfs.stat()
or fs.access()
instead.
Type: Documentation-only
\nThe fs.lchmod(path, mode, callback)
API has been deprecated.
Type: Documentation-only
\nThe fs.lchmodSync(path, mode)
API has been deprecated.
Type: Documentation-only
\nThe fs.lchown(path, uid, gid, callback)
API has been deprecated.
Type: Documentation-only
\nThe fs.lchownSync(path, uid, gid)
API has been deprecated.
Type: Documentation-only
\nThe require.extensions
property has been deprecated.
Type: Documentation-only
\nThe punycode
module has been deprecated. Please use a userland alternative\ninstead.
Type: End-of-Life
\nThe NODE_REPL_HISTORY_FILE
environment variable was removed. Please use\nNODE_REPL_HISTORY
instead.
Type: Documentation-only
\nThe tls.CryptoStream
class has been deprecated. Please use\ntls.TLSSocket
instead.
Type: Documentation-only
\nThe tls.SecurePair
class has been deprecated. Please use\ntls.TLSSocket
instead.
Type: Documentation-only
\nThe util.isArray()
API has been deprecated. Please use Array.isArray()
\ninstead.
Type: Documentation-only
\nThe util.isBoolean()
API has been deprecated.
Type: Documentation-only
\nThe util.isBuffer()
API has been deprecated. Please use\nBuffer.isBuffer()
instead.
Type: Documentation-only
\nThe util.isDate()
API has been deprecated.
Type: Documentation-only
\nThe util.isError()
API has been deprecated.
Type: Documentation-only
\nThe util.isFunction()
API has been deprecated.
Type: Documentation-only
\nThe util.isNull()
API has been deprecated.
Type: Documentation-only
\nThe util.isNullOrUndefined()
API has been deprecated.
Type: Documentation-only
\nThe util.isNumber()
API has been deprecated.
Type: Documentation-only
\nThe util.isObject()
API has been deprecated.
Type: Documentation-only
\nThe util.isPrimitive()
API has been deprecated.
Type: Documentation-only
\nThe util.isRegExp()
API has been deprecated.
Type: Documentation-only
\nThe util.isString()
API has been deprecated.
Type: Documentation-only
\nThe util.isSymbol()
API has been deprecated.
Type: Documentation-only
\nThe util.isUndefined()
API has been deprecated.
Type: Documentation-only
\nThe util.log()
API has been deprecated.
Type: Documentation-only
\nThe util._extend()
API has been deprecated.
Type: Runtime
\nThe fs.SyncWriteStream
class was never intended to be a publicly accessible\nAPI. No alternative API is available. Please use a userland alternative.
Type: Runtime
\n--debug
activates the legacy V8 debugger interface, which has been removed as\nof V8 5.8. It is replaced by Inspector which is activated with --inspect
\ninstead.
Type: Documentation-only
\nThe http
module ServerResponse.prototype.writeHeader()
API has been\ndeprecated. Please use ServerResponse.prototype.writeHead()
instead.
The ServerResponse.prototype.writeHeader()
method was never documented as an\nofficially supported API.
Type: Runtime
\nThe tls.createSecurePair()
API was deprecated in documentation in Node.js\n0.11.3. Users should use tls.Socket
instead.
Type: End-of-Life
\nThe repl
module's REPL_MODE_MAGIC
constant, used for replMode
option, has\nbeen removed. Its behavior has been functionally identical to that of\nREPL_MODE_SLOPPY
since Node.js 6.0.0, when V8 5.0 was imported. Please use\nREPL_MODE_SLOPPY
instead.
The NODE_REPL_MODE
environment variable is used to set the underlying\nreplMode
of an interactive node
session. Its value, magic
, is also\nremoved. Please use sloppy
instead.
Type: Documentation-only
\nThe http
module outgoingMessage._headers
and outgoingMessage._headerNames
\nproperties have been deprecated. Please instead use one of the public methods\n(e.g. outgoingMessage.getHeader()
, outgoingMessage.getHeaders()
,\noutgoingMessage.getHeaderNames()
, outgoingMessage.hasHeader()
,\noutgoingMessage.removeHeader()
, outgoingMessage.setHeader()
) for working\nwith outgoing headers.
The outgoingMessage._headers
and outgoingMessage._headerNames
properties\nwere never documented as officially supported properties.
Type: Documentation-only
\nThe http
module OutgoingMessage.prototype._renderHeaders()
API has been\ndeprecated.
The OutgoingMessage.prototype._renderHeaders
property was never documented as\nan officially supported API.
Type: Runtime
\nnode debug
corresponds to the legacy CLI debugger which has been replaced with\na V8-inspector based CLI debugger available through node inspect
.
Type: End-of-Life
\nDebugContext has been removed in V8 and is not available in Node.js 10+.
\nDebugContext was an experimental API.
\n\n", "type": "module", "displayName": "DEP0069: vm.runInDebugContext(string)" }, { "textRaw": "DEP0070: async_hooks.currentId()", "name": "dep0070:_async_hooks.currentid()", "desc": "Type: End-of-Life
\nasync_hooks.currentId()
was renamed to async_hooks.executionAsyncId()
for\nclarity.
This change was made while async_hooks
was an experimental API.
Type: End-of-Life
\nasync_hooks.triggerId()
was renamed to async_hooks.triggerAsyncId()
for\nclarity.
This change was made while async_hooks
was an experimental API.
Type: End-of-Life
\nasync_hooks.AsyncResource.triggerId()
was renamed to\nasync_hooks.AsyncResource.triggerAsyncId()
for clarity.
This change was made while async_hooks
was an experimental API.
Type: End-of-Life
\nAccessing several internal, undocumented properties of net.Server
instances\nwith inappropriate names has been deprecated.
As the original API was undocumented and not generally useful for non-internal\ncode, no replacement API is provided.
\n\n", "type": "module", "displayName": "DEP0073: Several internal properties of net.Server" }, { "textRaw": "DEP0074: REPLServer.bufferedCommand", "name": "dep0074:_replserver.bufferedcommand", "desc": "Type: Runtime
\nThe REPLServer.bufferedCommand
property was deprecated in favor of\nREPLServer.clearBufferedCommand()
.
Type: Runtime
\nREPLServer.parseREPLKeyword()
was removed from userland visibility.
Type: Runtime
\ntls.parseCertString()
is a trivial parsing helper that was made public by\nmistake. This function can usually be replaced with:
const querystring = require('querystring');\nquerystring.parse(str, '\\n', '=');\n
\nThis function is not completely equivalent to querystring.parse()
. One\ndifference is that querystring.parse()
does url decoding:
> querystring.parse('%E5%A5%BD=1', '\\n', '=');\n{ '好': '1' }\n> tls.parseCertString('%E5%A5%BD=1');\n{ '%E5%A5%BD': '1' }\n
\n\n",
"type": "module",
"displayName": "DEP0076: tls.parseCertString()"
},
{
"textRaw": "DEP0077: Module.\\_debug()",
"name": "dep0077:_module.\\_debug()",
"desc": "Type: Runtime
\nModule._debug()
has been deprecated.
The Module._debug()
function was never documented as an officially\nsupported API.
Type: Runtime
\nREPLServer.turnOffEditorMode()
was removed from userland visibility.
Type: Runtime
\nUsing a property named inspect
on an object to specify a custom inspection\nfunction for util.inspect()
is deprecated. Use util.inspect.custom
\ninstead. For backward compatibility with Node.js prior to version 6.4.0, both\nmay be specified.
Type: Documentation-only
\nThe internal path._makeLong()
was not intended for public use. However,\nuserland modules have found it useful. The internal API has been deprecated\nand replaced with an identical, public path.toNamespacedPath()
method.
Type: Runtime
\nfs.truncate()
fs.truncateSync()
usage with a file descriptor has been\ndeprecated. Please use fs.ftruncate()
or fs.ftruncateSync()
to work with\nfile descriptors.
Type: Runtime
\nREPLServer.prototype.memory()
is only necessary for the internal mechanics of\nthe REPLServer
itself. Do not use this function.
Type: Runtime
\nThe ecdhCurve
option to tls.createSecureContext()
and tls.TLSSocket
could\nbe set to false
to disable ECDH entirely on the server only. This mode is\ndeprecated in preparation for migrating to OpenSSL 1.1.0 and consistency with\nthe client. Use the ciphers
parameter instead.
Type: Runtime
\nSince Node.js versions 4.4.0 and 5.2.0, several modules only intended for\ninternal usage are mistakenly exposed to user code through require()
. These\nmodules are:
v8/tools/codemap
v8/tools/consarray
v8/tools/csvparser
v8/tools/logreader
v8/tools/profile_view
v8/tools/profile
v8/tools/SourceMap
v8/tools/splaytree
v8/tools/tickprocessor-driver
v8/tools/tickprocessor
node-inspect/lib/_inspect
(from 7.6.0)node-inspect/lib/internal/inspect_client
(from 7.6.0)node-inspect/lib/internal/inspect_repl
(from 7.6.0)The v8/*
modules do not have any exports, and if not imported in a specific\norder would in fact throw errors. As such there are virtually no legitimate use\ncases for importing them through require()
.
On the other hand, node-inspect
may be installed locally through a package\nmanager, as it is published on the npm registry under the same name. No source\ncode modification is necessary if that is done.
Type: End-of-Life
\nThe AsyncHooks Sensitive API was never documented and had various minor issues.\n(See https://github.com/nodejs/node/issues/15572.) Use the AsyncResource
\nAPI instead.
Type: End-of-Life
\nrunInAsyncIdScope
doesn't emit the 'before'
or 'after'
event and can thus\ncause a lot of issues. See https://github.com/nodejs/node/issues/14328 for more\ndetails.
Type: Documentation-only
\nImporting assert directly is not recommended as the exposed functions will use\nloose equality checks. Use require('assert').strict
instead. The API is the\nsame as the legacy assert but it will always use strict equality checks.
Type: Runtime
\nNode.js supports all GCM authentication tag lengths which are accepted by\nOpenSSL when calling decipher.setAuthTag()
. This behavior will change in\na future version at which point only authentication tag lengths of 128, 120,\n112, 104, 96, 64, and 32 bits will be allowed. Authentication tags whose length\nis not included in this list will be considered invalid in compliance with\nNIST SP 800-38D.
Type: Runtime
\nThe crypto.DEFAULT_ENCODING
property is deprecated.
Type: Documentation-only
\nAssigning properties to the top-level this
as an alternative\nto module.exports
is deprecated. Developers should use exports
\nor module.exports
instead.
Type: Documentation-only
\nThe crypto.fips
property is deprecated. Please use crypto.setFips()
\nand crypto.getFips()
instead.
Type: Runtime
\nUsing assert.fail()
with more than one argument is deprecated. Use\nassert.fail()
with only one argument or use a different assert
module\nmethod.
Type: Runtime
\ntimers.enroll()
is deprecated. Please use the publicly documented\nsetTimeout()
or setInterval()
instead.
Type: Runtime
\ntimers.unenroll()
is deprecated. Please use the publicly documented\nclearTimeout()
or clearInterval()
instead.
Type: Runtime
\nUsers of MakeCallback
that add the domain
property to carry context,\nshould start using the async_context
variant of MakeCallback
or\nCallbackScope
, or the high-level AsyncResource
class.
Type: Runtime
\nThe embedded API provided by AsyncHooks exposes .emitBefore()
and\n.emitAfter()
methods which are very easy to use incorrectly which can lead\nto unrecoverable errors.
Use asyncResource.runInAsyncScope()
API instead which provides a much\nsafer, and more convenient, alternative. See\nhttps://github.com/nodejs/node/pull/18513 for more details.
Type: Compile-time
\nCertain versions of node::MakeCallback
APIs available to native modules are\ndeprecated. Please use the versions of the API that accept an async_context
\nparameter.
Type: Runtime
\nprocess.assert()
is deprecated. Please use the assert
module instead.
This was never a documented feature.
\n\n", "type": "module", "displayName": "DEP0100: process.assert()" }, { "textRaw": "DEP0101: --with-lttng", "name": "dep0101:_--with-lttng", "desc": "Type: End-of-Life
\nThe --with-lttng
compile-time option has been removed.
Type: End-of-Life
\nUsing the noAssert
argument has no functionality anymore. All input is going\nto be verified, no matter if it is set to true or not. Skipping the verification\ncould lead to hard to find errors and crashes.
Type: Documentation-only (supports --pending-deprecation
)
Using process.binding()
in general should be avoided. The type checking\nmethods in particular can be replaced by using util.types
.
Type: Documentation-only (supports --pending-deprecation
)
When assigning a non-string property to process.env
, the assigned value is\nimplicitly converted to a string. This behavior is deprecated if the assigned\nvalue is not a string, boolean, or number. In the future, such assignment may\nresult in a thrown error. Please convert the property to a string before\nassigning it to process.env
.
Type: Runtime
\ndecipher.finaltol()
has never been documented and is currently an alias for\ndecipher.final()
. In the future, this API will likely be removed, and it\nis recommended to use decipher.final()
instead.
Type: Documentation-only
\nUsing crypto.createCipher()
and crypto.createDecipher()
should be\navoided as they use a weak key derivation function (MD5 with no salt) and static\ninitialization vectors. It is recommended to derive a key using\ncrypto.pbkdf2()
and to use crypto.createCipheriv()
and\ncrypto.createDecipheriv()
to obtain the Cipher
and Decipher
\nobjects respectively.
Type: Runtime
\nThis was an undocumented helper function not intended for use outside Node.js\ncore and obsoleted by the removal of NPN (Next Protocol Negotiation) support.
\n\n", "type": "module", "displayName": "DEP0107: tls.convertNPNProtocols()" }, { "textRaw": "DEP0108: zlib.bytesRead", "name": "dep0108:_zlib.bytesread", "desc": "Type: Documentation-only
\nDeprecated alias for zlib.bytesWritten
. This original name was chosen\nbecause it also made sense to interpret the value as the number of bytes\nread by the engine, but is inconsistent with other streams in Node.js that\nexpose values under these names.