11cb0ef41Sopenharmony_ci<!DOCTYPE html> 21cb0ef41Sopenharmony_ci<html lang="en"> 31cb0ef41Sopenharmony_ci<head> 41cb0ef41Sopenharmony_ci <meta charset="utf-8"> 51cb0ef41Sopenharmony_ci <meta name="viewport" content="width=device-width"> 61cb0ef41Sopenharmony_ci <meta name="nodejs.org:node-version" content="v18.20.1"> 71cb0ef41Sopenharmony_ci <title>Stream | Node.js v18.20.1 Documentation</title> 81cb0ef41Sopenharmony_ci <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 91cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/style.css"> 101cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/hljs.css"> 111cb0ef41Sopenharmony_ci <link rel="canonical" href="https://nodejs.org/api/stream.html"> 121cb0ef41Sopenharmony_ci <script async defer src="assets/api.js" type="text/javascript"></script> 131cb0ef41Sopenharmony_ci <style>@media(max-width:718px){.with-62-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:646px){.with-53-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}@media(max-width:558px){.with-42-chars>.js-flavor-selector{float:none;margin:0 0 1em auto;}}</style> 141cb0ef41Sopenharmony_ci</head> 151cb0ef41Sopenharmony_ci<body class="alt apidoc" id="api-section-stream"> 161cb0ef41Sopenharmony_ci <div id="content" class="clearfix"> 171cb0ef41Sopenharmony_ci <div id="column2" class="interior"> 181cb0ef41Sopenharmony_ci <div id="intro" class="interior"> 191cb0ef41Sopenharmony_ci <a href="/" title="Go back to the home page"> 201cb0ef41Sopenharmony_ci Node.js 211cb0ef41Sopenharmony_ci </a> 221cb0ef41Sopenharmony_ci </div> 231cb0ef41Sopenharmony_ci <ul> 241cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 251cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 261cb0ef41Sopenharmony_ci</ul> 271cb0ef41Sopenharmony_ci<hr class="line"> 281cb0ef41Sopenharmony_ci<ul> 291cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 301cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 311cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 321cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 331cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 341cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 351cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 361cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 371cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 381cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 391cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 401cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 411cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 421cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 431cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 441cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 451cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 461cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 471cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 481cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 491cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 501cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 511cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 521cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 531cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 541cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 551cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 561cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 571cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 581cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 591cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 601cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 611cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 621cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 631cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 641cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 651cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 661cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 671cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 681cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 691cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 701cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 711cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 721cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream active">Stream</a></li> 731cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 741cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 751cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 761cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 771cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 781cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 791cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 801cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 811cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 821cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 831cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 841cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 851cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 861cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 871cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 881cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 891cb0ef41Sopenharmony_ci</ul> 901cb0ef41Sopenharmony_ci<hr class="line"> 911cb0ef41Sopenharmony_ci<ul> 921cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 931cb0ef41Sopenharmony_ci</ul> 941cb0ef41Sopenharmony_ci </div> 951cb0ef41Sopenharmony_ci 961cb0ef41Sopenharmony_ci <div id="column1" data-id="stream" class="interior"> 971cb0ef41Sopenharmony_ci <header class="header"> 981cb0ef41Sopenharmony_ci <div class="header-container"> 991cb0ef41Sopenharmony_ci <h1>Node.js v18.20.1 documentation</h1> 1001cb0ef41Sopenharmony_ci <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 1011cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 1021cb0ef41Sopenharmony_ci <path fill="none" d="M0 0h24v24H0z" /> 1031cb0ef41Sopenharmony_ci <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> 1041cb0ef41Sopenharmony_ci <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> 1051cb0ef41Sopenharmony_ci </svg> 1061cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 1071cb0ef41Sopenharmony_ci <path d="M0 0h24v24H0z" fill="none" /> 1081cb0ef41Sopenharmony_ci <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> 1091cb0ef41Sopenharmony_ci </svg> 1101cb0ef41Sopenharmony_ci </button> 1111cb0ef41Sopenharmony_ci </div> 1121cb0ef41Sopenharmony_ci <div id="gtoc"> 1131cb0ef41Sopenharmony_ci <ul> 1141cb0ef41Sopenharmony_ci <li class="pinned-header">Node.js v18.20.1</li> 1151cb0ef41Sopenharmony_ci 1161cb0ef41Sopenharmony_ci <li class="picker-header"> 1171cb0ef41Sopenharmony_ci <a href="#"> 1181cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 1191cb0ef41Sopenharmony_ci Table of contents 1201cb0ef41Sopenharmony_ci </a> 1211cb0ef41Sopenharmony_ci 1221cb0ef41Sopenharmony_ci <div class="picker"><div class="toc"><ul> 1231cb0ef41Sopenharmony_ci<li><span class="stability_2"><a href="#stream">Stream</a></span> 1241cb0ef41Sopenharmony_ci<ul> 1251cb0ef41Sopenharmony_ci<li><a href="#organization-of-this-document">Organization of this document</a></li> 1261cb0ef41Sopenharmony_ci<li><a href="#types-of-streams">Types of streams</a> 1271cb0ef41Sopenharmony_ci<ul> 1281cb0ef41Sopenharmony_ci<li><a href="#streams-promises-api">Streams Promises API</a></li> 1291cb0ef41Sopenharmony_ci<li><a href="#streampipelinesource-transforms-destination-options"><code>stream.pipeline(source[, ...transforms], destination[, options])</code></a></li> 1301cb0ef41Sopenharmony_ci<li><a href="#streampipelinestreams-options"><code>stream.pipeline(streams[, options])</code></a></li> 1311cb0ef41Sopenharmony_ci<li><a href="#streamfinishedstream-options"><code>stream.finished(stream[, options])</code></a></li> 1321cb0ef41Sopenharmony_ci<li><a href="#object-mode">Object mode</a></li> 1331cb0ef41Sopenharmony_ci<li><a href="#buffering">Buffering</a></li> 1341cb0ef41Sopenharmony_ci</ul> 1351cb0ef41Sopenharmony_ci</li> 1361cb0ef41Sopenharmony_ci<li><a href="#api-for-stream-consumers">API for stream consumers</a> 1371cb0ef41Sopenharmony_ci<ul> 1381cb0ef41Sopenharmony_ci<li><a href="#writable-streams">Writable streams</a> 1391cb0ef41Sopenharmony_ci<ul> 1401cb0ef41Sopenharmony_ci<li><a href="#class-streamwritable">Class: <code>stream.Writable</code></a> 1411cb0ef41Sopenharmony_ci<ul> 1421cb0ef41Sopenharmony_ci<li><a href="#event-close">Event: <code>'close'</code></a></li> 1431cb0ef41Sopenharmony_ci<li><a href="#event-drain">Event: <code>'drain'</code></a></li> 1441cb0ef41Sopenharmony_ci<li><a href="#event-error">Event: <code>'error'</code></a></li> 1451cb0ef41Sopenharmony_ci<li><a href="#event-finish">Event: <code>'finish'</code></a></li> 1461cb0ef41Sopenharmony_ci<li><a href="#event-pipe">Event: <code>'pipe'</code></a></li> 1471cb0ef41Sopenharmony_ci<li><a href="#event-unpipe">Event: <code>'unpipe'</code></a></li> 1481cb0ef41Sopenharmony_ci<li><a href="#writablecork"><code>writable.cork()</code></a></li> 1491cb0ef41Sopenharmony_ci<li><a href="#writabledestroyerror"><code>writable.destroy([error])</code></a></li> 1501cb0ef41Sopenharmony_ci<li><a href="#writableclosed"><code>writable.closed</code></a></li> 1511cb0ef41Sopenharmony_ci<li><a href="#writabledestroyed"><code>writable.destroyed</code></a></li> 1521cb0ef41Sopenharmony_ci<li><a href="#writableendchunk-encoding-callback"><code>writable.end([chunk[, encoding]][, callback])</code></a></li> 1531cb0ef41Sopenharmony_ci<li><a href="#writablesetdefaultencodingencoding"><code>writable.setDefaultEncoding(encoding)</code></a></li> 1541cb0ef41Sopenharmony_ci<li><a href="#writableuncork"><code>writable.uncork()</code></a></li> 1551cb0ef41Sopenharmony_ci<li><a href="#writablewritable"><code>writable.writable</code></a></li> 1561cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#writablewritableaborted"><code>writable.writableAborted</code></a></span></li> 1571cb0ef41Sopenharmony_ci<li><a href="#writablewritableended"><code>writable.writableEnded</code></a></li> 1581cb0ef41Sopenharmony_ci<li><a href="#writablewritablecorked"><code>writable.writableCorked</code></a></li> 1591cb0ef41Sopenharmony_ci<li><a href="#writableerrored"><code>writable.errored</code></a></li> 1601cb0ef41Sopenharmony_ci<li><a href="#writablewritablefinished"><code>writable.writableFinished</code></a></li> 1611cb0ef41Sopenharmony_ci<li><a href="#writablewritablehighwatermark"><code>writable.writableHighWaterMark</code></a></li> 1621cb0ef41Sopenharmony_ci<li><a href="#writablewritablelength"><code>writable.writableLength</code></a></li> 1631cb0ef41Sopenharmony_ci<li><a href="#writablewritableneeddrain"><code>writable.writableNeedDrain</code></a></li> 1641cb0ef41Sopenharmony_ci<li><a href="#writablewritableobjectmode"><code>writable.writableObjectMode</code></a></li> 1651cb0ef41Sopenharmony_ci<li><a href="#writablewritechunk-encoding-callback"><code>writable.write(chunk[, encoding][, callback])</code></a></li> 1661cb0ef41Sopenharmony_ci</ul> 1671cb0ef41Sopenharmony_ci</li> 1681cb0ef41Sopenharmony_ci</ul> 1691cb0ef41Sopenharmony_ci</li> 1701cb0ef41Sopenharmony_ci<li><a href="#readable-streams">Readable streams</a> 1711cb0ef41Sopenharmony_ci<ul> 1721cb0ef41Sopenharmony_ci<li><a href="#two-reading-modes">Two reading modes</a></li> 1731cb0ef41Sopenharmony_ci<li><a href="#three-states">Three states</a></li> 1741cb0ef41Sopenharmony_ci<li><a href="#choose-one-api-style">Choose one API style</a></li> 1751cb0ef41Sopenharmony_ci<li><a href="#class-streamreadable">Class: <code>stream.Readable</code></a> 1761cb0ef41Sopenharmony_ci<ul> 1771cb0ef41Sopenharmony_ci<li><a href="#event-close_1">Event: <code>'close'</code></a></li> 1781cb0ef41Sopenharmony_ci<li><a href="#event-data">Event: <code>'data'</code></a></li> 1791cb0ef41Sopenharmony_ci<li><a href="#event-end">Event: <code>'end'</code></a></li> 1801cb0ef41Sopenharmony_ci<li><a href="#event-error_1">Event: <code>'error'</code></a></li> 1811cb0ef41Sopenharmony_ci<li><a href="#event-pause">Event: <code>'pause'</code></a></li> 1821cb0ef41Sopenharmony_ci<li><a href="#event-readable">Event: <code>'readable'</code></a></li> 1831cb0ef41Sopenharmony_ci<li><a href="#event-resume">Event: <code>'resume'</code></a></li> 1841cb0ef41Sopenharmony_ci<li><a href="#readabledestroyerror"><code>readable.destroy([error])</code></a></li> 1851cb0ef41Sopenharmony_ci<li><a href="#readableclosed"><code>readable.closed</code></a></li> 1861cb0ef41Sopenharmony_ci<li><a href="#readabledestroyed"><code>readable.destroyed</code></a></li> 1871cb0ef41Sopenharmony_ci<li><a href="#readableispaused"><code>readable.isPaused()</code></a></li> 1881cb0ef41Sopenharmony_ci<li><a href="#readablepause"><code>readable.pause()</code></a></li> 1891cb0ef41Sopenharmony_ci<li><a href="#readablepipedestination-options"><code>readable.pipe(destination[, options])</code></a></li> 1901cb0ef41Sopenharmony_ci<li><a href="#readablereadsize"><code>readable.read([size])</code></a></li> 1911cb0ef41Sopenharmony_ci<li><a href="#readablereadable"><code>readable.readable</code></a></li> 1921cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablereadableaborted"><code>readable.readableAborted</code></a></span></li> 1931cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablereadabledidread"><code>readable.readableDidRead</code></a></span></li> 1941cb0ef41Sopenharmony_ci<li><a href="#readablereadableencoding"><code>readable.readableEncoding</code></a></li> 1951cb0ef41Sopenharmony_ci<li><a href="#readablereadableended"><code>readable.readableEnded</code></a></li> 1961cb0ef41Sopenharmony_ci<li><a href="#readableerrored"><code>readable.errored</code></a></li> 1971cb0ef41Sopenharmony_ci<li><a href="#readablereadableflowing"><code>readable.readableFlowing</code></a></li> 1981cb0ef41Sopenharmony_ci<li><a href="#readablereadablehighwatermark"><code>readable.readableHighWaterMark</code></a></li> 1991cb0ef41Sopenharmony_ci<li><a href="#readablereadablelength"><code>readable.readableLength</code></a></li> 2001cb0ef41Sopenharmony_ci<li><a href="#readablereadableobjectmode"><code>readable.readableObjectMode</code></a></li> 2011cb0ef41Sopenharmony_ci<li><a href="#readableresume"><code>readable.resume()</code></a></li> 2021cb0ef41Sopenharmony_ci<li><a href="#readablesetencodingencoding"><code>readable.setEncoding(encoding)</code></a></li> 2031cb0ef41Sopenharmony_ci<li><a href="#readableunpipedestination"><code>readable.unpipe([destination])</code></a></li> 2041cb0ef41Sopenharmony_ci<li><a href="#readableunshiftchunk-encoding"><code>readable.unshift(chunk[, encoding])</code></a></li> 2051cb0ef41Sopenharmony_ci<li><a href="#readablewrapstream"><code>readable.wrap(stream)</code></a></li> 2061cb0ef41Sopenharmony_ci<li><a href="#readablesymbolasynciterator"><code>readable[Symbol.asyncIterator]()</code></a></li> 2071cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablesymbolasyncdispose"><code>readable[Symbol.asyncDispose]()</code></a></span></li> 2081cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablecomposestream-options"><code>readable.compose(stream[, options])</code></a></span></li> 2091cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readableiteratoroptions"><code>readable.iterator([options])</code></a></span></li> 2101cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablemapfn-options"><code>readable.map(fn[, options])</code></a></span></li> 2111cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablefilterfn-options"><code>readable.filter(fn[, options])</code></a></span></li> 2121cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readableforeachfn-options"><code>readable.forEach(fn[, options])</code></a></span></li> 2131cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readabletoarrayoptions"><code>readable.toArray([options])</code></a></span></li> 2141cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablesomefn-options"><code>readable.some(fn[, options])</code></a></span></li> 2151cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablefindfn-options"><code>readable.find(fn[, options])</code></a></span></li> 2161cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readableeveryfn-options"><code>readable.every(fn[, options])</code></a></span></li> 2171cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readableflatmapfn-options"><code>readable.flatMap(fn[, options])</code></a></span></li> 2181cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readabledroplimit-options"><code>readable.drop(limit[, options])</code></a></span></li> 2191cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readabletakelimit-options"><code>readable.take(limit[, options])</code></a></span></li> 2201cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readableasindexedpairsoptions"><code>readable.asIndexedPairs([options])</code></a></span></li> 2211cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablereducefn-initial-options"><code>readable.reduce(fn[, initial[, options]])</code></a></span></li> 2221cb0ef41Sopenharmony_ci</ul> 2231cb0ef41Sopenharmony_ci</li> 2241cb0ef41Sopenharmony_ci</ul> 2251cb0ef41Sopenharmony_ci</li> 2261cb0ef41Sopenharmony_ci<li><a href="#duplex-and-transform-streams">Duplex and transform streams</a> 2271cb0ef41Sopenharmony_ci<ul> 2281cb0ef41Sopenharmony_ci<li><a href="#class-streamduplex">Class: <code>stream.Duplex</code></a> 2291cb0ef41Sopenharmony_ci<ul> 2301cb0ef41Sopenharmony_ci<li><a href="#duplexallowhalfopen"><code>duplex.allowHalfOpen</code></a></li> 2311cb0ef41Sopenharmony_ci</ul> 2321cb0ef41Sopenharmony_ci</li> 2331cb0ef41Sopenharmony_ci<li><a href="#class-streamtransform">Class: <code>stream.Transform</code></a> 2341cb0ef41Sopenharmony_ci<ul> 2351cb0ef41Sopenharmony_ci<li><a href="#transformdestroyerror"><code>transform.destroy([error])</code></a></li> 2361cb0ef41Sopenharmony_ci</ul> 2371cb0ef41Sopenharmony_ci</li> 2381cb0ef41Sopenharmony_ci</ul> 2391cb0ef41Sopenharmony_ci</li> 2401cb0ef41Sopenharmony_ci<li><a href="#streamfinishedstream-options-callback"><code>stream.finished(stream[, options], callback)</code></a></li> 2411cb0ef41Sopenharmony_ci<li><a href="#streampipelinesource-transforms-destination-callback"><code>stream.pipeline(source[, ...transforms], destination, callback)</code></a></li> 2421cb0ef41Sopenharmony_ci<li><a href="#streampipelinestreams-callback"><code>stream.pipeline(streams, callback)</code></a></li> 2431cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamcomposestreams"><code>stream.compose(...streams)</code></a></span></li> 2441cb0ef41Sopenharmony_ci<li><a href="#streamreadablefromiterable-options"><code>stream.Readable.from(iterable[, options])</code></a></li> 2451cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamreadablefromwebreadablestream-options"><code>stream.Readable.fromWeb(readableStream[, options])</code></a></span></li> 2461cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamreadableisdisturbedstream"><code>stream.Readable.isDisturbed(stream)</code></a></span></li> 2471cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamiserroredstream"><code>stream.isErrored(stream)</code></a></span></li> 2481cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamisreadablestream"><code>stream.isReadable(stream)</code></a></span></li> 2491cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamreadabletowebstreamreadable-options"><code>stream.Readable.toWeb(streamReadable[, options])</code></a></span></li> 2501cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamwritablefromwebwritablestream-options"><code>stream.Writable.fromWeb(writableStream[, options])</code></a></span></li> 2511cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamwritabletowebstreamwritable"><code>stream.Writable.toWeb(streamWritable)</code></a></span></li> 2521cb0ef41Sopenharmony_ci<li><a href="#streamduplexfromsrc"><code>stream.Duplex.from(src)</code></a></li> 2531cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamduplexfromwebpair-options"><code>stream.Duplex.fromWeb(pair[, options])</code></a></span></li> 2541cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamduplextowebstreamduplex"><code>stream.Duplex.toWeb(streamDuplex)</code></a></span></li> 2551cb0ef41Sopenharmony_ci<li><a href="#streamaddabortsignalsignal-stream"><code>stream.addAbortSignal(signal, stream)</code></a></li> 2561cb0ef41Sopenharmony_ci<li><a href="#streamgetdefaulthighwatermarkobjectmode"><code>stream.getDefaultHighWaterMark(objectMode)</code></a></li> 2571cb0ef41Sopenharmony_ci<li><a href="#streamsetdefaulthighwatermarkobjectmode-value"><code>stream.setDefaultHighWaterMark(objectMode, value)</code></a></li> 2581cb0ef41Sopenharmony_ci</ul> 2591cb0ef41Sopenharmony_ci</li> 2601cb0ef41Sopenharmony_ci<li><a href="#api-for-stream-implementers">API for stream implementers</a> 2611cb0ef41Sopenharmony_ci<ul> 2621cb0ef41Sopenharmony_ci<li><a href="#simplified-construction">Simplified construction</a></li> 2631cb0ef41Sopenharmony_ci<li><a href="#implementing-a-writable-stream">Implementing a writable stream</a> 2641cb0ef41Sopenharmony_ci<ul> 2651cb0ef41Sopenharmony_ci<li><a href="#new-streamwritableoptions"><code>new stream.Writable([options])</code></a></li> 2661cb0ef41Sopenharmony_ci<li><a href="#writable_constructcallback"><code>writable._construct(callback)</code></a></li> 2671cb0ef41Sopenharmony_ci<li><a href="#writable_writechunk-encoding-callback"><code>writable._write(chunk, encoding, callback)</code></a></li> 2681cb0ef41Sopenharmony_ci<li><a href="#writable_writevchunks-callback"><code>writable._writev(chunks, callback)</code></a></li> 2691cb0ef41Sopenharmony_ci<li><a href="#writable_destroyerr-callback"><code>writable._destroy(err, callback)</code></a></li> 2701cb0ef41Sopenharmony_ci<li><a href="#writable_finalcallback"><code>writable._final(callback)</code></a></li> 2711cb0ef41Sopenharmony_ci<li><a href="#errors-while-writing">Errors while writing</a></li> 2721cb0ef41Sopenharmony_ci<li><a href="#an-example-writable-stream">An example writable stream</a></li> 2731cb0ef41Sopenharmony_ci<li><a href="#decoding-buffers-in-a-writable-stream">Decoding buffers in a writable stream</a></li> 2741cb0ef41Sopenharmony_ci</ul> 2751cb0ef41Sopenharmony_ci</li> 2761cb0ef41Sopenharmony_ci<li><a href="#implementing-a-readable-stream">Implementing a readable stream</a> 2771cb0ef41Sopenharmony_ci<ul> 2781cb0ef41Sopenharmony_ci<li><a href="#new-streamreadableoptions"><code>new stream.Readable([options])</code></a></li> 2791cb0ef41Sopenharmony_ci<li><a href="#readable_constructcallback"><code>readable._construct(callback)</code></a></li> 2801cb0ef41Sopenharmony_ci<li><a href="#readable_readsize"><code>readable._read(size)</code></a></li> 2811cb0ef41Sopenharmony_ci<li><a href="#readable_destroyerr-callback"><code>readable._destroy(err, callback)</code></a></li> 2821cb0ef41Sopenharmony_ci<li><a href="#readablepushchunk-encoding"><code>readable.push(chunk[, encoding])</code></a></li> 2831cb0ef41Sopenharmony_ci<li><a href="#errors-while-reading">Errors while reading</a></li> 2841cb0ef41Sopenharmony_ci<li><a href="#an-example-counting-stream">An example counting stream</a></li> 2851cb0ef41Sopenharmony_ci</ul> 2861cb0ef41Sopenharmony_ci</li> 2871cb0ef41Sopenharmony_ci<li><a href="#implementing-a-duplex-stream">Implementing a duplex stream</a> 2881cb0ef41Sopenharmony_ci<ul> 2891cb0ef41Sopenharmony_ci<li><a href="#new-streamduplexoptions"><code>new stream.Duplex(options)</code></a></li> 2901cb0ef41Sopenharmony_ci<li><a href="#an-example-duplex-stream">An example duplex stream</a></li> 2911cb0ef41Sopenharmony_ci<li><a href="#object-mode-duplex-streams">Object mode duplex streams</a></li> 2921cb0ef41Sopenharmony_ci</ul> 2931cb0ef41Sopenharmony_ci</li> 2941cb0ef41Sopenharmony_ci<li><a href="#implementing-a-transform-stream">Implementing a transform stream</a> 2951cb0ef41Sopenharmony_ci<ul> 2961cb0ef41Sopenharmony_ci<li><a href="#new-streamtransformoptions"><code>new stream.Transform([options])</code></a></li> 2971cb0ef41Sopenharmony_ci<li><a href="#event-end_1">Event: <code>'end'</code></a></li> 2981cb0ef41Sopenharmony_ci<li><a href="#event-finish_1">Event: <code>'finish'</code></a></li> 2991cb0ef41Sopenharmony_ci<li><a href="#transform_flushcallback"><code>transform._flush(callback)</code></a></li> 3001cb0ef41Sopenharmony_ci<li><a href="#transform_transformchunk-encoding-callback"><code>transform._transform(chunk, encoding, callback)</code></a></li> 3011cb0ef41Sopenharmony_ci<li><a href="#class-streampassthrough">Class: <code>stream.PassThrough</code></a></li> 3021cb0ef41Sopenharmony_ci</ul> 3031cb0ef41Sopenharmony_ci</li> 3041cb0ef41Sopenharmony_ci</ul> 3051cb0ef41Sopenharmony_ci</li> 3061cb0ef41Sopenharmony_ci<li><a href="#additional-notes">Additional notes</a> 3071cb0ef41Sopenharmony_ci<ul> 3081cb0ef41Sopenharmony_ci<li><a href="#streams-compatibility-with-async-generators-and-async-iterators">Streams compatibility with async generators and async iterators</a> 3091cb0ef41Sopenharmony_ci<ul> 3101cb0ef41Sopenharmony_ci<li><a href="#consuming-readable-streams-with-async-iterators">Consuming readable streams with async iterators</a></li> 3111cb0ef41Sopenharmony_ci<li><a href="#creating-readable-streams-with-async-generators">Creating readable streams with async generators</a></li> 3121cb0ef41Sopenharmony_ci<li><a href="#piping-to-writable-streams-from-async-iterators">Piping to writable streams from async iterators</a></li> 3131cb0ef41Sopenharmony_ci</ul> 3141cb0ef41Sopenharmony_ci</li> 3151cb0ef41Sopenharmony_ci<li><a href="#compatibility-with-older-nodejs-versions">Compatibility with older Node.js versions</a></li> 3161cb0ef41Sopenharmony_ci<li><a href="#readableread0"><code>readable.read(0)</code></a></li> 3171cb0ef41Sopenharmony_ci<li><a href="#readablepush"><code>readable.push('')</code></a></li> 3181cb0ef41Sopenharmony_ci<li><a href="#highwatermark-discrepancy-after-calling-readablesetencoding"><code>highWaterMark</code> discrepancy after calling <code>readable.setEncoding()</code></a></li> 3191cb0ef41Sopenharmony_ci</ul> 3201cb0ef41Sopenharmony_ci</li> 3211cb0ef41Sopenharmony_ci</ul> 3221cb0ef41Sopenharmony_ci</li> 3231cb0ef41Sopenharmony_ci</ul></div></div> 3241cb0ef41Sopenharmony_ci </li> 3251cb0ef41Sopenharmony_ci 3261cb0ef41Sopenharmony_ci 3271cb0ef41Sopenharmony_ci <li class="picker-header"> 3281cb0ef41Sopenharmony_ci <a href="#"> 3291cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 3301cb0ef41Sopenharmony_ci Index 3311cb0ef41Sopenharmony_ci </a> 3321cb0ef41Sopenharmony_ci 3331cb0ef41Sopenharmony_ci <div class="picker"><ul> 3341cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 3351cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 3361cb0ef41Sopenharmony_ci 3371cb0ef41Sopenharmony_ci <li> 3381cb0ef41Sopenharmony_ci <a href="index.html">Index</a> 3391cb0ef41Sopenharmony_ci </li> 3401cb0ef41Sopenharmony_ci </ul> 3411cb0ef41Sopenharmony_ci 3421cb0ef41Sopenharmony_ci<hr class="line"> 3431cb0ef41Sopenharmony_ci<ul> 3441cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 3451cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 3461cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 3471cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 3481cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 3491cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 3501cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 3511cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 3521cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 3531cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 3541cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 3551cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 3561cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 3571cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 3581cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 3591cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 3601cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 3611cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 3621cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 3631cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 3641cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 3651cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 3661cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 3671cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 3681cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 3691cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 3701cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 3711cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 3721cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 3731cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 3741cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li> 3751cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 3761cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 3771cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 3781cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 3791cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 3801cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 3811cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 3821cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 3831cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 3841cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 3851cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 3861cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 3871cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream active">Stream</a></li> 3881cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 3891cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 3901cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 3911cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 3921cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 3931cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 3941cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 3951cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 3961cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 3971cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 3981cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 3991cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 4001cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 4011cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 4021cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 4031cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 4041cb0ef41Sopenharmony_ci</ul> 4051cb0ef41Sopenharmony_ci<hr class="line"> 4061cb0ef41Sopenharmony_ci<ul> 4071cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 4081cb0ef41Sopenharmony_ci</ul></div> 4091cb0ef41Sopenharmony_ci </li> 4101cb0ef41Sopenharmony_ci 4111cb0ef41Sopenharmony_ci 4121cb0ef41Sopenharmony_ci <li class="picker-header"> 4131cb0ef41Sopenharmony_ci <a href="#"> 4141cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 4151cb0ef41Sopenharmony_ci Other versions 4161cb0ef41Sopenharmony_ci </a> 4171cb0ef41Sopenharmony_ci <div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v21.x/api/stream.html">21.x</a></li> 4181cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v20.x/api/stream.html">20.x <b>LTS</b></a></li> 4191cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v19.x/api/stream.html">19.x</a></li> 4201cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v18.x/api/stream.html">18.x <b>LTS</b></a></li> 4211cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v17.x/api/stream.html">17.x</a></li> 4221cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v16.x/api/stream.html">16.x</a></li> 4231cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v15.x/api/stream.html">15.x</a></li> 4241cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v14.x/api/stream.html">14.x</a></li> 4251cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v13.x/api/stream.html">13.x</a></li> 4261cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v12.x/api/stream.html">12.x</a></li> 4271cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v11.x/api/stream.html">11.x</a></li> 4281cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v10.x/api/stream.html">10.x</a></li> 4291cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v9.x/api/stream.html">9.x</a></li> 4301cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v8.x/api/stream.html">8.x</a></li> 4311cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v7.x/api/stream.html">7.x</a></li> 4321cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v6.x/api/stream.html">6.x</a></li> 4331cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v5.x/api/stream.html">5.x</a></li> 4341cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v4.x/api/stream.html">4.x</a></li> 4351cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/stream.html">0.12.x</a></li> 4361cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/stream.html">0.10.x</a></li></ol></div> 4371cb0ef41Sopenharmony_ci </li> 4381cb0ef41Sopenharmony_ci 4391cb0ef41Sopenharmony_ci <li class="picker-header"> 4401cb0ef41Sopenharmony_ci <a href="#"> 4411cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 4421cb0ef41Sopenharmony_ci Options 4431cb0ef41Sopenharmony_ci </a> 4441cb0ef41Sopenharmony_ci 4451cb0ef41Sopenharmony_ci <div class="picker"> 4461cb0ef41Sopenharmony_ci <ul> 4471cb0ef41Sopenharmony_ci <li> 4481cb0ef41Sopenharmony_ci <a href="all.html">View on single page</a> 4491cb0ef41Sopenharmony_ci </li> 4501cb0ef41Sopenharmony_ci <li> 4511cb0ef41Sopenharmony_ci <a href="stream.json">View as JSON</a> 4521cb0ef41Sopenharmony_ci </li> 4531cb0ef41Sopenharmony_ci <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/stream.md">Edit on GitHub</a></li> 4541cb0ef41Sopenharmony_ci </ul> 4551cb0ef41Sopenharmony_ci </div> 4561cb0ef41Sopenharmony_ci </li> 4571cb0ef41Sopenharmony_ci </ul> 4581cb0ef41Sopenharmony_ci </div> 4591cb0ef41Sopenharmony_ci <hr> 4601cb0ef41Sopenharmony_ci </header> 4611cb0ef41Sopenharmony_ci 4621cb0ef41Sopenharmony_ci <details id="toc" open><summary>Table of contents</summary><ul> 4631cb0ef41Sopenharmony_ci<li><span class="stability_2"><a href="#stream">Stream</a></span> 4641cb0ef41Sopenharmony_ci<ul> 4651cb0ef41Sopenharmony_ci<li><a href="#organization-of-this-document">Organization of this document</a></li> 4661cb0ef41Sopenharmony_ci<li><a href="#types-of-streams">Types of streams</a> 4671cb0ef41Sopenharmony_ci<ul> 4681cb0ef41Sopenharmony_ci<li><a href="#streams-promises-api">Streams Promises API</a></li> 4691cb0ef41Sopenharmony_ci<li><a href="#streampipelinesource-transforms-destination-options"><code>stream.pipeline(source[, ...transforms], destination[, options])</code></a></li> 4701cb0ef41Sopenharmony_ci<li><a href="#streampipelinestreams-options"><code>stream.pipeline(streams[, options])</code></a></li> 4711cb0ef41Sopenharmony_ci<li><a href="#streamfinishedstream-options"><code>stream.finished(stream[, options])</code></a></li> 4721cb0ef41Sopenharmony_ci<li><a href="#object-mode">Object mode</a></li> 4731cb0ef41Sopenharmony_ci<li><a href="#buffering">Buffering</a></li> 4741cb0ef41Sopenharmony_ci</ul> 4751cb0ef41Sopenharmony_ci</li> 4761cb0ef41Sopenharmony_ci<li><a href="#api-for-stream-consumers">API for stream consumers</a> 4771cb0ef41Sopenharmony_ci<ul> 4781cb0ef41Sopenharmony_ci<li><a href="#writable-streams">Writable streams</a> 4791cb0ef41Sopenharmony_ci<ul> 4801cb0ef41Sopenharmony_ci<li><a href="#class-streamwritable">Class: <code>stream.Writable</code></a> 4811cb0ef41Sopenharmony_ci<ul> 4821cb0ef41Sopenharmony_ci<li><a href="#event-close">Event: <code>'close'</code></a></li> 4831cb0ef41Sopenharmony_ci<li><a href="#event-drain">Event: <code>'drain'</code></a></li> 4841cb0ef41Sopenharmony_ci<li><a href="#event-error">Event: <code>'error'</code></a></li> 4851cb0ef41Sopenharmony_ci<li><a href="#event-finish">Event: <code>'finish'</code></a></li> 4861cb0ef41Sopenharmony_ci<li><a href="#event-pipe">Event: <code>'pipe'</code></a></li> 4871cb0ef41Sopenharmony_ci<li><a href="#event-unpipe">Event: <code>'unpipe'</code></a></li> 4881cb0ef41Sopenharmony_ci<li><a href="#writablecork"><code>writable.cork()</code></a></li> 4891cb0ef41Sopenharmony_ci<li><a href="#writabledestroyerror"><code>writable.destroy([error])</code></a></li> 4901cb0ef41Sopenharmony_ci<li><a href="#writableclosed"><code>writable.closed</code></a></li> 4911cb0ef41Sopenharmony_ci<li><a href="#writabledestroyed"><code>writable.destroyed</code></a></li> 4921cb0ef41Sopenharmony_ci<li><a href="#writableendchunk-encoding-callback"><code>writable.end([chunk[, encoding]][, callback])</code></a></li> 4931cb0ef41Sopenharmony_ci<li><a href="#writablesetdefaultencodingencoding"><code>writable.setDefaultEncoding(encoding)</code></a></li> 4941cb0ef41Sopenharmony_ci<li><a href="#writableuncork"><code>writable.uncork()</code></a></li> 4951cb0ef41Sopenharmony_ci<li><a href="#writablewritable"><code>writable.writable</code></a></li> 4961cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#writablewritableaborted"><code>writable.writableAborted</code></a></span></li> 4971cb0ef41Sopenharmony_ci<li><a href="#writablewritableended"><code>writable.writableEnded</code></a></li> 4981cb0ef41Sopenharmony_ci<li><a href="#writablewritablecorked"><code>writable.writableCorked</code></a></li> 4991cb0ef41Sopenharmony_ci<li><a href="#writableerrored"><code>writable.errored</code></a></li> 5001cb0ef41Sopenharmony_ci<li><a href="#writablewritablefinished"><code>writable.writableFinished</code></a></li> 5011cb0ef41Sopenharmony_ci<li><a href="#writablewritablehighwatermark"><code>writable.writableHighWaterMark</code></a></li> 5021cb0ef41Sopenharmony_ci<li><a href="#writablewritablelength"><code>writable.writableLength</code></a></li> 5031cb0ef41Sopenharmony_ci<li><a href="#writablewritableneeddrain"><code>writable.writableNeedDrain</code></a></li> 5041cb0ef41Sopenharmony_ci<li><a href="#writablewritableobjectmode"><code>writable.writableObjectMode</code></a></li> 5051cb0ef41Sopenharmony_ci<li><a href="#writablewritechunk-encoding-callback"><code>writable.write(chunk[, encoding][, callback])</code></a></li> 5061cb0ef41Sopenharmony_ci</ul> 5071cb0ef41Sopenharmony_ci</li> 5081cb0ef41Sopenharmony_ci</ul> 5091cb0ef41Sopenharmony_ci</li> 5101cb0ef41Sopenharmony_ci<li><a href="#readable-streams">Readable streams</a> 5111cb0ef41Sopenharmony_ci<ul> 5121cb0ef41Sopenharmony_ci<li><a href="#two-reading-modes">Two reading modes</a></li> 5131cb0ef41Sopenharmony_ci<li><a href="#three-states">Three states</a></li> 5141cb0ef41Sopenharmony_ci<li><a href="#choose-one-api-style">Choose one API style</a></li> 5151cb0ef41Sopenharmony_ci<li><a href="#class-streamreadable">Class: <code>stream.Readable</code></a> 5161cb0ef41Sopenharmony_ci<ul> 5171cb0ef41Sopenharmony_ci<li><a href="#event-close_1">Event: <code>'close'</code></a></li> 5181cb0ef41Sopenharmony_ci<li><a href="#event-data">Event: <code>'data'</code></a></li> 5191cb0ef41Sopenharmony_ci<li><a href="#event-end">Event: <code>'end'</code></a></li> 5201cb0ef41Sopenharmony_ci<li><a href="#event-error_1">Event: <code>'error'</code></a></li> 5211cb0ef41Sopenharmony_ci<li><a href="#event-pause">Event: <code>'pause'</code></a></li> 5221cb0ef41Sopenharmony_ci<li><a href="#event-readable">Event: <code>'readable'</code></a></li> 5231cb0ef41Sopenharmony_ci<li><a href="#event-resume">Event: <code>'resume'</code></a></li> 5241cb0ef41Sopenharmony_ci<li><a href="#readabledestroyerror"><code>readable.destroy([error])</code></a></li> 5251cb0ef41Sopenharmony_ci<li><a href="#readableclosed"><code>readable.closed</code></a></li> 5261cb0ef41Sopenharmony_ci<li><a href="#readabledestroyed"><code>readable.destroyed</code></a></li> 5271cb0ef41Sopenharmony_ci<li><a href="#readableispaused"><code>readable.isPaused()</code></a></li> 5281cb0ef41Sopenharmony_ci<li><a href="#readablepause"><code>readable.pause()</code></a></li> 5291cb0ef41Sopenharmony_ci<li><a href="#readablepipedestination-options"><code>readable.pipe(destination[, options])</code></a></li> 5301cb0ef41Sopenharmony_ci<li><a href="#readablereadsize"><code>readable.read([size])</code></a></li> 5311cb0ef41Sopenharmony_ci<li><a href="#readablereadable"><code>readable.readable</code></a></li> 5321cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablereadableaborted"><code>readable.readableAborted</code></a></span></li> 5331cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablereadabledidread"><code>readable.readableDidRead</code></a></span></li> 5341cb0ef41Sopenharmony_ci<li><a href="#readablereadableencoding"><code>readable.readableEncoding</code></a></li> 5351cb0ef41Sopenharmony_ci<li><a href="#readablereadableended"><code>readable.readableEnded</code></a></li> 5361cb0ef41Sopenharmony_ci<li><a href="#readableerrored"><code>readable.errored</code></a></li> 5371cb0ef41Sopenharmony_ci<li><a href="#readablereadableflowing"><code>readable.readableFlowing</code></a></li> 5381cb0ef41Sopenharmony_ci<li><a href="#readablereadablehighwatermark"><code>readable.readableHighWaterMark</code></a></li> 5391cb0ef41Sopenharmony_ci<li><a href="#readablereadablelength"><code>readable.readableLength</code></a></li> 5401cb0ef41Sopenharmony_ci<li><a href="#readablereadableobjectmode"><code>readable.readableObjectMode</code></a></li> 5411cb0ef41Sopenharmony_ci<li><a href="#readableresume"><code>readable.resume()</code></a></li> 5421cb0ef41Sopenharmony_ci<li><a href="#readablesetencodingencoding"><code>readable.setEncoding(encoding)</code></a></li> 5431cb0ef41Sopenharmony_ci<li><a href="#readableunpipedestination"><code>readable.unpipe([destination])</code></a></li> 5441cb0ef41Sopenharmony_ci<li><a href="#readableunshiftchunk-encoding"><code>readable.unshift(chunk[, encoding])</code></a></li> 5451cb0ef41Sopenharmony_ci<li><a href="#readablewrapstream"><code>readable.wrap(stream)</code></a></li> 5461cb0ef41Sopenharmony_ci<li><a href="#readablesymbolasynciterator"><code>readable[Symbol.asyncIterator]()</code></a></li> 5471cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablesymbolasyncdispose"><code>readable[Symbol.asyncDispose]()</code></a></span></li> 5481cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablecomposestream-options"><code>readable.compose(stream[, options])</code></a></span></li> 5491cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readableiteratoroptions"><code>readable.iterator([options])</code></a></span></li> 5501cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablemapfn-options"><code>readable.map(fn[, options])</code></a></span></li> 5511cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablefilterfn-options"><code>readable.filter(fn[, options])</code></a></span></li> 5521cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readableforeachfn-options"><code>readable.forEach(fn[, options])</code></a></span></li> 5531cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readabletoarrayoptions"><code>readable.toArray([options])</code></a></span></li> 5541cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablesomefn-options"><code>readable.some(fn[, options])</code></a></span></li> 5551cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablefindfn-options"><code>readable.find(fn[, options])</code></a></span></li> 5561cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readableeveryfn-options"><code>readable.every(fn[, options])</code></a></span></li> 5571cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readableflatmapfn-options"><code>readable.flatMap(fn[, options])</code></a></span></li> 5581cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readabledroplimit-options"><code>readable.drop(limit[, options])</code></a></span></li> 5591cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readabletakelimit-options"><code>readable.take(limit[, options])</code></a></span></li> 5601cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readableasindexedpairsoptions"><code>readable.asIndexedPairs([options])</code></a></span></li> 5611cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#readablereducefn-initial-options"><code>readable.reduce(fn[, initial[, options]])</code></a></span></li> 5621cb0ef41Sopenharmony_ci</ul> 5631cb0ef41Sopenharmony_ci</li> 5641cb0ef41Sopenharmony_ci</ul> 5651cb0ef41Sopenharmony_ci</li> 5661cb0ef41Sopenharmony_ci<li><a href="#duplex-and-transform-streams">Duplex and transform streams</a> 5671cb0ef41Sopenharmony_ci<ul> 5681cb0ef41Sopenharmony_ci<li><a href="#class-streamduplex">Class: <code>stream.Duplex</code></a> 5691cb0ef41Sopenharmony_ci<ul> 5701cb0ef41Sopenharmony_ci<li><a href="#duplexallowhalfopen"><code>duplex.allowHalfOpen</code></a></li> 5711cb0ef41Sopenharmony_ci</ul> 5721cb0ef41Sopenharmony_ci</li> 5731cb0ef41Sopenharmony_ci<li><a href="#class-streamtransform">Class: <code>stream.Transform</code></a> 5741cb0ef41Sopenharmony_ci<ul> 5751cb0ef41Sopenharmony_ci<li><a href="#transformdestroyerror"><code>transform.destroy([error])</code></a></li> 5761cb0ef41Sopenharmony_ci</ul> 5771cb0ef41Sopenharmony_ci</li> 5781cb0ef41Sopenharmony_ci</ul> 5791cb0ef41Sopenharmony_ci</li> 5801cb0ef41Sopenharmony_ci<li><a href="#streamfinishedstream-options-callback"><code>stream.finished(stream[, options], callback)</code></a></li> 5811cb0ef41Sopenharmony_ci<li><a href="#streampipelinesource-transforms-destination-callback"><code>stream.pipeline(source[, ...transforms], destination, callback)</code></a></li> 5821cb0ef41Sopenharmony_ci<li><a href="#streampipelinestreams-callback"><code>stream.pipeline(streams, callback)</code></a></li> 5831cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamcomposestreams"><code>stream.compose(...streams)</code></a></span></li> 5841cb0ef41Sopenharmony_ci<li><a href="#streamreadablefromiterable-options"><code>stream.Readable.from(iterable[, options])</code></a></li> 5851cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamreadablefromwebreadablestream-options"><code>stream.Readable.fromWeb(readableStream[, options])</code></a></span></li> 5861cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamreadableisdisturbedstream"><code>stream.Readable.isDisturbed(stream)</code></a></span></li> 5871cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamiserroredstream"><code>stream.isErrored(stream)</code></a></span></li> 5881cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamisreadablestream"><code>stream.isReadable(stream)</code></a></span></li> 5891cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamreadabletowebstreamreadable-options"><code>stream.Readable.toWeb(streamReadable[, options])</code></a></span></li> 5901cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamwritablefromwebwritablestream-options"><code>stream.Writable.fromWeb(writableStream[, options])</code></a></span></li> 5911cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamwritabletowebstreamwritable"><code>stream.Writable.toWeb(streamWritable)</code></a></span></li> 5921cb0ef41Sopenharmony_ci<li><a href="#streamduplexfromsrc"><code>stream.Duplex.from(src)</code></a></li> 5931cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamduplexfromwebpair-options"><code>stream.Duplex.fromWeb(pair[, options])</code></a></span></li> 5941cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#streamduplextowebstreamduplex"><code>stream.Duplex.toWeb(streamDuplex)</code></a></span></li> 5951cb0ef41Sopenharmony_ci<li><a href="#streamaddabortsignalsignal-stream"><code>stream.addAbortSignal(signal, stream)</code></a></li> 5961cb0ef41Sopenharmony_ci<li><a href="#streamgetdefaulthighwatermarkobjectmode"><code>stream.getDefaultHighWaterMark(objectMode)</code></a></li> 5971cb0ef41Sopenharmony_ci<li><a href="#streamsetdefaulthighwatermarkobjectmode-value"><code>stream.setDefaultHighWaterMark(objectMode, value)</code></a></li> 5981cb0ef41Sopenharmony_ci</ul> 5991cb0ef41Sopenharmony_ci</li> 6001cb0ef41Sopenharmony_ci<li><a href="#api-for-stream-implementers">API for stream implementers</a> 6011cb0ef41Sopenharmony_ci<ul> 6021cb0ef41Sopenharmony_ci<li><a href="#simplified-construction">Simplified construction</a></li> 6031cb0ef41Sopenharmony_ci<li><a href="#implementing-a-writable-stream">Implementing a writable stream</a> 6041cb0ef41Sopenharmony_ci<ul> 6051cb0ef41Sopenharmony_ci<li><a href="#new-streamwritableoptions"><code>new stream.Writable([options])</code></a></li> 6061cb0ef41Sopenharmony_ci<li><a href="#writable_constructcallback"><code>writable._construct(callback)</code></a></li> 6071cb0ef41Sopenharmony_ci<li><a href="#writable_writechunk-encoding-callback"><code>writable._write(chunk, encoding, callback)</code></a></li> 6081cb0ef41Sopenharmony_ci<li><a href="#writable_writevchunks-callback"><code>writable._writev(chunks, callback)</code></a></li> 6091cb0ef41Sopenharmony_ci<li><a href="#writable_destroyerr-callback"><code>writable._destroy(err, callback)</code></a></li> 6101cb0ef41Sopenharmony_ci<li><a href="#writable_finalcallback"><code>writable._final(callback)</code></a></li> 6111cb0ef41Sopenharmony_ci<li><a href="#errors-while-writing">Errors while writing</a></li> 6121cb0ef41Sopenharmony_ci<li><a href="#an-example-writable-stream">An example writable stream</a></li> 6131cb0ef41Sopenharmony_ci<li><a href="#decoding-buffers-in-a-writable-stream">Decoding buffers in a writable stream</a></li> 6141cb0ef41Sopenharmony_ci</ul> 6151cb0ef41Sopenharmony_ci</li> 6161cb0ef41Sopenharmony_ci<li><a href="#implementing-a-readable-stream">Implementing a readable stream</a> 6171cb0ef41Sopenharmony_ci<ul> 6181cb0ef41Sopenharmony_ci<li><a href="#new-streamreadableoptions"><code>new stream.Readable([options])</code></a></li> 6191cb0ef41Sopenharmony_ci<li><a href="#readable_constructcallback"><code>readable._construct(callback)</code></a></li> 6201cb0ef41Sopenharmony_ci<li><a href="#readable_readsize"><code>readable._read(size)</code></a></li> 6211cb0ef41Sopenharmony_ci<li><a href="#readable_destroyerr-callback"><code>readable._destroy(err, callback)</code></a></li> 6221cb0ef41Sopenharmony_ci<li><a href="#readablepushchunk-encoding"><code>readable.push(chunk[, encoding])</code></a></li> 6231cb0ef41Sopenharmony_ci<li><a href="#errors-while-reading">Errors while reading</a></li> 6241cb0ef41Sopenharmony_ci<li><a href="#an-example-counting-stream">An example counting stream</a></li> 6251cb0ef41Sopenharmony_ci</ul> 6261cb0ef41Sopenharmony_ci</li> 6271cb0ef41Sopenharmony_ci<li><a href="#implementing-a-duplex-stream">Implementing a duplex stream</a> 6281cb0ef41Sopenharmony_ci<ul> 6291cb0ef41Sopenharmony_ci<li><a href="#new-streamduplexoptions"><code>new stream.Duplex(options)</code></a></li> 6301cb0ef41Sopenharmony_ci<li><a href="#an-example-duplex-stream">An example duplex stream</a></li> 6311cb0ef41Sopenharmony_ci<li><a href="#object-mode-duplex-streams">Object mode duplex streams</a></li> 6321cb0ef41Sopenharmony_ci</ul> 6331cb0ef41Sopenharmony_ci</li> 6341cb0ef41Sopenharmony_ci<li><a href="#implementing-a-transform-stream">Implementing a transform stream</a> 6351cb0ef41Sopenharmony_ci<ul> 6361cb0ef41Sopenharmony_ci<li><a href="#new-streamtransformoptions"><code>new stream.Transform([options])</code></a></li> 6371cb0ef41Sopenharmony_ci<li><a href="#event-end_1">Event: <code>'end'</code></a></li> 6381cb0ef41Sopenharmony_ci<li><a href="#event-finish_1">Event: <code>'finish'</code></a></li> 6391cb0ef41Sopenharmony_ci<li><a href="#transform_flushcallback"><code>transform._flush(callback)</code></a></li> 6401cb0ef41Sopenharmony_ci<li><a href="#transform_transformchunk-encoding-callback"><code>transform._transform(chunk, encoding, callback)</code></a></li> 6411cb0ef41Sopenharmony_ci<li><a href="#class-streampassthrough">Class: <code>stream.PassThrough</code></a></li> 6421cb0ef41Sopenharmony_ci</ul> 6431cb0ef41Sopenharmony_ci</li> 6441cb0ef41Sopenharmony_ci</ul> 6451cb0ef41Sopenharmony_ci</li> 6461cb0ef41Sopenharmony_ci<li><a href="#additional-notes">Additional notes</a> 6471cb0ef41Sopenharmony_ci<ul> 6481cb0ef41Sopenharmony_ci<li><a href="#streams-compatibility-with-async-generators-and-async-iterators">Streams compatibility with async generators and async iterators</a> 6491cb0ef41Sopenharmony_ci<ul> 6501cb0ef41Sopenharmony_ci<li><a href="#consuming-readable-streams-with-async-iterators">Consuming readable streams with async iterators</a></li> 6511cb0ef41Sopenharmony_ci<li><a href="#creating-readable-streams-with-async-generators">Creating readable streams with async generators</a></li> 6521cb0ef41Sopenharmony_ci<li><a href="#piping-to-writable-streams-from-async-iterators">Piping to writable streams from async iterators</a></li> 6531cb0ef41Sopenharmony_ci</ul> 6541cb0ef41Sopenharmony_ci</li> 6551cb0ef41Sopenharmony_ci<li><a href="#compatibility-with-older-nodejs-versions">Compatibility with older Node.js versions</a></li> 6561cb0ef41Sopenharmony_ci<li><a href="#readableread0"><code>readable.read(0)</code></a></li> 6571cb0ef41Sopenharmony_ci<li><a href="#readablepush"><code>readable.push('')</code></a></li> 6581cb0ef41Sopenharmony_ci<li><a href="#highwatermark-discrepancy-after-calling-readablesetencoding"><code>highWaterMark</code> discrepancy after calling <code>readable.setEncoding()</code></a></li> 6591cb0ef41Sopenharmony_ci</ul> 6601cb0ef41Sopenharmony_ci</li> 6611cb0ef41Sopenharmony_ci</ul> 6621cb0ef41Sopenharmony_ci</li> 6631cb0ef41Sopenharmony_ci</ul></details> 6641cb0ef41Sopenharmony_ci 6651cb0ef41Sopenharmony_ci <div id="apicontent"> 6661cb0ef41Sopenharmony_ci <h2>Stream<a class="srclink" href="https://github.com/nodejs/node/blob/1d526a47af29d59ad196c4e05606b0ec6f8090d9/lib/stream.js#L54">[src]</a><span><a class="mark" href="#stream" id="stream">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream"></a></h2> 6671cb0ef41Sopenharmony_ci 6681cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_2"><a href="documentation.html#stability-index">Stability: 2</a> - Stable</div><p></p> 6691cb0ef41Sopenharmony_ci<p><strong>Source Code:</strong> <a href="https://github.com/nodejs/node/blob/v18.20.1/lib/stream.js">lib/stream.js</a></p> 6701cb0ef41Sopenharmony_ci<p>A stream is an abstract interface for working with streaming data in Node.js. 6711cb0ef41Sopenharmony_ciThe <code>node:stream</code> module provides an API for implementing the stream interface.</p> 6721cb0ef41Sopenharmony_ci<p>There are many stream objects provided by Node.js. For instance, a 6731cb0ef41Sopenharmony_ci<a href="http.html#class-httpincomingmessage">request to an HTTP server</a> and <a href="process.html#processstdout"><code>process.stdout</code></a> 6741cb0ef41Sopenharmony_ciare both stream instances.</p> 6751cb0ef41Sopenharmony_ci<p>Streams can be readable, writable, or both. All streams are instances of 6761cb0ef41Sopenharmony_ci<a href="events.html#class-eventemitter"><code>EventEmitter</code></a>.</p> 6771cb0ef41Sopenharmony_ci<p>To access the <code>node:stream</code> module:</p> 6781cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> stream = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>);</code> <button class="copy-button">copy</button></pre> 6791cb0ef41Sopenharmony_ci<p>The <code>node:stream</code> module is useful for creating new types of stream instances. 6801cb0ef41Sopenharmony_ciIt is usually not necessary to use the <code>node:stream</code> module to consume streams.</p> 6811cb0ef41Sopenharmony_ci<section><h3>Organization of this document<span><a class="mark" href="#organization-of-this-document" id="organization-of-this-document">#</a></span><a aria-hidden="true" class="legacy" id="stream_organization_of_this_document"></a></h3> 6821cb0ef41Sopenharmony_ci<p>This document contains two primary sections and a third section for notes. The 6831cb0ef41Sopenharmony_cifirst section explains how to use existing streams within an application. The 6841cb0ef41Sopenharmony_cisecond section explains how to create new types of streams.</p> 6851cb0ef41Sopenharmony_ci</section><section><h3>Types of streams<span><a class="mark" href="#types-of-streams" id="types-of-streams">#</a></span><a aria-hidden="true" class="legacy" id="stream_types_of_streams"></a></h3> 6861cb0ef41Sopenharmony_ci<p>There are four fundamental stream types within Node.js:</p> 6871cb0ef41Sopenharmony_ci<ul> 6881cb0ef41Sopenharmony_ci<li><a href="#class-streamwritable"><code>Writable</code></a>: streams to which data can be written (for example, 6891cb0ef41Sopenharmony_ci<a href="fs.html#fscreatewritestreampath-options"><code>fs.createWriteStream()</code></a>).</li> 6901cb0ef41Sopenharmony_ci<li><a href="#class-streamreadable"><code>Readable</code></a>: streams from which data can be read (for example, 6911cb0ef41Sopenharmony_ci<a href="fs.html#fscreatereadstreampath-options"><code>fs.createReadStream()</code></a>).</li> 6921cb0ef41Sopenharmony_ci<li><a href="#class-streamduplex"><code>Duplex</code></a>: streams that are both <code>Readable</code> and <code>Writable</code> (for example, 6931cb0ef41Sopenharmony_ci<a href="net.html#class-netsocket"><code>net.Socket</code></a>).</li> 6941cb0ef41Sopenharmony_ci<li><a href="#class-streamtransform"><code>Transform</code></a>: <code>Duplex</code> streams that can modify or transform the data as it 6951cb0ef41Sopenharmony_ciis written and read (for example, <a href="zlib.html#zlibcreatedeflateoptions"><code>zlib.createDeflate()</code></a>).</li> 6961cb0ef41Sopenharmony_ci</ul> 6971cb0ef41Sopenharmony_ci<p>Additionally, this module includes the utility functions 6981cb0ef41Sopenharmony_ci<a href="#streampipelinesource-transforms-destination-callback"><code>stream.pipeline()</code></a>, <a href="#streamfinishedstream-options-callback"><code>stream.finished()</code></a>, <a href="#streamreadablefromiterable-options"><code>stream.Readable.from()</code></a> 6991cb0ef41Sopenharmony_ciand <a href="#streamaddabortsignalsignal-stream"><code>stream.addAbortSignal()</code></a>.</p> 7001cb0ef41Sopenharmony_ci<h4>Streams Promises API<span><a class="mark" href="#streams-promises-api" id="streams-promises-api">#</a></span><a aria-hidden="true" class="legacy" id="stream_streams_promises_api"></a></h4> 7011cb0ef41Sopenharmony_ci<div class="api_metadata"> 7021cb0ef41Sopenharmony_ci<span>Added in: v15.0.0</span> 7031cb0ef41Sopenharmony_ci</div> 7041cb0ef41Sopenharmony_ci<p>The <code>stream/promises</code> API provides an alternative set of asynchronous utility 7051cb0ef41Sopenharmony_cifunctions for streams that return <code>Promise</code> objects rather than using 7061cb0ef41Sopenharmony_cicallbacks. The API is accessible via <code>require('node:stream/promises')</code> 7071cb0ef41Sopenharmony_cior <code>require('node:stream').promises</code>.</p> 7081cb0ef41Sopenharmony_ci<h4><code>stream.pipeline(source[, ...transforms], destination[, options])</code><span><a class="mark" href="#streampipelinesource-transforms-destination-options" id="streampipelinesource-transforms-destination-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_pipeline_source_transforms_destination_options"></a></h4> 7091cb0ef41Sopenharmony_ci<h4><code>stream.pipeline(streams[, options])</code><span><a class="mark" href="#streampipelinestreams-options" id="streampipelinestreams-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_pipeline_streams_options"></a></h4> 7101cb0ef41Sopenharmony_ci<div class="api_metadata"> 7111cb0ef41Sopenharmony_ci<span>Added in: v15.0.0</span> 7121cb0ef41Sopenharmony_ci</div> 7131cb0ef41Sopenharmony_ci<ul> 7141cb0ef41Sopenharmony_ci<li><code>streams</code> <a href="stream.html#stream" class="type"><Stream[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable[]></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function[]></a></li> 7151cb0ef41Sopenharmony_ci<li><code>source</code> <a href="stream.html#stream" class="type"><Stream></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 7161cb0ef41Sopenharmony_ci<ul> 7171cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a></li> 7181cb0ef41Sopenharmony_ci</ul> 7191cb0ef41Sopenharmony_ci</li> 7201cb0ef41Sopenharmony_ci<li><code>...transforms</code> <a href="stream.html#stream" class="type"><Stream></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 7211cb0ef41Sopenharmony_ci<ul> 7221cb0ef41Sopenharmony_ci<li><code>source</code> <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a></li> 7231cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a></li> 7241cb0ef41Sopenharmony_ci</ul> 7251cb0ef41Sopenharmony_ci</li> 7261cb0ef41Sopenharmony_ci<li><code>destination</code> <a href="stream.html#stream" class="type"><Stream></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> 7271cb0ef41Sopenharmony_ci<ul> 7281cb0ef41Sopenharmony_ci<li><code>source</code> <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a></li> 7291cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a></li> 7301cb0ef41Sopenharmony_ci</ul> 7311cb0ef41Sopenharmony_ci</li> 7321cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 7331cb0ef41Sopenharmony_ci<ul> 7341cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a></li> 7351cb0ef41Sopenharmony_ci<li><code>end</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 7361cb0ef41Sopenharmony_ci</ul> 7371cb0ef41Sopenharmony_ci</li> 7381cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills when the pipeline is complete.</li> 7391cb0ef41Sopenharmony_ci</ul> 7401cb0ef41Sopenharmony_ci 7411cb0ef41Sopenharmony_ci<pre class="with-62-chars"><input class="js-flavor-selector" type="checkbox" aria-label="Show modern ES modules syntax"><code class="language-js cjs"><span class="hljs-keyword">const</span> { pipeline } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream/promises'</span>); 7421cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 7431cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> zlib = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:zlib'</span>); 7441cb0ef41Sopenharmony_ci 7451cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">run</span>(<span class="hljs-params"></span>) { 7461cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">pipeline</span>( 7471cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'archive.tar'</span>), 7481cb0ef41Sopenharmony_ci zlib.<span class="hljs-title function_">createGzip</span>(), 7491cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'archive.tar.gz'</span>), 7501cb0ef41Sopenharmony_ci ); 7511cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Pipeline succeeded.'</span>); 7521cb0ef41Sopenharmony_ci} 7531cb0ef41Sopenharmony_ci 7541cb0ef41Sopenharmony_ci<span class="hljs-title function_">run</span>().<span class="hljs-title function_">catch</span>(<span class="hljs-variable language_">console</span>.<span class="hljs-property">error</span>);</code><code class="language-js mjs"><span class="hljs-keyword">import</span> { pipeline } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream/promises'</span>; 7551cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { createReadStream, createWriteStream } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs'</span>; 7561cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { createGzip } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:zlib'</span>; 7571cb0ef41Sopenharmony_ci 7581cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title function_">pipeline</span>( 7591cb0ef41Sopenharmony_ci <span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'archive.tar'</span>), 7601cb0ef41Sopenharmony_ci <span class="hljs-title function_">createGzip</span>(), 7611cb0ef41Sopenharmony_ci <span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'archive.tar.gz'</span>), 7621cb0ef41Sopenharmony_ci); 7631cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Pipeline succeeded.'</span>);</code><button class="copy-button">copy</button></pre> 7641cb0ef41Sopenharmony_ci<p>To use an <code>AbortSignal</code>, pass it inside an options object, as the last argument. 7651cb0ef41Sopenharmony_ciWhen the signal is aborted, <code>destroy</code> will be called on the underlying pipeline, 7661cb0ef41Sopenharmony_ciwith an <code>AbortError</code>.</p> 7671cb0ef41Sopenharmony_ci 7681cb0ef41Sopenharmony_ci<pre class="with-62-chars"><input class="js-flavor-selector" type="checkbox" aria-label="Show modern ES modules syntax"><code class="language-js cjs"><span class="hljs-keyword">const</span> { pipeline } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream/promises'</span>); 7691cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 7701cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> zlib = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:zlib'</span>); 7711cb0ef41Sopenharmony_ci 7721cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">run</span>(<span class="hljs-params"></span>) { 7731cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> ac = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 7741cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> signal = ac.<span class="hljs-property">signal</span>; 7751cb0ef41Sopenharmony_ci 7761cb0ef41Sopenharmony_ci <span class="hljs-title function_">setImmediate</span>(<span class="hljs-function">() =></span> ac.<span class="hljs-title function_">abort</span>()); 7771cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">pipeline</span>( 7781cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'archive.tar'</span>), 7791cb0ef41Sopenharmony_ci zlib.<span class="hljs-title function_">createGzip</span>(), 7801cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'archive.tar.gz'</span>), 7811cb0ef41Sopenharmony_ci { signal }, 7821cb0ef41Sopenharmony_ci ); 7831cb0ef41Sopenharmony_ci} 7841cb0ef41Sopenharmony_ci 7851cb0ef41Sopenharmony_ci<span class="hljs-title function_">run</span>().<span class="hljs-title function_">catch</span>(<span class="hljs-variable language_">console</span>.<span class="hljs-property">error</span>); <span class="hljs-comment">// AbortError</span></code><code class="language-js mjs"><span class="hljs-keyword">import</span> { pipeline } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream/promises'</span>; 7861cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { createReadStream, createWriteStream } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs'</span>; 7871cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { createGzip } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:zlib'</span>; 7881cb0ef41Sopenharmony_ci 7891cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> ac = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 7901cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { signal } = ac; 7911cb0ef41Sopenharmony_ci<span class="hljs-title function_">setImmediate</span>(<span class="hljs-function">() =></span> ac.<span class="hljs-title function_">abort</span>()); 7921cb0ef41Sopenharmony_ci<span class="hljs-keyword">try</span> { 7931cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">pipeline</span>( 7941cb0ef41Sopenharmony_ci <span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'archive.tar'</span>), 7951cb0ef41Sopenharmony_ci <span class="hljs-title function_">createGzip</span>(), 7961cb0ef41Sopenharmony_ci <span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'archive.tar.gz'</span>), 7971cb0ef41Sopenharmony_ci { signal }, 7981cb0ef41Sopenharmony_ci ); 7991cb0ef41Sopenharmony_ci} <span class="hljs-keyword">catch</span> (err) { 8001cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); <span class="hljs-comment">// AbortError</span> 8011cb0ef41Sopenharmony_ci}</code><button class="copy-button">copy</button></pre> 8021cb0ef41Sopenharmony_ci<p>The <code>pipeline</code> API also supports async generators:</p> 8031cb0ef41Sopenharmony_ci 8041cb0ef41Sopenharmony_ci<pre class="with-62-chars"><input class="js-flavor-selector" type="checkbox" aria-label="Show modern ES modules syntax"><code class="language-js cjs"><span class="hljs-keyword">const</span> { pipeline } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream/promises'</span>); 8051cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 8061cb0ef41Sopenharmony_ci 8071cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">run</span>(<span class="hljs-params"></span>) { 8081cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">pipeline</span>( 8091cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'lowercase.txt'</span>), 8101cb0ef41Sopenharmony_ci <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>* (source, { signal }) { 8111cb0ef41Sopenharmony_ci source.<span class="hljs-title function_">setEncoding</span>(<span class="hljs-string">'utf8'</span>); <span class="hljs-comment">// Work with strings rather than `Buffer`s.</span> 8121cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> source) { 8131cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-keyword">await</span> <span class="hljs-title function_">processChunk</span>(chunk, { signal }); 8141cb0ef41Sopenharmony_ci } 8151cb0ef41Sopenharmony_ci }, 8161cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'uppercase.txt'</span>), 8171cb0ef41Sopenharmony_ci ); 8181cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Pipeline succeeded.'</span>); 8191cb0ef41Sopenharmony_ci} 8201cb0ef41Sopenharmony_ci 8211cb0ef41Sopenharmony_ci<span class="hljs-title function_">run</span>().<span class="hljs-title function_">catch</span>(<span class="hljs-variable language_">console</span>.<span class="hljs-property">error</span>);</code><code class="language-js mjs"><span class="hljs-keyword">import</span> { pipeline } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream/promises'</span>; 8221cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { createReadStream, createWriteStream } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs'</span>; 8231cb0ef41Sopenharmony_ci 8241cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title function_">pipeline</span>( 8251cb0ef41Sopenharmony_ci <span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'lowercase.txt'</span>), 8261cb0ef41Sopenharmony_ci <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>* (source, { signal }) { 8271cb0ef41Sopenharmony_ci source.<span class="hljs-title function_">setEncoding</span>(<span class="hljs-string">'utf8'</span>); <span class="hljs-comment">// Work with strings rather than `Buffer`s.</span> 8281cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> source) { 8291cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-keyword">await</span> <span class="hljs-title function_">processChunk</span>(chunk, { signal }); 8301cb0ef41Sopenharmony_ci } 8311cb0ef41Sopenharmony_ci }, 8321cb0ef41Sopenharmony_ci <span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'uppercase.txt'</span>), 8331cb0ef41Sopenharmony_ci); 8341cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Pipeline succeeded.'</span>);</code><button class="copy-button">copy</button></pre> 8351cb0ef41Sopenharmony_ci<p>Remember to handle the <code>signal</code> argument passed into the async generator. 8361cb0ef41Sopenharmony_ciEspecially in the case where the async generator is the source for the 8371cb0ef41Sopenharmony_cipipeline (i.e. first argument) or the pipeline will never complete.</p> 8381cb0ef41Sopenharmony_ci 8391cb0ef41Sopenharmony_ci<pre class="with-53-chars"><input class="js-flavor-selector" type="checkbox" aria-label="Show modern ES modules syntax"><code class="language-js cjs"><span class="hljs-keyword">const</span> { pipeline } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream/promises'</span>); 8401cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 8411cb0ef41Sopenharmony_ci 8421cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">run</span>(<span class="hljs-params"></span>) { 8431cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">pipeline</span>( 8441cb0ef41Sopenharmony_ci <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>* ({ signal }) { 8451cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">someLongRunningfn</span>({ signal }); 8461cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-string">'asd'</span>; 8471cb0ef41Sopenharmony_ci }, 8481cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'uppercase.txt'</span>), 8491cb0ef41Sopenharmony_ci ); 8501cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Pipeline succeeded.'</span>); 8511cb0ef41Sopenharmony_ci} 8521cb0ef41Sopenharmony_ci 8531cb0ef41Sopenharmony_ci<span class="hljs-title function_">run</span>().<span class="hljs-title function_">catch</span>(<span class="hljs-variable language_">console</span>.<span class="hljs-property">error</span>);</code><code class="language-js mjs"><span class="hljs-keyword">import</span> { pipeline } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream/promises'</span>; 8541cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> fs <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs'</span>; 8551cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title function_">pipeline</span>( 8561cb0ef41Sopenharmony_ci <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>* ({ signal }) { 8571cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">someLongRunningfn</span>({ signal }); 8581cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-string">'asd'</span>; 8591cb0ef41Sopenharmony_ci }, 8601cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'uppercase.txt'</span>), 8611cb0ef41Sopenharmony_ci); 8621cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Pipeline succeeded.'</span>);</code><button class="copy-button">copy</button></pre> 8631cb0ef41Sopenharmony_ci<p>The <code>pipeline</code> API provides <a href="#streampipelinesource-transforms-destination-callback">callback version</a>:</p> 8641cb0ef41Sopenharmony_ci<h4><code>stream.finished(stream[, options])</code><span><a class="mark" href="#streamfinishedstream-options" id="streamfinishedstream-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_finished_stream_options"></a></h4> 8651cb0ef41Sopenharmony_ci<div class="api_metadata"> 8661cb0ef41Sopenharmony_ci<span>Added in: v15.0.0</span> 8671cb0ef41Sopenharmony_ci</div> 8681cb0ef41Sopenharmony_ci<ul> 8691cb0ef41Sopenharmony_ci<li><code>stream</code> <a href="stream.html#stream" class="type"><Stream></a></li> 8701cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 8711cb0ef41Sopenharmony_ci<ul> 8721cb0ef41Sopenharmony_ci<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a></li> 8731cb0ef41Sopenharmony_ci<li><code>readable</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a></li> 8741cb0ef41Sopenharmony_ci<li><code>writable</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a></li> 8751cb0ef41Sopenharmony_ci<li><code>signal</code>: <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type" class="type"><undefined></a></li> 8761cb0ef41Sopenharmony_ci</ul> 8771cb0ef41Sopenharmony_ci</li> 8781cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> Fulfills when the stream is no 8791cb0ef41Sopenharmony_cilonger readable or writable.</li> 8801cb0ef41Sopenharmony_ci</ul> 8811cb0ef41Sopenharmony_ci 8821cb0ef41Sopenharmony_ci<pre class="with-53-chars"><input class="js-flavor-selector" type="checkbox" aria-label="Show modern ES modules syntax"><code class="language-js cjs"><span class="hljs-keyword">const</span> { finished } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream/promises'</span>); 8831cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 8841cb0ef41Sopenharmony_ci 8851cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> rs = fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'archive.tar'</span>); 8861cb0ef41Sopenharmony_ci 8871cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">run</span>(<span class="hljs-params"></span>) { 8881cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">finished</span>(rs); 8891cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Stream is done reading.'</span>); 8901cb0ef41Sopenharmony_ci} 8911cb0ef41Sopenharmony_ci 8921cb0ef41Sopenharmony_ci<span class="hljs-title function_">run</span>().<span class="hljs-title function_">catch</span>(<span class="hljs-variable language_">console</span>.<span class="hljs-property">error</span>); 8931cb0ef41Sopenharmony_cirs.<span class="hljs-title function_">resume</span>(); <span class="hljs-comment">// Drain the stream.</span></code><code class="language-js mjs"><span class="hljs-keyword">import</span> { finished } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream/promises'</span>; 8941cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { createReadStream } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs'</span>; 8951cb0ef41Sopenharmony_ci 8961cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> rs = <span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'archive.tar'</span>); 8971cb0ef41Sopenharmony_ci 8981cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">run</span>(<span class="hljs-params"></span>) { 8991cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">finished</span>(rs); 9001cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Stream is done reading.'</span>); 9011cb0ef41Sopenharmony_ci} 9021cb0ef41Sopenharmony_ci 9031cb0ef41Sopenharmony_ci<span class="hljs-title function_">run</span>().<span class="hljs-title function_">catch</span>(<span class="hljs-variable language_">console</span>.<span class="hljs-property">error</span>); 9041cb0ef41Sopenharmony_cirs.<span class="hljs-title function_">resume</span>(); <span class="hljs-comment">// Drain the stream.</span></code><button class="copy-button">copy</button></pre> 9051cb0ef41Sopenharmony_ci<p>The <code>finished</code> API also provides a <a href="#streamfinishedstream-options-callback">callback version</a>.</p> 9061cb0ef41Sopenharmony_ci<h4>Object mode<span><a class="mark" href="#object-mode" id="object-mode">#</a></span><a aria-hidden="true" class="legacy" id="stream_object_mode"></a></h4> 9071cb0ef41Sopenharmony_ci<p>All streams created by Node.js APIs operate exclusively on strings and <code>Buffer</code> 9081cb0ef41Sopenharmony_ci(or <code>Uint8Array</code>) objects. It is possible, however, for stream implementations 9091cb0ef41Sopenharmony_cito work with other types of JavaScript values (with the exception of <code>null</code>, 9101cb0ef41Sopenharmony_ciwhich serves a special purpose within streams). Such streams are considered to 9111cb0ef41Sopenharmony_cioperate in "object mode".</p> 9121cb0ef41Sopenharmony_ci<p>Stream instances are switched into object mode using the <code>objectMode</code> option 9131cb0ef41Sopenharmony_ciwhen the stream is created. Attempting to switch an existing stream into 9141cb0ef41Sopenharmony_ciobject mode is not safe.</p> 9151cb0ef41Sopenharmony_ci<h4>Buffering<span><a class="mark" href="#buffering" id="buffering">#</a></span><a aria-hidden="true" class="legacy" id="stream_buffering"></a></h4> 9161cb0ef41Sopenharmony_ci 9171cb0ef41Sopenharmony_ci<p>Both <a href="#class-streamwritable"><code>Writable</code></a> and <a href="#class-streamreadable"><code>Readable</code></a> streams will store data in an internal 9181cb0ef41Sopenharmony_cibuffer.</p> 9191cb0ef41Sopenharmony_ci<p>The amount of data potentially buffered depends on the <code>highWaterMark</code> option 9201cb0ef41Sopenharmony_cipassed into the stream's constructor. For normal streams, the <code>highWaterMark</code> 9211cb0ef41Sopenharmony_cioption specifies a <a href="#highwatermark-discrepancy-after-calling-readablesetencoding">total number of bytes</a>. For streams operating 9221cb0ef41Sopenharmony_ciin object mode, the <code>highWaterMark</code> specifies a total number of objects.</p> 9231cb0ef41Sopenharmony_ci<p>Data is buffered in <code>Readable</code> streams when the implementation calls 9241cb0ef41Sopenharmony_ci<a href="#readablepushchunk-encoding"><code>stream.push(chunk)</code></a>. If the consumer of the Stream does not 9251cb0ef41Sopenharmony_cicall <a href="#readablereadsize"><code>stream.read()</code></a>, the data will sit in the internal 9261cb0ef41Sopenharmony_ciqueue until it is consumed.</p> 9271cb0ef41Sopenharmony_ci<p>Once the total size of the internal read buffer reaches the threshold specified 9281cb0ef41Sopenharmony_ciby <code>highWaterMark</code>, the stream will temporarily stop reading data from the 9291cb0ef41Sopenharmony_ciunderlying resource until the data currently buffered can be consumed (that is, 9301cb0ef41Sopenharmony_cithe stream will stop calling the internal <a href="#readable_readsize"><code>readable._read()</code></a> method that is 9311cb0ef41Sopenharmony_ciused to fill the read buffer).</p> 9321cb0ef41Sopenharmony_ci<p>Data is buffered in <code>Writable</code> streams when the 9331cb0ef41Sopenharmony_ci<a href="#writablewritechunk-encoding-callback"><code>writable.write(chunk)</code></a> method is called repeatedly. While the 9341cb0ef41Sopenharmony_citotal size of the internal write buffer is below the threshold set by 9351cb0ef41Sopenharmony_ci<code>highWaterMark</code>, calls to <code>writable.write()</code> will return <code>true</code>. Once 9361cb0ef41Sopenharmony_cithe size of the internal buffer reaches or exceeds the <code>highWaterMark</code>, <code>false</code> 9371cb0ef41Sopenharmony_ciwill be returned.</p> 9381cb0ef41Sopenharmony_ci<p>A key goal of the <code>stream</code> API, particularly the <a href="#readablepipedestination-options"><code>stream.pipe()</code></a> method, 9391cb0ef41Sopenharmony_ciis to limit the buffering of data to acceptable levels such that sources and 9401cb0ef41Sopenharmony_cidestinations of differing speeds will not overwhelm the available memory.</p> 9411cb0ef41Sopenharmony_ci<p>The <code>highWaterMark</code> option is a threshold, not a limit: it dictates the amount 9421cb0ef41Sopenharmony_ciof data that a stream buffers before it stops asking for more data. It does not 9431cb0ef41Sopenharmony_cienforce a strict memory limitation in general. Specific stream implementations 9441cb0ef41Sopenharmony_cimay choose to enforce stricter limits but doing so is optional.</p> 9451cb0ef41Sopenharmony_ci<p>Because <a href="#class-streamduplex"><code>Duplex</code></a> and <a href="#class-streamtransform"><code>Transform</code></a> streams are both <code>Readable</code> and 9461cb0ef41Sopenharmony_ci<code>Writable</code>, each maintains <em>two</em> separate internal buffers used for reading and 9471cb0ef41Sopenharmony_ciwriting, allowing each side to operate independently of the other while 9481cb0ef41Sopenharmony_cimaintaining an appropriate and efficient flow of data. For example, 9491cb0ef41Sopenharmony_ci<a href="net.html#class-netsocket"><code>net.Socket</code></a> instances are <a href="#class-streamduplex"><code>Duplex</code></a> streams whose <code>Readable</code> side allows 9501cb0ef41Sopenharmony_ciconsumption of data received <em>from</em> the socket and whose <code>Writable</code> side allows 9511cb0ef41Sopenharmony_ciwriting data <em>to</em> the socket. Because data may be written to the socket at a 9521cb0ef41Sopenharmony_cifaster or slower rate than data is received, each side should 9531cb0ef41Sopenharmony_cioperate (and buffer) independently of the other.</p> 9541cb0ef41Sopenharmony_ci<p>The mechanics of the internal buffering are an internal implementation detail 9551cb0ef41Sopenharmony_ciand may be changed at any time. However, for certain advanced implementations, 9561cb0ef41Sopenharmony_cithe internal buffers can be retrieved using <code>writable.writableBuffer</code> or 9571cb0ef41Sopenharmony_ci<code>readable.readableBuffer</code>. Use of these undocumented properties is discouraged.</p> 9581cb0ef41Sopenharmony_ci</section><section><h3>API for stream consumers<span><a class="mark" href="#api-for-stream-consumers" id="api-for-stream-consumers">#</a></span><a aria-hidden="true" class="legacy" id="stream_api_for_stream_consumers"></a></h3> 9591cb0ef41Sopenharmony_ci 9601cb0ef41Sopenharmony_ci<p>Almost all Node.js applications, no matter how simple, use streams in some 9611cb0ef41Sopenharmony_cimanner. The following is an example of using streams in a Node.js application 9621cb0ef41Sopenharmony_cithat implements an HTTP server:</p> 9631cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> http = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:http'</span>); 9641cb0ef41Sopenharmony_ci 9651cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> server = http.<span class="hljs-title function_">createServer</span>(<span class="hljs-function">(<span class="hljs-params">req, res</span>) =></span> { 9661cb0ef41Sopenharmony_ci <span class="hljs-comment">// `req` is an http.IncomingMessage, which is a readable stream.</span> 9671cb0ef41Sopenharmony_ci <span class="hljs-comment">// `res` is an http.ServerResponse, which is a writable stream.</span> 9681cb0ef41Sopenharmony_ci 9691cb0ef41Sopenharmony_ci <span class="hljs-keyword">let</span> body = <span class="hljs-string">''</span>; 9701cb0ef41Sopenharmony_ci <span class="hljs-comment">// Get the data as utf8 strings.</span> 9711cb0ef41Sopenharmony_ci <span class="hljs-comment">// If an encoding is not set, Buffer objects will be received.</span> 9721cb0ef41Sopenharmony_ci req.<span class="hljs-title function_">setEncoding</span>(<span class="hljs-string">'utf8'</span>); 9731cb0ef41Sopenharmony_ci 9741cb0ef41Sopenharmony_ci <span class="hljs-comment">// Readable streams emit 'data' events once a listener is added.</span> 9751cb0ef41Sopenharmony_ci req.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> { 9761cb0ef41Sopenharmony_ci body += chunk; 9771cb0ef41Sopenharmony_ci }); 9781cb0ef41Sopenharmony_ci 9791cb0ef41Sopenharmony_ci <span class="hljs-comment">// The 'end' event indicates that the entire body has been received.</span> 9801cb0ef41Sopenharmony_ci req.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> { 9811cb0ef41Sopenharmony_ci <span class="hljs-keyword">try</span> { 9821cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> data = <span class="hljs-title class_">JSON</span>.<span class="hljs-title function_">parse</span>(body); 9831cb0ef41Sopenharmony_ci <span class="hljs-comment">// Write back something interesting to the user:</span> 9841cb0ef41Sopenharmony_ci res.<span class="hljs-title function_">write</span>(<span class="hljs-keyword">typeof</span> data); 9851cb0ef41Sopenharmony_ci res.<span class="hljs-title function_">end</span>(); 9861cb0ef41Sopenharmony_ci } <span class="hljs-keyword">catch</span> (er) { 9871cb0ef41Sopenharmony_ci <span class="hljs-comment">// uh oh! bad json!</span> 9881cb0ef41Sopenharmony_ci res.<span class="hljs-property">statusCode</span> = <span class="hljs-number">400</span>; 9891cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> res.<span class="hljs-title function_">end</span>(<span class="hljs-string">`error: <span class="hljs-subst">${er.message}</span>`</span>); 9901cb0ef41Sopenharmony_ci } 9911cb0ef41Sopenharmony_ci }); 9921cb0ef41Sopenharmony_ci}); 9931cb0ef41Sopenharmony_ci 9941cb0ef41Sopenharmony_ciserver.<span class="hljs-title function_">listen</span>(<span class="hljs-number">1337</span>); 9951cb0ef41Sopenharmony_ci 9961cb0ef41Sopenharmony_ci<span class="hljs-comment">// $ curl localhost:1337 -d "{}"</span> 9971cb0ef41Sopenharmony_ci<span class="hljs-comment">// object</span> 9981cb0ef41Sopenharmony_ci<span class="hljs-comment">// $ curl localhost:1337 -d "\"foo\""</span> 9991cb0ef41Sopenharmony_ci<span class="hljs-comment">// string</span> 10001cb0ef41Sopenharmony_ci<span class="hljs-comment">// $ curl localhost:1337 -d "not json"</span> 10011cb0ef41Sopenharmony_ci<span class="hljs-comment">// error: Unexpected token 'o', "not json" is not valid JSON</span></code> <button class="copy-button">copy</button></pre> 10021cb0ef41Sopenharmony_ci<p><a href="#class-streamwritable"><code>Writable</code></a> streams (such as <code>res</code> in the example) expose methods such as 10031cb0ef41Sopenharmony_ci<code>write()</code> and <code>end()</code> that are used to write data onto the stream.</p> 10041cb0ef41Sopenharmony_ci<p><a href="#class-streamreadable"><code>Readable</code></a> streams use the <a href="events.html#class-eventemitter"><code>EventEmitter</code></a> API for notifying application 10051cb0ef41Sopenharmony_cicode when data is available to be read off the stream. That available data can 10061cb0ef41Sopenharmony_cibe read from the stream in multiple ways.</p> 10071cb0ef41Sopenharmony_ci<p>Both <a href="#class-streamwritable"><code>Writable</code></a> and <a href="#class-streamreadable"><code>Readable</code></a> streams use the <a href="events.html#class-eventemitter"><code>EventEmitter</code></a> API in 10081cb0ef41Sopenharmony_civarious ways to communicate the current state of the stream.</p> 10091cb0ef41Sopenharmony_ci<p><a href="#class-streamduplex"><code>Duplex</code></a> and <a href="#class-streamtransform"><code>Transform</code></a> streams are both <a href="#class-streamwritable"><code>Writable</code></a> and 10101cb0ef41Sopenharmony_ci<a href="#class-streamreadable"><code>Readable</code></a>.</p> 10111cb0ef41Sopenharmony_ci<p>Applications that are either writing data to or consuming data from a stream 10121cb0ef41Sopenharmony_ciare not required to implement the stream interfaces directly and will generally 10131cb0ef41Sopenharmony_cihave no reason to call <code>require('node:stream')</code>.</p> 10141cb0ef41Sopenharmony_ci<p>Developers wishing to implement new types of streams should refer to the 10151cb0ef41Sopenharmony_cisection <a href="#api-for-stream-implementers">API for stream implementers</a>.</p> 10161cb0ef41Sopenharmony_ci<h4>Writable streams<span><a class="mark" href="#writable-streams" id="writable-streams">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_streams"></a></h4> 10171cb0ef41Sopenharmony_ci<p>Writable streams are an abstraction for a <em>destination</em> to which data is 10181cb0ef41Sopenharmony_ciwritten.</p> 10191cb0ef41Sopenharmony_ci<p>Examples of <a href="#class-streamwritable"><code>Writable</code></a> streams include:</p> 10201cb0ef41Sopenharmony_ci<ul> 10211cb0ef41Sopenharmony_ci<li><a href="http.html#class-httpclientrequest">HTTP requests, on the client</a></li> 10221cb0ef41Sopenharmony_ci<li><a href="http.html#class-httpserverresponse">HTTP responses, on the server</a></li> 10231cb0ef41Sopenharmony_ci<li><a href="fs.html#class-fswritestream">fs write streams</a></li> 10241cb0ef41Sopenharmony_ci<li><a href="zlib.html">zlib streams</a></li> 10251cb0ef41Sopenharmony_ci<li><a href="crypto.html">crypto streams</a></li> 10261cb0ef41Sopenharmony_ci<li><a href="net.html#class-netsocket">TCP sockets</a></li> 10271cb0ef41Sopenharmony_ci<li><a href="child_process.html#subprocessstdin">child process stdin</a></li> 10281cb0ef41Sopenharmony_ci<li><a href="process.html#processstdout"><code>process.stdout</code></a>, <a href="process.html#processstderr"><code>process.stderr</code></a></li> 10291cb0ef41Sopenharmony_ci</ul> 10301cb0ef41Sopenharmony_ci<p>Some of these examples are actually <a href="#class-streamduplex"><code>Duplex</code></a> streams that implement the 10311cb0ef41Sopenharmony_ci<a href="#class-streamwritable"><code>Writable</code></a> interface.</p> 10321cb0ef41Sopenharmony_ci<p>All <a href="#class-streamwritable"><code>Writable</code></a> streams implement the interface defined by the 10331cb0ef41Sopenharmony_ci<code>stream.Writable</code> class.</p> 10341cb0ef41Sopenharmony_ci<p>While specific instances of <a href="#class-streamwritable"><code>Writable</code></a> streams may differ in various ways, 10351cb0ef41Sopenharmony_ciall <code>Writable</code> streams follow the same fundamental usage pattern as illustrated 10361cb0ef41Sopenharmony_ciin the example below:</p> 10371cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> myStream = <span class="hljs-title function_">getWritableStreamSomehow</span>(); 10381cb0ef41Sopenharmony_cimyStream.<span class="hljs-title function_">write</span>(<span class="hljs-string">'some data'</span>); 10391cb0ef41Sopenharmony_cimyStream.<span class="hljs-title function_">write</span>(<span class="hljs-string">'some more data'</span>); 10401cb0ef41Sopenharmony_cimyStream.<span class="hljs-title function_">end</span>(<span class="hljs-string">'done writing data'</span>);</code> <button class="copy-button">copy</button></pre> 10411cb0ef41Sopenharmony_ci<h5>Class: <code>stream.Writable</code><span><a class="mark" href="#class-streamwritable" id="class-streamwritable">#</a></span><a aria-hidden="true" class="legacy" id="stream_class_stream_writable"></a></h5> 10421cb0ef41Sopenharmony_ci<div class="api_metadata"> 10431cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 10441cb0ef41Sopenharmony_ci</div> 10451cb0ef41Sopenharmony_ci 10461cb0ef41Sopenharmony_ci<h6>Event: <code>'close'</code><span><a class="mark" href="#event-close" id="event-close">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_close"></a></h6> 10471cb0ef41Sopenharmony_ci<div class="api_metadata"> 10481cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 10491cb0ef41Sopenharmony_ci<table> 10501cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 10511cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 10521cb0ef41Sopenharmony_ci<td><p>Add <code>emitClose</code> option to specify if <code>'close'</code> is emitted on destroy.</p></td></tr> 10531cb0ef41Sopenharmony_ci<tr><td>v0.9.4</td> 10541cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.9.4</span></p></td></tr> 10551cb0ef41Sopenharmony_ci</tbody></table> 10561cb0ef41Sopenharmony_ci</details> 10571cb0ef41Sopenharmony_ci</div> 10581cb0ef41Sopenharmony_ci<p>The <code>'close'</code> event is emitted when the stream and any of its underlying 10591cb0ef41Sopenharmony_ciresources (a file descriptor, for example) have been closed. The event indicates 10601cb0ef41Sopenharmony_cithat no more events will be emitted, and no further computation will occur.</p> 10611cb0ef41Sopenharmony_ci<p>A <a href="#class-streamwritable"><code>Writable</code></a> stream will always emit the <code>'close'</code> event if it is 10621cb0ef41Sopenharmony_cicreated with the <code>emitClose</code> option.</p> 10631cb0ef41Sopenharmony_ci<h6>Event: <code>'drain'</code><span><a class="mark" href="#event-drain" id="event-drain">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_drain"></a></h6> 10641cb0ef41Sopenharmony_ci<div class="api_metadata"> 10651cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 10661cb0ef41Sopenharmony_ci</div> 10671cb0ef41Sopenharmony_ci<p>If a call to <a href="#writablewritechunk-encoding-callback"><code>stream.write(chunk)</code></a> returns <code>false</code>, the 10681cb0ef41Sopenharmony_ci<code>'drain'</code> event will be emitted when it is appropriate to resume writing data 10691cb0ef41Sopenharmony_cito the stream.</p> 10701cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// Write the data to the supplied writable stream one million times.</span> 10711cb0ef41Sopenharmony_ci<span class="hljs-comment">// Be attentive to back-pressure.</span> 10721cb0ef41Sopenharmony_ci<span class="hljs-keyword">function</span> <span class="hljs-title function_">writeOneMillionTimes</span>(<span class="hljs-params">writer, data, encoding, callback</span>) { 10731cb0ef41Sopenharmony_ci <span class="hljs-keyword">let</span> i = <span class="hljs-number">1000000</span>; 10741cb0ef41Sopenharmony_ci <span class="hljs-title function_">write</span>(); 10751cb0ef41Sopenharmony_ci <span class="hljs-keyword">function</span> <span class="hljs-title function_">write</span>(<span class="hljs-params"></span>) { 10761cb0ef41Sopenharmony_ci <span class="hljs-keyword">let</span> ok = <span class="hljs-literal">true</span>; 10771cb0ef41Sopenharmony_ci <span class="hljs-keyword">do</span> { 10781cb0ef41Sopenharmony_ci i--; 10791cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (i === <span class="hljs-number">0</span>) { 10801cb0ef41Sopenharmony_ci <span class="hljs-comment">// Last time!</span> 10811cb0ef41Sopenharmony_ci writer.<span class="hljs-title function_">write</span>(data, encoding, callback); 10821cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 10831cb0ef41Sopenharmony_ci <span class="hljs-comment">// See if we should continue, or wait.</span> 10841cb0ef41Sopenharmony_ci <span class="hljs-comment">// Don't pass the callback, because we're not done yet.</span> 10851cb0ef41Sopenharmony_ci ok = writer.<span class="hljs-title function_">write</span>(data, encoding); 10861cb0ef41Sopenharmony_ci } 10871cb0ef41Sopenharmony_ci } <span class="hljs-keyword">while</span> (i > <span class="hljs-number">0</span> && ok); 10881cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (i > <span class="hljs-number">0</span>) { 10891cb0ef41Sopenharmony_ci <span class="hljs-comment">// Had to stop early!</span> 10901cb0ef41Sopenharmony_ci <span class="hljs-comment">// Write some more once it drains.</span> 10911cb0ef41Sopenharmony_ci writer.<span class="hljs-title function_">once</span>(<span class="hljs-string">'drain'</span>, write); 10921cb0ef41Sopenharmony_ci } 10931cb0ef41Sopenharmony_ci } 10941cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 10951cb0ef41Sopenharmony_ci<h6>Event: <code>'error'</code><span><a class="mark" href="#event-error" id="event-error">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_error"></a></h6> 10961cb0ef41Sopenharmony_ci<div class="api_metadata"> 10971cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 10981cb0ef41Sopenharmony_ci</div> 10991cb0ef41Sopenharmony_ci<ul> 11001cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 11011cb0ef41Sopenharmony_ci</ul> 11021cb0ef41Sopenharmony_ci<p>The <code>'error'</code> event is emitted if an error occurred while writing or piping 11031cb0ef41Sopenharmony_cidata. The listener callback is passed a single <code>Error</code> argument when called.</p> 11041cb0ef41Sopenharmony_ci<p>The stream is closed when the <code>'error'</code> event is emitted unless the 11051cb0ef41Sopenharmony_ci<a href="#new-streamwritableoptions"><code>autoDestroy</code></a> option was set to <code>false</code> when creating the 11061cb0ef41Sopenharmony_cistream.</p> 11071cb0ef41Sopenharmony_ci<p>After <code>'error'</code>, no further events other than <code>'close'</code> <em>should</em> be emitted 11081cb0ef41Sopenharmony_ci(including <code>'error'</code> events).</p> 11091cb0ef41Sopenharmony_ci<h6>Event: <code>'finish'</code><span><a class="mark" href="#event-finish" id="event-finish">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_finish"></a></h6> 11101cb0ef41Sopenharmony_ci<div class="api_metadata"> 11111cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 11121cb0ef41Sopenharmony_ci</div> 11131cb0ef41Sopenharmony_ci<p>The <code>'finish'</code> event is emitted after the <a href="#writableendchunk-encoding-callback"><code>stream.end()</code></a> method 11141cb0ef41Sopenharmony_cihas been called, and all data has been flushed to the underlying system.</p> 11151cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> writer = <span class="hljs-title function_">getWritableStreamSomehow</span>(); 11161cb0ef41Sopenharmony_ci<span class="hljs-keyword">for</span> (<span class="hljs-keyword">let</span> i = <span class="hljs-number">0</span>; i < <span class="hljs-number">100</span>; i++) { 11171cb0ef41Sopenharmony_ci writer.<span class="hljs-title function_">write</span>(<span class="hljs-string">`hello, #<span class="hljs-subst">${i}</span>!\n`</span>); 11181cb0ef41Sopenharmony_ci} 11191cb0ef41Sopenharmony_ciwriter.<span class="hljs-title function_">on</span>(<span class="hljs-string">'finish'</span>, <span class="hljs-function">() =></span> { 11201cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'All writes are now complete.'</span>); 11211cb0ef41Sopenharmony_ci}); 11221cb0ef41Sopenharmony_ciwriter.<span class="hljs-title function_">end</span>(<span class="hljs-string">'This is the end\n'</span>);</code> <button class="copy-button">copy</button></pre> 11231cb0ef41Sopenharmony_ci<h6>Event: <code>'pipe'</code><span><a class="mark" href="#event-pipe" id="event-pipe">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_pipe"></a></h6> 11241cb0ef41Sopenharmony_ci<div class="api_metadata"> 11251cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 11261cb0ef41Sopenharmony_ci</div> 11271cb0ef41Sopenharmony_ci<ul> 11281cb0ef41Sopenharmony_ci<li><code>src</code> <a href="stream.html#class-streamreadable" class="type"><stream.Readable></a> source stream that is piping to this writable</li> 11291cb0ef41Sopenharmony_ci</ul> 11301cb0ef41Sopenharmony_ci<p>The <code>'pipe'</code> event is emitted when the <a href="#readablepipedestination-options"><code>stream.pipe()</code></a> method is called on 11311cb0ef41Sopenharmony_cia readable stream, adding this writable to its set of destinations.</p> 11321cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> writer = <span class="hljs-title function_">getWritableStreamSomehow</span>(); 11331cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> reader = <span class="hljs-title function_">getReadableStreamSomehow</span>(); 11341cb0ef41Sopenharmony_ciwriter.<span class="hljs-title function_">on</span>(<span class="hljs-string">'pipe'</span>, <span class="hljs-function">(<span class="hljs-params">src</span>) =></span> { 11351cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Something is piping into the writer.'</span>); 11361cb0ef41Sopenharmony_ci assert.<span class="hljs-title function_">equal</span>(src, reader); 11371cb0ef41Sopenharmony_ci}); 11381cb0ef41Sopenharmony_cireader.<span class="hljs-title function_">pipe</span>(writer);</code> <button class="copy-button">copy</button></pre> 11391cb0ef41Sopenharmony_ci<h6>Event: <code>'unpipe'</code><span><a class="mark" href="#event-unpipe" id="event-unpipe">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_unpipe"></a></h6> 11401cb0ef41Sopenharmony_ci<div class="api_metadata"> 11411cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 11421cb0ef41Sopenharmony_ci</div> 11431cb0ef41Sopenharmony_ci<ul> 11441cb0ef41Sopenharmony_ci<li><code>src</code> <a href="stream.html#class-streamreadable" class="type"><stream.Readable></a> The source stream that 11451cb0ef41Sopenharmony_ci<a href="#readableunpipedestination">unpiped</a> this writable</li> 11461cb0ef41Sopenharmony_ci</ul> 11471cb0ef41Sopenharmony_ci<p>The <code>'unpipe'</code> event is emitted when the <a href="#readableunpipedestination"><code>stream.unpipe()</code></a> method is called 11481cb0ef41Sopenharmony_cion a <a href="#class-streamreadable"><code>Readable</code></a> stream, removing this <a href="#class-streamwritable"><code>Writable</code></a> from its set of 11491cb0ef41Sopenharmony_cidestinations.</p> 11501cb0ef41Sopenharmony_ci<p>This is also emitted in case this <a href="#class-streamwritable"><code>Writable</code></a> stream emits an error when a 11511cb0ef41Sopenharmony_ci<a href="#class-streamreadable"><code>Readable</code></a> stream pipes into it.</p> 11521cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> writer = <span class="hljs-title function_">getWritableStreamSomehow</span>(); 11531cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> reader = <span class="hljs-title function_">getReadableStreamSomehow</span>(); 11541cb0ef41Sopenharmony_ciwriter.<span class="hljs-title function_">on</span>(<span class="hljs-string">'unpipe'</span>, <span class="hljs-function">(<span class="hljs-params">src</span>) =></span> { 11551cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Something has stopped piping into the writer.'</span>); 11561cb0ef41Sopenharmony_ci assert.<span class="hljs-title function_">equal</span>(src, reader); 11571cb0ef41Sopenharmony_ci}); 11581cb0ef41Sopenharmony_cireader.<span class="hljs-title function_">pipe</span>(writer); 11591cb0ef41Sopenharmony_cireader.<span class="hljs-title function_">unpipe</span>(writer);</code> <button class="copy-button">copy</button></pre> 11601cb0ef41Sopenharmony_ci<h6><code>writable.cork()</code><span><a class="mark" href="#writablecork" id="writablecork">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_cork"></a></h6> 11611cb0ef41Sopenharmony_ci<div class="api_metadata"> 11621cb0ef41Sopenharmony_ci<span>Added in: v0.11.2</span> 11631cb0ef41Sopenharmony_ci</div> 11641cb0ef41Sopenharmony_ci<p>The <code>writable.cork()</code> method forces all written data to be buffered in memory. 11651cb0ef41Sopenharmony_ciThe buffered data will be flushed when either the <a href="#writableuncork"><code>stream.uncork()</code></a> or 11661cb0ef41Sopenharmony_ci<a href="#writableendchunk-encoding-callback"><code>stream.end()</code></a> methods are called.</p> 11671cb0ef41Sopenharmony_ci<p>The primary intent of <code>writable.cork()</code> is to accommodate a situation in which 11681cb0ef41Sopenharmony_ciseveral small chunks are written to the stream in rapid succession. Instead of 11691cb0ef41Sopenharmony_ciimmediately forwarding them to the underlying destination, <code>writable.cork()</code> 11701cb0ef41Sopenharmony_cibuffers all the chunks until <code>writable.uncork()</code> is called, which will pass them 11711cb0ef41Sopenharmony_ciall to <code>writable._writev()</code>, if present. This prevents a head-of-line blocking 11721cb0ef41Sopenharmony_cisituation where data is being buffered while waiting for the first small chunk 11731cb0ef41Sopenharmony_cito be processed. However, use of <code>writable.cork()</code> without implementing 11741cb0ef41Sopenharmony_ci<code>writable._writev()</code> may have an adverse effect on throughput.</p> 11751cb0ef41Sopenharmony_ci<p>See also: <a href="#writableuncork"><code>writable.uncork()</code></a>, <a href="#writable_writevchunks-callback"><code>writable._writev()</code></a>.</p> 11761cb0ef41Sopenharmony_ci<h6><code>writable.destroy([error])</code><span><a class="mark" href="#writabledestroyerror" id="writabledestroyerror">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_destroy_error"></a></h6> 11771cb0ef41Sopenharmony_ci<div class="api_metadata"> 11781cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 11791cb0ef41Sopenharmony_ci<table> 11801cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 11811cb0ef41Sopenharmony_ci<tr><td>v14.0.0</td> 11821cb0ef41Sopenharmony_ci<td><p>Work as a no-op on a stream that has already been destroyed.</p></td></tr> 11831cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 11841cb0ef41Sopenharmony_ci<td><p><span>Added in: v8.0.0</span></p></td></tr> 11851cb0ef41Sopenharmony_ci</tbody></table> 11861cb0ef41Sopenharmony_ci</details> 11871cb0ef41Sopenharmony_ci</div> 11881cb0ef41Sopenharmony_ci<ul> 11891cb0ef41Sopenharmony_ci<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> Optional, an error to emit with <code>'error'</code> event.</li> 11901cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this" class="type"><this></a></li> 11911cb0ef41Sopenharmony_ci</ul> 11921cb0ef41Sopenharmony_ci<p>Destroy the stream. Optionally emit an <code>'error'</code> event, and emit a <code>'close'</code> 11931cb0ef41Sopenharmony_cievent (unless <code>emitClose</code> is set to <code>false</code>). After this call, the writable 11941cb0ef41Sopenharmony_cistream has ended and subsequent calls to <code>write()</code> or <code>end()</code> will result in 11951cb0ef41Sopenharmony_cian <code>ERR_STREAM_DESTROYED</code> error. 11961cb0ef41Sopenharmony_ciThis is a destructive and immediate way to destroy a stream. Previous calls to 11971cb0ef41Sopenharmony_ci<code>write()</code> may not have drained, and may trigger an <code>ERR_STREAM_DESTROYED</code> error. 11981cb0ef41Sopenharmony_ciUse <code>end()</code> instead of destroy if data should flush before close, or wait for 11991cb0ef41Sopenharmony_cithe <code>'drain'</code> event before destroying the stream.</p> 12001cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 12011cb0ef41Sopenharmony_ci 12021cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myStream = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Writable</span>(); 12031cb0ef41Sopenharmony_ci 12041cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fooErr = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Error</span>(<span class="hljs-string">'foo error'</span>); 12051cb0ef41Sopenharmony_cimyStream.<span class="hljs-title function_">destroy</span>(fooErr); 12061cb0ef41Sopenharmony_cimyStream.<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span class="hljs-function">(<span class="hljs-params">fooErr</span>) =></span> <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(fooErr.<span class="hljs-property">message</span>)); <span class="hljs-comment">// foo error</span></code> <button class="copy-button">copy</button></pre> 12071cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 12081cb0ef41Sopenharmony_ci 12091cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myStream = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Writable</span>(); 12101cb0ef41Sopenharmony_ci 12111cb0ef41Sopenharmony_cimyStream.<span class="hljs-title function_">destroy</span>(); 12121cb0ef41Sopenharmony_cimyStream.<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, <span class="hljs-keyword">function</span> <span class="hljs-title function_">wontHappen</span>(<span class="hljs-params"></span>) {});</code> <button class="copy-button">copy</button></pre> 12131cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 12141cb0ef41Sopenharmony_ci 12151cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myStream = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Writable</span>(); 12161cb0ef41Sopenharmony_cimyStream.<span class="hljs-title function_">destroy</span>(); 12171cb0ef41Sopenharmony_ci 12181cb0ef41Sopenharmony_cimyStream.<span class="hljs-title function_">write</span>(<span class="hljs-string">'foo'</span>, <span class="hljs-function">(<span class="hljs-params">error</span>) =></span> <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(error.<span class="hljs-property">code</span>)); 12191cb0ef41Sopenharmony_ci<span class="hljs-comment">// ERR_STREAM_DESTROYED</span></code> <button class="copy-button">copy</button></pre> 12201cb0ef41Sopenharmony_ci<p>Once <code>destroy()</code> has been called any further calls will be a no-op and no 12211cb0ef41Sopenharmony_cifurther errors except from <code>_destroy()</code> may be emitted as <code>'error'</code>.</p> 12221cb0ef41Sopenharmony_ci<p>Implementors should not override this method, 12231cb0ef41Sopenharmony_cibut instead implement <a href="#writable_destroyerr-callback"><code>writable._destroy()</code></a>.</p> 12241cb0ef41Sopenharmony_ci<h6><code>writable.closed</code><span><a class="mark" href="#writableclosed" id="writableclosed">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_closed"></a></h6> 12251cb0ef41Sopenharmony_ci<div class="api_metadata"> 12261cb0ef41Sopenharmony_ci<span>Added in: v18.0.0</span> 12271cb0ef41Sopenharmony_ci</div> 12281cb0ef41Sopenharmony_ci<ul> 12291cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 12301cb0ef41Sopenharmony_ci</ul> 12311cb0ef41Sopenharmony_ci<p>Is <code>true</code> after <code>'close'</code> has been emitted.</p> 12321cb0ef41Sopenharmony_ci<h6><code>writable.destroyed</code><span><a class="mark" href="#writabledestroyed" id="writabledestroyed">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_destroyed"></a></h6> 12331cb0ef41Sopenharmony_ci<div class="api_metadata"> 12341cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 12351cb0ef41Sopenharmony_ci</div> 12361cb0ef41Sopenharmony_ci<ul> 12371cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 12381cb0ef41Sopenharmony_ci</ul> 12391cb0ef41Sopenharmony_ci<p>Is <code>true</code> after <a href="#writabledestroyerror"><code>writable.destroy()</code></a> has been called.</p> 12401cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 12411cb0ef41Sopenharmony_ci 12421cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myStream = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Writable</span>(); 12431cb0ef41Sopenharmony_ci 12441cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(myStream.<span class="hljs-property">destroyed</span>); <span class="hljs-comment">// false</span> 12451cb0ef41Sopenharmony_cimyStream.<span class="hljs-title function_">destroy</span>(); 12461cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(myStream.<span class="hljs-property">destroyed</span>); <span class="hljs-comment">// true</span></code> <button class="copy-button">copy</button></pre> 12471cb0ef41Sopenharmony_ci<h6><code>writable.end([chunk[, encoding]][, callback])</code><span><a class="mark" href="#writableendchunk-encoding-callback" id="writableendchunk-encoding-callback">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_end_chunk_encoding_callback"></a></h6> 12481cb0ef41Sopenharmony_ci<div class="api_metadata"> 12491cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 12501cb0ef41Sopenharmony_ci<table> 12511cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 12521cb0ef41Sopenharmony_ci<tr><td>v15.0.0</td> 12531cb0ef41Sopenharmony_ci<td><p>The <code>callback</code> is invoked before 'finish' or on error.</p></td></tr> 12541cb0ef41Sopenharmony_ci<tr><td>v14.0.0</td> 12551cb0ef41Sopenharmony_ci<td><p>The <code>callback</code> is invoked if 'finish' or 'error' is emitted.</p></td></tr> 12561cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 12571cb0ef41Sopenharmony_ci<td><p>This method now returns a reference to <code>writable</code>.</p></td></tr> 12581cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 12591cb0ef41Sopenharmony_ci<td><p>The <code>chunk</code> argument can now be a <code>Uint8Array</code> instance.</p></td></tr> 12601cb0ef41Sopenharmony_ci<tr><td>v0.9.4</td> 12611cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.9.4</span></p></td></tr> 12621cb0ef41Sopenharmony_ci</tbody></table> 12631cb0ef41Sopenharmony_ci</details> 12641cb0ef41Sopenharmony_ci</div> 12651cb0ef41Sopenharmony_ci<ul> 12661cb0ef41Sopenharmony_ci<li><code>chunk</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> Optional data to write. For streams 12671cb0ef41Sopenharmony_cinot operating in object mode, <code>chunk</code> must be a string, <code>Buffer</code> or 12681cb0ef41Sopenharmony_ci<code>Uint8Array</code>. For object mode streams, <code>chunk</code> may be any JavaScript value 12691cb0ef41Sopenharmony_ciother than <code>null</code>.</li> 12701cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The encoding if <code>chunk</code> is a string</li> 12711cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Callback for when the stream is finished.</li> 12721cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this" class="type"><this></a></li> 12731cb0ef41Sopenharmony_ci</ul> 12741cb0ef41Sopenharmony_ci<p>Calling the <code>writable.end()</code> method signals that no more data will be written 12751cb0ef41Sopenharmony_cito the <a href="#class-streamwritable"><code>Writable</code></a>. The optional <code>chunk</code> and <code>encoding</code> arguments allow one 12761cb0ef41Sopenharmony_cifinal additional chunk of data to be written immediately before closing the 12771cb0ef41Sopenharmony_cistream.</p> 12781cb0ef41Sopenharmony_ci<p>Calling the <a href="#writablewritechunk-encoding-callback"><code>stream.write()</code></a> method after calling 12791cb0ef41Sopenharmony_ci<a href="#writableendchunk-encoding-callback"><code>stream.end()</code></a> will raise an error.</p> 12801cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// Write 'hello, ' and then end with 'world!'.</span> 12811cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 12821cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> file = fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'example.txt'</span>); 12831cb0ef41Sopenharmony_cifile.<span class="hljs-title function_">write</span>(<span class="hljs-string">'hello, '</span>); 12841cb0ef41Sopenharmony_cifile.<span class="hljs-title function_">end</span>(<span class="hljs-string">'world!'</span>); 12851cb0ef41Sopenharmony_ci<span class="hljs-comment">// Writing more now is not allowed!</span></code> <button class="copy-button">copy</button></pre> 12861cb0ef41Sopenharmony_ci<h6><code>writable.setDefaultEncoding(encoding)</code><span><a class="mark" href="#writablesetdefaultencodingencoding" id="writablesetdefaultencodingencoding">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_setdefaultencoding_encoding"></a></h6> 12871cb0ef41Sopenharmony_ci<div class="api_metadata"> 12881cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 12891cb0ef41Sopenharmony_ci<table> 12901cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 12911cb0ef41Sopenharmony_ci<tr><td>v6.1.0</td> 12921cb0ef41Sopenharmony_ci<td><p>This method now returns a reference to <code>writable</code>.</p></td></tr> 12931cb0ef41Sopenharmony_ci<tr><td>v0.11.15</td> 12941cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.11.15</span></p></td></tr> 12951cb0ef41Sopenharmony_ci</tbody></table> 12961cb0ef41Sopenharmony_ci</details> 12971cb0ef41Sopenharmony_ci</div> 12981cb0ef41Sopenharmony_ci<ul> 12991cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The new default encoding</li> 13001cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this" class="type"><this></a></li> 13011cb0ef41Sopenharmony_ci</ul> 13021cb0ef41Sopenharmony_ci<p>The <code>writable.setDefaultEncoding()</code> method sets the default <code>encoding</code> for a 13031cb0ef41Sopenharmony_ci<a href="#class-streamwritable"><code>Writable</code></a> stream.</p> 13041cb0ef41Sopenharmony_ci<h6><code>writable.uncork()</code><span><a class="mark" href="#writableuncork" id="writableuncork">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_uncork"></a></h6> 13051cb0ef41Sopenharmony_ci<div class="api_metadata"> 13061cb0ef41Sopenharmony_ci<span>Added in: v0.11.2</span> 13071cb0ef41Sopenharmony_ci</div> 13081cb0ef41Sopenharmony_ci<p>The <code>writable.uncork()</code> method flushes all data buffered since 13091cb0ef41Sopenharmony_ci<a href="#writablecork"><code>stream.cork()</code></a> was called.</p> 13101cb0ef41Sopenharmony_ci<p>When using <a href="#writablecork"><code>writable.cork()</code></a> and <code>writable.uncork()</code> to manage the buffering 13111cb0ef41Sopenharmony_ciof writes to a stream, defer calls to <code>writable.uncork()</code> using 13121cb0ef41Sopenharmony_ci<code>process.nextTick()</code>. Doing so allows batching of all 13131cb0ef41Sopenharmony_ci<code>writable.write()</code> calls that occur within a given Node.js event loop phase.</p> 13141cb0ef41Sopenharmony_ci<pre><code class="language-js">stream.<span class="hljs-title function_">cork</span>(); 13151cb0ef41Sopenharmony_cistream.<span class="hljs-title function_">write</span>(<span class="hljs-string">'some '</span>); 13161cb0ef41Sopenharmony_cistream.<span class="hljs-title function_">write</span>(<span class="hljs-string">'data '</span>); 13171cb0ef41Sopenharmony_ciprocess.<span class="hljs-title function_">nextTick</span>(<span class="hljs-function">() =></span> stream.<span class="hljs-title function_">uncork</span>());</code> <button class="copy-button">copy</button></pre> 13181cb0ef41Sopenharmony_ci<p>If the <a href="#writablecork"><code>writable.cork()</code></a> method is called multiple times on a stream, the 13191cb0ef41Sopenharmony_cisame number of calls to <code>writable.uncork()</code> must be called to flush the buffered 13201cb0ef41Sopenharmony_cidata.</p> 13211cb0ef41Sopenharmony_ci<pre><code class="language-js">stream.<span class="hljs-title function_">cork</span>(); 13221cb0ef41Sopenharmony_cistream.<span class="hljs-title function_">write</span>(<span class="hljs-string">'some '</span>); 13231cb0ef41Sopenharmony_cistream.<span class="hljs-title function_">cork</span>(); 13241cb0ef41Sopenharmony_cistream.<span class="hljs-title function_">write</span>(<span class="hljs-string">'data '</span>); 13251cb0ef41Sopenharmony_ciprocess.<span class="hljs-title function_">nextTick</span>(<span class="hljs-function">() =></span> { 13261cb0ef41Sopenharmony_ci stream.<span class="hljs-title function_">uncork</span>(); 13271cb0ef41Sopenharmony_ci <span class="hljs-comment">// The data will not be flushed until uncork() is called a second time.</span> 13281cb0ef41Sopenharmony_ci stream.<span class="hljs-title function_">uncork</span>(); 13291cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 13301cb0ef41Sopenharmony_ci<p>See also: <a href="#writablecork"><code>writable.cork()</code></a>.</p> 13311cb0ef41Sopenharmony_ci<h6><code>writable.writable</code><span><a class="mark" href="#writablewritable" id="writablewritable">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_writable"></a></h6> 13321cb0ef41Sopenharmony_ci<div class="api_metadata"> 13331cb0ef41Sopenharmony_ci<span>Added in: v11.4.0</span> 13341cb0ef41Sopenharmony_ci</div> 13351cb0ef41Sopenharmony_ci<ul> 13361cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 13371cb0ef41Sopenharmony_ci</ul> 13381cb0ef41Sopenharmony_ci<p>Is <code>true</code> if it is safe to call <a href="#writablewritechunk-encoding-callback"><code>writable.write()</code></a>, which means 13391cb0ef41Sopenharmony_cithe stream has not been destroyed, errored, or ended.</p> 13401cb0ef41Sopenharmony_ci<h6><code>writable.writableAborted</code><span><a class="mark" href="#writablewritableaborted" id="writablewritableaborted">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_writableaborted"></a></h6> 13411cb0ef41Sopenharmony_ci<div class="api_metadata"> 13421cb0ef41Sopenharmony_ci<span>Added in: v18.0.0</span> 13431cb0ef41Sopenharmony_ci</div> 13441cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 13451cb0ef41Sopenharmony_ci<ul> 13461cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 13471cb0ef41Sopenharmony_ci</ul> 13481cb0ef41Sopenharmony_ci<p>Returns whether the stream was destroyed or errored before emitting <code>'finish'</code>.</p> 13491cb0ef41Sopenharmony_ci<h6><code>writable.writableEnded</code><span><a class="mark" href="#writablewritableended" id="writablewritableended">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_writableended"></a></h6> 13501cb0ef41Sopenharmony_ci<div class="api_metadata"> 13511cb0ef41Sopenharmony_ci<span>Added in: v12.9.0</span> 13521cb0ef41Sopenharmony_ci</div> 13531cb0ef41Sopenharmony_ci<ul> 13541cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 13551cb0ef41Sopenharmony_ci</ul> 13561cb0ef41Sopenharmony_ci<p>Is <code>true</code> after <a href="#writableendchunk-encoding-callback"><code>writable.end()</code></a> has been called. This property 13571cb0ef41Sopenharmony_cidoes not indicate whether the data has been flushed, for this use 13581cb0ef41Sopenharmony_ci<a href="#writablewritablefinished"><code>writable.writableFinished</code></a> instead.</p> 13591cb0ef41Sopenharmony_ci<h6><code>writable.writableCorked</code><span><a class="mark" href="#writablewritablecorked" id="writablewritablecorked">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_writablecorked"></a></h6> 13601cb0ef41Sopenharmony_ci<div class="api_metadata"> 13611cb0ef41Sopenharmony_ci<span>Added in: v13.2.0, v12.16.0</span> 13621cb0ef41Sopenharmony_ci</div> 13631cb0ef41Sopenharmony_ci<ul> 13641cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 13651cb0ef41Sopenharmony_ci</ul> 13661cb0ef41Sopenharmony_ci<p>Number of times <a href="#writableuncork"><code>writable.uncork()</code></a> needs to be 13671cb0ef41Sopenharmony_cicalled in order to fully uncork the stream.</p> 13681cb0ef41Sopenharmony_ci<h6><code>writable.errored</code><span><a class="mark" href="#writableerrored" id="writableerrored">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_errored"></a></h6> 13691cb0ef41Sopenharmony_ci<div class="api_metadata"> 13701cb0ef41Sopenharmony_ci<span>Added in: v18.0.0</span> 13711cb0ef41Sopenharmony_ci</div> 13721cb0ef41Sopenharmony_ci<ul> 13731cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 13741cb0ef41Sopenharmony_ci</ul> 13751cb0ef41Sopenharmony_ci<p>Returns error if the stream has been destroyed with an error.</p> 13761cb0ef41Sopenharmony_ci<h6><code>writable.writableFinished</code><span><a class="mark" href="#writablewritablefinished" id="writablewritablefinished">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_writablefinished"></a></h6> 13771cb0ef41Sopenharmony_ci<div class="api_metadata"> 13781cb0ef41Sopenharmony_ci<span>Added in: v12.6.0</span> 13791cb0ef41Sopenharmony_ci</div> 13801cb0ef41Sopenharmony_ci<ul> 13811cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 13821cb0ef41Sopenharmony_ci</ul> 13831cb0ef41Sopenharmony_ci<p>Is set to <code>true</code> immediately before the <a href="#event-finish"><code>'finish'</code></a> event is emitted.</p> 13841cb0ef41Sopenharmony_ci<h6><code>writable.writableHighWaterMark</code><span><a class="mark" href="#writablewritablehighwatermark" id="writablewritablehighwatermark">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_writablehighwatermark"></a></h6> 13851cb0ef41Sopenharmony_ci<div class="api_metadata"> 13861cb0ef41Sopenharmony_ci<span>Added in: v9.3.0</span> 13871cb0ef41Sopenharmony_ci</div> 13881cb0ef41Sopenharmony_ci<ul> 13891cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 13901cb0ef41Sopenharmony_ci</ul> 13911cb0ef41Sopenharmony_ci<p>Return the value of <code>highWaterMark</code> passed when creating this <code>Writable</code>.</p> 13921cb0ef41Sopenharmony_ci<h6><code>writable.writableLength</code><span><a class="mark" href="#writablewritablelength" id="writablewritablelength">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_writablelength"></a></h6> 13931cb0ef41Sopenharmony_ci<div class="api_metadata"> 13941cb0ef41Sopenharmony_ci<span>Added in: v9.4.0</span> 13951cb0ef41Sopenharmony_ci</div> 13961cb0ef41Sopenharmony_ci<ul> 13971cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 13981cb0ef41Sopenharmony_ci</ul> 13991cb0ef41Sopenharmony_ci<p>This property contains the number of bytes (or objects) in the queue 14001cb0ef41Sopenharmony_ciready to be written. The value provides introspection data regarding 14011cb0ef41Sopenharmony_cithe status of the <code>highWaterMark</code>.</p> 14021cb0ef41Sopenharmony_ci<h6><code>writable.writableNeedDrain</code><span><a class="mark" href="#writablewritableneeddrain" id="writablewritableneeddrain">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_writableneeddrain"></a></h6> 14031cb0ef41Sopenharmony_ci<div class="api_metadata"> 14041cb0ef41Sopenharmony_ci<span>Added in: v15.2.0, v14.17.0</span> 14051cb0ef41Sopenharmony_ci</div> 14061cb0ef41Sopenharmony_ci<ul> 14071cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 14081cb0ef41Sopenharmony_ci</ul> 14091cb0ef41Sopenharmony_ci<p>Is <code>true</code> if the stream's buffer has been full and stream will emit <code>'drain'</code>.</p> 14101cb0ef41Sopenharmony_ci<h6><code>writable.writableObjectMode</code><span><a class="mark" href="#writablewritableobjectmode" id="writablewritableobjectmode">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_writableobjectmode"></a></h6> 14111cb0ef41Sopenharmony_ci<div class="api_metadata"> 14121cb0ef41Sopenharmony_ci<span>Added in: v12.3.0</span> 14131cb0ef41Sopenharmony_ci</div> 14141cb0ef41Sopenharmony_ci<ul> 14151cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 14161cb0ef41Sopenharmony_ci</ul> 14171cb0ef41Sopenharmony_ci<p>Getter for the property <code>objectMode</code> of a given <code>Writable</code> stream.</p> 14181cb0ef41Sopenharmony_ci<h6><code>writable.write(chunk[, encoding][, callback])</code><span><a class="mark" href="#writablewritechunk-encoding-callback" id="writablewritechunk-encoding-callback">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_write_chunk_encoding_callback"></a></h6> 14191cb0ef41Sopenharmony_ci<div class="api_metadata"> 14201cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 14211cb0ef41Sopenharmony_ci<table> 14221cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 14231cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 14241cb0ef41Sopenharmony_ci<td><p>The <code>chunk</code> argument can now be a <code>Uint8Array</code> instance.</p></td></tr> 14251cb0ef41Sopenharmony_ci<tr><td>v6.0.0</td> 14261cb0ef41Sopenharmony_ci<td><p>Passing <code>null</code> as the <code>chunk</code> parameter will always be considered invalid now, even in object mode.</p></td></tr> 14271cb0ef41Sopenharmony_ci<tr><td>v0.9.4</td> 14281cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.9.4</span></p></td></tr> 14291cb0ef41Sopenharmony_ci</tbody></table> 14301cb0ef41Sopenharmony_ci</details> 14311cb0ef41Sopenharmony_ci</div> 14321cb0ef41Sopenharmony_ci<ul> 14331cb0ef41Sopenharmony_ci<li><code>chunk</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> Optional data to write. For streams 14341cb0ef41Sopenharmony_cinot operating in object mode, <code>chunk</code> must be a string, <code>Buffer</code> or 14351cb0ef41Sopenharmony_ci<code>Uint8Array</code>. For object mode streams, <code>chunk</code> may be any JavaScript value 14361cb0ef41Sopenharmony_ciother than <code>null</code>.</li> 14371cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> The encoding, if <code>chunk</code> is a string. <strong>Default:</strong> <code>'utf8'</code></li> 14381cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Callback for when this chunk of data is flushed.</li> 14391cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <code>false</code> if the stream wishes for the calling code to 14401cb0ef41Sopenharmony_ciwait for the <code>'drain'</code> event to be emitted before continuing to write 14411cb0ef41Sopenharmony_ciadditional data; otherwise <code>true</code>.</li> 14421cb0ef41Sopenharmony_ci</ul> 14431cb0ef41Sopenharmony_ci<p>The <code>writable.write()</code> method writes some data to the stream, and calls the 14441cb0ef41Sopenharmony_cisupplied <code>callback</code> once the data has been fully handled. If an error 14451cb0ef41Sopenharmony_cioccurs, the <code>callback</code> will be called with the error as its 14461cb0ef41Sopenharmony_cifirst argument. The <code>callback</code> is called asynchronously and before <code>'error'</code> is 14471cb0ef41Sopenharmony_ciemitted.</p> 14481cb0ef41Sopenharmony_ci<p>The return value is <code>true</code> if the internal buffer is less than the 14491cb0ef41Sopenharmony_ci<code>highWaterMark</code> configured when the stream was created after admitting <code>chunk</code>. 14501cb0ef41Sopenharmony_ciIf <code>false</code> is returned, further attempts to write data to the stream should 14511cb0ef41Sopenharmony_cistop until the <a href="#event-drain"><code>'drain'</code></a> event is emitted.</p> 14521cb0ef41Sopenharmony_ci<p>While a stream is not draining, calls to <code>write()</code> will buffer <code>chunk</code>, and 14531cb0ef41Sopenharmony_cireturn false. Once all currently buffered chunks are drained (accepted for 14541cb0ef41Sopenharmony_cidelivery by the operating system), the <code>'drain'</code> event will be emitted. 14551cb0ef41Sopenharmony_ciOnce <code>write()</code> returns false, do not write more chunks 14561cb0ef41Sopenharmony_ciuntil the <code>'drain'</code> event is emitted. While calling <code>write()</code> on a stream that 14571cb0ef41Sopenharmony_ciis not draining is allowed, Node.js will buffer all written chunks until 14581cb0ef41Sopenharmony_cimaximum memory usage occurs, at which point it will abort unconditionally. 14591cb0ef41Sopenharmony_ciEven before it aborts, high memory usage will cause poor garbage collector 14601cb0ef41Sopenharmony_ciperformance and high RSS (which is not typically released back to the system, 14611cb0ef41Sopenharmony_cieven after the memory is no longer required). Since TCP sockets may never 14621cb0ef41Sopenharmony_cidrain if the remote peer does not read the data, writing a socket that is 14631cb0ef41Sopenharmony_cinot draining may lead to a remotely exploitable vulnerability.</p> 14641cb0ef41Sopenharmony_ci<p>Writing data while the stream is not draining is particularly 14651cb0ef41Sopenharmony_ciproblematic for a <a href="#class-streamtransform"><code>Transform</code></a>, because the <code>Transform</code> streams are paused 14661cb0ef41Sopenharmony_ciby default until they are piped or a <code>'data'</code> or <code>'readable'</code> event handler 14671cb0ef41Sopenharmony_ciis added.</p> 14681cb0ef41Sopenharmony_ci<p>If the data to be written can be generated or fetched on demand, it is 14691cb0ef41Sopenharmony_cirecommended to encapsulate the logic into a <a href="#class-streamreadable"><code>Readable</code></a> and use 14701cb0ef41Sopenharmony_ci<a href="#readablepipedestination-options"><code>stream.pipe()</code></a>. However, if calling <code>write()</code> is preferred, it is 14711cb0ef41Sopenharmony_cipossible to respect backpressure and avoid memory issues using the 14721cb0ef41Sopenharmony_ci<a href="#event-drain"><code>'drain'</code></a> event:</p> 14731cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">function</span> <span class="hljs-title function_">write</span>(<span class="hljs-params">data, cb</span>) { 14741cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (!stream.<span class="hljs-title function_">write</span>(data)) { 14751cb0ef41Sopenharmony_ci stream.<span class="hljs-title function_">once</span>(<span class="hljs-string">'drain'</span>, cb); 14761cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 14771cb0ef41Sopenharmony_ci process.<span class="hljs-title function_">nextTick</span>(cb); 14781cb0ef41Sopenharmony_ci } 14791cb0ef41Sopenharmony_ci} 14801cb0ef41Sopenharmony_ci 14811cb0ef41Sopenharmony_ci<span class="hljs-comment">// Wait for cb to be called before doing any other write.</span> 14821cb0ef41Sopenharmony_ci<span class="hljs-title function_">write</span>(<span class="hljs-string">'hello'</span>, <span class="hljs-function">() =></span> { 14831cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Write completed, do more writes now.'</span>); 14841cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 14851cb0ef41Sopenharmony_ci<p>A <code>Writable</code> stream in object mode will always ignore the <code>encoding</code> argument.</p> 14861cb0ef41Sopenharmony_ci<h4>Readable streams<span><a class="mark" href="#readable-streams" id="readable-streams">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_streams"></a></h4> 14871cb0ef41Sopenharmony_ci<p>Readable streams are an abstraction for a <em>source</em> from which data is 14881cb0ef41Sopenharmony_ciconsumed.</p> 14891cb0ef41Sopenharmony_ci<p>Examples of <code>Readable</code> streams include:</p> 14901cb0ef41Sopenharmony_ci<ul> 14911cb0ef41Sopenharmony_ci<li><a href="http.html#class-httpincomingmessage">HTTP responses, on the client</a></li> 14921cb0ef41Sopenharmony_ci<li><a href="http.html#class-httpincomingmessage">HTTP requests, on the server</a></li> 14931cb0ef41Sopenharmony_ci<li><a href="fs.html#class-fsreadstream">fs read streams</a></li> 14941cb0ef41Sopenharmony_ci<li><a href="zlib.html">zlib streams</a></li> 14951cb0ef41Sopenharmony_ci<li><a href="crypto.html">crypto streams</a></li> 14961cb0ef41Sopenharmony_ci<li><a href="net.html#class-netsocket">TCP sockets</a></li> 14971cb0ef41Sopenharmony_ci<li><a href="child_process.html#subprocessstdout">child process stdout and stderr</a></li> 14981cb0ef41Sopenharmony_ci<li><a href="process.html#processstdin"><code>process.stdin</code></a></li> 14991cb0ef41Sopenharmony_ci</ul> 15001cb0ef41Sopenharmony_ci<p>All <a href="#class-streamreadable"><code>Readable</code></a> streams implement the interface defined by the 15011cb0ef41Sopenharmony_ci<code>stream.Readable</code> class.</p> 15021cb0ef41Sopenharmony_ci<h5>Two reading modes<span><a class="mark" href="#two-reading-modes" id="two-reading-modes">#</a></span><a aria-hidden="true" class="legacy" id="stream_two_reading_modes"></a></h5> 15031cb0ef41Sopenharmony_ci<p><code>Readable</code> streams effectively operate in one of two modes: flowing and 15041cb0ef41Sopenharmony_cipaused. These modes are separate from <a href="#object-mode">object mode</a>. 15051cb0ef41Sopenharmony_ciA <a href="#class-streamreadable"><code>Readable</code></a> stream can be in object mode or not, regardless of whether 15061cb0ef41Sopenharmony_ciit is in flowing mode or paused mode.</p> 15071cb0ef41Sopenharmony_ci<ul> 15081cb0ef41Sopenharmony_ci<li> 15091cb0ef41Sopenharmony_ci<p>In flowing mode, data is read from the underlying system automatically 15101cb0ef41Sopenharmony_ciand provided to an application as quickly as possible using events via the 15111cb0ef41Sopenharmony_ci<a href="events.html#class-eventemitter"><code>EventEmitter</code></a> interface.</p> 15121cb0ef41Sopenharmony_ci</li> 15131cb0ef41Sopenharmony_ci<li> 15141cb0ef41Sopenharmony_ci<p>In paused mode, the <a href="#readablereadsize"><code>stream.read()</code></a> method must be called 15151cb0ef41Sopenharmony_ciexplicitly to read chunks of data from the stream.</p> 15161cb0ef41Sopenharmony_ci</li> 15171cb0ef41Sopenharmony_ci</ul> 15181cb0ef41Sopenharmony_ci<p>All <a href="#class-streamreadable"><code>Readable</code></a> streams begin in paused mode but can be switched to flowing 15191cb0ef41Sopenharmony_cimode in one of the following ways:</p> 15201cb0ef41Sopenharmony_ci<ul> 15211cb0ef41Sopenharmony_ci<li>Adding a <a href="#event-data"><code>'data'</code></a> event handler.</li> 15221cb0ef41Sopenharmony_ci<li>Calling the <a href="#readableresume"><code>stream.resume()</code></a> method.</li> 15231cb0ef41Sopenharmony_ci<li>Calling the <a href="#readablepipedestination-options"><code>stream.pipe()</code></a> method to send the data to a <a href="#class-streamwritable"><code>Writable</code></a>.</li> 15241cb0ef41Sopenharmony_ci</ul> 15251cb0ef41Sopenharmony_ci<p>The <code>Readable</code> can switch back to paused mode using one of the following:</p> 15261cb0ef41Sopenharmony_ci<ul> 15271cb0ef41Sopenharmony_ci<li>If there are no pipe destinations, by calling the 15281cb0ef41Sopenharmony_ci<a href="#readablepause"><code>stream.pause()</code></a> method.</li> 15291cb0ef41Sopenharmony_ci<li>If there are pipe destinations, by removing all pipe destinations. 15301cb0ef41Sopenharmony_ciMultiple pipe destinations may be removed by calling the 15311cb0ef41Sopenharmony_ci<a href="#readableunpipedestination"><code>stream.unpipe()</code></a> method.</li> 15321cb0ef41Sopenharmony_ci</ul> 15331cb0ef41Sopenharmony_ci<p>The important concept to remember is that a <code>Readable</code> will not generate data 15341cb0ef41Sopenharmony_ciuntil a mechanism for either consuming or ignoring that data is provided. If 15351cb0ef41Sopenharmony_cithe consuming mechanism is disabled or taken away, the <code>Readable</code> will <em>attempt</em> 15361cb0ef41Sopenharmony_cito stop generating the data.</p> 15371cb0ef41Sopenharmony_ci<p>For backward compatibility reasons, removing <a href="#event-data"><code>'data'</code></a> event handlers will 15381cb0ef41Sopenharmony_ci<strong>not</strong> automatically pause the stream. Also, if there are piped destinations, 15391cb0ef41Sopenharmony_cithen calling <a href="#readablepause"><code>stream.pause()</code></a> will not guarantee that the 15401cb0ef41Sopenharmony_cistream will <em>remain</em> paused once those destinations drain and ask for more data.</p> 15411cb0ef41Sopenharmony_ci<p>If a <a href="#class-streamreadable"><code>Readable</code></a> is switched into flowing mode and there are no consumers 15421cb0ef41Sopenharmony_ciavailable to handle the data, that data will be lost. This can occur, for 15431cb0ef41Sopenharmony_ciinstance, when the <code>readable.resume()</code> method is called without a listener 15441cb0ef41Sopenharmony_ciattached to the <code>'data'</code> event, or when a <code>'data'</code> event handler is removed 15451cb0ef41Sopenharmony_cifrom the stream.</p> 15461cb0ef41Sopenharmony_ci<p>Adding a <a href="#event-readable"><code>'readable'</code></a> event handler automatically makes the stream 15471cb0ef41Sopenharmony_cistop flowing, and the data has to be consumed via 15481cb0ef41Sopenharmony_ci<a href="#readablereadsize"><code>readable.read()</code></a>. If the <a href="#event-readable"><code>'readable'</code></a> event handler is 15491cb0ef41Sopenharmony_ciremoved, then the stream will start flowing again if there is a 15501cb0ef41Sopenharmony_ci<a href="#event-data"><code>'data'</code></a> event handler.</p> 15511cb0ef41Sopenharmony_ci<h5>Three states<span><a class="mark" href="#three-states" id="three-states">#</a></span><a aria-hidden="true" class="legacy" id="stream_three_states"></a></h5> 15521cb0ef41Sopenharmony_ci<p>The "two modes" of operation for a <code>Readable</code> stream are a simplified 15531cb0ef41Sopenharmony_ciabstraction for the more complicated internal state management that is happening 15541cb0ef41Sopenharmony_ciwithin the <code>Readable</code> stream implementation.</p> 15551cb0ef41Sopenharmony_ci<p>Specifically, at any given point in time, every <code>Readable</code> is in one of three 15561cb0ef41Sopenharmony_cipossible states:</p> 15571cb0ef41Sopenharmony_ci<ul> 15581cb0ef41Sopenharmony_ci<li><code>readable.readableFlowing === null</code></li> 15591cb0ef41Sopenharmony_ci<li><code>readable.readableFlowing === false</code></li> 15601cb0ef41Sopenharmony_ci<li><code>readable.readableFlowing === true</code></li> 15611cb0ef41Sopenharmony_ci</ul> 15621cb0ef41Sopenharmony_ci<p>When <code>readable.readableFlowing</code> is <code>null</code>, no mechanism for consuming the 15631cb0ef41Sopenharmony_cistream's data is provided. Therefore, the stream will not generate data. 15641cb0ef41Sopenharmony_ciWhile in this state, attaching a listener for the <code>'data'</code> event, calling the 15651cb0ef41Sopenharmony_ci<code>readable.pipe()</code> method, or calling the <code>readable.resume()</code> method will switch 15661cb0ef41Sopenharmony_ci<code>readable.readableFlowing</code> to <code>true</code>, causing the <code>Readable</code> to begin actively 15671cb0ef41Sopenharmony_ciemitting events as data is generated.</p> 15681cb0ef41Sopenharmony_ci<p>Calling <code>readable.pause()</code>, <code>readable.unpipe()</code>, or receiving backpressure 15691cb0ef41Sopenharmony_ciwill cause the <code>readable.readableFlowing</code> to be set as <code>false</code>, 15701cb0ef41Sopenharmony_citemporarily halting the flowing of events but <em>not</em> halting the generation of 15711cb0ef41Sopenharmony_cidata. While in this state, attaching a listener for the <code>'data'</code> event 15721cb0ef41Sopenharmony_ciwill not switch <code>readable.readableFlowing</code> to <code>true</code>.</p> 15731cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">PassThrough</span>, <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 15741cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> pass = <span class="hljs-keyword">new</span> <span class="hljs-title class_">PassThrough</span>(); 15751cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> writable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Writable</span>(); 15761cb0ef41Sopenharmony_ci 15771cb0ef41Sopenharmony_cipass.<span class="hljs-title function_">pipe</span>(writable); 15781cb0ef41Sopenharmony_cipass.<span class="hljs-title function_">unpipe</span>(writable); 15791cb0ef41Sopenharmony_ci<span class="hljs-comment">// readableFlowing is now false.</span> 15801cb0ef41Sopenharmony_ci 15811cb0ef41Sopenharmony_cipass.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> { <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk.<span class="hljs-title function_">toString</span>()); }); 15821cb0ef41Sopenharmony_ci<span class="hljs-comment">// readableFlowing is still false.</span> 15831cb0ef41Sopenharmony_cipass.<span class="hljs-title function_">write</span>(<span class="hljs-string">'ok'</span>); <span class="hljs-comment">// Will not emit 'data'.</span> 15841cb0ef41Sopenharmony_cipass.<span class="hljs-title function_">resume</span>(); <span class="hljs-comment">// Must be called to make stream emit 'data'.</span> 15851cb0ef41Sopenharmony_ci<span class="hljs-comment">// readableFlowing is now true.</span></code> <button class="copy-button">copy</button></pre> 15861cb0ef41Sopenharmony_ci<p>While <code>readable.readableFlowing</code> is <code>false</code>, data may be accumulating 15871cb0ef41Sopenharmony_ciwithin the stream's internal buffer.</p> 15881cb0ef41Sopenharmony_ci<h5>Choose one API style<span><a class="mark" href="#choose-one-api-style" id="choose-one-api-style">#</a></span><a aria-hidden="true" class="legacy" id="stream_choose_one_api_style"></a></h5> 15891cb0ef41Sopenharmony_ci<p>The <code>Readable</code> stream API evolved across multiple Node.js versions and provides 15901cb0ef41Sopenharmony_cimultiple methods of consuming stream data. In general, developers should choose 15911cb0ef41Sopenharmony_ci<em>one</em> of the methods of consuming data and <em>should never</em> use multiple methods 15921cb0ef41Sopenharmony_cito consume data from a single stream. Specifically, using a combination 15931cb0ef41Sopenharmony_ciof <code>on('data')</code>, <code>on('readable')</code>, <code>pipe()</code>, or async iterators could 15941cb0ef41Sopenharmony_cilead to unintuitive behavior.</p> 15951cb0ef41Sopenharmony_ci<h5>Class: <code>stream.Readable</code><span><a class="mark" href="#class-streamreadable" id="class-streamreadable">#</a></span><a aria-hidden="true" class="legacy" id="stream_class_stream_readable"></a></h5> 15961cb0ef41Sopenharmony_ci<div class="api_metadata"> 15971cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 15981cb0ef41Sopenharmony_ci</div> 15991cb0ef41Sopenharmony_ci 16001cb0ef41Sopenharmony_ci<h6>Event: <code>'close'</code><span><a class="mark" href="#event-close_1" id="event-close_1">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_close_1"></a></h6> 16011cb0ef41Sopenharmony_ci<div class="api_metadata"> 16021cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 16031cb0ef41Sopenharmony_ci<table> 16041cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 16051cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 16061cb0ef41Sopenharmony_ci<td><p>Add <code>emitClose</code> option to specify if <code>'close'</code> is emitted on destroy.</p></td></tr> 16071cb0ef41Sopenharmony_ci<tr><td>v0.9.4</td> 16081cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.9.4</span></p></td></tr> 16091cb0ef41Sopenharmony_ci</tbody></table> 16101cb0ef41Sopenharmony_ci</details> 16111cb0ef41Sopenharmony_ci</div> 16121cb0ef41Sopenharmony_ci<p>The <code>'close'</code> event is emitted when the stream and any of its underlying 16131cb0ef41Sopenharmony_ciresources (a file descriptor, for example) have been closed. The event indicates 16141cb0ef41Sopenharmony_cithat no more events will be emitted, and no further computation will occur.</p> 16151cb0ef41Sopenharmony_ci<p>A <a href="#class-streamreadable"><code>Readable</code></a> stream will always emit the <code>'close'</code> event if it is 16161cb0ef41Sopenharmony_cicreated with the <code>emitClose</code> option.</p> 16171cb0ef41Sopenharmony_ci<h6>Event: <code>'data'</code><span><a class="mark" href="#event-data" id="event-data">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_data"></a></h6> 16181cb0ef41Sopenharmony_ci<div class="api_metadata"> 16191cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 16201cb0ef41Sopenharmony_ci</div> 16211cb0ef41Sopenharmony_ci<ul> 16221cb0ef41Sopenharmony_ci<li><code>chunk</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> The chunk of data. For streams that are not 16231cb0ef41Sopenharmony_cioperating in object mode, the chunk will be either a string or <code>Buffer</code>. 16241cb0ef41Sopenharmony_ciFor streams that are in object mode, the chunk can be any JavaScript value 16251cb0ef41Sopenharmony_ciother than <code>null</code>.</li> 16261cb0ef41Sopenharmony_ci</ul> 16271cb0ef41Sopenharmony_ci<p>The <code>'data'</code> event is emitted whenever the stream is relinquishing ownership of 16281cb0ef41Sopenharmony_cia chunk of data to a consumer. This may occur whenever the stream is switched 16291cb0ef41Sopenharmony_ciin flowing mode by calling <code>readable.pipe()</code>, <code>readable.resume()</code>, or by 16301cb0ef41Sopenharmony_ciattaching a listener callback to the <code>'data'</code> event. The <code>'data'</code> event will 16311cb0ef41Sopenharmony_cialso be emitted whenever the <code>readable.read()</code> method is called and a chunk of 16321cb0ef41Sopenharmony_cidata is available to be returned.</p> 16331cb0ef41Sopenharmony_ci<p>Attaching a <code>'data'</code> event listener to a stream that has not been explicitly 16341cb0ef41Sopenharmony_cipaused will switch the stream into flowing mode. Data will then be passed as 16351cb0ef41Sopenharmony_cisoon as it is available.</p> 16361cb0ef41Sopenharmony_ci<p>The listener callback will be passed the chunk of data as a string if a default 16371cb0ef41Sopenharmony_ciencoding has been specified for the stream using the 16381cb0ef41Sopenharmony_ci<code>readable.setEncoding()</code> method; otherwise the data will be passed as a 16391cb0ef41Sopenharmony_ci<code>Buffer</code>.</p> 16401cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> readable = <span class="hljs-title function_">getReadableStreamSomehow</span>(); 16411cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> { 16421cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`Received <span class="hljs-subst">${chunk.length}</span> bytes of data.`</span>); 16431cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 16441cb0ef41Sopenharmony_ci<h6>Event: <code>'end'</code><span><a class="mark" href="#event-end" id="event-end">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_end"></a></h6> 16451cb0ef41Sopenharmony_ci<div class="api_metadata"> 16461cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 16471cb0ef41Sopenharmony_ci</div> 16481cb0ef41Sopenharmony_ci<p>The <code>'end'</code> event is emitted when there is no more data to be consumed from 16491cb0ef41Sopenharmony_cithe stream.</p> 16501cb0ef41Sopenharmony_ci<p>The <code>'end'</code> event <strong>will not be emitted</strong> unless the data is completely 16511cb0ef41Sopenharmony_ciconsumed. This can be accomplished by switching the stream into flowing mode, 16521cb0ef41Sopenharmony_cior by calling <a href="#readablereadsize"><code>stream.read()</code></a> repeatedly until all data has been 16531cb0ef41Sopenharmony_ciconsumed.</p> 16541cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> readable = <span class="hljs-title function_">getReadableStreamSomehow</span>(); 16551cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> { 16561cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`Received <span class="hljs-subst">${chunk.length}</span> bytes of data.`</span>); 16571cb0ef41Sopenharmony_ci}); 16581cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> { 16591cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'There will be no more data.'</span>); 16601cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 16611cb0ef41Sopenharmony_ci<h6>Event: <code>'error'</code><span><a class="mark" href="#event-error_1" id="event-error_1">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_error_1"></a></h6> 16621cb0ef41Sopenharmony_ci<div class="api_metadata"> 16631cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 16641cb0ef41Sopenharmony_ci</div> 16651cb0ef41Sopenharmony_ci<ul> 16661cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 16671cb0ef41Sopenharmony_ci</ul> 16681cb0ef41Sopenharmony_ci<p>The <code>'error'</code> event may be emitted by a <code>Readable</code> implementation at any time. 16691cb0ef41Sopenharmony_ciTypically, this may occur if the underlying stream is unable to generate data 16701cb0ef41Sopenharmony_cidue to an underlying internal failure, or when a stream implementation attempts 16711cb0ef41Sopenharmony_cito push an invalid chunk of data.</p> 16721cb0ef41Sopenharmony_ci<p>The listener callback will be passed a single <code>Error</code> object.</p> 16731cb0ef41Sopenharmony_ci<h6>Event: <code>'pause'</code><span><a class="mark" href="#event-pause" id="event-pause">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_pause"></a></h6> 16741cb0ef41Sopenharmony_ci<div class="api_metadata"> 16751cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 16761cb0ef41Sopenharmony_ci</div> 16771cb0ef41Sopenharmony_ci<p>The <code>'pause'</code> event is emitted when <a href="#readablepause"><code>stream.pause()</code></a> is called 16781cb0ef41Sopenharmony_ciand <code>readableFlowing</code> is not <code>false</code>.</p> 16791cb0ef41Sopenharmony_ci<h6>Event: <code>'readable'</code><span><a class="mark" href="#event-readable" id="event-readable">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_readable"></a></h6> 16801cb0ef41Sopenharmony_ci<div class="api_metadata"> 16811cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 16821cb0ef41Sopenharmony_ci<table> 16831cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 16841cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 16851cb0ef41Sopenharmony_ci<td><p>The <code>'readable'</code> is always emitted in the next tick after <code>.push()</code> is called.</p></td></tr> 16861cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 16871cb0ef41Sopenharmony_ci<td><p>Using <code>'readable'</code> requires calling <code>.read()</code>.</p></td></tr> 16881cb0ef41Sopenharmony_ci<tr><td>v0.9.4</td> 16891cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.9.4</span></p></td></tr> 16901cb0ef41Sopenharmony_ci</tbody></table> 16911cb0ef41Sopenharmony_ci</details> 16921cb0ef41Sopenharmony_ci</div> 16931cb0ef41Sopenharmony_ci<p>The <code>'readable'</code> event is emitted when there is data available to be read from 16941cb0ef41Sopenharmony_cithe stream or when the end of the stream has been reached. Effectively, the 16951cb0ef41Sopenharmony_ci<code>'readable'</code> event indicates that the stream has new information. If data is 16961cb0ef41Sopenharmony_ciavailable, <a href="#readablereadsize"><code>stream.read()</code></a> will return that data.</p> 16971cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> readable = <span class="hljs-title function_">getReadableStreamSomehow</span>(); 16981cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'readable'</span>, <span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) { 16991cb0ef41Sopenharmony_ci <span class="hljs-comment">// There is some data to read now.</span> 17001cb0ef41Sopenharmony_ci <span class="hljs-keyword">let</span> data; 17011cb0ef41Sopenharmony_ci 17021cb0ef41Sopenharmony_ci <span class="hljs-keyword">while</span> ((data = <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">read</span>()) !== <span class="hljs-literal">null</span>) { 17031cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(data); 17041cb0ef41Sopenharmony_ci } 17051cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 17061cb0ef41Sopenharmony_ci<p>If the end of the stream has been reached, calling 17071cb0ef41Sopenharmony_ci<a href="#readablereadsize"><code>stream.read()</code></a> will return <code>null</code> and trigger the <code>'end'</code> 17081cb0ef41Sopenharmony_cievent. This is also true if there never was any data to be read. For instance, 17091cb0ef41Sopenharmony_ciin the following example, <code>foo.txt</code> is an empty file:</p> 17101cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 17111cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> rr = fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'foo.txt'</span>); 17121cb0ef41Sopenharmony_cirr.<span class="hljs-title function_">on</span>(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> { 17131cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`readable: <span class="hljs-subst">${rr.read()}</span>`</span>); 17141cb0ef41Sopenharmony_ci}); 17151cb0ef41Sopenharmony_cirr.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> { 17161cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'end'</span>); 17171cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 17181cb0ef41Sopenharmony_ci<p>The output of running this script is:</p> 17191cb0ef41Sopenharmony_ci<pre><code class="language-console"><span class="hljs-meta prompt_">$ </span><span class="language-bash">node test.js</span> 17201cb0ef41Sopenharmony_cireadable: null 17211cb0ef41Sopenharmony_ciend</code> <button class="copy-button">copy</button></pre> 17221cb0ef41Sopenharmony_ci<p>In some cases, attaching a listener for the <code>'readable'</code> event will cause some 17231cb0ef41Sopenharmony_ciamount of data to be read into an internal buffer.</p> 17241cb0ef41Sopenharmony_ci<p>In general, the <code>readable.pipe()</code> and <code>'data'</code> event mechanisms are easier to 17251cb0ef41Sopenharmony_ciunderstand than the <code>'readable'</code> event. However, handling <code>'readable'</code> might 17261cb0ef41Sopenharmony_ciresult in increased throughput.</p> 17271cb0ef41Sopenharmony_ci<p>If both <code>'readable'</code> and <a href="#event-data"><code>'data'</code></a> are used at the same time, <code>'readable'</code> 17281cb0ef41Sopenharmony_citakes precedence in controlling the flow, i.e. <code>'data'</code> will be emitted 17291cb0ef41Sopenharmony_cionly when <a href="#readablereadsize"><code>stream.read()</code></a> is called. The 17301cb0ef41Sopenharmony_ci<code>readableFlowing</code> property would become <code>false</code>. 17311cb0ef41Sopenharmony_ciIf there are <code>'data'</code> listeners when <code>'readable'</code> is removed, the stream 17321cb0ef41Sopenharmony_ciwill start flowing, i.e. <code>'data'</code> events will be emitted without calling 17331cb0ef41Sopenharmony_ci<code>.resume()</code>.</p> 17341cb0ef41Sopenharmony_ci<h6>Event: <code>'resume'</code><span><a class="mark" href="#event-resume" id="event-resume">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_resume"></a></h6> 17351cb0ef41Sopenharmony_ci<div class="api_metadata"> 17361cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 17371cb0ef41Sopenharmony_ci</div> 17381cb0ef41Sopenharmony_ci<p>The <code>'resume'</code> event is emitted when <a href="#readableresume"><code>stream.resume()</code></a> is 17391cb0ef41Sopenharmony_cicalled and <code>readableFlowing</code> is not <code>true</code>.</p> 17401cb0ef41Sopenharmony_ci<h6><code>readable.destroy([error])</code><span><a class="mark" href="#readabledestroyerror" id="readabledestroyerror">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_destroy_error"></a></h6> 17411cb0ef41Sopenharmony_ci<div class="api_metadata"> 17421cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 17431cb0ef41Sopenharmony_ci<table> 17441cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 17451cb0ef41Sopenharmony_ci<tr><td>v14.0.0</td> 17461cb0ef41Sopenharmony_ci<td><p>Work as a no-op on a stream that has already been destroyed.</p></td></tr> 17471cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 17481cb0ef41Sopenharmony_ci<td><p><span>Added in: v8.0.0</span></p></td></tr> 17491cb0ef41Sopenharmony_ci</tbody></table> 17501cb0ef41Sopenharmony_ci</details> 17511cb0ef41Sopenharmony_ci</div> 17521cb0ef41Sopenharmony_ci<ul> 17531cb0ef41Sopenharmony_ci<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> Error which will be passed as payload in <code>'error'</code> event</li> 17541cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this" class="type"><this></a></li> 17551cb0ef41Sopenharmony_ci</ul> 17561cb0ef41Sopenharmony_ci<p>Destroy the stream. Optionally emit an <code>'error'</code> event, and emit a <code>'close'</code> 17571cb0ef41Sopenharmony_cievent (unless <code>emitClose</code> is set to <code>false</code>). After this call, the readable 17581cb0ef41Sopenharmony_cistream will release any internal resources and subsequent calls to <code>push()</code> 17591cb0ef41Sopenharmony_ciwill be ignored.</p> 17601cb0ef41Sopenharmony_ci<p>Once <code>destroy()</code> has been called any further calls will be a no-op and no 17611cb0ef41Sopenharmony_cifurther errors except from <code>_destroy()</code> may be emitted as <code>'error'</code>.</p> 17621cb0ef41Sopenharmony_ci<p>Implementors should not override this method, but instead implement 17631cb0ef41Sopenharmony_ci<a href="#readable_destroyerr-callback"><code>readable._destroy()</code></a>.</p> 17641cb0ef41Sopenharmony_ci<h6><code>readable.closed</code><span><a class="mark" href="#readableclosed" id="readableclosed">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_closed"></a></h6> 17651cb0ef41Sopenharmony_ci<div class="api_metadata"> 17661cb0ef41Sopenharmony_ci<span>Added in: v18.0.0</span> 17671cb0ef41Sopenharmony_ci</div> 17681cb0ef41Sopenharmony_ci<ul> 17691cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 17701cb0ef41Sopenharmony_ci</ul> 17711cb0ef41Sopenharmony_ci<p>Is <code>true</code> after <code>'close'</code> has been emitted.</p> 17721cb0ef41Sopenharmony_ci<h6><code>readable.destroyed</code><span><a class="mark" href="#readabledestroyed" id="readabledestroyed">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_destroyed"></a></h6> 17731cb0ef41Sopenharmony_ci<div class="api_metadata"> 17741cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 17751cb0ef41Sopenharmony_ci</div> 17761cb0ef41Sopenharmony_ci<ul> 17771cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 17781cb0ef41Sopenharmony_ci</ul> 17791cb0ef41Sopenharmony_ci<p>Is <code>true</code> after <a href="#readabledestroyerror"><code>readable.destroy()</code></a> has been called.</p> 17801cb0ef41Sopenharmony_ci<h6><code>readable.isPaused()</code><span><a class="mark" href="#readableispaused" id="readableispaused">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_ispaused"></a></h6> 17811cb0ef41Sopenharmony_ci<div class="api_metadata"> 17821cb0ef41Sopenharmony_ci<span>Added in: v0.11.14</span> 17831cb0ef41Sopenharmony_ci</div> 17841cb0ef41Sopenharmony_ci<ul> 17851cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 17861cb0ef41Sopenharmony_ci</ul> 17871cb0ef41Sopenharmony_ci<p>The <code>readable.isPaused()</code> method returns the current operating state of the 17881cb0ef41Sopenharmony_ci<code>Readable</code>. This is used primarily by the mechanism that underlies the 17891cb0ef41Sopenharmony_ci<code>readable.pipe()</code> method. In most typical cases, there will be no reason to 17901cb0ef41Sopenharmony_ciuse this method directly.</p> 17911cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> readable = <span class="hljs-keyword">new</span> stream.<span class="hljs-title class_">Readable</span>(); 17921cb0ef41Sopenharmony_ci 17931cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">isPaused</span>(); <span class="hljs-comment">// === false</span> 17941cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">pause</span>(); 17951cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">isPaused</span>(); <span class="hljs-comment">// === true</span> 17961cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">resume</span>(); 17971cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">isPaused</span>(); <span class="hljs-comment">// === false</span></code> <button class="copy-button">copy</button></pre> 17981cb0ef41Sopenharmony_ci<h6><code>readable.pause()</code><span><a class="mark" href="#readablepause" id="readablepause">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_pause"></a></h6> 17991cb0ef41Sopenharmony_ci<div class="api_metadata"> 18001cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 18011cb0ef41Sopenharmony_ci</div> 18021cb0ef41Sopenharmony_ci<ul> 18031cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this" class="type"><this></a></li> 18041cb0ef41Sopenharmony_ci</ul> 18051cb0ef41Sopenharmony_ci<p>The <code>readable.pause()</code> method will cause a stream in flowing mode to stop 18061cb0ef41Sopenharmony_ciemitting <a href="#event-data"><code>'data'</code></a> events, switching out of flowing mode. Any data that 18071cb0ef41Sopenharmony_cibecomes available will remain in the internal buffer.</p> 18081cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> readable = <span class="hljs-title function_">getReadableStreamSomehow</span>(); 18091cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> { 18101cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`Received <span class="hljs-subst">${chunk.length}</span> bytes of data.`</span>); 18111cb0ef41Sopenharmony_ci readable.<span class="hljs-title function_">pause</span>(); 18121cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'There will be no additional data for 1 second.'</span>); 18131cb0ef41Sopenharmony_ci <span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> { 18141cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Now data will start flowing again.'</span>); 18151cb0ef41Sopenharmony_ci readable.<span class="hljs-title function_">resume</span>(); 18161cb0ef41Sopenharmony_ci }, <span class="hljs-number">1000</span>); 18171cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 18181cb0ef41Sopenharmony_ci<p>The <code>readable.pause()</code> method has no effect if there is a <code>'readable'</code> 18191cb0ef41Sopenharmony_cievent listener.</p> 18201cb0ef41Sopenharmony_ci<h6><code>readable.pipe(destination[, options])</code><span><a class="mark" href="#readablepipedestination-options" id="readablepipedestination-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_pipe_destination_options"></a></h6> 18211cb0ef41Sopenharmony_ci<div class="api_metadata"> 18221cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 18231cb0ef41Sopenharmony_ci</div> 18241cb0ef41Sopenharmony_ci<ul> 18251cb0ef41Sopenharmony_ci<li><code>destination</code> <a href="stream.html#class-streamwritable" class="type"><stream.Writable></a> The destination for writing data</li> 18261cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Pipe options 18271cb0ef41Sopenharmony_ci<ul> 18281cb0ef41Sopenharmony_ci<li><code>end</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> End the writer when the reader ends. <strong>Default:</strong> <code>true</code>.</li> 18291cb0ef41Sopenharmony_ci</ul> 18301cb0ef41Sopenharmony_ci</li> 18311cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamwritable" class="type"><stream.Writable></a> The <em>destination</em>, allowing for a chain of pipes if 18321cb0ef41Sopenharmony_ciit is a <a href="#class-streamduplex"><code>Duplex</code></a> or a <a href="#class-streamtransform"><code>Transform</code></a> stream</li> 18331cb0ef41Sopenharmony_ci</ul> 18341cb0ef41Sopenharmony_ci<p>The <code>readable.pipe()</code> method attaches a <a href="#class-streamwritable"><code>Writable</code></a> stream to the <code>readable</code>, 18351cb0ef41Sopenharmony_cicausing it to switch automatically into flowing mode and push all of its data 18361cb0ef41Sopenharmony_cito the attached <a href="#class-streamwritable"><code>Writable</code></a>. The flow of data will be automatically managed 18371cb0ef41Sopenharmony_ciso that the destination <code>Writable</code> stream is not overwhelmed by a faster 18381cb0ef41Sopenharmony_ci<code>Readable</code> stream.</p> 18391cb0ef41Sopenharmony_ci<p>The following example pipes all of the data from the <code>readable</code> into a file 18401cb0ef41Sopenharmony_cinamed <code>file.txt</code>:</p> 18411cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 18421cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> readable = <span class="hljs-title function_">getReadableStreamSomehow</span>(); 18431cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> writable = fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'file.txt'</span>); 18441cb0ef41Sopenharmony_ci<span class="hljs-comment">// All the data from readable goes into 'file.txt'.</span> 18451cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">pipe</span>(writable);</code> <button class="copy-button">copy</button></pre> 18461cb0ef41Sopenharmony_ci<p>It is possible to attach multiple <code>Writable</code> streams to a single <code>Readable</code> 18471cb0ef41Sopenharmony_cistream.</p> 18481cb0ef41Sopenharmony_ci<p>The <code>readable.pipe()</code> method returns a reference to the <em>destination</em> stream 18491cb0ef41Sopenharmony_cimaking it possible to set up chains of piped streams:</p> 18501cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 18511cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> zlib = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:zlib'</span>); 18521cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> r = fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'file.txt'</span>); 18531cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> z = zlib.<span class="hljs-title function_">createGzip</span>(); 18541cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> w = fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'file.txt.gz'</span>); 18551cb0ef41Sopenharmony_cir.<span class="hljs-title function_">pipe</span>(z).<span class="hljs-title function_">pipe</span>(w);</code> <button class="copy-button">copy</button></pre> 18561cb0ef41Sopenharmony_ci<p>By default, <a href="#writableendchunk-encoding-callback"><code>stream.end()</code></a> is called on the destination <code>Writable</code> 18571cb0ef41Sopenharmony_cistream when the source <code>Readable</code> stream emits <a href="#event-end"><code>'end'</code></a>, so that the 18581cb0ef41Sopenharmony_cidestination is no longer writable. To disable this default behavior, the <code>end</code> 18591cb0ef41Sopenharmony_cioption can be passed as <code>false</code>, causing the destination stream to remain open:</p> 18601cb0ef41Sopenharmony_ci<pre><code class="language-js">reader.<span class="hljs-title function_">pipe</span>(writer, { <span class="hljs-attr">end</span>: <span class="hljs-literal">false</span> }); 18611cb0ef41Sopenharmony_cireader.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> { 18621cb0ef41Sopenharmony_ci writer.<span class="hljs-title function_">end</span>(<span class="hljs-string">'Goodbye\n'</span>); 18631cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 18641cb0ef41Sopenharmony_ci<p>One important caveat is that if the <code>Readable</code> stream emits an error during 18651cb0ef41Sopenharmony_ciprocessing, the <code>Writable</code> destination <em>is not closed</em> automatically. If an 18661cb0ef41Sopenharmony_cierror occurs, it will be necessary to <em>manually</em> close each stream in order 18671cb0ef41Sopenharmony_cito prevent memory leaks.</p> 18681cb0ef41Sopenharmony_ci<p>The <a href="process.html#processstderr"><code>process.stderr</code></a> and <a href="process.html#processstdout"><code>process.stdout</code></a> <code>Writable</code> streams are never 18691cb0ef41Sopenharmony_ciclosed until the Node.js process exits, regardless of the specified options.</p> 18701cb0ef41Sopenharmony_ci<h6><code>readable.read([size])</code><span><a class="mark" href="#readablereadsize" id="readablereadsize">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_read_size"></a></h6> 18711cb0ef41Sopenharmony_ci<div class="api_metadata"> 18721cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 18731cb0ef41Sopenharmony_ci</div> 18741cb0ef41Sopenharmony_ci<ul> 18751cb0ef41Sopenharmony_ci<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Optional argument to specify how much data to read.</li> 18761cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a></li> 18771cb0ef41Sopenharmony_ci</ul> 18781cb0ef41Sopenharmony_ci<p>The <code>readable.read()</code> method reads data out of the internal buffer and 18791cb0ef41Sopenharmony_cireturns it. If no data is available to be read, <code>null</code> is returned. By default, 18801cb0ef41Sopenharmony_cithe data is returned as a <code>Buffer</code> object unless an encoding has been 18811cb0ef41Sopenharmony_cispecified using the <code>readable.setEncoding()</code> method or the stream is operating 18821cb0ef41Sopenharmony_ciin object mode.</p> 18831cb0ef41Sopenharmony_ci<p>The optional <code>size</code> argument specifies a specific number of bytes to read. If 18841cb0ef41Sopenharmony_ci<code>size</code> bytes are not available to be read, <code>null</code> will be returned <em>unless</em> 18851cb0ef41Sopenharmony_cithe stream has ended, in which case all of the data remaining in the internal 18861cb0ef41Sopenharmony_cibuffer will be returned.</p> 18871cb0ef41Sopenharmony_ci<p>If the <code>size</code> argument is not specified, all of the data contained in the 18881cb0ef41Sopenharmony_ciinternal buffer will be returned.</p> 18891cb0ef41Sopenharmony_ci<p>The <code>size</code> argument must be less than or equal to 1 GiB.</p> 18901cb0ef41Sopenharmony_ci<p>The <code>readable.read()</code> method should only be called on <code>Readable</code> streams 18911cb0ef41Sopenharmony_cioperating in paused mode. In flowing mode, <code>readable.read()</code> is called 18921cb0ef41Sopenharmony_ciautomatically until the internal buffer is fully drained.</p> 18931cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> readable = <span class="hljs-title function_">getReadableStreamSomehow</span>(); 18941cb0ef41Sopenharmony_ci 18951cb0ef41Sopenharmony_ci<span class="hljs-comment">// 'readable' may be triggered multiple times as data is buffered in</span> 18961cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> { 18971cb0ef41Sopenharmony_ci <span class="hljs-keyword">let</span> chunk; 18981cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Stream is readable (new data received in buffer)'</span>); 18991cb0ef41Sopenharmony_ci <span class="hljs-comment">// Use a loop to make sure we read all currently available data</span> 19001cb0ef41Sopenharmony_ci <span class="hljs-keyword">while</span> (<span class="hljs-literal">null</span> !== (chunk = readable.<span class="hljs-title function_">read</span>())) { 19011cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`Read <span class="hljs-subst">${chunk.length}</span> bytes of data...`</span>); 19021cb0ef41Sopenharmony_ci } 19031cb0ef41Sopenharmony_ci}); 19041cb0ef41Sopenharmony_ci 19051cb0ef41Sopenharmony_ci<span class="hljs-comment">// 'end' will be triggered once when there is no more data available</span> 19061cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> { 19071cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Reached end of stream.'</span>); 19081cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 19091cb0ef41Sopenharmony_ci<p>Each call to <code>readable.read()</code> returns a chunk of data, or <code>null</code>. The chunks 19101cb0ef41Sopenharmony_ciare not concatenated. A <code>while</code> loop is necessary to consume all data 19111cb0ef41Sopenharmony_cicurrently in the buffer. When reading a large file <code>.read()</code> may return <code>null</code>, 19121cb0ef41Sopenharmony_cihaving consumed all buffered content so far, but there is still more data to 19131cb0ef41Sopenharmony_cicome not yet buffered. In this case a new <code>'readable'</code> event will be emitted 19141cb0ef41Sopenharmony_ciwhen there is more data in the buffer. Finally the <code>'end'</code> event will be 19151cb0ef41Sopenharmony_ciemitted when there is no more data to come.</p> 19161cb0ef41Sopenharmony_ci<p>Therefore to read a file's whole contents from a <code>readable</code>, it is necessary 19171cb0ef41Sopenharmony_cito collect chunks across multiple <code>'readable'</code> events:</p> 19181cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> chunks = []; 19191cb0ef41Sopenharmony_ci 19201cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> { 19211cb0ef41Sopenharmony_ci <span class="hljs-keyword">let</span> chunk; 19221cb0ef41Sopenharmony_ci <span class="hljs-keyword">while</span> (<span class="hljs-literal">null</span> !== (chunk = readable.<span class="hljs-title function_">read</span>())) { 19231cb0ef41Sopenharmony_ci chunks.<span class="hljs-title function_">push</span>(chunk); 19241cb0ef41Sopenharmony_ci } 19251cb0ef41Sopenharmony_ci}); 19261cb0ef41Sopenharmony_ci 19271cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> { 19281cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> content = chunks.<span class="hljs-title function_">join</span>(<span class="hljs-string">''</span>); 19291cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 19301cb0ef41Sopenharmony_ci<p>A <code>Readable</code> stream in object mode will always return a single item from 19311cb0ef41Sopenharmony_cia call to <a href="#readablereadsize"><code>readable.read(size)</code></a>, regardless of the value of the 19321cb0ef41Sopenharmony_ci<code>size</code> argument.</p> 19331cb0ef41Sopenharmony_ci<p>If the <code>readable.read()</code> method returns a chunk of data, a <code>'data'</code> event will 19341cb0ef41Sopenharmony_cialso be emitted.</p> 19351cb0ef41Sopenharmony_ci<p>Calling <a href="#readablereadsize"><code>stream.read([size])</code></a> after the <a href="#event-end"><code>'end'</code></a> event has 19361cb0ef41Sopenharmony_cibeen emitted will return <code>null</code>. No runtime error will be raised.</p> 19371cb0ef41Sopenharmony_ci<h6><code>readable.readable</code><span><a class="mark" href="#readablereadable" id="readablereadable">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_readable"></a></h6> 19381cb0ef41Sopenharmony_ci<div class="api_metadata"> 19391cb0ef41Sopenharmony_ci<span>Added in: v11.4.0</span> 19401cb0ef41Sopenharmony_ci</div> 19411cb0ef41Sopenharmony_ci<ul> 19421cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 19431cb0ef41Sopenharmony_ci</ul> 19441cb0ef41Sopenharmony_ci<p>Is <code>true</code> if it is safe to call <a href="#readablereadsize"><code>readable.read()</code></a>, which means 19451cb0ef41Sopenharmony_cithe stream has not been destroyed or emitted <code>'error'</code> or <code>'end'</code>.</p> 19461cb0ef41Sopenharmony_ci<h6><code>readable.readableAborted</code><span><a class="mark" href="#readablereadableaborted" id="readablereadableaborted">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_readableaborted"></a></h6> 19471cb0ef41Sopenharmony_ci<div class="api_metadata"> 19481cb0ef41Sopenharmony_ci<span>Added in: v16.8.0</span> 19491cb0ef41Sopenharmony_ci</div> 19501cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 19511cb0ef41Sopenharmony_ci<ul> 19521cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 19531cb0ef41Sopenharmony_ci</ul> 19541cb0ef41Sopenharmony_ci<p>Returns whether the stream was destroyed or errored before emitting <code>'end'</code>.</p> 19551cb0ef41Sopenharmony_ci<h6><code>readable.readableDidRead</code><span><a class="mark" href="#readablereadabledidread" id="readablereadabledidread">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_readabledidread"></a></h6> 19561cb0ef41Sopenharmony_ci<div class="api_metadata"> 19571cb0ef41Sopenharmony_ci<span>Added in: v16.7.0, v14.18.0</span> 19581cb0ef41Sopenharmony_ci</div> 19591cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 19601cb0ef41Sopenharmony_ci<ul> 19611cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 19621cb0ef41Sopenharmony_ci</ul> 19631cb0ef41Sopenharmony_ci<p>Returns whether <code>'data'</code> has been emitted.</p> 19641cb0ef41Sopenharmony_ci<h6><code>readable.readableEncoding</code><span><a class="mark" href="#readablereadableencoding" id="readablereadableencoding">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_readableencoding"></a></h6> 19651cb0ef41Sopenharmony_ci<div class="api_metadata"> 19661cb0ef41Sopenharmony_ci<span>Added in: v12.7.0</span> 19671cb0ef41Sopenharmony_ci</div> 19681cb0ef41Sopenharmony_ci<ul> 19691cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 19701cb0ef41Sopenharmony_ci</ul> 19711cb0ef41Sopenharmony_ci<p>Getter for the property <code>encoding</code> of a given <code>Readable</code> stream. The <code>encoding</code> 19721cb0ef41Sopenharmony_ciproperty can be set using the <a href="#readablesetencodingencoding"><code>readable.setEncoding()</code></a> method.</p> 19731cb0ef41Sopenharmony_ci<h6><code>readable.readableEnded</code><span><a class="mark" href="#readablereadableended" id="readablereadableended">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_readableended"></a></h6> 19741cb0ef41Sopenharmony_ci<div class="api_metadata"> 19751cb0ef41Sopenharmony_ci<span>Added in: v12.9.0</span> 19761cb0ef41Sopenharmony_ci</div> 19771cb0ef41Sopenharmony_ci<ul> 19781cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 19791cb0ef41Sopenharmony_ci</ul> 19801cb0ef41Sopenharmony_ci<p>Becomes <code>true</code> when <a href="#event-end"><code>'end'</code></a> event is emitted.</p> 19811cb0ef41Sopenharmony_ci<h6><code>readable.errored</code><span><a class="mark" href="#readableerrored" id="readableerrored">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_errored"></a></h6> 19821cb0ef41Sopenharmony_ci<div class="api_metadata"> 19831cb0ef41Sopenharmony_ci<span>Added in: v18.0.0</span> 19841cb0ef41Sopenharmony_ci</div> 19851cb0ef41Sopenharmony_ci<ul> 19861cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 19871cb0ef41Sopenharmony_ci</ul> 19881cb0ef41Sopenharmony_ci<p>Returns error if the stream has been destroyed with an error.</p> 19891cb0ef41Sopenharmony_ci<h6><code>readable.readableFlowing</code><span><a class="mark" href="#readablereadableflowing" id="readablereadableflowing">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_readableflowing"></a></h6> 19901cb0ef41Sopenharmony_ci<div class="api_metadata"> 19911cb0ef41Sopenharmony_ci<span>Added in: v9.4.0</span> 19921cb0ef41Sopenharmony_ci</div> 19931cb0ef41Sopenharmony_ci<ul> 19941cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 19951cb0ef41Sopenharmony_ci</ul> 19961cb0ef41Sopenharmony_ci<p>This property reflects the current state of a <code>Readable</code> stream as described 19971cb0ef41Sopenharmony_ciin the <a href="#three-states">Three states</a> section.</p> 19981cb0ef41Sopenharmony_ci<h6><code>readable.readableHighWaterMark</code><span><a class="mark" href="#readablereadablehighwatermark" id="readablereadablehighwatermark">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_readablehighwatermark"></a></h6> 19991cb0ef41Sopenharmony_ci<div class="api_metadata"> 20001cb0ef41Sopenharmony_ci<span>Added in: v9.3.0</span> 20011cb0ef41Sopenharmony_ci</div> 20021cb0ef41Sopenharmony_ci<ul> 20031cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 20041cb0ef41Sopenharmony_ci</ul> 20051cb0ef41Sopenharmony_ci<p>Returns the value of <code>highWaterMark</code> passed when creating this <code>Readable</code>.</p> 20061cb0ef41Sopenharmony_ci<h6><code>readable.readableLength</code><span><a class="mark" href="#readablereadablelength" id="readablereadablelength">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_readablelength"></a></h6> 20071cb0ef41Sopenharmony_ci<div class="api_metadata"> 20081cb0ef41Sopenharmony_ci<span>Added in: v9.4.0</span> 20091cb0ef41Sopenharmony_ci</div> 20101cb0ef41Sopenharmony_ci<ul> 20111cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 20121cb0ef41Sopenharmony_ci</ul> 20131cb0ef41Sopenharmony_ci<p>This property contains the number of bytes (or objects) in the queue 20141cb0ef41Sopenharmony_ciready to be read. The value provides introspection data regarding 20151cb0ef41Sopenharmony_cithe status of the <code>highWaterMark</code>.</p> 20161cb0ef41Sopenharmony_ci<h6><code>readable.readableObjectMode</code><span><a class="mark" href="#readablereadableobjectmode" id="readablereadableobjectmode">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_readableobjectmode"></a></h6> 20171cb0ef41Sopenharmony_ci<div class="api_metadata"> 20181cb0ef41Sopenharmony_ci<span>Added in: v12.3.0</span> 20191cb0ef41Sopenharmony_ci</div> 20201cb0ef41Sopenharmony_ci<ul> 20211cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 20221cb0ef41Sopenharmony_ci</ul> 20231cb0ef41Sopenharmony_ci<p>Getter for the property <code>objectMode</code> of a given <code>Readable</code> stream.</p> 20241cb0ef41Sopenharmony_ci<h6><code>readable.resume()</code><span><a class="mark" href="#readableresume" id="readableresume">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_resume"></a></h6> 20251cb0ef41Sopenharmony_ci<div class="api_metadata"> 20261cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 20271cb0ef41Sopenharmony_ci<table> 20281cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 20291cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 20301cb0ef41Sopenharmony_ci<td><p>The <code>resume()</code> has no effect if there is a <code>'readable'</code> event listening.</p></td></tr> 20311cb0ef41Sopenharmony_ci<tr><td>v0.9.4</td> 20321cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.9.4</span></p></td></tr> 20331cb0ef41Sopenharmony_ci</tbody></table> 20341cb0ef41Sopenharmony_ci</details> 20351cb0ef41Sopenharmony_ci</div> 20361cb0ef41Sopenharmony_ci<ul> 20371cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this" class="type"><this></a></li> 20381cb0ef41Sopenharmony_ci</ul> 20391cb0ef41Sopenharmony_ci<p>The <code>readable.resume()</code> method causes an explicitly paused <code>Readable</code> stream to 20401cb0ef41Sopenharmony_ciresume emitting <a href="#event-data"><code>'data'</code></a> events, switching the stream into flowing mode.</p> 20411cb0ef41Sopenharmony_ci<p>The <code>readable.resume()</code> method can be used to fully consume the data from a 20421cb0ef41Sopenharmony_cistream without actually processing any of that data:</p> 20431cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-title function_">getReadableStreamSomehow</span>() 20441cb0ef41Sopenharmony_ci .<span class="hljs-title function_">resume</span>() 20451cb0ef41Sopenharmony_ci .<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> { 20461cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Reached the end, but did not read anything.'</span>); 20471cb0ef41Sopenharmony_ci });</code> <button class="copy-button">copy</button></pre> 20481cb0ef41Sopenharmony_ci<p>The <code>readable.resume()</code> method has no effect if there is a <code>'readable'</code> 20491cb0ef41Sopenharmony_cievent listener.</p> 20501cb0ef41Sopenharmony_ci<h6><code>readable.setEncoding(encoding)</code><span><a class="mark" href="#readablesetencodingencoding" id="readablesetencodingencoding">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_setencoding_encoding"></a></h6> 20511cb0ef41Sopenharmony_ci<div class="api_metadata"> 20521cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 20531cb0ef41Sopenharmony_ci</div> 20541cb0ef41Sopenharmony_ci<ul> 20551cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The encoding to use.</li> 20561cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this" class="type"><this></a></li> 20571cb0ef41Sopenharmony_ci</ul> 20581cb0ef41Sopenharmony_ci<p>The <code>readable.setEncoding()</code> method sets the character encoding for 20591cb0ef41Sopenharmony_cidata read from the <code>Readable</code> stream.</p> 20601cb0ef41Sopenharmony_ci<p>By default, no encoding is assigned and stream data will be returned as 20611cb0ef41Sopenharmony_ci<code>Buffer</code> objects. Setting an encoding causes the stream data 20621cb0ef41Sopenharmony_cito be returned as strings of the specified encoding rather than as <code>Buffer</code> 20631cb0ef41Sopenharmony_ciobjects. For instance, calling <code>readable.setEncoding('utf8')</code> will cause the 20641cb0ef41Sopenharmony_cioutput data to be interpreted as UTF-8 data, and passed as strings. Calling 20651cb0ef41Sopenharmony_ci<code>readable.setEncoding('hex')</code> will cause the data to be encoded in hexadecimal 20661cb0ef41Sopenharmony_cistring format.</p> 20671cb0ef41Sopenharmony_ci<p>The <code>Readable</code> stream will properly handle multi-byte characters delivered 20681cb0ef41Sopenharmony_cithrough the stream that would otherwise become improperly decoded if simply 20691cb0ef41Sopenharmony_cipulled from the stream as <code>Buffer</code> objects.</p> 20701cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> readable = <span class="hljs-title function_">getReadableStreamSomehow</span>(); 20711cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">setEncoding</span>(<span class="hljs-string">'utf8'</span>); 20721cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> { 20731cb0ef41Sopenharmony_ci assert.<span class="hljs-title function_">equal</span>(<span class="hljs-keyword">typeof</span> chunk, <span class="hljs-string">'string'</span>); 20741cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Got %d characters of string data:'</span>, chunk.<span class="hljs-property">length</span>); 20751cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 20761cb0ef41Sopenharmony_ci<h6><code>readable.unpipe([destination])</code><span><a class="mark" href="#readableunpipedestination" id="readableunpipedestination">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_unpipe_destination"></a></h6> 20771cb0ef41Sopenharmony_ci<div class="api_metadata"> 20781cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 20791cb0ef41Sopenharmony_ci</div> 20801cb0ef41Sopenharmony_ci<ul> 20811cb0ef41Sopenharmony_ci<li><code>destination</code> <a href="stream.html#class-streamwritable" class="type"><stream.Writable></a> Optional specific stream to unpipe</li> 20821cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this" class="type"><this></a></li> 20831cb0ef41Sopenharmony_ci</ul> 20841cb0ef41Sopenharmony_ci<p>The <code>readable.unpipe()</code> method detaches a <code>Writable</code> stream previously attached 20851cb0ef41Sopenharmony_ciusing the <a href="#readablepipedestination-options"><code>stream.pipe()</code></a> method.</p> 20861cb0ef41Sopenharmony_ci<p>If the <code>destination</code> is not specified, then <em>all</em> pipes are detached.</p> 20871cb0ef41Sopenharmony_ci<p>If the <code>destination</code> is specified, but no pipe is set up for it, then 20881cb0ef41Sopenharmony_cithe method does nothing.</p> 20891cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 20901cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> readable = <span class="hljs-title function_">getReadableStreamSomehow</span>(); 20911cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> writable = fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'file.txt'</span>); 20921cb0ef41Sopenharmony_ci<span class="hljs-comment">// All the data from readable goes into 'file.txt',</span> 20931cb0ef41Sopenharmony_ci<span class="hljs-comment">// but only for the first second.</span> 20941cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">pipe</span>(writable); 20951cb0ef41Sopenharmony_ci<span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> { 20961cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Stop writing to file.txt.'</span>); 20971cb0ef41Sopenharmony_ci readable.<span class="hljs-title function_">unpipe</span>(writable); 20981cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Manually close the file stream.'</span>); 20991cb0ef41Sopenharmony_ci writable.<span class="hljs-title function_">end</span>(); 21001cb0ef41Sopenharmony_ci}, <span class="hljs-number">1000</span>);</code> <button class="copy-button">copy</button></pre> 21011cb0ef41Sopenharmony_ci<h6><code>readable.unshift(chunk[, encoding])</code><span><a class="mark" href="#readableunshiftchunk-encoding" id="readableunshiftchunk-encoding">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_unshift_chunk_encoding"></a></h6> 21021cb0ef41Sopenharmony_ci<div class="api_metadata"> 21031cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 21041cb0ef41Sopenharmony_ci<table> 21051cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 21061cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 21071cb0ef41Sopenharmony_ci<td><p>The <code>chunk</code> argument can now be a <code>Uint8Array</code> instance.</p></td></tr> 21081cb0ef41Sopenharmony_ci<tr><td>v0.9.11</td> 21091cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.9.11</span></p></td></tr> 21101cb0ef41Sopenharmony_ci</tbody></table> 21111cb0ef41Sopenharmony_ci</details> 21121cb0ef41Sopenharmony_ci</div> 21131cb0ef41Sopenharmony_ci<ul> 21141cb0ef41Sopenharmony_ci<li><code>chunk</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> Chunk of data to unshift onto the 21151cb0ef41Sopenharmony_ciread queue. For streams not operating in object mode, <code>chunk</code> must be a 21161cb0ef41Sopenharmony_cistring, <code>Buffer</code>, <code>Uint8Array</code>, or <code>null</code>. For object mode streams, <code>chunk</code> 21171cb0ef41Sopenharmony_cimay be any JavaScript value.</li> 21181cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Encoding of string chunks. Must be a valid 21191cb0ef41Sopenharmony_ci<code>Buffer</code> encoding, such as <code>'utf8'</code> or <code>'ascii'</code>.</li> 21201cb0ef41Sopenharmony_ci</ul> 21211cb0ef41Sopenharmony_ci<p>Passing <code>chunk</code> as <code>null</code> signals the end of the stream (EOF) and behaves the 21221cb0ef41Sopenharmony_cisame as <code>readable.push(null)</code>, after which no more data can be written. The EOF 21231cb0ef41Sopenharmony_cisignal is put at the end of the buffer and any buffered data will still be 21241cb0ef41Sopenharmony_ciflushed.</p> 21251cb0ef41Sopenharmony_ci<p>The <code>readable.unshift()</code> method pushes a chunk of data back into the internal 21261cb0ef41Sopenharmony_cibuffer. This is useful in certain situations where a stream is being consumed by 21271cb0ef41Sopenharmony_cicode that needs to "un-consume" some amount of data that it has optimistically 21281cb0ef41Sopenharmony_cipulled out of the source, so that the data can be passed on to some other party.</p> 21291cb0ef41Sopenharmony_ci<p>The <code>stream.unshift(chunk)</code> method cannot be called after the <a href="#event-end"><code>'end'</code></a> event 21301cb0ef41Sopenharmony_cihas been emitted or a runtime error will be thrown.</p> 21311cb0ef41Sopenharmony_ci<p>Developers using <code>stream.unshift()</code> often should consider switching to 21321cb0ef41Sopenharmony_ciuse of a <a href="#class-streamtransform"><code>Transform</code></a> stream instead. See the <a href="#api-for-stream-implementers">API for stream implementers</a> 21331cb0ef41Sopenharmony_cisection for more information.</p> 21341cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// Pull off a header delimited by \n\n.</span> 21351cb0ef41Sopenharmony_ci<span class="hljs-comment">// Use unshift() if we get too much.</span> 21361cb0ef41Sopenharmony_ci<span class="hljs-comment">// Call the callback with (error, header, stream).</span> 21371cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { <span class="hljs-title class_">StringDecoder</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:string_decoder'</span>); 21381cb0ef41Sopenharmony_ci<span class="hljs-keyword">function</span> <span class="hljs-title function_">parseHeader</span>(<span class="hljs-params">stream, callback</span>) { 21391cb0ef41Sopenharmony_ci stream.<span class="hljs-title function_">on</span>(<span class="hljs-string">'error'</span>, callback); 21401cb0ef41Sopenharmony_ci stream.<span class="hljs-title function_">on</span>(<span class="hljs-string">'readable'</span>, onReadable); 21411cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> decoder = <span class="hljs-keyword">new</span> <span class="hljs-title class_">StringDecoder</span>(<span class="hljs-string">'utf8'</span>); 21421cb0ef41Sopenharmony_ci <span class="hljs-keyword">let</span> header = <span class="hljs-string">''</span>; 21431cb0ef41Sopenharmony_ci <span class="hljs-keyword">function</span> <span class="hljs-title function_">onReadable</span>(<span class="hljs-params"></span>) { 21441cb0ef41Sopenharmony_ci <span class="hljs-keyword">let</span> chunk; 21451cb0ef41Sopenharmony_ci <span class="hljs-keyword">while</span> (<span class="hljs-literal">null</span> !== (chunk = stream.<span class="hljs-title function_">read</span>())) { 21461cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> str = decoder.<span class="hljs-title function_">write</span>(chunk); 21471cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (str.<span class="hljs-title function_">includes</span>(<span class="hljs-string">'\n\n'</span>)) { 21481cb0ef41Sopenharmony_ci <span class="hljs-comment">// Found the header boundary.</span> 21491cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> split = str.<span class="hljs-title function_">split</span>(<span class="hljs-regexp">/\n\n/</span>); 21501cb0ef41Sopenharmony_ci header += split.<span class="hljs-title function_">shift</span>(); 21511cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> remaining = split.<span class="hljs-title function_">join</span>(<span class="hljs-string">'\n\n'</span>); 21521cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> buf = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(remaining, <span class="hljs-string">'utf8'</span>); 21531cb0ef41Sopenharmony_ci stream.<span class="hljs-title function_">removeListener</span>(<span class="hljs-string">'error'</span>, callback); 21541cb0ef41Sopenharmony_ci <span class="hljs-comment">// Remove the 'readable' listener before unshifting.</span> 21551cb0ef41Sopenharmony_ci stream.<span class="hljs-title function_">removeListener</span>(<span class="hljs-string">'readable'</span>, onReadable); 21561cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (buf.<span class="hljs-property">length</span>) 21571cb0ef41Sopenharmony_ci stream.<span class="hljs-title function_">unshift</span>(buf); 21581cb0ef41Sopenharmony_ci <span class="hljs-comment">// Now the body of the message can be read from the stream.</span> 21591cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, header, stream); 21601cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span>; 21611cb0ef41Sopenharmony_ci } 21621cb0ef41Sopenharmony_ci <span class="hljs-comment">// Still reading the header.</span> 21631cb0ef41Sopenharmony_ci header += str; 21641cb0ef41Sopenharmony_ci } 21651cb0ef41Sopenharmony_ci } 21661cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 21671cb0ef41Sopenharmony_ci<p>Unlike <a href="#readablepushchunk-encoding"><code>stream.push(chunk)</code></a>, <code>stream.unshift(chunk)</code> will not 21681cb0ef41Sopenharmony_ciend the reading process by resetting the internal reading state of the stream. 21691cb0ef41Sopenharmony_ciThis can cause unexpected results if <code>readable.unshift()</code> is called during a 21701cb0ef41Sopenharmony_ciread (i.e. from within a <a href="#readable_readsize"><code>stream._read()</code></a> implementation on a 21711cb0ef41Sopenharmony_cicustom stream). Following the call to <code>readable.unshift()</code> with an immediate 21721cb0ef41Sopenharmony_ci<a href="#readablepushchunk-encoding"><code>stream.push('')</code></a> will reset the reading state appropriately, 21731cb0ef41Sopenharmony_cihowever it is best to simply avoid calling <code>readable.unshift()</code> while in the 21741cb0ef41Sopenharmony_ciprocess of performing a read.</p> 21751cb0ef41Sopenharmony_ci<h6><code>readable.wrap(stream)</code><span><a class="mark" href="#readablewrapstream" id="readablewrapstream">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_wrap_stream"></a></h6> 21761cb0ef41Sopenharmony_ci<div class="api_metadata"> 21771cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 21781cb0ef41Sopenharmony_ci</div> 21791cb0ef41Sopenharmony_ci<ul> 21801cb0ef41Sopenharmony_ci<li><code>stream</code> <a href="stream.html#stream" class="type"><Stream></a> An "old style" readable stream</li> 21811cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this" class="type"><this></a></li> 21821cb0ef41Sopenharmony_ci</ul> 21831cb0ef41Sopenharmony_ci<p>Prior to Node.js 0.10, streams did not implement the entire <code>node:stream</code> 21841cb0ef41Sopenharmony_cimodule API as it is currently defined. (See <a href="#compatibility-with-older-nodejs-versions">Compatibility</a> for more 21851cb0ef41Sopenharmony_ciinformation.)</p> 21861cb0ef41Sopenharmony_ci<p>When using an older Node.js library that emits <a href="#event-data"><code>'data'</code></a> events and has a 21871cb0ef41Sopenharmony_ci<a href="#readablepause"><code>stream.pause()</code></a> method that is advisory only, the 21881cb0ef41Sopenharmony_ci<code>readable.wrap()</code> method can be used to create a <a href="#class-streamreadable"><code>Readable</code></a> stream that uses 21891cb0ef41Sopenharmony_cithe old stream as its data source.</p> 21901cb0ef41Sopenharmony_ci<p>It will rarely be necessary to use <code>readable.wrap()</code> but the method has been 21911cb0ef41Sopenharmony_ciprovided as a convenience for interacting with older Node.js applications and 21921cb0ef41Sopenharmony_cilibraries.</p> 21931cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">OldReader</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./old-api-module.js'</span>); 21941cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 21951cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> oreader = <span class="hljs-keyword">new</span> <span class="hljs-title class_">OldReader</span>(); 21961cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myReader = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Readable</span>().<span class="hljs-title function_">wrap</span>(oreader); 21971cb0ef41Sopenharmony_ci 21981cb0ef41Sopenharmony_cimyReader.<span class="hljs-title function_">on</span>(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> { 21991cb0ef41Sopenharmony_ci myReader.<span class="hljs-title function_">read</span>(); <span class="hljs-comment">// etc.</span> 22001cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 22011cb0ef41Sopenharmony_ci<h6><code>readable[Symbol.asyncIterator]()</code><span><a class="mark" href="#readablesymbolasynciterator" id="readablesymbolasynciterator">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_symbol_asynciterator"></a></h6> 22021cb0ef41Sopenharmony_ci<div class="api_metadata"> 22031cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 22041cb0ef41Sopenharmony_ci<table> 22051cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 22061cb0ef41Sopenharmony_ci<tr><td>v11.14.0</td> 22071cb0ef41Sopenharmony_ci<td><p>Symbol.asyncIterator support is no longer experimental.</p></td></tr> 22081cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 22091cb0ef41Sopenharmony_ci<td><p><span>Added in: v10.0.0</span></p></td></tr> 22101cb0ef41Sopenharmony_ci</tbody></table> 22111cb0ef41Sopenharmony_ci</details> 22121cb0ef41Sopenharmony_ci</div> 22131cb0ef41Sopenharmony_ci<ul> 22141cb0ef41Sopenharmony_ci<li>Returns: <a href="https://tc39.github.io/ecma262/#sec-asynciterator-interface" class="type"><AsyncIterator></a> to fully consume the stream.</li> 22151cb0ef41Sopenharmony_ci</ul> 22161cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 22171cb0ef41Sopenharmony_ci 22181cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">print</span>(<span class="hljs-params">readable</span>) { 22191cb0ef41Sopenharmony_ci readable.<span class="hljs-title function_">setEncoding</span>(<span class="hljs-string">'utf8'</span>); 22201cb0ef41Sopenharmony_ci <span class="hljs-keyword">let</span> data = <span class="hljs-string">''</span>; 22211cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> readable) { 22221cb0ef41Sopenharmony_ci data += chunk; 22231cb0ef41Sopenharmony_ci } 22241cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(data); 22251cb0ef41Sopenharmony_ci} 22261cb0ef41Sopenharmony_ci 22271cb0ef41Sopenharmony_ci<span class="hljs-title function_">print</span>(fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'file'</span>)).<span class="hljs-title function_">catch</span>(<span class="hljs-variable language_">console</span>.<span class="hljs-property">error</span>);</code> <button class="copy-button">copy</button></pre> 22281cb0ef41Sopenharmony_ci<p>If the loop terminates with a <code>break</code>, <code>return</code>, or a <code>throw</code>, the stream will 22291cb0ef41Sopenharmony_cibe destroyed. In other terms, iterating over a stream will consume the stream 22301cb0ef41Sopenharmony_cifully. The stream will be read in chunks of size equal to the <code>highWaterMark</code> 22311cb0ef41Sopenharmony_cioption. In the code example above, data will be in a single chunk if the file 22321cb0ef41Sopenharmony_cihas less then 64 KiB of data because no <code>highWaterMark</code> option is provided to 22331cb0ef41Sopenharmony_ci<a href="fs.html#fscreatereadstreampath-options"><code>fs.createReadStream()</code></a>.</p> 22341cb0ef41Sopenharmony_ci<h6><code>readable[Symbol.asyncDispose]()</code><span><a class="mark" href="#readablesymbolasyncdispose" id="readablesymbolasyncdispose">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_symbol_asyncdispose"></a></h6> 22351cb0ef41Sopenharmony_ci<div class="api_metadata"> 22361cb0ef41Sopenharmony_ci<span>Added in: v18.18.0</span> 22371cb0ef41Sopenharmony_ci</div> 22381cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 22391cb0ef41Sopenharmony_ci<p>Calls <a href="#readabledestroyerror"><code>readable.destroy()</code></a> with an <code>AbortError</code> and returns 22401cb0ef41Sopenharmony_cia promise that fulfills when the stream is finished.</p> 22411cb0ef41Sopenharmony_ci<h6><code>readable.compose(stream[, options])</code><span><a class="mark" href="#readablecomposestream-options" id="readablecomposestream-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_compose_stream_options"></a></h6> 22421cb0ef41Sopenharmony_ci<div class="api_metadata"> 22431cb0ef41Sopenharmony_ci<span>Added in: v18.13.0</span> 22441cb0ef41Sopenharmony_ci</div> 22451cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 22461cb0ef41Sopenharmony_ci<ul> 22471cb0ef41Sopenharmony_ci<li><code>stream</code> <a href="stream.html#stream" class="type"><Stream></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a></li> 22481cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 22491cb0ef41Sopenharmony_ci<ul> 22501cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 22511cb0ef41Sopenharmony_ciaborted.</li> 22521cb0ef41Sopenharmony_ci</ul> 22531cb0ef41Sopenharmony_ci</li> 22541cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamduplex" class="type"><Duplex></a> a stream composed with the stream <code>stream</code>.</li> 22551cb0ef41Sopenharmony_ci</ul> 22561cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 22571cb0ef41Sopenharmony_ci 22581cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>* <span class="hljs-title function_">splitToWords</span>(<span class="hljs-params">source</span>) { 22591cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> source) { 22601cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> words = <span class="hljs-title class_">String</span>(chunk).<span class="hljs-title function_">split</span>(<span class="hljs-string">' '</span>); 22611cb0ef41Sopenharmony_ci 22621cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> (<span class="hljs-keyword">const</span> word <span class="hljs-keyword">of</span> words) { 22631cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> word; 22641cb0ef41Sopenharmony_ci } 22651cb0ef41Sopenharmony_ci } 22661cb0ef41Sopenharmony_ci} 22671cb0ef41Sopenharmony_ci 22681cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> wordsStream = <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-string">'this is'</span>, <span class="hljs-string">'compose as operator'</span>]).<span class="hljs-title function_">compose</span>(splitToWords); 22691cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> words = <span class="hljs-keyword">await</span> wordsStream.<span class="hljs-title function_">toArray</span>(); 22701cb0ef41Sopenharmony_ci 22711cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(words); <span class="hljs-comment">// prints ['this', 'is', 'compose', 'as', 'operator']</span></code> <button class="copy-button">copy</button></pre> 22721cb0ef41Sopenharmony_ci<p>See <a href="#streamcomposestreams"><code>stream.compose</code></a> for more information.</p> 22731cb0ef41Sopenharmony_ci<h6><code>readable.iterator([options])</code><span><a class="mark" href="#readableiteratoroptions" id="readableiteratoroptions">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_iterator_options"></a></h6> 22741cb0ef41Sopenharmony_ci<div class="api_metadata"> 22751cb0ef41Sopenharmony_ci<span>Added in: v16.3.0</span> 22761cb0ef41Sopenharmony_ci</div> 22771cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 22781cb0ef41Sopenharmony_ci<ul> 22791cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 22801cb0ef41Sopenharmony_ci<ul> 22811cb0ef41Sopenharmony_ci<li><code>destroyOnReturn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> When set to <code>false</code>, calling <code>return</code> on the 22821cb0ef41Sopenharmony_ciasync iterator, or exiting a <code>for await...of</code> iteration using a <code>break</code>, 22831cb0ef41Sopenharmony_ci<code>return</code>, or <code>throw</code> will not destroy the stream. <strong>Default:</strong> <code>true</code>.</li> 22841cb0ef41Sopenharmony_ci</ul> 22851cb0ef41Sopenharmony_ci</li> 22861cb0ef41Sopenharmony_ci<li>Returns: <a href="https://tc39.github.io/ecma262/#sec-asynciterator-interface" class="type"><AsyncIterator></a> to consume the stream.</li> 22871cb0ef41Sopenharmony_ci</ul> 22881cb0ef41Sopenharmony_ci<p>The iterator created by this method gives users the option to cancel the 22891cb0ef41Sopenharmony_cidestruction of the stream if the <code>for await...of</code> loop is exited by <code>return</code>, 22901cb0ef41Sopenharmony_ci<code>break</code>, or <code>throw</code>, or if the iterator should destroy the stream if the stream 22911cb0ef41Sopenharmony_ciemitted an error during iteration.</p> 22921cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 22931cb0ef41Sopenharmony_ci 22941cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">printIterator</span>(<span class="hljs-params">readable</span>) { 22951cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> readable.<span class="hljs-title function_">iterator</span>({ <span class="hljs-attr">destroyOnReturn</span>: <span class="hljs-literal">false</span> })) { 22961cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk); <span class="hljs-comment">// 1</span> 22971cb0ef41Sopenharmony_ci <span class="hljs-keyword">break</span>; 22981cb0ef41Sopenharmony_ci } 22991cb0ef41Sopenharmony_ci 23001cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(readable.<span class="hljs-property">destroyed</span>); <span class="hljs-comment">// false</span> 23011cb0ef41Sopenharmony_ci 23021cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> readable.<span class="hljs-title function_">iterator</span>({ <span class="hljs-attr">destroyOnReturn</span>: <span class="hljs-literal">false</span> })) { 23031cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk); <span class="hljs-comment">// Will print 2 and then 3</span> 23041cb0ef41Sopenharmony_ci } 23051cb0ef41Sopenharmony_ci 23061cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(readable.<span class="hljs-property">destroyed</span>); <span class="hljs-comment">// True, stream was totally consumed</span> 23071cb0ef41Sopenharmony_ci} 23081cb0ef41Sopenharmony_ci 23091cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">printSymbolAsyncIterator</span>(<span class="hljs-params">readable</span>) { 23101cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> readable) { 23111cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk); <span class="hljs-comment">// 1</span> 23121cb0ef41Sopenharmony_ci <span class="hljs-keyword">break</span>; 23131cb0ef41Sopenharmony_ci } 23141cb0ef41Sopenharmony_ci 23151cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(readable.<span class="hljs-property">destroyed</span>); <span class="hljs-comment">// true</span> 23161cb0ef41Sopenharmony_ci} 23171cb0ef41Sopenharmony_ci 23181cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">showBoth</span>(<span class="hljs-params"></span>) { 23191cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">printIterator</span>(<span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>])); 23201cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">printSymbolAsyncIterator</span>(<span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>])); 23211cb0ef41Sopenharmony_ci} 23221cb0ef41Sopenharmony_ci 23231cb0ef41Sopenharmony_ci<span class="hljs-title function_">showBoth</span>();</code> <button class="copy-button">copy</button></pre> 23241cb0ef41Sopenharmony_ci<h6><code>readable.map(fn[, options])</code><span><a class="mark" href="#readablemapfn-options" id="readablemapfn-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_map_fn_options"></a></h6> 23251cb0ef41Sopenharmony_ci<div class="api_metadata"> 23261cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 23271cb0ef41Sopenharmony_ci<table> 23281cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 23291cb0ef41Sopenharmony_ci<tr><td>v18.19.0</td> 23301cb0ef41Sopenharmony_ci<td><p>added <code>highWaterMark</code> in options.</p></td></tr> 23311cb0ef41Sopenharmony_ci<tr><td>v17.4.0, v16.14.0</td> 23321cb0ef41Sopenharmony_ci<td><p><span>Added in: v17.4.0, v16.14.0</span></p></td></tr> 23331cb0ef41Sopenharmony_ci</tbody></table> 23341cb0ef41Sopenharmony_ci</details> 23351cb0ef41Sopenharmony_ci</div> 23361cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 23371cb0ef41Sopenharmony_ci<ul> 23381cb0ef41Sopenharmony_ci<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> a function to map over every chunk in the 23391cb0ef41Sopenharmony_cistream. 23401cb0ef41Sopenharmony_ci<ul> 23411cb0ef41Sopenharmony_ci<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> a chunk of data from the stream.</li> 23421cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 23431cb0ef41Sopenharmony_ci<ul> 23441cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> aborted if the stream is destroyed allowing to 23451cb0ef41Sopenharmony_ciabort the <code>fn</code> call early.</li> 23461cb0ef41Sopenharmony_ci</ul> 23471cb0ef41Sopenharmony_ci</li> 23481cb0ef41Sopenharmony_ci</ul> 23491cb0ef41Sopenharmony_ci</li> 23501cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 23511cb0ef41Sopenharmony_ci<ul> 23521cb0ef41Sopenharmony_ci<li><code>concurrency</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the maximum concurrent invocation of <code>fn</code> to call 23531cb0ef41Sopenharmony_cion the stream at once. <strong>Default:</strong> <code>1</code>.</li> 23541cb0ef41Sopenharmony_ci<li><code>highWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> how many items to buffer while waiting for user 23551cb0ef41Sopenharmony_ciconsumption of the mapped items. <strong>Default:</strong> <code>concurrency * 2 - 1</code>.</li> 23561cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 23571cb0ef41Sopenharmony_ciaborted.</li> 23581cb0ef41Sopenharmony_ci</ul> 23591cb0ef41Sopenharmony_ci</li> 23601cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamreadable" class="type"><Readable></a> a stream mapped with the function <code>fn</code>.</li> 23611cb0ef41Sopenharmony_ci</ul> 23621cb0ef41Sopenharmony_ci<p>This method allows mapping over the stream. The <code>fn</code> function will be called 23631cb0ef41Sopenharmony_cifor every chunk in the stream. If the <code>fn</code> function returns a promise - that 23641cb0ef41Sopenharmony_cipromise will be <code>await</code>ed before being passed to the result stream.</p> 23651cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 23661cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { <span class="hljs-title class_">Resolver</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:dns/promises'</span>; 23671cb0ef41Sopenharmony_ci 23681cb0ef41Sopenharmony_ci<span class="hljs-comment">// With a synchronous mapper.</span> 23691cb0ef41Sopenharmony_ci<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">map</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> x * <span class="hljs-number">2</span>)) { 23701cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk); <span class="hljs-comment">// 2, 4, 6, 8</span> 23711cb0ef41Sopenharmony_ci} 23721cb0ef41Sopenharmony_ci<span class="hljs-comment">// With an asynchronous mapper, making at most 2 queries at a time.</span> 23731cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> resolver = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Resolver</span>(); 23741cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> dnsResults = <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([ 23751cb0ef41Sopenharmony_ci <span class="hljs-string">'nodejs.org'</span>, 23761cb0ef41Sopenharmony_ci <span class="hljs-string">'openjsf.org'</span>, 23771cb0ef41Sopenharmony_ci <span class="hljs-string">'www.linuxfoundation.org'</span>, 23781cb0ef41Sopenharmony_ci]).<span class="hljs-title function_">map</span>(<span class="hljs-function">(<span class="hljs-params">domain</span>) =></span> resolver.<span class="hljs-title function_">resolve4</span>(domain), { <span class="hljs-attr">concurrency</span>: <span class="hljs-number">2</span> }); 23791cb0ef41Sopenharmony_ci<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> result <span class="hljs-keyword">of</span> dnsResults) { 23801cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(result); <span class="hljs-comment">// Logs the DNS result of resolver.resolve4.</span> 23811cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 23821cb0ef41Sopenharmony_ci<h6><code>readable.filter(fn[, options])</code><span><a class="mark" href="#readablefilterfn-options" id="readablefilterfn-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_filter_fn_options"></a></h6> 23831cb0ef41Sopenharmony_ci<div class="api_metadata"> 23841cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 23851cb0ef41Sopenharmony_ci<table> 23861cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 23871cb0ef41Sopenharmony_ci<tr><td>v18.19.0</td> 23881cb0ef41Sopenharmony_ci<td><p>added <code>highWaterMark</code> in options.</p></td></tr> 23891cb0ef41Sopenharmony_ci<tr><td>v17.4.0, v16.14.0</td> 23901cb0ef41Sopenharmony_ci<td><p><span>Added in: v17.4.0, v16.14.0</span></p></td></tr> 23911cb0ef41Sopenharmony_ci</tbody></table> 23921cb0ef41Sopenharmony_ci</details> 23931cb0ef41Sopenharmony_ci</div> 23941cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 23951cb0ef41Sopenharmony_ci<ul> 23961cb0ef41Sopenharmony_ci<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> a function to filter chunks from the stream. 23971cb0ef41Sopenharmony_ci<ul> 23981cb0ef41Sopenharmony_ci<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> a chunk of data from the stream.</li> 23991cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 24001cb0ef41Sopenharmony_ci<ul> 24011cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> aborted if the stream is destroyed allowing to 24021cb0ef41Sopenharmony_ciabort the <code>fn</code> call early.</li> 24031cb0ef41Sopenharmony_ci</ul> 24041cb0ef41Sopenharmony_ci</li> 24051cb0ef41Sopenharmony_ci</ul> 24061cb0ef41Sopenharmony_ci</li> 24071cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 24081cb0ef41Sopenharmony_ci<ul> 24091cb0ef41Sopenharmony_ci<li><code>concurrency</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the maximum concurrent invocation of <code>fn</code> to call 24101cb0ef41Sopenharmony_cion the stream at once. <strong>Default:</strong> <code>1</code>.</li> 24111cb0ef41Sopenharmony_ci<li><code>highWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> how many items to buffer while waiting for user 24121cb0ef41Sopenharmony_ciconsumption of the filtered items. <strong>Default:</strong> <code>concurrency * 2 - 1</code>.</li> 24131cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 24141cb0ef41Sopenharmony_ciaborted.</li> 24151cb0ef41Sopenharmony_ci</ul> 24161cb0ef41Sopenharmony_ci</li> 24171cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamreadable" class="type"><Readable></a> a stream filtered with the predicate <code>fn</code>.</li> 24181cb0ef41Sopenharmony_ci</ul> 24191cb0ef41Sopenharmony_ci<p>This method allows filtering the stream. For each chunk in the stream the <code>fn</code> 24201cb0ef41Sopenharmony_cifunction will be called and if it returns a truthy value, the chunk will be 24211cb0ef41Sopenharmony_cipassed to the result stream. If the <code>fn</code> function returns a promise - that 24221cb0ef41Sopenharmony_cipromise will be <code>await</code>ed.</p> 24231cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 24241cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { <span class="hljs-title class_">Resolver</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:dns/promises'</span>; 24251cb0ef41Sopenharmony_ci 24261cb0ef41Sopenharmony_ci<span class="hljs-comment">// With a synchronous predicate.</span> 24271cb0ef41Sopenharmony_ci<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">filter</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> x > <span class="hljs-number">2</span>)) { 24281cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk); <span class="hljs-comment">// 3, 4</span> 24291cb0ef41Sopenharmony_ci} 24301cb0ef41Sopenharmony_ci<span class="hljs-comment">// With an asynchronous predicate, making at most 2 queries at a time.</span> 24311cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> resolver = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Resolver</span>(); 24321cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> dnsResults = <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([ 24331cb0ef41Sopenharmony_ci <span class="hljs-string">'nodejs.org'</span>, 24341cb0ef41Sopenharmony_ci <span class="hljs-string">'openjsf.org'</span>, 24351cb0ef41Sopenharmony_ci <span class="hljs-string">'www.linuxfoundation.org'</span>, 24361cb0ef41Sopenharmony_ci]).<span class="hljs-title function_">filter</span>(<span class="hljs-keyword">async</span> (domain) => { 24371cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> { address } = <span class="hljs-keyword">await</span> resolver.<span class="hljs-title function_">resolve4</span>(domain, { <span class="hljs-attr">ttl</span>: <span class="hljs-literal">true</span> }); 24381cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> address.<span class="hljs-property">ttl</span> > <span class="hljs-number">60</span>; 24391cb0ef41Sopenharmony_ci}, { <span class="hljs-attr">concurrency</span>: <span class="hljs-number">2</span> }); 24401cb0ef41Sopenharmony_ci<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> result <span class="hljs-keyword">of</span> dnsResults) { 24411cb0ef41Sopenharmony_ci <span class="hljs-comment">// Logs domains with more than 60 seconds on the resolved dns record.</span> 24421cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(result); 24431cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 24441cb0ef41Sopenharmony_ci<h6><code>readable.forEach(fn[, options])</code><span><a class="mark" href="#readableforeachfn-options" id="readableforeachfn-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_foreach_fn_options"></a></h6> 24451cb0ef41Sopenharmony_ci<div class="api_metadata"> 24461cb0ef41Sopenharmony_ci<span>Added in: v17.5.0</span> 24471cb0ef41Sopenharmony_ci</div> 24481cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 24491cb0ef41Sopenharmony_ci<ul> 24501cb0ef41Sopenharmony_ci<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> a function to call on each chunk of the stream. 24511cb0ef41Sopenharmony_ci<ul> 24521cb0ef41Sopenharmony_ci<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> a chunk of data from the stream.</li> 24531cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 24541cb0ef41Sopenharmony_ci<ul> 24551cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> aborted if the stream is destroyed allowing to 24561cb0ef41Sopenharmony_ciabort the <code>fn</code> call early.</li> 24571cb0ef41Sopenharmony_ci</ul> 24581cb0ef41Sopenharmony_ci</li> 24591cb0ef41Sopenharmony_ci</ul> 24601cb0ef41Sopenharmony_ci</li> 24611cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 24621cb0ef41Sopenharmony_ci<ul> 24631cb0ef41Sopenharmony_ci<li><code>concurrency</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the maximum concurrent invocation of <code>fn</code> to call 24641cb0ef41Sopenharmony_cion the stream at once. <strong>Default:</strong> <code>1</code>.</li> 24651cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 24661cb0ef41Sopenharmony_ciaborted.</li> 24671cb0ef41Sopenharmony_ci</ul> 24681cb0ef41Sopenharmony_ci</li> 24691cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> a promise for when the stream has finished.</li> 24701cb0ef41Sopenharmony_ci</ul> 24711cb0ef41Sopenharmony_ci<p>This method allows iterating a stream. For each chunk in the stream the 24721cb0ef41Sopenharmony_ci<code>fn</code> function will be called. If the <code>fn</code> function returns a promise - that 24731cb0ef41Sopenharmony_cipromise will be <code>await</code>ed.</p> 24741cb0ef41Sopenharmony_ci<p>This method is different from <code>for await...of</code> loops in that it can optionally 24751cb0ef41Sopenharmony_ciprocess chunks concurrently. In addition, a <code>forEach</code> iteration can only be 24761cb0ef41Sopenharmony_cistopped by having passed a <code>signal</code> option and aborting the related 24771cb0ef41Sopenharmony_ci<code>AbortController</code> while <code>for await...of</code> can be stopped with <code>break</code> or 24781cb0ef41Sopenharmony_ci<code>return</code>. In either case the stream will be destroyed.</p> 24791cb0ef41Sopenharmony_ci<p>This method is different from listening to the <a href="#event-data"><code>'data'</code></a> event in that it 24801cb0ef41Sopenharmony_ciuses the <a href="#class-streamreadable"><code>readable</code></a> event in the underlying machinary and can limit the 24811cb0ef41Sopenharmony_cinumber of concurrent <code>fn</code> calls.</p> 24821cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 24831cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { <span class="hljs-title class_">Resolver</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:dns/promises'</span>; 24841cb0ef41Sopenharmony_ci 24851cb0ef41Sopenharmony_ci<span class="hljs-comment">// With a synchronous predicate.</span> 24861cb0ef41Sopenharmony_ci<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">filter</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> x > <span class="hljs-number">2</span>)) { 24871cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk); <span class="hljs-comment">// 3, 4</span> 24881cb0ef41Sopenharmony_ci} 24891cb0ef41Sopenharmony_ci<span class="hljs-comment">// With an asynchronous predicate, making at most 2 queries at a time.</span> 24901cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> resolver = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Resolver</span>(); 24911cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> dnsResults = <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([ 24921cb0ef41Sopenharmony_ci <span class="hljs-string">'nodejs.org'</span>, 24931cb0ef41Sopenharmony_ci <span class="hljs-string">'openjsf.org'</span>, 24941cb0ef41Sopenharmony_ci <span class="hljs-string">'www.linuxfoundation.org'</span>, 24951cb0ef41Sopenharmony_ci]).<span class="hljs-title function_">map</span>(<span class="hljs-keyword">async</span> (domain) => { 24961cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> { address } = <span class="hljs-keyword">await</span> resolver.<span class="hljs-title function_">resolve4</span>(domain, { <span class="hljs-attr">ttl</span>: <span class="hljs-literal">true</span> }); 24971cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> address; 24981cb0ef41Sopenharmony_ci}, { <span class="hljs-attr">concurrency</span>: <span class="hljs-number">2</span> }); 24991cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> dnsResults.<span class="hljs-title function_">forEach</span>(<span class="hljs-function">(<span class="hljs-params">result</span>) =></span> { 25001cb0ef41Sopenharmony_ci <span class="hljs-comment">// Logs result, similar to `for await (const result of dnsResults)`</span> 25011cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(result); 25021cb0ef41Sopenharmony_ci}); 25031cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'done'</span>); <span class="hljs-comment">// Stream has finished</span></code> <button class="copy-button">copy</button></pre> 25041cb0ef41Sopenharmony_ci<h6><code>readable.toArray([options])</code><span><a class="mark" href="#readabletoarrayoptions" id="readabletoarrayoptions">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_toarray_options"></a></h6> 25051cb0ef41Sopenharmony_ci<div class="api_metadata"> 25061cb0ef41Sopenharmony_ci<span>Added in: v17.5.0</span> 25071cb0ef41Sopenharmony_ci</div> 25081cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 25091cb0ef41Sopenharmony_ci<ul> 25101cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 25111cb0ef41Sopenharmony_ci<ul> 25121cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows cancelling the toArray operation if the 25131cb0ef41Sopenharmony_cisignal is aborted.</li> 25141cb0ef41Sopenharmony_ci</ul> 25151cb0ef41Sopenharmony_ci</li> 25161cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> a promise containing an array with the contents of the 25171cb0ef41Sopenharmony_cistream.</li> 25181cb0ef41Sopenharmony_ci</ul> 25191cb0ef41Sopenharmony_ci<p>This method allows easily obtaining the contents of a stream.</p> 25201cb0ef41Sopenharmony_ci<p>As this method reads the entire stream into memory, it negates the benefits of 25211cb0ef41Sopenharmony_cistreams. It's intended for interoperability and convenience, not as the primary 25221cb0ef41Sopenharmony_ciway to consume streams.</p> 25231cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 25241cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { <span class="hljs-title class_">Resolver</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:dns/promises'</span>; 25251cb0ef41Sopenharmony_ci 25261cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">toArray</span>(); <span class="hljs-comment">// [1, 2, 3, 4]</span> 25271cb0ef41Sopenharmony_ci 25281cb0ef41Sopenharmony_ci<span class="hljs-comment">// Make dns queries concurrently using .map and collect</span> 25291cb0ef41Sopenharmony_ci<span class="hljs-comment">// the results into an array using toArray</span> 25301cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> dnsResults = <span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([ 25311cb0ef41Sopenharmony_ci <span class="hljs-string">'nodejs.org'</span>, 25321cb0ef41Sopenharmony_ci <span class="hljs-string">'openjsf.org'</span>, 25331cb0ef41Sopenharmony_ci <span class="hljs-string">'www.linuxfoundation.org'</span>, 25341cb0ef41Sopenharmony_ci]).<span class="hljs-title function_">map</span>(<span class="hljs-keyword">async</span> (domain) => { 25351cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> { address } = <span class="hljs-keyword">await</span> resolver.<span class="hljs-title function_">resolve4</span>(domain, { <span class="hljs-attr">ttl</span>: <span class="hljs-literal">true</span> }); 25361cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> address; 25371cb0ef41Sopenharmony_ci}, { <span class="hljs-attr">concurrency</span>: <span class="hljs-number">2</span> }).<span class="hljs-title function_">toArray</span>();</code> <button class="copy-button">copy</button></pre> 25381cb0ef41Sopenharmony_ci<h6><code>readable.some(fn[, options])</code><span><a class="mark" href="#readablesomefn-options" id="readablesomefn-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_some_fn_options"></a></h6> 25391cb0ef41Sopenharmony_ci<div class="api_metadata"> 25401cb0ef41Sopenharmony_ci<span>Added in: v17.5.0</span> 25411cb0ef41Sopenharmony_ci</div> 25421cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 25431cb0ef41Sopenharmony_ci<ul> 25441cb0ef41Sopenharmony_ci<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> a function to call on each chunk of the stream. 25451cb0ef41Sopenharmony_ci<ul> 25461cb0ef41Sopenharmony_ci<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> a chunk of data from the stream.</li> 25471cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 25481cb0ef41Sopenharmony_ci<ul> 25491cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> aborted if the stream is destroyed allowing to 25501cb0ef41Sopenharmony_ciabort the <code>fn</code> call early.</li> 25511cb0ef41Sopenharmony_ci</ul> 25521cb0ef41Sopenharmony_ci</li> 25531cb0ef41Sopenharmony_ci</ul> 25541cb0ef41Sopenharmony_ci</li> 25551cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 25561cb0ef41Sopenharmony_ci<ul> 25571cb0ef41Sopenharmony_ci<li><code>concurrency</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the maximum concurrent invocation of <code>fn</code> to call 25581cb0ef41Sopenharmony_cion the stream at once. <strong>Default:</strong> <code>1</code>.</li> 25591cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 25601cb0ef41Sopenharmony_ciaborted.</li> 25611cb0ef41Sopenharmony_ci</ul> 25621cb0ef41Sopenharmony_ci</li> 25631cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> a promise evaluating to <code>true</code> if <code>fn</code> returned a truthy 25641cb0ef41Sopenharmony_civalue for at least one of the chunks.</li> 25651cb0ef41Sopenharmony_ci</ul> 25661cb0ef41Sopenharmony_ci<p>This method is similar to <code>Array.prototype.some</code> and calls <code>fn</code> on each chunk 25671cb0ef41Sopenharmony_ciin the stream until the awaited return value is <code>true</code> (or any truthy value). 25681cb0ef41Sopenharmony_ciOnce an <code>fn</code> call on a chunk awaited return value is truthy, the stream is 25691cb0ef41Sopenharmony_cidestroyed and the promise is fulfilled with <code>true</code>. If none of the <code>fn</code> 25701cb0ef41Sopenharmony_cicalls on the chunks return a truthy value, the promise is fulfilled with 25711cb0ef41Sopenharmony_ci<code>false</code>.</p> 25721cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 25731cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { stat } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs/promises'</span>; 25741cb0ef41Sopenharmony_ci 25751cb0ef41Sopenharmony_ci<span class="hljs-comment">// With a synchronous predicate.</span> 25761cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">some</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> x > <span class="hljs-number">2</span>); <span class="hljs-comment">// true</span> 25771cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">some</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> x < <span class="hljs-number">0</span>); <span class="hljs-comment">// false</span> 25781cb0ef41Sopenharmony_ci 25791cb0ef41Sopenharmony_ci<span class="hljs-comment">// With an asynchronous predicate, making at most 2 file checks at a time.</span> 25801cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> anyBigFile = <span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([ 25811cb0ef41Sopenharmony_ci <span class="hljs-string">'file1'</span>, 25821cb0ef41Sopenharmony_ci <span class="hljs-string">'file2'</span>, 25831cb0ef41Sopenharmony_ci <span class="hljs-string">'file3'</span>, 25841cb0ef41Sopenharmony_ci]).<span class="hljs-title function_">some</span>(<span class="hljs-keyword">async</span> (fileName) => { 25851cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> stats = <span class="hljs-keyword">await</span> <span class="hljs-title function_">stat</span>(fileName); 25861cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> stats.<span class="hljs-property">size</span> > <span class="hljs-number">1024</span> * <span class="hljs-number">1024</span>; 25871cb0ef41Sopenharmony_ci}, { <span class="hljs-attr">concurrency</span>: <span class="hljs-number">2</span> }); 25881cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(anyBigFile); <span class="hljs-comment">// `true` if any file in the list is bigger than 1MB</span> 25891cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'done'</span>); <span class="hljs-comment">// Stream has finished</span></code> <button class="copy-button">copy</button></pre> 25901cb0ef41Sopenharmony_ci<h6><code>readable.find(fn[, options])</code><span><a class="mark" href="#readablefindfn-options" id="readablefindfn-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_find_fn_options"></a></h6> 25911cb0ef41Sopenharmony_ci<div class="api_metadata"> 25921cb0ef41Sopenharmony_ci<span>Added in: v17.5.0</span> 25931cb0ef41Sopenharmony_ci</div> 25941cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 25951cb0ef41Sopenharmony_ci<ul> 25961cb0ef41Sopenharmony_ci<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> a function to call on each chunk of the stream. 25971cb0ef41Sopenharmony_ci<ul> 25981cb0ef41Sopenharmony_ci<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> a chunk of data from the stream.</li> 25991cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 26001cb0ef41Sopenharmony_ci<ul> 26011cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> aborted if the stream is destroyed allowing to 26021cb0ef41Sopenharmony_ciabort the <code>fn</code> call early.</li> 26031cb0ef41Sopenharmony_ci</ul> 26041cb0ef41Sopenharmony_ci</li> 26051cb0ef41Sopenharmony_ci</ul> 26061cb0ef41Sopenharmony_ci</li> 26071cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 26081cb0ef41Sopenharmony_ci<ul> 26091cb0ef41Sopenharmony_ci<li><code>concurrency</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the maximum concurrent invocation of <code>fn</code> to call 26101cb0ef41Sopenharmony_cion the stream at once. <strong>Default:</strong> <code>1</code>.</li> 26111cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 26121cb0ef41Sopenharmony_ciaborted.</li> 26131cb0ef41Sopenharmony_ci</ul> 26141cb0ef41Sopenharmony_ci</li> 26151cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> a promise evaluating to the first chunk for which <code>fn</code> 26161cb0ef41Sopenharmony_cievaluated with a truthy value, or <code>undefined</code> if no element was found.</li> 26171cb0ef41Sopenharmony_ci</ul> 26181cb0ef41Sopenharmony_ci<p>This method is similar to <code>Array.prototype.find</code> and calls <code>fn</code> on each chunk 26191cb0ef41Sopenharmony_ciin the stream to find a chunk with a truthy value for <code>fn</code>. Once an <code>fn</code> call's 26201cb0ef41Sopenharmony_ciawaited return value is truthy, the stream is destroyed and the promise is 26211cb0ef41Sopenharmony_cifulfilled with value for which <code>fn</code> returned a truthy value. If all of the 26221cb0ef41Sopenharmony_ci<code>fn</code> calls on the chunks return a falsy value, the promise is fulfilled with 26231cb0ef41Sopenharmony_ci<code>undefined</code>.</p> 26241cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 26251cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { stat } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs/promises'</span>; 26261cb0ef41Sopenharmony_ci 26271cb0ef41Sopenharmony_ci<span class="hljs-comment">// With a synchronous predicate.</span> 26281cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">find</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> x > <span class="hljs-number">2</span>); <span class="hljs-comment">// 3</span> 26291cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">find</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> x > <span class="hljs-number">0</span>); <span class="hljs-comment">// 1</span> 26301cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">find</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> x > <span class="hljs-number">10</span>); <span class="hljs-comment">// undefined</span> 26311cb0ef41Sopenharmony_ci 26321cb0ef41Sopenharmony_ci<span class="hljs-comment">// With an asynchronous predicate, making at most 2 file checks at a time.</span> 26331cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> foundBigFile = <span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([ 26341cb0ef41Sopenharmony_ci <span class="hljs-string">'file1'</span>, 26351cb0ef41Sopenharmony_ci <span class="hljs-string">'file2'</span>, 26361cb0ef41Sopenharmony_ci <span class="hljs-string">'file3'</span>, 26371cb0ef41Sopenharmony_ci]).<span class="hljs-title function_">find</span>(<span class="hljs-keyword">async</span> (fileName) => { 26381cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> stats = <span class="hljs-keyword">await</span> <span class="hljs-title function_">stat</span>(fileName); 26391cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> stats.<span class="hljs-property">size</span> > <span class="hljs-number">1024</span> * <span class="hljs-number">1024</span>; 26401cb0ef41Sopenharmony_ci}, { <span class="hljs-attr">concurrency</span>: <span class="hljs-number">2</span> }); 26411cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(foundBigFile); <span class="hljs-comment">// File name of large file, if any file in the list is bigger than 1MB</span> 26421cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'done'</span>); <span class="hljs-comment">// Stream has finished</span></code> <button class="copy-button">copy</button></pre> 26431cb0ef41Sopenharmony_ci<h6><code>readable.every(fn[, options])</code><span><a class="mark" href="#readableeveryfn-options" id="readableeveryfn-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_every_fn_options"></a></h6> 26441cb0ef41Sopenharmony_ci<div class="api_metadata"> 26451cb0ef41Sopenharmony_ci<span>Added in: v17.5.0</span> 26461cb0ef41Sopenharmony_ci</div> 26471cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 26481cb0ef41Sopenharmony_ci<ul> 26491cb0ef41Sopenharmony_ci<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> a function to call on each chunk of the stream. 26501cb0ef41Sopenharmony_ci<ul> 26511cb0ef41Sopenharmony_ci<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> a chunk of data from the stream.</li> 26521cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 26531cb0ef41Sopenharmony_ci<ul> 26541cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> aborted if the stream is destroyed allowing to 26551cb0ef41Sopenharmony_ciabort the <code>fn</code> call early.</li> 26561cb0ef41Sopenharmony_ci</ul> 26571cb0ef41Sopenharmony_ci</li> 26581cb0ef41Sopenharmony_ci</ul> 26591cb0ef41Sopenharmony_ci</li> 26601cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 26611cb0ef41Sopenharmony_ci<ul> 26621cb0ef41Sopenharmony_ci<li><code>concurrency</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the maximum concurrent invocation of <code>fn</code> to call 26631cb0ef41Sopenharmony_cion the stream at once. <strong>Default:</strong> <code>1</code>.</li> 26641cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 26651cb0ef41Sopenharmony_ciaborted.</li> 26661cb0ef41Sopenharmony_ci</ul> 26671cb0ef41Sopenharmony_ci</li> 26681cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> a promise evaluating to <code>true</code> if <code>fn</code> returned a truthy 26691cb0ef41Sopenharmony_civalue for all of the chunks.</li> 26701cb0ef41Sopenharmony_ci</ul> 26711cb0ef41Sopenharmony_ci<p>This method is similar to <code>Array.prototype.every</code> and calls <code>fn</code> on each chunk 26721cb0ef41Sopenharmony_ciin the stream to check if all awaited return values are truthy value for <code>fn</code>. 26731cb0ef41Sopenharmony_ciOnce an <code>fn</code> call on a chunk awaited return value is falsy, the stream is 26741cb0ef41Sopenharmony_cidestroyed and the promise is fulfilled with <code>false</code>. If all of the <code>fn</code> calls 26751cb0ef41Sopenharmony_cion the chunks return a truthy value, the promise is fulfilled with <code>true</code>.</p> 26761cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 26771cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { stat } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs/promises'</span>; 26781cb0ef41Sopenharmony_ci 26791cb0ef41Sopenharmony_ci<span class="hljs-comment">// With a synchronous predicate.</span> 26801cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">every</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> x > <span class="hljs-number">2</span>); <span class="hljs-comment">// false</span> 26811cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">every</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> x > <span class="hljs-number">0</span>); <span class="hljs-comment">// true</span> 26821cb0ef41Sopenharmony_ci 26831cb0ef41Sopenharmony_ci<span class="hljs-comment">// With an asynchronous predicate, making at most 2 file checks at a time.</span> 26841cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> allBigFiles = <span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([ 26851cb0ef41Sopenharmony_ci <span class="hljs-string">'file1'</span>, 26861cb0ef41Sopenharmony_ci <span class="hljs-string">'file2'</span>, 26871cb0ef41Sopenharmony_ci <span class="hljs-string">'file3'</span>, 26881cb0ef41Sopenharmony_ci]).<span class="hljs-title function_">every</span>(<span class="hljs-keyword">async</span> (fileName) => { 26891cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> stats = <span class="hljs-keyword">await</span> <span class="hljs-title function_">stat</span>(fileName); 26901cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> stats.<span class="hljs-property">size</span> > <span class="hljs-number">1024</span> * <span class="hljs-number">1024</span>; 26911cb0ef41Sopenharmony_ci}, { <span class="hljs-attr">concurrency</span>: <span class="hljs-number">2</span> }); 26921cb0ef41Sopenharmony_ci<span class="hljs-comment">// `true` if all files in the list are bigger than 1MiB</span> 26931cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(allBigFiles); 26941cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'done'</span>); <span class="hljs-comment">// Stream has finished</span></code> <button class="copy-button">copy</button></pre> 26951cb0ef41Sopenharmony_ci<h6><code>readable.flatMap(fn[, options])</code><span><a class="mark" href="#readableflatmapfn-options" id="readableflatmapfn-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_flatmap_fn_options"></a></h6> 26961cb0ef41Sopenharmony_ci<div class="api_metadata"> 26971cb0ef41Sopenharmony_ci<span>Added in: v17.5.0</span> 26981cb0ef41Sopenharmony_ci</div> 26991cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 27001cb0ef41Sopenharmony_ci<ul> 27011cb0ef41Sopenharmony_ci<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/proposal-async-iteration/#sec-asyncgeneratorfunction-constructor" class="type"><AsyncGeneratorFunction></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> a function to map over 27021cb0ef41Sopenharmony_cievery chunk in the stream. 27031cb0ef41Sopenharmony_ci<ul> 27041cb0ef41Sopenharmony_ci<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> a chunk of data from the stream.</li> 27051cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 27061cb0ef41Sopenharmony_ci<ul> 27071cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> aborted if the stream is destroyed allowing to 27081cb0ef41Sopenharmony_ciabort the <code>fn</code> call early.</li> 27091cb0ef41Sopenharmony_ci</ul> 27101cb0ef41Sopenharmony_ci</li> 27111cb0ef41Sopenharmony_ci</ul> 27121cb0ef41Sopenharmony_ci</li> 27131cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 27141cb0ef41Sopenharmony_ci<ul> 27151cb0ef41Sopenharmony_ci<li><code>concurrency</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the maximum concurrent invocation of <code>fn</code> to call 27161cb0ef41Sopenharmony_cion the stream at once. <strong>Default:</strong> <code>1</code>.</li> 27171cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 27181cb0ef41Sopenharmony_ciaborted.</li> 27191cb0ef41Sopenharmony_ci</ul> 27201cb0ef41Sopenharmony_ci</li> 27211cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamreadable" class="type"><Readable></a> a stream flat-mapped with the function <code>fn</code>.</li> 27221cb0ef41Sopenharmony_ci</ul> 27231cb0ef41Sopenharmony_ci<p>This method returns a new stream by applying the given callback to each 27241cb0ef41Sopenharmony_cichunk of the stream and then flattening the result.</p> 27251cb0ef41Sopenharmony_ci<p>It is possible to return a stream or another iterable or async iterable from 27261cb0ef41Sopenharmony_ci<code>fn</code> and the result streams will be merged (flattened) into the returned 27271cb0ef41Sopenharmony_cistream.</p> 27281cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 27291cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { createReadStream } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs'</span>; 27301cb0ef41Sopenharmony_ci 27311cb0ef41Sopenharmony_ci<span class="hljs-comment">// With a synchronous mapper.</span> 27321cb0ef41Sopenharmony_ci<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">flatMap</span>(<span class="hljs-function">(<span class="hljs-params">x</span>) =></span> [x, x])) { 27331cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk); <span class="hljs-comment">// 1, 1, 2, 2, 3, 3, 4, 4</span> 27341cb0ef41Sopenharmony_ci} 27351cb0ef41Sopenharmony_ci<span class="hljs-comment">// With an asynchronous mapper, combine the contents of 4 files</span> 27361cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> concatResult = <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([ 27371cb0ef41Sopenharmony_ci <span class="hljs-string">'./1.mjs'</span>, 27381cb0ef41Sopenharmony_ci <span class="hljs-string">'./2.mjs'</span>, 27391cb0ef41Sopenharmony_ci <span class="hljs-string">'./3.mjs'</span>, 27401cb0ef41Sopenharmony_ci <span class="hljs-string">'./4.mjs'</span>, 27411cb0ef41Sopenharmony_ci]).<span class="hljs-title function_">flatMap</span>(<span class="hljs-function">(<span class="hljs-params">fileName</span>) =></span> <span class="hljs-title function_">createReadStream</span>(fileName)); 27421cb0ef41Sopenharmony_ci<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> result <span class="hljs-keyword">of</span> concatResult) { 27431cb0ef41Sopenharmony_ci <span class="hljs-comment">// This will contain the contents (all chunks) of all 4 files</span> 27441cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(result); 27451cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 27461cb0ef41Sopenharmony_ci<h6><code>readable.drop(limit[, options])</code><span><a class="mark" href="#readabledroplimit-options" id="readabledroplimit-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_drop_limit_options"></a></h6> 27471cb0ef41Sopenharmony_ci<div class="api_metadata"> 27481cb0ef41Sopenharmony_ci<span>Added in: v17.5.0</span> 27491cb0ef41Sopenharmony_ci</div> 27501cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 27511cb0ef41Sopenharmony_ci<ul> 27521cb0ef41Sopenharmony_ci<li><code>limit</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the number of chunks to drop from the readable.</li> 27531cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 27541cb0ef41Sopenharmony_ci<ul> 27551cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 27561cb0ef41Sopenharmony_ciaborted.</li> 27571cb0ef41Sopenharmony_ci</ul> 27581cb0ef41Sopenharmony_ci</li> 27591cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamreadable" class="type"><Readable></a> a stream with <code>limit</code> chunks dropped.</li> 27601cb0ef41Sopenharmony_ci</ul> 27611cb0ef41Sopenharmony_ci<p>This method returns a new stream with the first <code>limit</code> chunks dropped.</p> 27621cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 27631cb0ef41Sopenharmony_ci 27641cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">drop</span>(<span class="hljs-number">2</span>).<span class="hljs-title function_">toArray</span>(); <span class="hljs-comment">// [3, 4]</span></code> <button class="copy-button">copy</button></pre> 27651cb0ef41Sopenharmony_ci<h6><code>readable.take(limit[, options])</code><span><a class="mark" href="#readabletakelimit-options" id="readabletakelimit-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_take_limit_options"></a></h6> 27661cb0ef41Sopenharmony_ci<div class="api_metadata"> 27671cb0ef41Sopenharmony_ci<span>Added in: v17.5.0</span> 27681cb0ef41Sopenharmony_ci</div> 27691cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 27701cb0ef41Sopenharmony_ci<ul> 27711cb0ef41Sopenharmony_ci<li><code>limit</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> the number of chunks to take from the readable.</li> 27721cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 27731cb0ef41Sopenharmony_ci<ul> 27741cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 27751cb0ef41Sopenharmony_ciaborted.</li> 27761cb0ef41Sopenharmony_ci</ul> 27771cb0ef41Sopenharmony_ci</li> 27781cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamreadable" class="type"><Readable></a> a stream with <code>limit</code> chunks taken.</li> 27791cb0ef41Sopenharmony_ci</ul> 27801cb0ef41Sopenharmony_ci<p>This method returns a new stream with the first <code>limit</code> chunks.</p> 27811cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 27821cb0ef41Sopenharmony_ci 27831cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-number">1</span>, <span class="hljs-number">2</span>, <span class="hljs-number">3</span>, <span class="hljs-number">4</span>]).<span class="hljs-title function_">take</span>(<span class="hljs-number">2</span>).<span class="hljs-title function_">toArray</span>(); <span class="hljs-comment">// [1, 2]</span></code> <button class="copy-button">copy</button></pre> 27841cb0ef41Sopenharmony_ci<h6><code>readable.asIndexedPairs([options])</code><span><a class="mark" href="#readableasindexedpairsoptions" id="readableasindexedpairsoptions">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_asindexedpairs_options"></a></h6> 27851cb0ef41Sopenharmony_ci<div class="api_metadata"> 27861cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 27871cb0ef41Sopenharmony_ci<table> 27881cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 27891cb0ef41Sopenharmony_ci<tr><td>v18.17.0</td> 27901cb0ef41Sopenharmony_ci<td><p>Using the <code>asIndexedPairs</code> method emits a runtime warning that it will be removed in a future version.</p></td></tr> 27911cb0ef41Sopenharmony_ci<tr><td>v17.5.0</td> 27921cb0ef41Sopenharmony_ci<td><p><span>Added in: v17.5.0</span></p></td></tr> 27931cb0ef41Sopenharmony_ci</tbody></table> 27941cb0ef41Sopenharmony_ci</details> 27951cb0ef41Sopenharmony_ci</div> 27961cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 27971cb0ef41Sopenharmony_ci<ul> 27981cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 27991cb0ef41Sopenharmony_ci<ul> 28001cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 28011cb0ef41Sopenharmony_ciaborted.</li> 28021cb0ef41Sopenharmony_ci</ul> 28031cb0ef41Sopenharmony_ci</li> 28041cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamreadable" class="type"><Readable></a> a stream of indexed pairs.</li> 28051cb0ef41Sopenharmony_ci</ul> 28061cb0ef41Sopenharmony_ci<p>This method returns a new stream with chunks of the underlying stream paired 28071cb0ef41Sopenharmony_ciwith a counter in the form <code>[index, chunk]</code>. The first index value is 0 and it 28081cb0ef41Sopenharmony_ciincreases by 1 for each chunk produced.</p> 28091cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 28101cb0ef41Sopenharmony_ci 28111cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> pairs = <span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([<span class="hljs-string">'a'</span>, <span class="hljs-string">'b'</span>, <span class="hljs-string">'c'</span>]).<span class="hljs-title function_">asIndexedPairs</span>().<span class="hljs-title function_">toArray</span>(); 28121cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(pairs); <span class="hljs-comment">// [[0, 'a'], [1, 'b'], [2, 'c']]</span></code> <button class="copy-button">copy</button></pre> 28131cb0ef41Sopenharmony_ci<h6><code>readable.reduce(fn[, initial[, options]])</code><span><a class="mark" href="#readablereducefn-initial-options" id="readablereducefn-initial-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_reduce_fn_initial_options"></a></h6> 28141cb0ef41Sopenharmony_ci<div class="api_metadata"> 28151cb0ef41Sopenharmony_ci<span>Added in: v17.5.0</span> 28161cb0ef41Sopenharmony_ci</div> 28171cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 28181cb0ef41Sopenharmony_ci<ul> 28191cb0ef41Sopenharmony_ci<li><code>fn</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> a reducer function to call over every chunk 28201cb0ef41Sopenharmony_ciin the stream. 28211cb0ef41Sopenharmony_ci<ul> 28221cb0ef41Sopenharmony_ci<li><code>previous</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> the value obtained from the last call to <code>fn</code> or the 28231cb0ef41Sopenharmony_ci<code>initial</code> value if specified or the first chunk of the stream otherwise.</li> 28241cb0ef41Sopenharmony_ci<li><code>data</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> a chunk of data from the stream.</li> 28251cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 28261cb0ef41Sopenharmony_ci<ul> 28271cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> aborted if the stream is destroyed allowing to 28281cb0ef41Sopenharmony_ciabort the <code>fn</code> call early.</li> 28291cb0ef41Sopenharmony_ci</ul> 28301cb0ef41Sopenharmony_ci</li> 28311cb0ef41Sopenharmony_ci</ul> 28321cb0ef41Sopenharmony_ci</li> 28331cb0ef41Sopenharmony_ci<li><code>initial</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> the initial value to use in the reduction.</li> 28341cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 28351cb0ef41Sopenharmony_ci<ul> 28361cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows destroying the stream if the signal is 28371cb0ef41Sopenharmony_ciaborted.</li> 28381cb0ef41Sopenharmony_ci</ul> 28391cb0ef41Sopenharmony_ci</li> 28401cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> a promise for the final value of the reduction.</li> 28411cb0ef41Sopenharmony_ci</ul> 28421cb0ef41Sopenharmony_ci<p>This method calls <code>fn</code> on each chunk of the stream in order, passing it the 28431cb0ef41Sopenharmony_ciresult from the calculation on the previous element. It returns a promise for 28441cb0ef41Sopenharmony_cithe final value of the reduction.</p> 28451cb0ef41Sopenharmony_ci<p>If no <code>initial</code> value is supplied the first chunk of the stream is used as the 28461cb0ef41Sopenharmony_ciinitial value. If the stream is empty, the promise is rejected with a 28471cb0ef41Sopenharmony_ci<code>TypeError</code> with the <code>ERR_INVALID_ARGS</code> code property.</p> 28481cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 28491cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { readdir, stat } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs/promises'</span>; 28501cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { join } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:path'</span>; 28511cb0ef41Sopenharmony_ci 28521cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> directoryPath = <span class="hljs-string">'./src'</span>; 28531cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> filesInDir = <span class="hljs-keyword">await</span> <span class="hljs-title function_">readdir</span>(directoryPath); 28541cb0ef41Sopenharmony_ci 28551cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> folderSize = <span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>(filesInDir) 28561cb0ef41Sopenharmony_ci .<span class="hljs-title function_">reduce</span>(<span class="hljs-keyword">async</span> (totalSize, file) => { 28571cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> { size } = <span class="hljs-keyword">await</span> <span class="hljs-title function_">stat</span>(<span class="hljs-title function_">join</span>(directoryPath, file)); 28581cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> totalSize + size; 28591cb0ef41Sopenharmony_ci }, <span class="hljs-number">0</span>); 28601cb0ef41Sopenharmony_ci 28611cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(folderSize);</code> <button class="copy-button">copy</button></pre> 28621cb0ef41Sopenharmony_ci<p>The reducer function iterates the stream element-by-element which means that 28631cb0ef41Sopenharmony_cithere is no <code>concurrency</code> parameter or parallelism. To perform a <code>reduce</code> 28641cb0ef41Sopenharmony_ciconcurrently, you can extract the async function to <a href="#readablemapfn-options"><code>readable.map</code></a> method.</p> 28651cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Readable</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 28661cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { readdir, stat } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:fs/promises'</span>; 28671cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { join } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:path'</span>; 28681cb0ef41Sopenharmony_ci 28691cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> directoryPath = <span class="hljs-string">'./src'</span>; 28701cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> filesInDir = <span class="hljs-keyword">await</span> <span class="hljs-title function_">readdir</span>(directoryPath); 28711cb0ef41Sopenharmony_ci 28721cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> folderSize = <span class="hljs-keyword">await</span> <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>(filesInDir) 28731cb0ef41Sopenharmony_ci .<span class="hljs-title function_">map</span>(<span class="hljs-function">(<span class="hljs-params">file</span>) =></span> <span class="hljs-title function_">stat</span>(<span class="hljs-title function_">join</span>(directoryPath, file)), { <span class="hljs-attr">concurrency</span>: <span class="hljs-number">2</span> }) 28741cb0ef41Sopenharmony_ci .<span class="hljs-title function_">reduce</span>(<span class="hljs-function">(<span class="hljs-params">totalSize, { size }</span>) =></span> totalSize + size, <span class="hljs-number">0</span>); 28751cb0ef41Sopenharmony_ci 28761cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(folderSize);</code> <button class="copy-button">copy</button></pre> 28771cb0ef41Sopenharmony_ci<h4>Duplex and transform streams<span><a class="mark" href="#duplex-and-transform-streams" id="duplex-and-transform-streams">#</a></span><a aria-hidden="true" class="legacy" id="stream_duplex_and_transform_streams"></a></h4> 28781cb0ef41Sopenharmony_ci<h5>Class: <code>stream.Duplex</code><span><a class="mark" href="#class-streamduplex" id="class-streamduplex">#</a></span><a aria-hidden="true" class="legacy" id="stream_class_stream_duplex"></a></h5> 28791cb0ef41Sopenharmony_ci<div class="api_metadata"> 28801cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 28811cb0ef41Sopenharmony_ci<table> 28821cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 28831cb0ef41Sopenharmony_ci<tr><td>v6.8.0</td> 28841cb0ef41Sopenharmony_ci<td><p>Instances of <code>Duplex</code> now return <code>true</code> when checking <code>instanceof stream.Writable</code>.</p></td></tr> 28851cb0ef41Sopenharmony_ci<tr><td>v0.9.4</td> 28861cb0ef41Sopenharmony_ci<td><p><span>Added in: v0.9.4</span></p></td></tr> 28871cb0ef41Sopenharmony_ci</tbody></table> 28881cb0ef41Sopenharmony_ci</details> 28891cb0ef41Sopenharmony_ci</div> 28901cb0ef41Sopenharmony_ci 28911cb0ef41Sopenharmony_ci<p>Duplex streams are streams that implement both the <a href="#class-streamreadable"><code>Readable</code></a> and 28921cb0ef41Sopenharmony_ci<a href="#class-streamwritable"><code>Writable</code></a> interfaces.</p> 28931cb0ef41Sopenharmony_ci<p>Examples of <code>Duplex</code> streams include:</p> 28941cb0ef41Sopenharmony_ci<ul> 28951cb0ef41Sopenharmony_ci<li><a href="net.html#class-netsocket">TCP sockets</a></li> 28961cb0ef41Sopenharmony_ci<li><a href="zlib.html">zlib streams</a></li> 28971cb0ef41Sopenharmony_ci<li><a href="crypto.html">crypto streams</a></li> 28981cb0ef41Sopenharmony_ci</ul> 28991cb0ef41Sopenharmony_ci<h6><code>duplex.allowHalfOpen</code><span><a class="mark" href="#duplexallowhalfopen" id="duplexallowhalfopen">#</a></span><a aria-hidden="true" class="legacy" id="stream_duplex_allowhalfopen"></a></h6> 29001cb0ef41Sopenharmony_ci<div class="api_metadata"> 29011cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 29021cb0ef41Sopenharmony_ci</div> 29031cb0ef41Sopenharmony_ci<ul> 29041cb0ef41Sopenharmony_ci<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 29051cb0ef41Sopenharmony_ci</ul> 29061cb0ef41Sopenharmony_ci<p>If <code>false</code> then the stream will automatically end the writable side when the 29071cb0ef41Sopenharmony_cireadable side ends. Set initially by the <code>allowHalfOpen</code> constructor option, 29081cb0ef41Sopenharmony_ciwhich defaults to <code>true</code>.</p> 29091cb0ef41Sopenharmony_ci<p>This can be changed manually to change the half-open behavior of an existing 29101cb0ef41Sopenharmony_ci<code>Duplex</code> stream instance, but must be changed before the <code>'end'</code> event is 29111cb0ef41Sopenharmony_ciemitted.</p> 29121cb0ef41Sopenharmony_ci<h5>Class: <code>stream.Transform</code><span><a class="mark" href="#class-streamtransform" id="class-streamtransform">#</a></span><a aria-hidden="true" class="legacy" id="stream_class_stream_transform"></a></h5> 29131cb0ef41Sopenharmony_ci<div class="api_metadata"> 29141cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 29151cb0ef41Sopenharmony_ci</div> 29161cb0ef41Sopenharmony_ci 29171cb0ef41Sopenharmony_ci<p>Transform streams are <a href="#class-streamduplex"><code>Duplex</code></a> streams where the output is in some way 29181cb0ef41Sopenharmony_cirelated to the input. Like all <a href="#class-streamduplex"><code>Duplex</code></a> streams, <code>Transform</code> streams 29191cb0ef41Sopenharmony_ciimplement both the <a href="#class-streamreadable"><code>Readable</code></a> and <a href="#class-streamwritable"><code>Writable</code></a> interfaces.</p> 29201cb0ef41Sopenharmony_ci<p>Examples of <code>Transform</code> streams include:</p> 29211cb0ef41Sopenharmony_ci<ul> 29221cb0ef41Sopenharmony_ci<li><a href="zlib.html">zlib streams</a></li> 29231cb0ef41Sopenharmony_ci<li><a href="crypto.html">crypto streams</a></li> 29241cb0ef41Sopenharmony_ci</ul> 29251cb0ef41Sopenharmony_ci<h6><code>transform.destroy([error])</code><span><a class="mark" href="#transformdestroyerror" id="transformdestroyerror">#</a></span><a aria-hidden="true" class="legacy" id="stream_transform_destroy_error"></a></h6> 29261cb0ef41Sopenharmony_ci<div class="api_metadata"> 29271cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 29281cb0ef41Sopenharmony_ci<table> 29291cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 29301cb0ef41Sopenharmony_ci<tr><td>v14.0.0</td> 29311cb0ef41Sopenharmony_ci<td><p>Work as a no-op on a stream that has already been destroyed.</p></td></tr> 29321cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 29331cb0ef41Sopenharmony_ci<td><p><span>Added in: v8.0.0</span></p></td></tr> 29341cb0ef41Sopenharmony_ci</tbody></table> 29351cb0ef41Sopenharmony_ci</details> 29361cb0ef41Sopenharmony_ci</div> 29371cb0ef41Sopenharmony_ci<ul> 29381cb0ef41Sopenharmony_ci<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 29391cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this" class="type"><this></a></li> 29401cb0ef41Sopenharmony_ci</ul> 29411cb0ef41Sopenharmony_ci<p>Destroy the stream, and optionally emit an <code>'error'</code> event. After this call, the 29421cb0ef41Sopenharmony_citransform stream would release any internal resources. 29431cb0ef41Sopenharmony_ciImplementors should not override this method, but instead implement 29441cb0ef41Sopenharmony_ci<a href="#readable_destroyerr-callback"><code>readable._destroy()</code></a>. 29451cb0ef41Sopenharmony_ciThe default implementation of <code>_destroy()</code> for <code>Transform</code> also emit <code>'close'</code> 29461cb0ef41Sopenharmony_ciunless <code>emitClose</code> is set in false.</p> 29471cb0ef41Sopenharmony_ci<p>Once <code>destroy()</code> has been called, any further calls will be a no-op and no 29481cb0ef41Sopenharmony_cifurther errors except from <code>_destroy()</code> may be emitted as <code>'error'</code>.</p> 29491cb0ef41Sopenharmony_ci<h4><code>stream.finished(stream[, options], callback)</code><span><a class="mark" href="#streamfinishedstream-options-callback" id="streamfinishedstream-options-callback">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_finished_stream_options_callback"></a></h4> 29501cb0ef41Sopenharmony_ci<div class="api_metadata"> 29511cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 29521cb0ef41Sopenharmony_ci<table> 29531cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 29541cb0ef41Sopenharmony_ci<tr><td>v18.14.0</td> 29551cb0ef41Sopenharmony_ci<td><p>Added support for <code>ReadableStream</code> and <code>WritableStream</code>.</p></td></tr> 29561cb0ef41Sopenharmony_ci<tr><td>v15.11.0</td> 29571cb0ef41Sopenharmony_ci<td><p>The <code>signal</code> option was added.</p></td></tr> 29581cb0ef41Sopenharmony_ci<tr><td>v14.0.0</td> 29591cb0ef41Sopenharmony_ci<td><p>The <code>finished(stream, cb)</code> will wait for the <code>'close'</code> event before invoking the callback. The implementation tries to detect legacy streams and only apply this behavior to streams which are expected to emit <code>'close'</code>.</p></td></tr> 29601cb0ef41Sopenharmony_ci<tr><td>v14.0.0</td> 29611cb0ef41Sopenharmony_ci<td><p>Emitting <code>'close'</code> before <code>'end'</code> on a <code>Readable</code> stream will cause an <code>ERR_STREAM_PREMATURE_CLOSE</code> error.</p></td></tr> 29621cb0ef41Sopenharmony_ci<tr><td>v14.0.0</td> 29631cb0ef41Sopenharmony_ci<td><p>Callback will be invoked on streams which have already finished before the call to <code>finished(stream, cb)</code>.</p></td></tr> 29641cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 29651cb0ef41Sopenharmony_ci<td><p><span>Added in: v10.0.0</span></p></td></tr> 29661cb0ef41Sopenharmony_ci</tbody></table> 29671cb0ef41Sopenharmony_ci</details> 29681cb0ef41Sopenharmony_ci</div> 29691cb0ef41Sopenharmony_ci<ul> 29701cb0ef41Sopenharmony_ci<li><code>stream</code> <a href="stream.html#stream" class="type"><Stream></a> | <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a> | <a href="webstreams.html#class-writablestream" class="type"><WritableStream></a></li> 29711cb0ef41Sopenharmony_ci</ul> 29721cb0ef41Sopenharmony_ci<p>A readable and/or writable stream/webstream.</p> 29731cb0ef41Sopenharmony_ci<ul> 29741cb0ef41Sopenharmony_ci<li> 29751cb0ef41Sopenharmony_ci<p><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></p> 29761cb0ef41Sopenharmony_ci<ul> 29771cb0ef41Sopenharmony_ci<li><code>error</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If set to <code>false</code>, then a call to <code>emit('error', err)</code> is 29781cb0ef41Sopenharmony_cinot treated as finished. <strong>Default:</strong> <code>true</code>.</li> 29791cb0ef41Sopenharmony_ci<li><code>readable</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> When set to <code>false</code>, the callback will be called when 29801cb0ef41Sopenharmony_cithe stream ends even though the stream might still be readable. 29811cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>true</code>.</li> 29821cb0ef41Sopenharmony_ci<li><code>writable</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> When set to <code>false</code>, the callback will be called when 29831cb0ef41Sopenharmony_cithe stream ends even though the stream might still be writable. 29841cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>true</code>.</li> 29851cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> allows aborting the wait for the stream finish. The 29861cb0ef41Sopenharmony_ciunderlying stream will <em>not</em> be aborted if the signal is aborted. The 29871cb0ef41Sopenharmony_cicallback will get called with an <code>AbortError</code>. All registered 29881cb0ef41Sopenharmony_cilisteners added by this function will also be removed.</li> 29891cb0ef41Sopenharmony_ci<li><code>cleanup</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> remove all registered stream listeners. 29901cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>false</code>.</li> 29911cb0ef41Sopenharmony_ci</ul> 29921cb0ef41Sopenharmony_ci</li> 29931cb0ef41Sopenharmony_ci<li> 29941cb0ef41Sopenharmony_ci<p><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A callback function that takes an optional error 29951cb0ef41Sopenharmony_ciargument.</p> 29961cb0ef41Sopenharmony_ci</li> 29971cb0ef41Sopenharmony_ci<li> 29981cb0ef41Sopenharmony_ci<p>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A cleanup function which removes all registered 29991cb0ef41Sopenharmony_cilisteners.</p> 30001cb0ef41Sopenharmony_ci</li> 30011cb0ef41Sopenharmony_ci</ul> 30021cb0ef41Sopenharmony_ci<p>A function to get notified when a stream is no longer readable, writable 30031cb0ef41Sopenharmony_cior has experienced an error or a premature close event.</p> 30041cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { finished } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 30051cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 30061cb0ef41Sopenharmony_ci 30071cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> rs = fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'archive.tar'</span>); 30081cb0ef41Sopenharmony_ci 30091cb0ef41Sopenharmony_ci<span class="hljs-title function_">finished</span>(rs, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 30101cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err) { 30111cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'Stream failed.'</span>, err); 30121cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 30131cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Stream is done reading.'</span>); 30141cb0ef41Sopenharmony_ci } 30151cb0ef41Sopenharmony_ci}); 30161cb0ef41Sopenharmony_ci 30171cb0ef41Sopenharmony_cirs.<span class="hljs-title function_">resume</span>(); <span class="hljs-comment">// Drain the stream.</span></code> <button class="copy-button">copy</button></pre> 30181cb0ef41Sopenharmony_ci<p>Especially useful in error handling scenarios where a stream is destroyed 30191cb0ef41Sopenharmony_ciprematurely (like an aborted HTTP request), and will not emit <code>'end'</code> 30201cb0ef41Sopenharmony_cior <code>'finish'</code>.</p> 30211cb0ef41Sopenharmony_ci<p>The <code>finished</code> API provides <a href="#streamfinishedstream-options">promise version</a>.</p> 30221cb0ef41Sopenharmony_ci<p><code>stream.finished()</code> leaves dangling event listeners (in particular 30231cb0ef41Sopenharmony_ci<code>'error'</code>, <code>'end'</code>, <code>'finish'</code> and <code>'close'</code>) after <code>callback</code> has been 30241cb0ef41Sopenharmony_ciinvoked. The reason for this is so that unexpected <code>'error'</code> events (due to 30251cb0ef41Sopenharmony_ciincorrect stream implementations) do not cause unexpected crashes. 30261cb0ef41Sopenharmony_ciIf this is unwanted behavior then the returned cleanup function needs to be 30271cb0ef41Sopenharmony_ciinvoked in the callback:</p> 30281cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> cleanup = <span class="hljs-title function_">finished</span>(rs, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 30291cb0ef41Sopenharmony_ci <span class="hljs-title function_">cleanup</span>(); 30301cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 30311cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 30321cb0ef41Sopenharmony_ci<h4><code>stream.pipeline(source[, ...transforms], destination, callback)</code><span><a class="mark" href="#streampipelinesource-transforms-destination-callback" id="streampipelinesource-transforms-destination-callback">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_pipeline_source_transforms_destination_callback"></a></h4> 30331cb0ef41Sopenharmony_ci<h4><code>stream.pipeline(streams, callback)</code><span><a class="mark" href="#streampipelinestreams-callback" id="streampipelinestreams-callback">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_pipeline_streams_callback"></a></h4> 30341cb0ef41Sopenharmony_ci<div class="api_metadata"> 30351cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 30361cb0ef41Sopenharmony_ci<table> 30371cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 30381cb0ef41Sopenharmony_ci<tr><td>v18.16.0</td> 30391cb0ef41Sopenharmony_ci<td><p>Added support for webstreams.</p></td></tr> 30401cb0ef41Sopenharmony_ci<tr><td>v18.0.0</td> 30411cb0ef41Sopenharmony_ci<td><p>Passing an invalid callback to the <code>callback</code> argument now throws <code>ERR_INVALID_ARG_TYPE</code> instead of <code>ERR_INVALID_CALLBACK</code>.</p></td></tr> 30421cb0ef41Sopenharmony_ci<tr><td>v14.0.0</td> 30431cb0ef41Sopenharmony_ci<td><p>The <code>pipeline(..., cb)</code> will wait for the <code>'close'</code> event before invoking the callback. The implementation tries to detect legacy streams and only apply this behavior to streams which are expected to emit <code>'close'</code>.</p></td></tr> 30441cb0ef41Sopenharmony_ci<tr><td>v13.10.0</td> 30451cb0ef41Sopenharmony_ci<td><p>Add support for async generators.</p></td></tr> 30461cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 30471cb0ef41Sopenharmony_ci<td><p><span>Added in: v10.0.0</span></p></td></tr> 30481cb0ef41Sopenharmony_ci</tbody></table> 30491cb0ef41Sopenharmony_ci</details> 30501cb0ef41Sopenharmony_ci</div> 30511cb0ef41Sopenharmony_ci<ul> 30521cb0ef41Sopenharmony_ci<li><code>streams</code> <a href="stream.html#stream" class="type"><Stream[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable[]></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function[]></a> | <a href="webstreams.html#class-readablestream" class="type"><ReadableStream[]></a> | <a href="webstreams.html#class-writablestream" class="type"><WritableStream[]></a> | <a href="webstreams.html#class-transformstream" class="type"><TransformStream[]></a></li> 30531cb0ef41Sopenharmony_ci<li><code>source</code> <a href="stream.html#stream" class="type"><Stream></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a> 30541cb0ef41Sopenharmony_ci<ul> 30551cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a></li> 30561cb0ef41Sopenharmony_ci</ul> 30571cb0ef41Sopenharmony_ci</li> 30581cb0ef41Sopenharmony_ci<li><code>...transforms</code> <a href="stream.html#stream" class="type"><Stream></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="webstreams.html#class-transformstream" class="type"><TransformStream></a> 30591cb0ef41Sopenharmony_ci<ul> 30601cb0ef41Sopenharmony_ci<li><code>source</code> <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a></li> 30611cb0ef41Sopenharmony_ci<li>Returns: <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a></li> 30621cb0ef41Sopenharmony_ci</ul> 30631cb0ef41Sopenharmony_ci</li> 30641cb0ef41Sopenharmony_ci<li><code>destination</code> <a href="stream.html#stream" class="type"><Stream></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> | <a href="webstreams.html#class-writablestream" class="type"><WritableStream></a> 30651cb0ef41Sopenharmony_ci<ul> 30661cb0ef41Sopenharmony_ci<li><code>source</code> <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a></li> 30671cb0ef41Sopenharmony_ci<li>Returns: <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a></li> 30681cb0ef41Sopenharmony_ci</ul> 30691cb0ef41Sopenharmony_ci</li> 30701cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Called when the pipeline is fully done. 30711cb0ef41Sopenharmony_ci<ul> 30721cb0ef41Sopenharmony_ci<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a></li> 30731cb0ef41Sopenharmony_ci<li><code>val</code> Resolved value of <code>Promise</code> returned by <code>destination</code>.</li> 30741cb0ef41Sopenharmony_ci</ul> 30751cb0ef41Sopenharmony_ci</li> 30761cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#stream" class="type"><Stream></a></li> 30771cb0ef41Sopenharmony_ci</ul> 30781cb0ef41Sopenharmony_ci<p>A module method to pipe between streams and generators forwarding errors and 30791cb0ef41Sopenharmony_ciproperly cleaning up and provide a callback when the pipeline is complete.</p> 30801cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { pipeline } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 30811cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 30821cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> zlib = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:zlib'</span>); 30831cb0ef41Sopenharmony_ci 30841cb0ef41Sopenharmony_ci<span class="hljs-comment">// Use the pipeline API to easily pipe a series of streams</span> 30851cb0ef41Sopenharmony_ci<span class="hljs-comment">// together and get notified when the pipeline is fully done.</span> 30861cb0ef41Sopenharmony_ci 30871cb0ef41Sopenharmony_ci<span class="hljs-comment">// A pipeline to gzip a potentially huge tar file efficiently:</span> 30881cb0ef41Sopenharmony_ci 30891cb0ef41Sopenharmony_ci<span class="hljs-title function_">pipeline</span>( 30901cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'archive.tar'</span>), 30911cb0ef41Sopenharmony_ci zlib.<span class="hljs-title function_">createGzip</span>(), 30921cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'archive.tar.gz'</span>), 30931cb0ef41Sopenharmony_ci <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 30941cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err) { 30951cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'Pipeline failed.'</span>, err); 30961cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 30971cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Pipeline succeeded.'</span>); 30981cb0ef41Sopenharmony_ci } 30991cb0ef41Sopenharmony_ci }, 31001cb0ef41Sopenharmony_ci);</code> <button class="copy-button">copy</button></pre> 31011cb0ef41Sopenharmony_ci<p>The <code>pipeline</code> API provides a <a href="#streampipelinesource-transforms-destination-options">promise version</a>.</p> 31021cb0ef41Sopenharmony_ci<p><code>stream.pipeline()</code> will call <code>stream.destroy(err)</code> on all streams except:</p> 31031cb0ef41Sopenharmony_ci<ul> 31041cb0ef41Sopenharmony_ci<li><code>Readable</code> streams which have emitted <code>'end'</code> or <code>'close'</code>.</li> 31051cb0ef41Sopenharmony_ci<li><code>Writable</code> streams which have emitted <code>'finish'</code> or <code>'close'</code>.</li> 31061cb0ef41Sopenharmony_ci</ul> 31071cb0ef41Sopenharmony_ci<p><code>stream.pipeline()</code> leaves dangling event listeners on the streams 31081cb0ef41Sopenharmony_ciafter the <code>callback</code> has been invoked. In the case of reuse of streams after 31091cb0ef41Sopenharmony_cifailure, this can cause event listener leaks and swallowed errors. If the last 31101cb0ef41Sopenharmony_cistream is readable, dangling event listeners will be removed so that the last 31111cb0ef41Sopenharmony_cistream can be consumed later.</p> 31121cb0ef41Sopenharmony_ci<p><code>stream.pipeline()</code> closes all the streams when an error is raised. 31131cb0ef41Sopenharmony_ciThe <code>IncomingRequest</code> usage with <code>pipeline</code> could lead to an unexpected behavior 31141cb0ef41Sopenharmony_cionce it would destroy the socket without sending the expected response. 31151cb0ef41Sopenharmony_ciSee the example below:</p> 31161cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 31171cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> http = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:http'</span>); 31181cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { pipeline } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 31191cb0ef41Sopenharmony_ci 31201cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> server = http.<span class="hljs-title function_">createServer</span>(<span class="hljs-function">(<span class="hljs-params">req, res</span>) =></span> { 31211cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> fileStream = fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'./fileNotExist.txt'</span>); 31221cb0ef41Sopenharmony_ci <span class="hljs-title function_">pipeline</span>(fileStream, res, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 31231cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err) { 31241cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(err); <span class="hljs-comment">// No such file</span> 31251cb0ef41Sopenharmony_ci <span class="hljs-comment">// this message can't be sent once `pipeline` already destroyed the socket</span> 31261cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> res.<span class="hljs-title function_">end</span>(<span class="hljs-string">'error!!!'</span>); 31271cb0ef41Sopenharmony_ci } 31281cb0ef41Sopenharmony_ci }); 31291cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 31301cb0ef41Sopenharmony_ci<h4><code>stream.compose(...streams)</code><span><a class="mark" href="#streamcomposestreams" id="streamcomposestreams">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_compose_streams"></a></h4> 31311cb0ef41Sopenharmony_ci<div class="api_metadata"> 31321cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 31331cb0ef41Sopenharmony_ci<table> 31341cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 31351cb0ef41Sopenharmony_ci<tr><td>v18.16.0</td> 31361cb0ef41Sopenharmony_ci<td><p>Added support for webstreams.</p></td></tr> 31371cb0ef41Sopenharmony_ci<tr><td>v16.9.0</td> 31381cb0ef41Sopenharmony_ci<td><p><span>Added in: v16.9.0</span></p></td></tr> 31391cb0ef41Sopenharmony_ci</tbody></table> 31401cb0ef41Sopenharmony_ci</details> 31411cb0ef41Sopenharmony_ci</div> 31421cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - <code>stream.compose</code> is experimental.</div><p></p> 31431cb0ef41Sopenharmony_ci<ul> 31441cb0ef41Sopenharmony_ci<li><code>streams</code> <a href="stream.html#stream" class="type"><Stream[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable[]></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable[]></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function[]></a> | <a href="webstreams.html#class-readablestream" class="type"><ReadableStream[]></a> | <a href="webstreams.html#class-writablestream" class="type"><WritableStream[]></a> | <a href="webstreams.html#class-transformstream" class="type"><TransformStream[]></a></li> 31451cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamduplex" class="type"><stream.Duplex></a></li> 31461cb0ef41Sopenharmony_ci</ul> 31471cb0ef41Sopenharmony_ci<p>Combines two or more streams into a <code>Duplex</code> stream that writes to the 31481cb0ef41Sopenharmony_cifirst stream and reads from the last. Each provided stream is piped into 31491cb0ef41Sopenharmony_cithe next, using <code>stream.pipeline</code>. If any of the streams error then all 31501cb0ef41Sopenharmony_ciare destroyed, including the outer <code>Duplex</code> stream.</p> 31511cb0ef41Sopenharmony_ci<p>Because <code>stream.compose</code> returns a new stream that in turn can (and 31521cb0ef41Sopenharmony_cishould) be piped into other streams, it enables composition. In contrast, 31531cb0ef41Sopenharmony_ciwhen passing streams to <code>stream.pipeline</code>, typically the first stream is 31541cb0ef41Sopenharmony_cia readable stream and the last a writable stream, forming a closed 31551cb0ef41Sopenharmony_cicircuit.</p> 31561cb0ef41Sopenharmony_ci<p>If passed a <code>Function</code> it must be a factory method taking a <code>source</code> 31571cb0ef41Sopenharmony_ci<code>Iterable</code>.</p> 31581cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { compose, <span class="hljs-title class_">Transform</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 31591cb0ef41Sopenharmony_ci 31601cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> removeSpaces = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Transform</span>({ 31611cb0ef41Sopenharmony_ci <span class="hljs-title function_">transform</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 31621cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-title class_">String</span>(chunk).<span class="hljs-title function_">replace</span>(<span class="hljs-string">' '</span>, <span class="hljs-string">''</span>)); 31631cb0ef41Sopenharmony_ci }, 31641cb0ef41Sopenharmony_ci}); 31651cb0ef41Sopenharmony_ci 31661cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>* <span class="hljs-title function_">toUpper</span>(<span class="hljs-params">source</span>) { 31671cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> source) { 31681cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-title class_">String</span>(chunk).<span class="hljs-title function_">toUpperCase</span>(); 31691cb0ef41Sopenharmony_ci } 31701cb0ef41Sopenharmony_ci} 31711cb0ef41Sopenharmony_ci 31721cb0ef41Sopenharmony_ci<span class="hljs-keyword">let</span> res = <span class="hljs-string">''</span>; 31731cb0ef41Sopenharmony_ci<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> buf <span class="hljs-keyword">of</span> <span class="hljs-title function_">compose</span>(removeSpaces, toUpper).<span class="hljs-title function_">end</span>(<span class="hljs-string">'hello world'</span>)) { 31741cb0ef41Sopenharmony_ci res += buf; 31751cb0ef41Sopenharmony_ci} 31761cb0ef41Sopenharmony_ci 31771cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(res); <span class="hljs-comment">// prints 'HELLOWORLD'</span></code> <button class="copy-button">copy</button></pre> 31781cb0ef41Sopenharmony_ci<p><code>stream.compose</code> can be used to convert async iterables, generators and 31791cb0ef41Sopenharmony_cifunctions into streams.</p> 31801cb0ef41Sopenharmony_ci<ul> 31811cb0ef41Sopenharmony_ci<li><code>AsyncIterable</code> converts into a readable <code>Duplex</code>. Cannot yield 31821cb0ef41Sopenharmony_ci<code>null</code>.</li> 31831cb0ef41Sopenharmony_ci<li><code>AsyncGeneratorFunction</code> converts into a readable/writable transform <code>Duplex</code>. 31841cb0ef41Sopenharmony_ciMust take a source <code>AsyncIterable</code> as first parameter. Cannot yield 31851cb0ef41Sopenharmony_ci<code>null</code>.</li> 31861cb0ef41Sopenharmony_ci<li><code>AsyncFunction</code> converts into a writable <code>Duplex</code>. Must return 31871cb0ef41Sopenharmony_cieither <code>null</code> or <code>undefined</code>.</li> 31881cb0ef41Sopenharmony_ci</ul> 31891cb0ef41Sopenharmony_ci<pre><code class="language-js mjs"><span class="hljs-keyword">import</span> { compose } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 31901cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { finished } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream/promises'</span>; 31911cb0ef41Sopenharmony_ci 31921cb0ef41Sopenharmony_ci<span class="hljs-comment">// Convert AsyncIterable into readable Duplex.</span> 31931cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> s1 = <span class="hljs-title function_">compose</span>(<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>*() { 31941cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-string">'Hello'</span>; 31951cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-string">'World'</span>; 31961cb0ef41Sopenharmony_ci}()); 31971cb0ef41Sopenharmony_ci 31981cb0ef41Sopenharmony_ci<span class="hljs-comment">// Convert AsyncGenerator into transform Duplex.</span> 31991cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> s2 = <span class="hljs-title function_">compose</span>(<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>*(source) { 32001cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> source) { 32011cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-title class_">String</span>(chunk).<span class="hljs-title function_">toUpperCase</span>(); 32021cb0ef41Sopenharmony_ci } 32031cb0ef41Sopenharmony_ci}); 32041cb0ef41Sopenharmony_ci 32051cb0ef41Sopenharmony_ci<span class="hljs-keyword">let</span> res = <span class="hljs-string">''</span>; 32061cb0ef41Sopenharmony_ci 32071cb0ef41Sopenharmony_ci<span class="hljs-comment">// Convert AsyncFunction into writable Duplex.</span> 32081cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> s3 = <span class="hljs-title function_">compose</span>(<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>(<span class="hljs-params">source</span>) { 32091cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> source) { 32101cb0ef41Sopenharmony_ci res += chunk; 32111cb0ef41Sopenharmony_ci } 32121cb0ef41Sopenharmony_ci}); 32131cb0ef41Sopenharmony_ci 32141cb0ef41Sopenharmony_ci<span class="hljs-keyword">await</span> <span class="hljs-title function_">finished</span>(<span class="hljs-title function_">compose</span>(s1, s2, s3)); 32151cb0ef41Sopenharmony_ci 32161cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(res); <span class="hljs-comment">// prints 'HELLOWORLD'</span></code> <button class="copy-button">copy</button></pre> 32171cb0ef41Sopenharmony_ci<p>See <a href="#readablecomposestream-options"><code>readable.compose(stream)</code></a> for <code>stream.compose</code> as operator.</p> 32181cb0ef41Sopenharmony_ci<h4><code>stream.Readable.from(iterable[, options])</code><span><a class="mark" href="#streamreadablefromiterable-options" id="streamreadablefromiterable-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_readable_from_iterable_options"></a></h4> 32191cb0ef41Sopenharmony_ci<div class="api_metadata"> 32201cb0ef41Sopenharmony_ci<span>Added in: v12.3.0, v10.17.0</span> 32211cb0ef41Sopenharmony_ci</div> 32221cb0ef41Sopenharmony_ci<ul> 32231cb0ef41Sopenharmony_ci<li><code>iterable</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable></a> Object implementing the <code>Symbol.asyncIterator</code> or 32241cb0ef41Sopenharmony_ci<code>Symbol.iterator</code> iterable protocol. Emits an 'error' event if a null 32251cb0ef41Sopenharmony_civalue is passed.</li> 32261cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Options provided to <code>new stream.Readable([options])</code>. 32271cb0ef41Sopenharmony_ciBy default, <code>Readable.from()</code> will set <code>options.objectMode</code> to <code>true</code>, unless 32281cb0ef41Sopenharmony_cithis is explicitly opted out by setting <code>options.objectMode</code> to <code>false</code>.</li> 32291cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamreadable" class="type"><stream.Readable></a></li> 32301cb0ef41Sopenharmony_ci</ul> 32311cb0ef41Sopenharmony_ci<p>A utility method for creating readable streams out of iterators.</p> 32321cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 32331cb0ef41Sopenharmony_ci 32341cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> * <span class="hljs-title function_">generate</span>(<span class="hljs-params"></span>) { 32351cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-string">'hello'</span>; 32361cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-string">'streams'</span>; 32371cb0ef41Sopenharmony_ci} 32381cb0ef41Sopenharmony_ci 32391cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> readable = <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>(<span class="hljs-title function_">generate</span>()); 32401cb0ef41Sopenharmony_ci 32411cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> { 32421cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk); 32431cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 32441cb0ef41Sopenharmony_ci<p>Calling <code>Readable.from(string)</code> or <code>Readable.from(buffer)</code> will not have 32451cb0ef41Sopenharmony_cithe strings or buffers be iterated to match the other streams semantics 32461cb0ef41Sopenharmony_cifor performance reasons.</p> 32471cb0ef41Sopenharmony_ci<p>If an <code>Iterable</code> object containing promises is passed as an argument, 32481cb0ef41Sopenharmony_ciit might result in unhandled rejection.</p> 32491cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 32501cb0ef41Sopenharmony_ci 32511cb0ef41Sopenharmony_ci<span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>([ 32521cb0ef41Sopenharmony_ci <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function">(<span class="hljs-params">resolve</span>) =></span> <span class="hljs-built_in">setTimeout</span>(<span class="hljs-title function_">resolve</span>(<span class="hljs-string">'1'</span>), <span class="hljs-number">1500</span>)), 32531cb0ef41Sopenharmony_ci <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function">(<span class="hljs-params">_, reject</span>) =></span> <span class="hljs-built_in">setTimeout</span>(<span class="hljs-title function_">reject</span>(<span class="hljs-keyword">new</span> <span class="hljs-title class_">Error</span>(<span class="hljs-string">'2'</span>)), <span class="hljs-number">1000</span>)), <span class="hljs-comment">// Unhandled rejection</span> 32541cb0ef41Sopenharmony_ci]);</code> <button class="copy-button">copy</button></pre> 32551cb0ef41Sopenharmony_ci<h4><code>stream.Readable.fromWeb(readableStream[, options])</code><span><a class="mark" href="#streamreadablefromwebreadablestream-options" id="streamreadablefromwebreadablestream-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_readable_fromweb_readablestream_options"></a></h4> 32561cb0ef41Sopenharmony_ci<div class="api_metadata"> 32571cb0ef41Sopenharmony_ci<span>Added in: v17.0.0</span> 32581cb0ef41Sopenharmony_ci</div> 32591cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 32601cb0ef41Sopenharmony_ci<ul> 32611cb0ef41Sopenharmony_ci<li><code>readableStream</code> <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a></li> 32621cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 32631cb0ef41Sopenharmony_ci<ul> 32641cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 32651cb0ef41Sopenharmony_ci<li><code>highWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 32661cb0ef41Sopenharmony_ci<li><code>objectMode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 32671cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a></li> 32681cb0ef41Sopenharmony_ci</ul> 32691cb0ef41Sopenharmony_ci</li> 32701cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamreadable" class="type"><stream.Readable></a></li> 32711cb0ef41Sopenharmony_ci</ul> 32721cb0ef41Sopenharmony_ci<h4><code>stream.Readable.isDisturbed(stream)</code><span><a class="mark" href="#streamreadableisdisturbedstream" id="streamreadableisdisturbedstream">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_readable_isdisturbed_stream"></a></h4> 32731cb0ef41Sopenharmony_ci<div class="api_metadata"> 32741cb0ef41Sopenharmony_ci<span>Added in: v16.8.0</span> 32751cb0ef41Sopenharmony_ci</div> 32761cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 32771cb0ef41Sopenharmony_ci<ul> 32781cb0ef41Sopenharmony_ci<li><code>stream</code> <a href="stream.html#class-streamreadable" class="type"><stream.Readable></a> | <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a></li> 32791cb0ef41Sopenharmony_ci<li>Returns: <code>boolean</code></li> 32801cb0ef41Sopenharmony_ci</ul> 32811cb0ef41Sopenharmony_ci<p>Returns whether the stream has been read from or cancelled.</p> 32821cb0ef41Sopenharmony_ci<h4><code>stream.isErrored(stream)</code><span><a class="mark" href="#streamiserroredstream" id="streamiserroredstream">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_iserrored_stream"></a></h4> 32831cb0ef41Sopenharmony_ci<div class="api_metadata"> 32841cb0ef41Sopenharmony_ci<span>Added in: v17.3.0, v16.14.0</span> 32851cb0ef41Sopenharmony_ci</div> 32861cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 32871cb0ef41Sopenharmony_ci<ul> 32881cb0ef41Sopenharmony_ci<li><code>stream</code> <a href="stream.html#class-streamreadable" class="type"><Readable></a> | <a href="stream.html#class-streamwritable" class="type"><Writable></a> | <a href="stream.html#class-streamduplex" class="type"><Duplex></a> | <a href="webstreams.html#class-writablestream" class="type"><WritableStream></a> | <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a></li> 32891cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 32901cb0ef41Sopenharmony_ci</ul> 32911cb0ef41Sopenharmony_ci<p>Returns whether the stream has encountered an error.</p> 32921cb0ef41Sopenharmony_ci<h4><code>stream.isReadable(stream)</code><span><a class="mark" href="#streamisreadablestream" id="streamisreadablestream">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_isreadable_stream"></a></h4> 32931cb0ef41Sopenharmony_ci<div class="api_metadata"> 32941cb0ef41Sopenharmony_ci<span>Added in: v17.4.0, v16.14.0</span> 32951cb0ef41Sopenharmony_ci</div> 32961cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 32971cb0ef41Sopenharmony_ci<ul> 32981cb0ef41Sopenharmony_ci<li><code>stream</code> <a href="stream.html#class-streamreadable" class="type"><Readable></a> | <a href="stream.html#class-streamduplex" class="type"><Duplex></a> | <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a></li> 32991cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 33001cb0ef41Sopenharmony_ci</ul> 33011cb0ef41Sopenharmony_ci<p>Returns whether the stream is readable.</p> 33021cb0ef41Sopenharmony_ci<h4><code>stream.Readable.toWeb(streamReadable[, options])</code><span><a class="mark" href="#streamreadabletowebstreamreadable-options" id="streamreadabletowebstreamreadable-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_readable_toweb_streamreadable_options"></a></h4> 33031cb0ef41Sopenharmony_ci<div class="api_metadata"> 33041cb0ef41Sopenharmony_ci<span>Added in: v17.0.0</span> 33051cb0ef41Sopenharmony_ci</div> 33061cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 33071cb0ef41Sopenharmony_ci<ul> 33081cb0ef41Sopenharmony_ci<li><code>streamReadable</code> <a href="stream.html#class-streamreadable" class="type"><stream.Readable></a></li> 33091cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 33101cb0ef41Sopenharmony_ci<ul> 33111cb0ef41Sopenharmony_ci<li><code>strategy</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 33121cb0ef41Sopenharmony_ci<ul> 33131cb0ef41Sopenharmony_ci<li><code>highWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The maximum internal queue size (of the created 33141cb0ef41Sopenharmony_ci<code>ReadableStream</code>) before backpressure is applied in reading from the given 33151cb0ef41Sopenharmony_ci<code>stream.Readable</code>. If no value is provided, it will be taken from the 33161cb0ef41Sopenharmony_cigiven <code>stream.Readable</code>.</li> 33171cb0ef41Sopenharmony_ci<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A function that size of the given chunk of data. 33181cb0ef41Sopenharmony_ciIf no value is provided, the size will be <code>1</code> for all the chunks. 33191cb0ef41Sopenharmony_ci<ul> 33201cb0ef41Sopenharmony_ci<li><code>chunk</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a></li> 33211cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 33221cb0ef41Sopenharmony_ci</ul> 33231cb0ef41Sopenharmony_ci</li> 33241cb0ef41Sopenharmony_ci</ul> 33251cb0ef41Sopenharmony_ci</li> 33261cb0ef41Sopenharmony_ci</ul> 33271cb0ef41Sopenharmony_ci</li> 33281cb0ef41Sopenharmony_ci<li>Returns: <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a></li> 33291cb0ef41Sopenharmony_ci</ul> 33301cb0ef41Sopenharmony_ci<h4><code>stream.Writable.fromWeb(writableStream[, options])</code><span><a class="mark" href="#streamwritablefromwebwritablestream-options" id="streamwritablefromwebwritablestream-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_writable_fromweb_writablestream_options"></a></h4> 33311cb0ef41Sopenharmony_ci<div class="api_metadata"> 33321cb0ef41Sopenharmony_ci<span>Added in: v17.0.0</span> 33331cb0ef41Sopenharmony_ci</div> 33341cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 33351cb0ef41Sopenharmony_ci<ul> 33361cb0ef41Sopenharmony_ci<li><code>writableStream</code> <a href="webstreams.html#class-writablestream" class="type"><WritableStream></a></li> 33371cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 33381cb0ef41Sopenharmony_ci<ul> 33391cb0ef41Sopenharmony_ci<li><code>decodeStrings</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 33401cb0ef41Sopenharmony_ci<li><code>highWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 33411cb0ef41Sopenharmony_ci<li><code>objectMode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 33421cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a></li> 33431cb0ef41Sopenharmony_ci</ul> 33441cb0ef41Sopenharmony_ci</li> 33451cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamwritable" class="type"><stream.Writable></a></li> 33461cb0ef41Sopenharmony_ci</ul> 33471cb0ef41Sopenharmony_ci<h4><code>stream.Writable.toWeb(streamWritable)</code><span><a class="mark" href="#streamwritabletowebstreamwritable" id="streamwritabletowebstreamwritable">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_writable_toweb_streamwritable"></a></h4> 33481cb0ef41Sopenharmony_ci<div class="api_metadata"> 33491cb0ef41Sopenharmony_ci<span>Added in: v17.0.0</span> 33501cb0ef41Sopenharmony_ci</div> 33511cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 33521cb0ef41Sopenharmony_ci<ul> 33531cb0ef41Sopenharmony_ci<li><code>streamWritable</code> <a href="stream.html#class-streamwritable" class="type"><stream.Writable></a></li> 33541cb0ef41Sopenharmony_ci<li>Returns: <a href="webstreams.html#class-writablestream" class="type"><WritableStream></a></li> 33551cb0ef41Sopenharmony_ci</ul> 33561cb0ef41Sopenharmony_ci<h4><code>stream.Duplex.from(src)</code><span><a class="mark" href="#streamduplexfromsrc" id="streamduplexfromsrc">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_duplex_from_src"></a></h4> 33571cb0ef41Sopenharmony_ci<div class="api_metadata"> 33581cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 33591cb0ef41Sopenharmony_ci<table> 33601cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 33611cb0ef41Sopenharmony_ci<tr><td>v18.17.0</td> 33621cb0ef41Sopenharmony_ci<td><p>The <code>src</code> argument can now be a <code>ReadableStream</code> or <code>WritableStream</code>.</p></td></tr> 33631cb0ef41Sopenharmony_ci<tr><td>v16.8.0</td> 33641cb0ef41Sopenharmony_ci<td><p><span>Added in: v16.8.0</span></p></td></tr> 33651cb0ef41Sopenharmony_ci</tbody></table> 33661cb0ef41Sopenharmony_ci</details> 33671cb0ef41Sopenharmony_ci</div> 33681cb0ef41Sopenharmony_ci<ul> 33691cb0ef41Sopenharmony_ci<li><code>src</code> <a href="stream.html#stream" class="type"><Stream></a> | <a href="buffer.html#class-blob" class="type"><Blob></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer" class="type"><ArrayBuffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol" class="type"><Iterable></a> | <a href="https://tc39.github.io/ecma262/#sec-asynciterable-interface" class="type"><AsyncIterable></a> | <a href="https://tc39.es/proposal-async-iteration/#sec-asyncgeneratorfunction-constructor" class="type"><AsyncGeneratorFunction></a> | <a href="https://tc39.es/ecma262/#sec-async-function-constructor" class="type"><AsyncFunction></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise" class="type"><Promise></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a> | <a href="webstreams.html#class-writablestream" class="type"><WritableStream></a></li> 33701cb0ef41Sopenharmony_ci</ul> 33711cb0ef41Sopenharmony_ci<p>A utility method for creating duplex streams.</p> 33721cb0ef41Sopenharmony_ci<ul> 33731cb0ef41Sopenharmony_ci<li><code>Stream</code> converts writable stream into writable <code>Duplex</code> and readable stream 33741cb0ef41Sopenharmony_cito <code>Duplex</code>.</li> 33751cb0ef41Sopenharmony_ci<li><code>Blob</code> converts into readable <code>Duplex</code>.</li> 33761cb0ef41Sopenharmony_ci<li><code>string</code> converts into readable <code>Duplex</code>.</li> 33771cb0ef41Sopenharmony_ci<li><code>ArrayBuffer</code> converts into readable <code>Duplex</code>.</li> 33781cb0ef41Sopenharmony_ci<li><code>AsyncIterable</code> converts into a readable <code>Duplex</code>. Cannot yield 33791cb0ef41Sopenharmony_ci<code>null</code>.</li> 33801cb0ef41Sopenharmony_ci<li><code>AsyncGeneratorFunction</code> converts into a readable/writable transform 33811cb0ef41Sopenharmony_ci<code>Duplex</code>. Must take a source <code>AsyncIterable</code> as first parameter. Cannot yield 33821cb0ef41Sopenharmony_ci<code>null</code>.</li> 33831cb0ef41Sopenharmony_ci<li><code>AsyncFunction</code> converts into a writable <code>Duplex</code>. Must return 33841cb0ef41Sopenharmony_cieither <code>null</code> or <code>undefined</code></li> 33851cb0ef41Sopenharmony_ci<li><code>Object ({ writable, readable })</code> converts <code>readable</code> and 33861cb0ef41Sopenharmony_ci<code>writable</code> into <code>Stream</code> and then combines them into <code>Duplex</code> where the 33871cb0ef41Sopenharmony_ci<code>Duplex</code> will write to the <code>writable</code> and read from the <code>readable</code>.</li> 33881cb0ef41Sopenharmony_ci<li><code>Promise</code> converts into readable <code>Duplex</code>. Value <code>null</code> is ignored.</li> 33891cb0ef41Sopenharmony_ci<li><code>ReadableStream</code> converts into readable <code>Duplex</code>.</li> 33901cb0ef41Sopenharmony_ci<li><code>WritableStream</code> converts into writable <code>Duplex</code>.</li> 33911cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamduplex" class="type"><stream.Duplex></a></li> 33921cb0ef41Sopenharmony_ci</ul> 33931cb0ef41Sopenharmony_ci<p>If an <code>Iterable</code> object containing promises is passed as an argument, 33941cb0ef41Sopenharmony_ciit might result in unhandled rejection.</p> 33951cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Duplex</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 33961cb0ef41Sopenharmony_ci 33971cb0ef41Sopenharmony_ci<span class="hljs-title class_">Duplex</span>.<span class="hljs-title function_">from</span>([ 33981cb0ef41Sopenharmony_ci <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function">(<span class="hljs-params">resolve</span>) =></span> <span class="hljs-built_in">setTimeout</span>(<span class="hljs-title function_">resolve</span>(<span class="hljs-string">'1'</span>), <span class="hljs-number">1500</span>)), 33991cb0ef41Sopenharmony_ci <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function">(<span class="hljs-params">_, reject</span>) =></span> <span class="hljs-built_in">setTimeout</span>(<span class="hljs-title function_">reject</span>(<span class="hljs-keyword">new</span> <span class="hljs-title class_">Error</span>(<span class="hljs-string">'2'</span>)), <span class="hljs-number">1000</span>)), <span class="hljs-comment">// Unhandled rejection</span> 34001cb0ef41Sopenharmony_ci]);</code> <button class="copy-button">copy</button></pre> 34011cb0ef41Sopenharmony_ci<h4><code>stream.Duplex.fromWeb(pair[, options])</code><span><a class="mark" href="#streamduplexfromwebpair-options" id="streamduplexfromwebpair-options">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_duplex_fromweb_pair_options"></a></h4> 34021cb0ef41Sopenharmony_ci<div class="api_metadata"> 34031cb0ef41Sopenharmony_ci<span>Added in: v17.0.0</span> 34041cb0ef41Sopenharmony_ci</div> 34051cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 34061cb0ef41Sopenharmony_ci<ul> 34071cb0ef41Sopenharmony_ci<li><code>pair</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 34081cb0ef41Sopenharmony_ci<ul> 34091cb0ef41Sopenharmony_ci<li><code>readable</code> <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a></li> 34101cb0ef41Sopenharmony_ci<li><code>writable</code> <a href="webstreams.html#class-writablestream" class="type"><WritableStream></a></li> 34111cb0ef41Sopenharmony_ci</ul> 34121cb0ef41Sopenharmony_ci</li> 34131cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 34141cb0ef41Sopenharmony_ci<ul> 34151cb0ef41Sopenharmony_ci<li><code>allowHalfOpen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 34161cb0ef41Sopenharmony_ci<li><code>decodeStrings</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 34171cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 34181cb0ef41Sopenharmony_ci<li><code>highWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a></li> 34191cb0ef41Sopenharmony_ci<li><code>objectMode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 34201cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a></li> 34211cb0ef41Sopenharmony_ci</ul> 34221cb0ef41Sopenharmony_ci</li> 34231cb0ef41Sopenharmony_ci<li>Returns: <a href="stream.html#class-streamduplex" class="type"><stream.Duplex></a></li> 34241cb0ef41Sopenharmony_ci</ul> 34251cb0ef41Sopenharmony_ci 34261cb0ef41Sopenharmony_ci<pre class="with-42-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Duplex</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 34271cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { 34281cb0ef41Sopenharmony_ci <span class="hljs-title class_">ReadableStream</span>, 34291cb0ef41Sopenharmony_ci <span class="hljs-title class_">WritableStream</span>, 34301cb0ef41Sopenharmony_ci} <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream/web'</span>; 34311cb0ef41Sopenharmony_ci 34321cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> readable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">ReadableStream</span>({ 34331cb0ef41Sopenharmony_ci <span class="hljs-title function_">start</span>(<span class="hljs-params">controller</span>) { 34341cb0ef41Sopenharmony_ci controller.<span class="hljs-title function_">enqueue</span>(<span class="hljs-string">'world'</span>); 34351cb0ef41Sopenharmony_ci }, 34361cb0ef41Sopenharmony_ci}); 34371cb0ef41Sopenharmony_ci 34381cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> writable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">WritableStream</span>({ 34391cb0ef41Sopenharmony_ci <span class="hljs-title function_">write</span>(<span class="hljs-params">chunk</span>) { 34401cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'writable'</span>, chunk); 34411cb0ef41Sopenharmony_ci }, 34421cb0ef41Sopenharmony_ci}); 34431cb0ef41Sopenharmony_ci 34441cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> pair = { 34451cb0ef41Sopenharmony_ci readable, 34461cb0ef41Sopenharmony_ci writable, 34471cb0ef41Sopenharmony_ci}; 34481cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> duplex = <span class="hljs-title class_">Duplex</span>.<span class="hljs-title function_">fromWeb</span>(pair, { <span class="hljs-attr">encoding</span>: <span class="hljs-string">'utf8'</span>, <span class="hljs-attr">objectMode</span>: <span class="hljs-literal">true</span> }); 34491cb0ef41Sopenharmony_ci 34501cb0ef41Sopenharmony_ciduplex.<span class="hljs-title function_">write</span>(<span class="hljs-string">'hello'</span>); 34511cb0ef41Sopenharmony_ci 34521cb0ef41Sopenharmony_ci<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> duplex) { 34531cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'readable'</span>, chunk); 34541cb0ef41Sopenharmony_ci}</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Duplex</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 34551cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { 34561cb0ef41Sopenharmony_ci <span class="hljs-title class_">ReadableStream</span>, 34571cb0ef41Sopenharmony_ci <span class="hljs-title class_">WritableStream</span>, 34581cb0ef41Sopenharmony_ci} = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream/web'</span>); 34591cb0ef41Sopenharmony_ci 34601cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> readable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">ReadableStream</span>({ 34611cb0ef41Sopenharmony_ci <span class="hljs-title function_">start</span>(<span class="hljs-params">controller</span>) { 34621cb0ef41Sopenharmony_ci controller.<span class="hljs-title function_">enqueue</span>(<span class="hljs-string">'world'</span>); 34631cb0ef41Sopenharmony_ci }, 34641cb0ef41Sopenharmony_ci}); 34651cb0ef41Sopenharmony_ci 34661cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> writable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">WritableStream</span>({ 34671cb0ef41Sopenharmony_ci <span class="hljs-title function_">write</span>(<span class="hljs-params">chunk</span>) { 34681cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'writable'</span>, chunk); 34691cb0ef41Sopenharmony_ci }, 34701cb0ef41Sopenharmony_ci}); 34711cb0ef41Sopenharmony_ci 34721cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> pair = { 34731cb0ef41Sopenharmony_ci readable, 34741cb0ef41Sopenharmony_ci writable, 34751cb0ef41Sopenharmony_ci}; 34761cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> duplex = <span class="hljs-title class_">Duplex</span>.<span class="hljs-title function_">fromWeb</span>(pair, { <span class="hljs-attr">encoding</span>: <span class="hljs-string">'utf8'</span>, <span class="hljs-attr">objectMode</span>: <span class="hljs-literal">true</span> }); 34771cb0ef41Sopenharmony_ci 34781cb0ef41Sopenharmony_ciduplex.<span class="hljs-title function_">write</span>(<span class="hljs-string">'hello'</span>); 34791cb0ef41Sopenharmony_ciduplex.<span class="hljs-title function_">once</span>(<span class="hljs-string">'readable'</span>, <span class="hljs-function">() =></span> <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'readable'</span>, duplex.<span class="hljs-title function_">read</span>()));</code><button class="copy-button">copy</button></pre> 34801cb0ef41Sopenharmony_ci<h4><code>stream.Duplex.toWeb(streamDuplex)</code><span><a class="mark" href="#streamduplextowebstreamduplex" id="streamduplextowebstreamduplex">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_duplex_toweb_streamduplex"></a></h4> 34811cb0ef41Sopenharmony_ci<div class="api_metadata"> 34821cb0ef41Sopenharmony_ci<span>Added in: v17.0.0</span> 34831cb0ef41Sopenharmony_ci</div> 34841cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 34851cb0ef41Sopenharmony_ci<ul> 34861cb0ef41Sopenharmony_ci<li><code>streamDuplex</code> <a href="stream.html#class-streamduplex" class="type"><stream.Duplex></a></li> 34871cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 34881cb0ef41Sopenharmony_ci<ul> 34891cb0ef41Sopenharmony_ci<li><code>readable</code> <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a></li> 34901cb0ef41Sopenharmony_ci<li><code>writable</code> <a href="webstreams.html#class-writablestream" class="type"><WritableStream></a></li> 34911cb0ef41Sopenharmony_ci</ul> 34921cb0ef41Sopenharmony_ci</li> 34931cb0ef41Sopenharmony_ci</ul> 34941cb0ef41Sopenharmony_ci 34951cb0ef41Sopenharmony_ci<pre class="with-42-chars"><input class="js-flavor-selector" type="checkbox" checked aria-label="Show modern ES modules syntax"><code class="language-js mjs"><span class="hljs-keyword">import</span> { <span class="hljs-title class_">Duplex</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'node:stream'</span>; 34961cb0ef41Sopenharmony_ci 34971cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> duplex = <span class="hljs-title class_">Duplex</span>({ 34981cb0ef41Sopenharmony_ci <span class="hljs-attr">objectMode</span>: <span class="hljs-literal">true</span>, 34991cb0ef41Sopenharmony_ci <span class="hljs-title function_">read</span>(<span class="hljs-params"></span>) { 35001cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(<span class="hljs-string">'world'</span>); 35011cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(<span class="hljs-literal">null</span>); 35021cb0ef41Sopenharmony_ci }, 35031cb0ef41Sopenharmony_ci <span class="hljs-title function_">write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 35041cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'writable'</span>, chunk); 35051cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 35061cb0ef41Sopenharmony_ci }, 35071cb0ef41Sopenharmony_ci}); 35081cb0ef41Sopenharmony_ci 35091cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { readable, writable } = <span class="hljs-title class_">Duplex</span>.<span class="hljs-title function_">toWeb</span>(duplex); 35101cb0ef41Sopenharmony_ciwritable.<span class="hljs-title function_">getWriter</span>().<span class="hljs-title function_">write</span>(<span class="hljs-string">'hello'</span>); 35111cb0ef41Sopenharmony_ci 35121cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { value } = <span class="hljs-keyword">await</span> readable.<span class="hljs-title function_">getReader</span>().<span class="hljs-title function_">read</span>(); 35131cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'readable'</span>, value);</code><code class="language-js cjs"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Duplex</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 35141cb0ef41Sopenharmony_ci 35151cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> duplex = <span class="hljs-title class_">Duplex</span>({ 35161cb0ef41Sopenharmony_ci <span class="hljs-attr">objectMode</span>: <span class="hljs-literal">true</span>, 35171cb0ef41Sopenharmony_ci <span class="hljs-title function_">read</span>(<span class="hljs-params"></span>) { 35181cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(<span class="hljs-string">'world'</span>); 35191cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(<span class="hljs-literal">null</span>); 35201cb0ef41Sopenharmony_ci }, 35211cb0ef41Sopenharmony_ci <span class="hljs-title function_">write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 35221cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'writable'</span>, chunk); 35231cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 35241cb0ef41Sopenharmony_ci }, 35251cb0ef41Sopenharmony_ci}); 35261cb0ef41Sopenharmony_ci 35271cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { readable, writable } = <span class="hljs-title class_">Duplex</span>.<span class="hljs-title function_">toWeb</span>(duplex); 35281cb0ef41Sopenharmony_ciwritable.<span class="hljs-title function_">getWriter</span>().<span class="hljs-title function_">write</span>(<span class="hljs-string">'hello'</span>); 35291cb0ef41Sopenharmony_ci 35301cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">getReader</span>().<span class="hljs-title function_">read</span>().<span class="hljs-title function_">then</span>(<span class="hljs-function">(<span class="hljs-params">result</span>) =></span> { 35311cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'readable'</span>, result.<span class="hljs-property">value</span>); 35321cb0ef41Sopenharmony_ci});</code><button class="copy-button">copy</button></pre> 35331cb0ef41Sopenharmony_ci<h4><code>stream.addAbortSignal(signal, stream)</code><span><a class="mark" href="#streamaddabortsignalsignal-stream" id="streamaddabortsignalsignal-stream">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_addabortsignal_signal_stream"></a></h4> 35341cb0ef41Sopenharmony_ci<div class="api_metadata"> 35351cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 35361cb0ef41Sopenharmony_ci<table> 35371cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 35381cb0ef41Sopenharmony_ci<tr><td>v18.16.0</td> 35391cb0ef41Sopenharmony_ci<td><p>Added support for <code>ReadableStream</code> and <code>WritableStream</code>.</p></td></tr> 35401cb0ef41Sopenharmony_ci<tr><td>v15.4.0</td> 35411cb0ef41Sopenharmony_ci<td><p><span>Added in: v15.4.0</span></p></td></tr> 35421cb0ef41Sopenharmony_ci</tbody></table> 35431cb0ef41Sopenharmony_ci</details> 35441cb0ef41Sopenharmony_ci</div> 35451cb0ef41Sopenharmony_ci<ul> 35461cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> A signal representing possible cancellation</li> 35471cb0ef41Sopenharmony_ci<li><code>stream</code> <a href="stream.html#stream" class="type"><Stream></a> | <a href="webstreams.html#class-readablestream" class="type"><ReadableStream></a> | <a href="webstreams.html#class-writablestream" class="type"><WritableStream></a></li> 35481cb0ef41Sopenharmony_ci</ul> 35491cb0ef41Sopenharmony_ci<p>A stream to attach a signal to.</p> 35501cb0ef41Sopenharmony_ci<p>Attaches an AbortSignal to a readable or writeable stream. This lets code 35511cb0ef41Sopenharmony_cicontrol stream destruction using an <code>AbortController</code>.</p> 35521cb0ef41Sopenharmony_ci<p>Calling <code>abort</code> on the <code>AbortController</code> corresponding to the passed 35531cb0ef41Sopenharmony_ci<code>AbortSignal</code> will behave the same way as calling <code>.destroy(new AbortError())</code> 35541cb0ef41Sopenharmony_cion the stream, and <code>controller.error(new AbortError())</code> for webstreams.</p> 35551cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 35561cb0ef41Sopenharmony_ci 35571cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 35581cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> read = <span class="hljs-title function_">addAbortSignal</span>( 35591cb0ef41Sopenharmony_ci controller.<span class="hljs-property">signal</span>, 35601cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createReadStream</span>((<span class="hljs-string">'object.json'</span>)), 35611cb0ef41Sopenharmony_ci); 35621cb0ef41Sopenharmony_ci<span class="hljs-comment">// Later, abort the operation closing the stream</span> 35631cb0ef41Sopenharmony_cicontroller.<span class="hljs-title function_">abort</span>();</code> <button class="copy-button">copy</button></pre> 35641cb0ef41Sopenharmony_ci<p>Or using an <code>AbortSignal</code> with a readable stream as an async iterable:</p> 35651cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 35661cb0ef41Sopenharmony_ci<span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =></span> controller.<span class="hljs-title function_">abort</span>(), <span class="hljs-number">10_000</span>); <span class="hljs-comment">// set a timeout</span> 35671cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> stream = <span class="hljs-title function_">addAbortSignal</span>( 35681cb0ef41Sopenharmony_ci controller.<span class="hljs-property">signal</span>, 35691cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createReadStream</span>((<span class="hljs-string">'object.json'</span>)), 35701cb0ef41Sopenharmony_ci); 35711cb0ef41Sopenharmony_ci(<span class="hljs-keyword">async</span> () => { 35721cb0ef41Sopenharmony_ci <span class="hljs-keyword">try</span> { 35731cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> stream) { 35741cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">process</span>(chunk); 35751cb0ef41Sopenharmony_ci } 35761cb0ef41Sopenharmony_ci } <span class="hljs-keyword">catch</span> (e) { 35771cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (e.<span class="hljs-property">name</span> === <span class="hljs-string">'AbortError'</span>) { 35781cb0ef41Sopenharmony_ci <span class="hljs-comment">// The operation was cancelled</span> 35791cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 35801cb0ef41Sopenharmony_ci <span class="hljs-keyword">throw</span> e; 35811cb0ef41Sopenharmony_ci } 35821cb0ef41Sopenharmony_ci } 35831cb0ef41Sopenharmony_ci})();</code> <button class="copy-button">copy</button></pre> 35841cb0ef41Sopenharmony_ci<p>Or using an <code>AbortSignal</code> with a ReadableStream:</p> 35851cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 35861cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> rs = <span class="hljs-keyword">new</span> <span class="hljs-title class_">ReadableStream</span>({ 35871cb0ef41Sopenharmony_ci <span class="hljs-title function_">start</span>(<span class="hljs-params">controller</span>) { 35881cb0ef41Sopenharmony_ci controller.<span class="hljs-title function_">enqueue</span>(<span class="hljs-string">'hello'</span>); 35891cb0ef41Sopenharmony_ci controller.<span class="hljs-title function_">enqueue</span>(<span class="hljs-string">'world'</span>); 35901cb0ef41Sopenharmony_ci controller.<span class="hljs-title function_">close</span>(); 35911cb0ef41Sopenharmony_ci }, 35921cb0ef41Sopenharmony_ci}); 35931cb0ef41Sopenharmony_ci 35941cb0ef41Sopenharmony_ci<span class="hljs-title function_">addAbortSignal</span>(controller.<span class="hljs-property">signal</span>, rs); 35951cb0ef41Sopenharmony_ci 35961cb0ef41Sopenharmony_ci<span class="hljs-title function_">finished</span>(rs, <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 35971cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err) { 35981cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err.<span class="hljs-property">name</span> === <span class="hljs-string">'AbortError'</span>) { 35991cb0ef41Sopenharmony_ci <span class="hljs-comment">// The operation was cancelled</span> 36001cb0ef41Sopenharmony_ci } 36011cb0ef41Sopenharmony_ci } 36021cb0ef41Sopenharmony_ci}); 36031cb0ef41Sopenharmony_ci 36041cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> reader = rs.<span class="hljs-title function_">getReader</span>(); 36051cb0ef41Sopenharmony_ci 36061cb0ef41Sopenharmony_cireader.<span class="hljs-title function_">read</span>().<span class="hljs-title function_">then</span>(<span class="hljs-function">(<span class="hljs-params">{ value, done }</span>) =></span> { 36071cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(value); <span class="hljs-comment">// hello</span> 36081cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(done); <span class="hljs-comment">// false</span> 36091cb0ef41Sopenharmony_ci controller.<span class="hljs-title function_">abort</span>(); 36101cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 36111cb0ef41Sopenharmony_ci<h4><code>stream.getDefaultHighWaterMark(objectMode)</code><span><a class="mark" href="#streamgetdefaulthighwatermarkobjectmode" id="streamgetdefaulthighwatermarkobjectmode">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_getdefaulthighwatermark_objectmode"></a></h4> 36121cb0ef41Sopenharmony_ci<div class="api_metadata"> 36131cb0ef41Sopenharmony_ci<span>Added in: v18.17.0</span> 36141cb0ef41Sopenharmony_ci</div> 36151cb0ef41Sopenharmony_ci<ul> 36161cb0ef41Sopenharmony_ci<li><code>objectMode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 36171cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a></li> 36181cb0ef41Sopenharmony_ci</ul> 36191cb0ef41Sopenharmony_ci<p>Returns the default highWaterMark used by streams. 36201cb0ef41Sopenharmony_ciDefaults to <code>16384</code> (16 KiB), or <code>16</code> for <code>objectMode</code>.</p> 36211cb0ef41Sopenharmony_ci<h4><code>stream.setDefaultHighWaterMark(objectMode, value)</code><span><a class="mark" href="#streamsetdefaulthighwatermarkobjectmode-value" id="streamsetdefaulthighwatermarkobjectmode-value">#</a></span><a aria-hidden="true" class="legacy" id="stream_stream_setdefaulthighwatermark_objectmode_value"></a></h4> 36221cb0ef41Sopenharmony_ci<div class="api_metadata"> 36231cb0ef41Sopenharmony_ci<span>Added in: v18.17.0</span> 36241cb0ef41Sopenharmony_ci</div> 36251cb0ef41Sopenharmony_ci<ul> 36261cb0ef41Sopenharmony_ci<li><code>objectMode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a></li> 36271cb0ef41Sopenharmony_ci<li><code>value</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><integer></a> highWaterMark value</li> 36281cb0ef41Sopenharmony_ci</ul> 36291cb0ef41Sopenharmony_ci<p>Sets the default highWaterMark used by streams.</p> 36301cb0ef41Sopenharmony_ci</section><section><h3>API for stream implementers<span><a class="mark" href="#api-for-stream-implementers" id="api-for-stream-implementers">#</a></span><a aria-hidden="true" class="legacy" id="stream_api_for_stream_implementers"></a></h3> 36311cb0ef41Sopenharmony_ci 36321cb0ef41Sopenharmony_ci<p>The <code>node:stream</code> module API has been designed to make it possible to easily 36331cb0ef41Sopenharmony_ciimplement streams using JavaScript's prototypal inheritance model.</p> 36341cb0ef41Sopenharmony_ci<p>First, a stream developer would declare a new JavaScript class that extends one 36351cb0ef41Sopenharmony_ciof the four basic stream classes (<code>stream.Writable</code>, <code>stream.Readable</code>, 36361cb0ef41Sopenharmony_ci<code>stream.Duplex</code>, or <code>stream.Transform</code>), making sure they call the appropriate 36371cb0ef41Sopenharmony_ciparent class constructor:</p> 36381cb0ef41Sopenharmony_ci<!-- eslint-disable no-useless-constructor --> 36391cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 36401cb0ef41Sopenharmony_ci 36411cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyWritable</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Writable</span> { 36421cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">{ highWaterMark, ...options }</span>) { 36431cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>({ highWaterMark }); 36441cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 36451cb0ef41Sopenharmony_ci } 36461cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 36471cb0ef41Sopenharmony_ci<p>When extending streams, keep in mind what options the user 36481cb0ef41Sopenharmony_cican and should provide before forwarding these to the base constructor. For 36491cb0ef41Sopenharmony_ciexample, if the implementation makes assumptions in regard to the 36501cb0ef41Sopenharmony_ci<code>autoDestroy</code> and <code>emitClose</code> options, do not allow the 36511cb0ef41Sopenharmony_ciuser to override these. Be explicit about what 36521cb0ef41Sopenharmony_cioptions are forwarded instead of implicitly forwarding all options.</p> 36531cb0ef41Sopenharmony_ci<p>The new stream class must then implement one or more specific methods, depending 36541cb0ef41Sopenharmony_cion the type of stream being created, as detailed in the chart below:</p> 36551cb0ef41Sopenharmony_ci 36561cb0ef41Sopenharmony_ci 36571cb0ef41Sopenharmony_ci 36581cb0ef41Sopenharmony_ci 36591cb0ef41Sopenharmony_ci 36601cb0ef41Sopenharmony_ci 36611cb0ef41Sopenharmony_ci 36621cb0ef41Sopenharmony_ci 36631cb0ef41Sopenharmony_ci 36641cb0ef41Sopenharmony_ci 36651cb0ef41Sopenharmony_ci 36661cb0ef41Sopenharmony_ci 36671cb0ef41Sopenharmony_ci 36681cb0ef41Sopenharmony_ci 36691cb0ef41Sopenharmony_ci 36701cb0ef41Sopenharmony_ci 36711cb0ef41Sopenharmony_ci 36721cb0ef41Sopenharmony_ci 36731cb0ef41Sopenharmony_ci 36741cb0ef41Sopenharmony_ci 36751cb0ef41Sopenharmony_ci 36761cb0ef41Sopenharmony_ci 36771cb0ef41Sopenharmony_ci 36781cb0ef41Sopenharmony_ci 36791cb0ef41Sopenharmony_ci 36801cb0ef41Sopenharmony_ci 36811cb0ef41Sopenharmony_ci 36821cb0ef41Sopenharmony_ci 36831cb0ef41Sopenharmony_ci 36841cb0ef41Sopenharmony_ci 36851cb0ef41Sopenharmony_ci<table><thead><tr><th>Use-case</th><th>Class</th><th>Method(s) to implement</th></tr></thead><tbody><tr><td>Reading only</td><td><a href="#class-streamreadable"><code>Readable</code></a></td><td><a href="#readable_readsize"><code>_read()</code></a></td></tr><tr><td>Writing only</td><td><a href="#class-streamwritable"><code>Writable</code></a></td><td><a href="#writable_writechunk-encoding-callback"><code>_write()</code></a>, <a href="#writable_writevchunks-callback"><code>_writev()</code></a>, <a href="#writable_finalcallback"><code>_final()</code></a></td></tr><tr><td>Reading and writing</td><td><a href="#class-streamduplex"><code>Duplex</code></a></td><td><a href="#readable_readsize"><code>_read()</code></a>, <a href="#writable_writechunk-encoding-callback"><code>_write()</code></a>, <a href="#writable_writevchunks-callback"><code>_writev()</code></a>, <a href="#writable_finalcallback"><code>_final()</code></a></td></tr><tr><td>Operate on written data, then read the result</td><td><a href="#class-streamtransform"><code>Transform</code></a></td><td><a href="#transform_transformchunk-encoding-callback"><code>_transform()</code></a>, <a href="#transform_flushcallback"><code>_flush()</code></a>, <a href="#writable_finalcallback"><code>_final()</code></a></td></tr></tbody></table> 36861cb0ef41Sopenharmony_ci<p>The implementation code for a stream should <em>never</em> call the "public" methods 36871cb0ef41Sopenharmony_ciof a stream that are intended for use by consumers (as described in the 36881cb0ef41Sopenharmony_ci<a href="#api-for-stream-consumers">API for stream consumers</a> section). Doing so may lead to adverse side effects 36891cb0ef41Sopenharmony_ciin application code consuming the stream.</p> 36901cb0ef41Sopenharmony_ci<p>Avoid overriding public methods such as <code>write()</code>, <code>end()</code>, <code>cork()</code>, 36911cb0ef41Sopenharmony_ci<code>uncork()</code>, <code>read()</code> and <code>destroy()</code>, or emitting internal events such 36921cb0ef41Sopenharmony_cias <code>'error'</code>, <code>'data'</code>, <code>'end'</code>, <code>'finish'</code> and <code>'close'</code> through <code>.emit()</code>. 36931cb0ef41Sopenharmony_ciDoing so can break current and future stream invariants leading to behavior 36941cb0ef41Sopenharmony_ciand/or compatibility issues with other streams, stream utilities, and user 36951cb0ef41Sopenharmony_ciexpectations.</p> 36961cb0ef41Sopenharmony_ci<h4>Simplified construction<span><a class="mark" href="#simplified-construction" id="simplified-construction">#</a></span><a aria-hidden="true" class="legacy" id="stream_simplified_construction"></a></h4> 36971cb0ef41Sopenharmony_ci<div class="api_metadata"> 36981cb0ef41Sopenharmony_ci<span>Added in: v1.2.0</span> 36991cb0ef41Sopenharmony_ci</div> 37001cb0ef41Sopenharmony_ci<p>For many simple cases, it is possible to create a stream without relying on 37011cb0ef41Sopenharmony_ciinheritance. This can be accomplished by directly creating instances of the 37021cb0ef41Sopenharmony_ci<code>stream.Writable</code>, <code>stream.Readable</code>, <code>stream.Duplex</code>, or <code>stream.Transform</code> 37031cb0ef41Sopenharmony_ciobjects and passing appropriate methods as constructor options.</p> 37041cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 37051cb0ef41Sopenharmony_ci 37061cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myWritable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Writable</span>({ 37071cb0ef41Sopenharmony_ci <span class="hljs-title function_">construct</span>(<span class="hljs-params">callback</span>) { 37081cb0ef41Sopenharmony_ci <span class="hljs-comment">// Initialize state and load resources...</span> 37091cb0ef41Sopenharmony_ci }, 37101cb0ef41Sopenharmony_ci <span class="hljs-title function_">write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 37111cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 37121cb0ef41Sopenharmony_ci }, 37131cb0ef41Sopenharmony_ci <span class="hljs-title function_">destroy</span>(<span class="hljs-params"></span>) { 37141cb0ef41Sopenharmony_ci <span class="hljs-comment">// Free resources...</span> 37151cb0ef41Sopenharmony_ci }, 37161cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 37171cb0ef41Sopenharmony_ci<h4>Implementing a writable stream<span><a class="mark" href="#implementing-a-writable-stream" id="implementing-a-writable-stream">#</a></span><a aria-hidden="true" class="legacy" id="stream_implementing_a_writable_stream"></a></h4> 37181cb0ef41Sopenharmony_ci<p>The <code>stream.Writable</code> class is extended to implement a <a href="#class-streamwritable"><code>Writable</code></a> stream.</p> 37191cb0ef41Sopenharmony_ci<p>Custom <code>Writable</code> streams <em>must</em> call the <code>new stream.Writable([options])</code> 37201cb0ef41Sopenharmony_ciconstructor and implement the <code>writable._write()</code> and/or <code>writable._writev()</code> 37211cb0ef41Sopenharmony_cimethod.</p> 37221cb0ef41Sopenharmony_ci<h5><code>new stream.Writable([options])</code><span><a class="mark" href="#new-streamwritableoptions" id="new-streamwritableoptions">#</a></span><a aria-hidden="true" class="legacy" id="stream_new_stream_writable_options"></a></h5> 37231cb0ef41Sopenharmony_ci<div class="api_metadata"> 37241cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 37251cb0ef41Sopenharmony_ci<table> 37261cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 37271cb0ef41Sopenharmony_ci<tr><td>v15.5.0</td> 37281cb0ef41Sopenharmony_ci<td><p>support passing in an AbortSignal.</p></td></tr> 37291cb0ef41Sopenharmony_ci<tr><td>v14.0.0</td> 37301cb0ef41Sopenharmony_ci<td><p>Change <code>autoDestroy</code> option default to <code>true</code>.</p></td></tr> 37311cb0ef41Sopenharmony_ci<tr><td>v11.2.0, v10.16.0</td> 37321cb0ef41Sopenharmony_ci<td><p>Add <code>autoDestroy</code> option to automatically <code>destroy()</code> the stream when it emits <code>'finish'</code> or errors.</p></td></tr> 37331cb0ef41Sopenharmony_ci<tr><td>v10.0.0</td> 37341cb0ef41Sopenharmony_ci<td><p>Add <code>emitClose</code> option to specify if <code>'close'</code> is emitted on destroy.</p></td></tr> 37351cb0ef41Sopenharmony_ci</tbody></table> 37361cb0ef41Sopenharmony_ci</details> 37371cb0ef41Sopenharmony_ci</div> 37381cb0ef41Sopenharmony_ci<ul> 37391cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 37401cb0ef41Sopenharmony_ci<ul> 37411cb0ef41Sopenharmony_ci<li><code>highWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Buffer level when 37421cb0ef41Sopenharmony_ci<a href="#writablewritechunk-encoding-callback"><code>stream.write()</code></a> starts returning <code>false</code>. <strong>Default:</strong> 37431cb0ef41Sopenharmony_ci<code>16384</code> (16 KiB), or <code>16</code> for <code>objectMode</code> streams.</li> 37441cb0ef41Sopenharmony_ci<li><code>decodeStrings</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether to encode <code>string</code>s passed to 37451cb0ef41Sopenharmony_ci<a href="#writablewritechunk-encoding-callback"><code>stream.write()</code></a> to <code>Buffer</code>s (with the encoding 37461cb0ef41Sopenharmony_cispecified in the <a href="#writablewritechunk-encoding-callback"><code>stream.write()</code></a> call) before passing 37471cb0ef41Sopenharmony_cithem to <a href="#writable_writechunk-encoding-callback"><code>stream._write()</code></a>. Other types of data are not 37481cb0ef41Sopenharmony_ciconverted (i.e. <code>Buffer</code>s are not decoded into <code>string</code>s). Setting to 37491cb0ef41Sopenharmony_cifalse will prevent <code>string</code>s from being converted. <strong>Default:</strong> <code>true</code>.</li> 37501cb0ef41Sopenharmony_ci<li><code>defaultEncoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The default encoding that is used when no 37511cb0ef41Sopenharmony_ciencoding is specified as an argument to <a href="#writablewritechunk-encoding-callback"><code>stream.write()</code></a>. 37521cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>'utf8'</code>.</li> 37531cb0ef41Sopenharmony_ci<li><code>objectMode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether or not the 37541cb0ef41Sopenharmony_ci<a href="#writablewritechunk-encoding-callback"><code>stream.write(anyObj)</code></a> is a valid operation. When set, 37551cb0ef41Sopenharmony_ciit becomes possible to write JavaScript values other than string, 37561cb0ef41Sopenharmony_ci<code>Buffer</code> or <code>Uint8Array</code> if supported by the stream implementation. 37571cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>false</code>.</li> 37581cb0ef41Sopenharmony_ci<li><code>emitClose</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether or not the stream should emit <code>'close'</code> 37591cb0ef41Sopenharmony_ciafter it has been destroyed. <strong>Default:</strong> <code>true</code>.</li> 37601cb0ef41Sopenharmony_ci<li><code>write</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Implementation for the 37611cb0ef41Sopenharmony_ci<a href="#writable_writechunk-encoding-callback"><code>stream._write()</code></a> method.</li> 37621cb0ef41Sopenharmony_ci<li><code>writev</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Implementation for the 37631cb0ef41Sopenharmony_ci<a href="#writable_writevchunks-callback"><code>stream._writev()</code></a> method.</li> 37641cb0ef41Sopenharmony_ci<li><code>destroy</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Implementation for the 37651cb0ef41Sopenharmony_ci<a href="#writable_destroyerr-callback"><code>stream._destroy()</code></a> method.</li> 37661cb0ef41Sopenharmony_ci<li><code>final</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Implementation for the 37671cb0ef41Sopenharmony_ci<a href="#writable_finalcallback"><code>stream._final()</code></a> method.</li> 37681cb0ef41Sopenharmony_ci<li><code>construct</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Implementation for the 37691cb0ef41Sopenharmony_ci<a href="#writable_constructcallback"><code>stream._construct()</code></a> method.</li> 37701cb0ef41Sopenharmony_ci<li><code>autoDestroy</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether this stream should automatically call 37711cb0ef41Sopenharmony_ci<code>.destroy()</code> on itself after ending. <strong>Default:</strong> <code>true</code>.</li> 37721cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> A signal representing possible cancellation.</li> 37731cb0ef41Sopenharmony_ci</ul> 37741cb0ef41Sopenharmony_ci</li> 37751cb0ef41Sopenharmony_ci</ul> 37761cb0ef41Sopenharmony_ci<!-- eslint-disable no-useless-constructor --> 37771cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 37781cb0ef41Sopenharmony_ci 37791cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyWritable</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Writable</span> { 37801cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">options</span>) { 37811cb0ef41Sopenharmony_ci <span class="hljs-comment">// Calls the stream.Writable() constructor.</span> 37821cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>(options); 37831cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 37841cb0ef41Sopenharmony_ci } 37851cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 37861cb0ef41Sopenharmony_ci<p>Or, when using pre-ES6 style constructors:</p> 37871cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 37881cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> util = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:util'</span>); 37891cb0ef41Sopenharmony_ci 37901cb0ef41Sopenharmony_ci<span class="hljs-keyword">function</span> <span class="hljs-title function_">MyWritable</span>(<span class="hljs-params">options</span>) { 37911cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (!(<span class="hljs-variable language_">this</span> <span class="hljs-keyword">instanceof</span> <span class="hljs-title class_">MyWritable</span>)) 37921cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">MyWritable</span>(options); 37931cb0ef41Sopenharmony_ci <span class="hljs-title class_">Writable</span>.<span class="hljs-title function_">call</span>(<span class="hljs-variable language_">this</span>, options); 37941cb0ef41Sopenharmony_ci} 37951cb0ef41Sopenharmony_ciutil.<span class="hljs-title function_">inherits</span>(<span class="hljs-title class_">MyWritable</span>, <span class="hljs-title class_">Writable</span>);</code> <button class="copy-button">copy</button></pre> 37961cb0ef41Sopenharmony_ci<p>Or, using the simplified constructor approach:</p> 37971cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 37981cb0ef41Sopenharmony_ci 37991cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myWritable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Writable</span>({ 38001cb0ef41Sopenharmony_ci <span class="hljs-title function_">write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 38011cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 38021cb0ef41Sopenharmony_ci }, 38031cb0ef41Sopenharmony_ci <span class="hljs-title function_">writev</span>(<span class="hljs-params">chunks, callback</span>) { 38041cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 38051cb0ef41Sopenharmony_ci }, 38061cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 38071cb0ef41Sopenharmony_ci<p>Calling <code>abort</code> on the <code>AbortController</code> corresponding to the passed 38081cb0ef41Sopenharmony_ci<code>AbortSignal</code> will behave the same way as calling <code>.destroy(new AbortError())</code> 38091cb0ef41Sopenharmony_cion the writeable stream.</p> 38101cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 38111cb0ef41Sopenharmony_ci 38121cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 38131cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myWritable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Writable</span>({ 38141cb0ef41Sopenharmony_ci <span class="hljs-title function_">write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 38151cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 38161cb0ef41Sopenharmony_ci }, 38171cb0ef41Sopenharmony_ci <span class="hljs-title function_">writev</span>(<span class="hljs-params">chunks, callback</span>) { 38181cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 38191cb0ef41Sopenharmony_ci }, 38201cb0ef41Sopenharmony_ci <span class="hljs-attr">signal</span>: controller.<span class="hljs-property">signal</span>, 38211cb0ef41Sopenharmony_ci}); 38221cb0ef41Sopenharmony_ci<span class="hljs-comment">// Later, abort the operation closing the stream</span> 38231cb0ef41Sopenharmony_cicontroller.<span class="hljs-title function_">abort</span>();</code> <button class="copy-button">copy</button></pre> 38241cb0ef41Sopenharmony_ci<h5><code>writable._construct(callback)</code><span><a class="mark" href="#writable_constructcallback" id="writable_constructcallback">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_construct_callback"></a></h5> 38251cb0ef41Sopenharmony_ci<div class="api_metadata"> 38261cb0ef41Sopenharmony_ci<span>Added in: v15.0.0</span> 38271cb0ef41Sopenharmony_ci</div> 38281cb0ef41Sopenharmony_ci<ul> 38291cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Call this function (optionally with an error 38301cb0ef41Sopenharmony_ciargument) when the stream has finished initializing.</li> 38311cb0ef41Sopenharmony_ci</ul> 38321cb0ef41Sopenharmony_ci<p>The <code>_construct()</code> method MUST NOT be called directly. It may be implemented 38331cb0ef41Sopenharmony_ciby child classes, and if so, will be called by the internal <code>Writable</code> 38341cb0ef41Sopenharmony_ciclass methods only.</p> 38351cb0ef41Sopenharmony_ci<p>This optional function will be called in a tick after the stream constructor 38361cb0ef41Sopenharmony_cihas returned, delaying any <code>_write()</code>, <code>_final()</code> and <code>_destroy()</code> calls until 38371cb0ef41Sopenharmony_ci<code>callback</code> is called. This is useful to initialize state or asynchronously 38381cb0ef41Sopenharmony_ciinitialize resources before the stream can be used.</p> 38391cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 38401cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 38411cb0ef41Sopenharmony_ci 38421cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">WriteStream</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Writable</span> { 38431cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">filename</span>) { 38441cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>(); 38451cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">filename</span> = filename; 38461cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">fd</span> = <span class="hljs-literal">null</span>; 38471cb0ef41Sopenharmony_ci } 38481cb0ef41Sopenharmony_ci <span class="hljs-title function_">_construct</span>(<span class="hljs-params">callback</span>) { 38491cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">open</span>(<span class="hljs-variable language_">this</span>.<span class="hljs-property">filename</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 38501cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err) { 38511cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(err); 38521cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 38531cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">fd</span> = fd; 38541cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 38551cb0ef41Sopenharmony_ci } 38561cb0ef41Sopenharmony_ci }); 38571cb0ef41Sopenharmony_ci } 38581cb0ef41Sopenharmony_ci <span class="hljs-title function_">_write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 38591cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">write</span>(<span class="hljs-variable language_">this</span>.<span class="hljs-property">fd</span>, chunk, callback); 38601cb0ef41Sopenharmony_ci } 38611cb0ef41Sopenharmony_ci <span class="hljs-title function_">_destroy</span>(<span class="hljs-params">err, callback</span>) { 38621cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (<span class="hljs-variable language_">this</span>.<span class="hljs-property">fd</span>) { 38631cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">close</span>(<span class="hljs-variable language_">this</span>.<span class="hljs-property">fd</span>, <span class="hljs-function">(<span class="hljs-params">er</span>) =></span> <span class="hljs-title function_">callback</span>(er || err)); 38641cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 38651cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(err); 38661cb0ef41Sopenharmony_ci } 38671cb0ef41Sopenharmony_ci } 38681cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 38691cb0ef41Sopenharmony_ci<h5><code>writable._write(chunk, encoding, callback)</code><span><a class="mark" href="#writable_writechunk-encoding-callback" id="writable_writechunk-encoding-callback">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_write_chunk_encoding_callback_1"></a></h5> 38701cb0ef41Sopenharmony_ci<div class="api_metadata"> 38711cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 38721cb0ef41Sopenharmony_ci<table> 38731cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 38741cb0ef41Sopenharmony_ci<tr><td>v12.11.0</td> 38751cb0ef41Sopenharmony_ci<td><p>_write() is optional when providing _writev().</p></td></tr> 38761cb0ef41Sopenharmony_ci</tbody></table> 38771cb0ef41Sopenharmony_ci</details> 38781cb0ef41Sopenharmony_ci</div> 38791cb0ef41Sopenharmony_ci<ul> 38801cb0ef41Sopenharmony_ci<li><code>chunk</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> The <code>Buffer</code> to be written, converted from the 38811cb0ef41Sopenharmony_ci<code>string</code> passed to <a href="#writablewritechunk-encoding-callback"><code>stream.write()</code></a>. If the stream's 38821cb0ef41Sopenharmony_ci<code>decodeStrings</code> option is <code>false</code> or the stream is operating in object mode, 38831cb0ef41Sopenharmony_cithe chunk will not be converted & will be whatever was passed to 38841cb0ef41Sopenharmony_ci<a href="#writablewritechunk-encoding-callback"><code>stream.write()</code></a>.</li> 38851cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If the chunk is a string, then <code>encoding</code> is the 38861cb0ef41Sopenharmony_cicharacter encoding of that string. If chunk is a <code>Buffer</code>, or if the 38871cb0ef41Sopenharmony_cistream is operating in object mode, <code>encoding</code> may be ignored.</li> 38881cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Call this function (optionally with an error 38891cb0ef41Sopenharmony_ciargument) when processing is complete for the supplied chunk.</li> 38901cb0ef41Sopenharmony_ci</ul> 38911cb0ef41Sopenharmony_ci<p>All <code>Writable</code> stream implementations must provide a 38921cb0ef41Sopenharmony_ci<a href="#writable_writechunk-encoding-callback"><code>writable._write()</code></a> and/or 38931cb0ef41Sopenharmony_ci<a href="#writable_writevchunks-callback"><code>writable._writev()</code></a> method to send data to the underlying 38941cb0ef41Sopenharmony_ciresource.</p> 38951cb0ef41Sopenharmony_ci<p><a href="#class-streamtransform"><code>Transform</code></a> streams provide their own implementation of the 38961cb0ef41Sopenharmony_ci<a href="#writable_writechunk-encoding-callback"><code>writable._write()</code></a>.</p> 38971cb0ef41Sopenharmony_ci<p>This function MUST NOT be called by application code directly. It should be 38981cb0ef41Sopenharmony_ciimplemented by child classes, and called by the internal <code>Writable</code> class 38991cb0ef41Sopenharmony_cimethods only.</p> 39001cb0ef41Sopenharmony_ci<p>The <code>callback</code> function must be called synchronously inside of 39011cb0ef41Sopenharmony_ci<code>writable._write()</code> or asynchronously (i.e. different tick) to signal either 39021cb0ef41Sopenharmony_cithat the write completed successfully or failed with an error. 39031cb0ef41Sopenharmony_ciThe first argument passed to the <code>callback</code> must be the <code>Error</code> object if the 39041cb0ef41Sopenharmony_cicall failed or <code>null</code> if the write succeeded.</p> 39051cb0ef41Sopenharmony_ci<p>All calls to <code>writable.write()</code> that occur between the time <code>writable._write()</code> 39061cb0ef41Sopenharmony_ciis called and the <code>callback</code> is called will cause the written data to be 39071cb0ef41Sopenharmony_cibuffered. When the <code>callback</code> is invoked, the stream might emit a <a href="#event-drain"><code>'drain'</code></a> 39081cb0ef41Sopenharmony_cievent. If a stream implementation is capable of processing multiple chunks of 39091cb0ef41Sopenharmony_cidata at once, the <code>writable._writev()</code> method should be implemented.</p> 39101cb0ef41Sopenharmony_ci<p>If the <code>decodeStrings</code> property is explicitly set to <code>false</code> in the constructor 39111cb0ef41Sopenharmony_cioptions, then <code>chunk</code> will remain the same object that is passed to <code>.write()</code>, 39121cb0ef41Sopenharmony_ciand may be a string rather than a <code>Buffer</code>. This is to support implementations 39131cb0ef41Sopenharmony_cithat have an optimized handling for certain string data encodings. In that case, 39141cb0ef41Sopenharmony_cithe <code>encoding</code> argument will indicate the character encoding of the string. 39151cb0ef41Sopenharmony_ciOtherwise, the <code>encoding</code> argument can be safely ignored.</p> 39161cb0ef41Sopenharmony_ci<p>The <code>writable._write()</code> method is prefixed with an underscore because it is 39171cb0ef41Sopenharmony_ciinternal to the class that defines it, and should never be called directly by 39181cb0ef41Sopenharmony_ciuser programs.</p> 39191cb0ef41Sopenharmony_ci<h5><code>writable._writev(chunks, callback)</code><span><a class="mark" href="#writable_writevchunks-callback" id="writable_writevchunks-callback">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_writev_chunks_callback"></a></h5> 39201cb0ef41Sopenharmony_ci<ul> 39211cb0ef41Sopenharmony_ci<li><code>chunks</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object[]></a> The data to be written. The value is an array of <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 39221cb0ef41Sopenharmony_cithat each represent a discrete chunk of data to write. The properties of 39231cb0ef41Sopenharmony_cithese objects are: 39241cb0ef41Sopenharmony_ci<ul> 39251cb0ef41Sopenharmony_ci<li><code>chunk</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> A buffer instance or string containing the data to 39261cb0ef41Sopenharmony_cibe written. The <code>chunk</code> will be a string if the <code>Writable</code> was created with 39271cb0ef41Sopenharmony_cithe <code>decodeStrings</code> option set to <code>false</code> and a string was passed to <code>write()</code>.</li> 39281cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> The character encoding of the <code>chunk</code>. If <code>chunk</code> is 39291cb0ef41Sopenharmony_cia <code>Buffer</code>, the <code>encoding</code> will be <code>'buffer'</code>.</li> 39301cb0ef41Sopenharmony_ci</ul> 39311cb0ef41Sopenharmony_ci</li> 39321cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A callback function (optionally with an error 39331cb0ef41Sopenharmony_ciargument) to be invoked when processing is complete for the supplied chunks.</li> 39341cb0ef41Sopenharmony_ci</ul> 39351cb0ef41Sopenharmony_ci<p>This function MUST NOT be called by application code directly. It should be 39361cb0ef41Sopenharmony_ciimplemented by child classes, and called by the internal <code>Writable</code> class 39371cb0ef41Sopenharmony_cimethods only.</p> 39381cb0ef41Sopenharmony_ci<p>The <code>writable._writev()</code> method may be implemented in addition or alternatively 39391cb0ef41Sopenharmony_cito <code>writable._write()</code> in stream implementations that are capable of processing 39401cb0ef41Sopenharmony_cimultiple chunks of data at once. If implemented and if there is buffered data 39411cb0ef41Sopenharmony_cifrom previous writes, <code>_writev()</code> will be called instead of <code>_write()</code>.</p> 39421cb0ef41Sopenharmony_ci<p>The <code>writable._writev()</code> method is prefixed with an underscore because it is 39431cb0ef41Sopenharmony_ciinternal to the class that defines it, and should never be called directly by 39441cb0ef41Sopenharmony_ciuser programs.</p> 39451cb0ef41Sopenharmony_ci<h5><code>writable._destroy(err, callback)</code><span><a class="mark" href="#writable_destroyerr-callback" id="writable_destroyerr-callback">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_destroy_err_callback"></a></h5> 39461cb0ef41Sopenharmony_ci<div class="api_metadata"> 39471cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 39481cb0ef41Sopenharmony_ci</div> 39491cb0ef41Sopenharmony_ci<ul> 39501cb0ef41Sopenharmony_ci<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> A possible error.</li> 39511cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A callback function that takes an optional error 39521cb0ef41Sopenharmony_ciargument.</li> 39531cb0ef41Sopenharmony_ci</ul> 39541cb0ef41Sopenharmony_ci<p>The <code>_destroy()</code> method is called by <a href="#writabledestroyerror"><code>writable.destroy()</code></a>. 39551cb0ef41Sopenharmony_ciIt can be overridden by child classes but it <strong>must not</strong> be called directly. 39561cb0ef41Sopenharmony_ciFurthermore, the <code>callback</code> should not be mixed with async/await 39571cb0ef41Sopenharmony_cionce it is executed when a promise is resolved.</p> 39581cb0ef41Sopenharmony_ci<h5><code>writable._final(callback)</code><span><a class="mark" href="#writable_finalcallback" id="writable_finalcallback">#</a></span><a aria-hidden="true" class="legacy" id="stream_writable_final_callback"></a></h5> 39591cb0ef41Sopenharmony_ci<div class="api_metadata"> 39601cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 39611cb0ef41Sopenharmony_ci</div> 39621cb0ef41Sopenharmony_ci<ul> 39631cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Call this function (optionally with an error 39641cb0ef41Sopenharmony_ciargument) when finished writing any remaining data.</li> 39651cb0ef41Sopenharmony_ci</ul> 39661cb0ef41Sopenharmony_ci<p>The <code>_final()</code> method <strong>must not</strong> be called directly. It may be implemented 39671cb0ef41Sopenharmony_ciby child classes, and if so, will be called by the internal <code>Writable</code> 39681cb0ef41Sopenharmony_ciclass methods only.</p> 39691cb0ef41Sopenharmony_ci<p>This optional function will be called before the stream closes, delaying the 39701cb0ef41Sopenharmony_ci<code>'finish'</code> event until <code>callback</code> is called. This is useful to close resources 39711cb0ef41Sopenharmony_cior write buffered data before a stream ends.</p> 39721cb0ef41Sopenharmony_ci<h5>Errors while writing<span><a class="mark" href="#errors-while-writing" id="errors-while-writing">#</a></span><a aria-hidden="true" class="legacy" id="stream_errors_while_writing"></a></h5> 39731cb0ef41Sopenharmony_ci<p>Errors occurring during the processing of the <a href="#writable_writechunk-encoding-callback"><code>writable._write()</code></a>, 39741cb0ef41Sopenharmony_ci<a href="#writable_writevchunks-callback"><code>writable._writev()</code></a> and <a href="#writable_finalcallback"><code>writable._final()</code></a> methods must be propagated 39751cb0ef41Sopenharmony_ciby invoking the callback and passing the error as the first argument. 39761cb0ef41Sopenharmony_ciThrowing an <code>Error</code> from within these methods or manually emitting an <code>'error'</code> 39771cb0ef41Sopenharmony_cievent results in undefined behavior.</p> 39781cb0ef41Sopenharmony_ci<p>If a <code>Readable</code> stream pipes into a <code>Writable</code> stream when <code>Writable</code> emits an 39791cb0ef41Sopenharmony_cierror, the <code>Readable</code> stream will be unpiped.</p> 39801cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 39811cb0ef41Sopenharmony_ci 39821cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myWritable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Writable</span>({ 39831cb0ef41Sopenharmony_ci <span class="hljs-title function_">write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 39841cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (chunk.<span class="hljs-title function_">toString</span>().<span class="hljs-title function_">indexOf</span>(<span class="hljs-string">'a'</span>) >= <span class="hljs-number">0</span>) { 39851cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(<span class="hljs-keyword">new</span> <span class="hljs-title class_">Error</span>(<span class="hljs-string">'chunk is invalid'</span>)); 39861cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 39871cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 39881cb0ef41Sopenharmony_ci } 39891cb0ef41Sopenharmony_ci }, 39901cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 39911cb0ef41Sopenharmony_ci<h5>An example writable stream<span><a class="mark" href="#an-example-writable-stream" id="an-example-writable-stream">#</a></span><a aria-hidden="true" class="legacy" id="stream_an_example_writable_stream"></a></h5> 39921cb0ef41Sopenharmony_ci<p>The following illustrates a rather simplistic (and somewhat pointless) custom 39931cb0ef41Sopenharmony_ci<code>Writable</code> stream implementation. While this specific <code>Writable</code> stream instance 39941cb0ef41Sopenharmony_ciis not of any real particular usefulness, the example illustrates each of the 39951cb0ef41Sopenharmony_cirequired elements of a custom <a href="#class-streamwritable"><code>Writable</code></a> stream instance:</p> 39961cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 39971cb0ef41Sopenharmony_ci 39981cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyWritable</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Writable</span> { 39991cb0ef41Sopenharmony_ci <span class="hljs-title function_">_write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 40001cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (chunk.<span class="hljs-title function_">toString</span>().<span class="hljs-title function_">indexOf</span>(<span class="hljs-string">'a'</span>) >= <span class="hljs-number">0</span>) { 40011cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(<span class="hljs-keyword">new</span> <span class="hljs-title class_">Error</span>(<span class="hljs-string">'chunk is invalid'</span>)); 40021cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 40031cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 40041cb0ef41Sopenharmony_ci } 40051cb0ef41Sopenharmony_ci } 40061cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 40071cb0ef41Sopenharmony_ci<h5>Decoding buffers in a writable stream<span><a class="mark" href="#decoding-buffers-in-a-writable-stream" id="decoding-buffers-in-a-writable-stream">#</a></span><a aria-hidden="true" class="legacy" id="stream_decoding_buffers_in_a_writable_stream"></a></h5> 40081cb0ef41Sopenharmony_ci<p>Decoding buffers is a common task, for instance, when using transformers whose 40091cb0ef41Sopenharmony_ciinput is a string. This is not a trivial process when using multi-byte 40101cb0ef41Sopenharmony_cicharacters encoding, such as UTF-8. The following example shows how to decode 40111cb0ef41Sopenharmony_cimulti-byte strings using <code>StringDecoder</code> and <a href="#class-streamwritable"><code>Writable</code></a>.</p> 40121cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Writable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 40131cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { <span class="hljs-title class_">StringDecoder</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:string_decoder'</span>); 40141cb0ef41Sopenharmony_ci 40151cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">StringWritable</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Writable</span> { 40161cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">options</span>) { 40171cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>(options); 40181cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">_decoder</span> = <span class="hljs-keyword">new</span> <span class="hljs-title class_">StringDecoder</span>(options && options.<span class="hljs-property">defaultEncoding</span>); 40191cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">data</span> = <span class="hljs-string">''</span>; 40201cb0ef41Sopenharmony_ci } 40211cb0ef41Sopenharmony_ci <span class="hljs-title function_">_write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 40221cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (encoding === <span class="hljs-string">'buffer'</span>) { 40231cb0ef41Sopenharmony_ci chunk = <span class="hljs-variable language_">this</span>.<span class="hljs-property">_decoder</span>.<span class="hljs-title function_">write</span>(chunk); 40241cb0ef41Sopenharmony_ci } 40251cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">data</span> += chunk; 40261cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 40271cb0ef41Sopenharmony_ci } 40281cb0ef41Sopenharmony_ci <span class="hljs-title function_">_final</span>(<span class="hljs-params">callback</span>) { 40291cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">data</span> += <span class="hljs-variable language_">this</span>.<span class="hljs-property">_decoder</span>.<span class="hljs-title function_">end</span>(); 40301cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 40311cb0ef41Sopenharmony_ci } 40321cb0ef41Sopenharmony_ci} 40331cb0ef41Sopenharmony_ci 40341cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> euro = [[<span class="hljs-number">0xE2</span>, <span class="hljs-number">0x82</span>], [<span class="hljs-number">0xAC</span>]].<span class="hljs-title function_">map</span>(<span class="hljs-title class_">Buffer</span>.<span class="hljs-property">from</span>); 40351cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> w = <span class="hljs-keyword">new</span> <span class="hljs-title class_">StringWritable</span>(); 40361cb0ef41Sopenharmony_ci 40371cb0ef41Sopenharmony_ciw.<span class="hljs-title function_">write</span>(<span class="hljs-string">'currency: '</span>); 40381cb0ef41Sopenharmony_ciw.<span class="hljs-title function_">write</span>(euro[<span class="hljs-number">0</span>]); 40391cb0ef41Sopenharmony_ciw.<span class="hljs-title function_">end</span>(euro[<span class="hljs-number">1</span>]); 40401cb0ef41Sopenharmony_ci 40411cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(w.<span class="hljs-property">data</span>); <span class="hljs-comment">// currency: €</span></code> <button class="copy-button">copy</button></pre> 40421cb0ef41Sopenharmony_ci<h4>Implementing a readable stream<span><a class="mark" href="#implementing-a-readable-stream" id="implementing-a-readable-stream">#</a></span><a aria-hidden="true" class="legacy" id="stream_implementing_a_readable_stream"></a></h4> 40431cb0ef41Sopenharmony_ci<p>The <code>stream.Readable</code> class is extended to implement a <a href="#class-streamreadable"><code>Readable</code></a> stream.</p> 40441cb0ef41Sopenharmony_ci<p>Custom <code>Readable</code> streams <em>must</em> call the <code>new stream.Readable([options])</code> 40451cb0ef41Sopenharmony_ciconstructor and implement the <a href="#readable_readsize"><code>readable._read()</code></a> method.</p> 40461cb0ef41Sopenharmony_ci<h5><code>new stream.Readable([options])</code><span><a class="mark" href="#new-streamreadableoptions" id="new-streamreadableoptions">#</a></span><a aria-hidden="true" class="legacy" id="stream_new_stream_readable_options"></a></h5> 40471cb0ef41Sopenharmony_ci<div class="api_metadata"> 40481cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 40491cb0ef41Sopenharmony_ci<table> 40501cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 40511cb0ef41Sopenharmony_ci<tr><td>v15.5.0</td> 40521cb0ef41Sopenharmony_ci<td><p>support passing in an AbortSignal.</p></td></tr> 40531cb0ef41Sopenharmony_ci<tr><td>v14.0.0</td> 40541cb0ef41Sopenharmony_ci<td><p>Change <code>autoDestroy</code> option default to <code>true</code>.</p></td></tr> 40551cb0ef41Sopenharmony_ci<tr><td>v11.2.0, v10.16.0</td> 40561cb0ef41Sopenharmony_ci<td><p>Add <code>autoDestroy</code> option to automatically <code>destroy()</code> the stream when it emits <code>'end'</code> or errors.</p></td></tr> 40571cb0ef41Sopenharmony_ci</tbody></table> 40581cb0ef41Sopenharmony_ci</details> 40591cb0ef41Sopenharmony_ci</div> 40601cb0ef41Sopenharmony_ci<ul> 40611cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> 40621cb0ef41Sopenharmony_ci<ul> 40631cb0ef41Sopenharmony_ci<li><code>highWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> The maximum <a href="#highwatermark-discrepancy-after-calling-readablesetencoding">number of bytes</a> to store 40641cb0ef41Sopenharmony_ciin the internal buffer before ceasing to read from the underlying resource. 40651cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>16384</code> (16 KiB), or <code>16</code> for <code>objectMode</code> streams.</li> 40661cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If specified, then buffers will be decoded to 40671cb0ef41Sopenharmony_cistrings using the specified encoding. <strong>Default:</strong> <code>null</code>.</li> 40681cb0ef41Sopenharmony_ci<li><code>objectMode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether this stream should behave 40691cb0ef41Sopenharmony_cias a stream of objects. Meaning that <a href="#readablereadsize"><code>stream.read(n)</code></a> returns 40701cb0ef41Sopenharmony_cia single value instead of a <code>Buffer</code> of size <code>n</code>. <strong>Default:</strong> <code>false</code>.</li> 40711cb0ef41Sopenharmony_ci<li><code>emitClose</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether or not the stream should emit <code>'close'</code> 40721cb0ef41Sopenharmony_ciafter it has been destroyed. <strong>Default:</strong> <code>true</code>.</li> 40731cb0ef41Sopenharmony_ci<li><code>read</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Implementation for the <a href="#readable_readsize"><code>stream._read()</code></a> 40741cb0ef41Sopenharmony_cimethod.</li> 40751cb0ef41Sopenharmony_ci<li><code>destroy</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Implementation for the 40761cb0ef41Sopenharmony_ci<a href="#readable_destroyerr-callback"><code>stream._destroy()</code></a> method.</li> 40771cb0ef41Sopenharmony_ci<li><code>construct</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Implementation for the 40781cb0ef41Sopenharmony_ci<a href="#readable_constructcallback"><code>stream._construct()</code></a> method.</li> 40791cb0ef41Sopenharmony_ci<li><code>autoDestroy</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Whether this stream should automatically call 40801cb0ef41Sopenharmony_ci<code>.destroy()</code> on itself after ending. <strong>Default:</strong> <code>true</code>.</li> 40811cb0ef41Sopenharmony_ci<li><code>signal</code> <a href="globals.html#class-abortsignal" class="type"><AbortSignal></a> A signal representing possible cancellation.</li> 40821cb0ef41Sopenharmony_ci</ul> 40831cb0ef41Sopenharmony_ci</li> 40841cb0ef41Sopenharmony_ci</ul> 40851cb0ef41Sopenharmony_ci<!-- eslint-disable no-useless-constructor --> 40861cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 40871cb0ef41Sopenharmony_ci 40881cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyReadable</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Readable</span> { 40891cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">options</span>) { 40901cb0ef41Sopenharmony_ci <span class="hljs-comment">// Calls the stream.Readable(options) constructor.</span> 40911cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>(options); 40921cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 40931cb0ef41Sopenharmony_ci } 40941cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 40951cb0ef41Sopenharmony_ci<p>Or, when using pre-ES6 style constructors:</p> 40961cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 40971cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> util = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:util'</span>); 40981cb0ef41Sopenharmony_ci 40991cb0ef41Sopenharmony_ci<span class="hljs-keyword">function</span> <span class="hljs-title function_">MyReadable</span>(<span class="hljs-params">options</span>) { 41001cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (!(<span class="hljs-variable language_">this</span> <span class="hljs-keyword">instanceof</span> <span class="hljs-title class_">MyReadable</span>)) 41011cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">MyReadable</span>(options); 41021cb0ef41Sopenharmony_ci <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">call</span>(<span class="hljs-variable language_">this</span>, options); 41031cb0ef41Sopenharmony_ci} 41041cb0ef41Sopenharmony_ciutil.<span class="hljs-title function_">inherits</span>(<span class="hljs-title class_">MyReadable</span>, <span class="hljs-title class_">Readable</span>);</code> <button class="copy-button">copy</button></pre> 41051cb0ef41Sopenharmony_ci<p>Or, using the simplified constructor approach:</p> 41061cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 41071cb0ef41Sopenharmony_ci 41081cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myReadable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Readable</span>({ 41091cb0ef41Sopenharmony_ci <span class="hljs-title function_">read</span>(<span class="hljs-params">size</span>) { 41101cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 41111cb0ef41Sopenharmony_ci }, 41121cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 41131cb0ef41Sopenharmony_ci<p>Calling <code>abort</code> on the <code>AbortController</code> corresponding to the passed 41141cb0ef41Sopenharmony_ci<code>AbortSignal</code> will behave the same way as calling <code>.destroy(new AbortError())</code> 41151cb0ef41Sopenharmony_cion the readable created.</p> 41161cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 41171cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 41181cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> read = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Readable</span>({ 41191cb0ef41Sopenharmony_ci <span class="hljs-title function_">read</span>(<span class="hljs-params">size</span>) { 41201cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 41211cb0ef41Sopenharmony_ci }, 41221cb0ef41Sopenharmony_ci <span class="hljs-attr">signal</span>: controller.<span class="hljs-property">signal</span>, 41231cb0ef41Sopenharmony_ci}); 41241cb0ef41Sopenharmony_ci<span class="hljs-comment">// Later, abort the operation closing the stream</span> 41251cb0ef41Sopenharmony_cicontroller.<span class="hljs-title function_">abort</span>();</code> <button class="copy-button">copy</button></pre> 41261cb0ef41Sopenharmony_ci<h5><code>readable._construct(callback)</code><span><a class="mark" href="#readable_constructcallback" id="readable_constructcallback">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_construct_callback"></a></h5> 41271cb0ef41Sopenharmony_ci<div class="api_metadata"> 41281cb0ef41Sopenharmony_ci<span>Added in: v15.0.0</span> 41291cb0ef41Sopenharmony_ci</div> 41301cb0ef41Sopenharmony_ci<ul> 41311cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Call this function (optionally with an error 41321cb0ef41Sopenharmony_ciargument) when the stream has finished initializing.</li> 41331cb0ef41Sopenharmony_ci</ul> 41341cb0ef41Sopenharmony_ci<p>The <code>_construct()</code> method MUST NOT be called directly. It may be implemented 41351cb0ef41Sopenharmony_ciby child classes, and if so, will be called by the internal <code>Readable</code> 41361cb0ef41Sopenharmony_ciclass methods only.</p> 41371cb0ef41Sopenharmony_ci<p>This optional function will be scheduled in the next tick by the stream 41381cb0ef41Sopenharmony_ciconstructor, delaying any <code>_read()</code> and <code>_destroy()</code> calls until <code>callback</code> is 41391cb0ef41Sopenharmony_cicalled. This is useful to initialize state or asynchronously initialize 41401cb0ef41Sopenharmony_ciresources before the stream can be used.</p> 41411cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 41421cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 41431cb0ef41Sopenharmony_ci 41441cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">ReadStream</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Readable</span> { 41451cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">filename</span>) { 41461cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>(); 41471cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">filename</span> = filename; 41481cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">fd</span> = <span class="hljs-literal">null</span>; 41491cb0ef41Sopenharmony_ci } 41501cb0ef41Sopenharmony_ci <span class="hljs-title function_">_construct</span>(<span class="hljs-params">callback</span>) { 41511cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">open</span>(<span class="hljs-variable language_">this</span>.<span class="hljs-property">filename</span>, <span class="hljs-function">(<span class="hljs-params">err, fd</span>) =></span> { 41521cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err) { 41531cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(err); 41541cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 41551cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">fd</span> = fd; 41561cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 41571cb0ef41Sopenharmony_ci } 41581cb0ef41Sopenharmony_ci }); 41591cb0ef41Sopenharmony_ci } 41601cb0ef41Sopenharmony_ci <span class="hljs-title function_">_read</span>(<span class="hljs-params">n</span>) { 41611cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> buf = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">alloc</span>(n); 41621cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">read</span>(<span class="hljs-variable language_">this</span>.<span class="hljs-property">fd</span>, buf, <span class="hljs-number">0</span>, n, <span class="hljs-literal">null</span>, <span class="hljs-function">(<span class="hljs-params">err, bytesRead</span>) =></span> { 41631cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err) { 41641cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">destroy</span>(err); 41651cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 41661cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(bytesRead > <span class="hljs-number">0</span> ? buf.<span class="hljs-title function_">slice</span>(<span class="hljs-number">0</span>, bytesRead) : <span class="hljs-literal">null</span>); 41671cb0ef41Sopenharmony_ci } 41681cb0ef41Sopenharmony_ci }); 41691cb0ef41Sopenharmony_ci } 41701cb0ef41Sopenharmony_ci <span class="hljs-title function_">_destroy</span>(<span class="hljs-params">err, callback</span>) { 41711cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (<span class="hljs-variable language_">this</span>.<span class="hljs-property">fd</span>) { 41721cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">close</span>(<span class="hljs-variable language_">this</span>.<span class="hljs-property">fd</span>, <span class="hljs-function">(<span class="hljs-params">er</span>) =></span> <span class="hljs-title function_">callback</span>(er || err)); 41731cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 41741cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(err); 41751cb0ef41Sopenharmony_ci } 41761cb0ef41Sopenharmony_ci } 41771cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 41781cb0ef41Sopenharmony_ci<h5><code>readable._read(size)</code><span><a class="mark" href="#readable_readsize" id="readable_readsize">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_read_size_1"></a></h5> 41791cb0ef41Sopenharmony_ci<div class="api_metadata"> 41801cb0ef41Sopenharmony_ci<span>Added in: v0.9.4</span> 41811cb0ef41Sopenharmony_ci</div> 41821cb0ef41Sopenharmony_ci<ul> 41831cb0ef41Sopenharmony_ci<li><code>size</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Number of bytes to read asynchronously</li> 41841cb0ef41Sopenharmony_ci</ul> 41851cb0ef41Sopenharmony_ci<p>This function MUST NOT be called by application code directly. It should be 41861cb0ef41Sopenharmony_ciimplemented by child classes, and called by the internal <code>Readable</code> class 41871cb0ef41Sopenharmony_cimethods only.</p> 41881cb0ef41Sopenharmony_ci<p>All <code>Readable</code> stream implementations must provide an implementation of the 41891cb0ef41Sopenharmony_ci<a href="#readable_readsize"><code>readable._read()</code></a> method to fetch data from the underlying resource.</p> 41901cb0ef41Sopenharmony_ci<p>When <a href="#readable_readsize"><code>readable._read()</code></a> is called, if data is available from the resource, 41911cb0ef41Sopenharmony_cithe implementation should begin pushing that data into the read queue using the 41921cb0ef41Sopenharmony_ci<a href="#readablepushchunk-encoding"><code>this.push(dataChunk)</code></a> method. <code>_read()</code> will be called again 41931cb0ef41Sopenharmony_ciafter each call to <a href="#readablepushchunk-encoding"><code>this.push(dataChunk)</code></a> once the stream is 41941cb0ef41Sopenharmony_ciready to accept more data. <code>_read()</code> may continue reading from the resource and 41951cb0ef41Sopenharmony_cipushing data until <code>readable.push()</code> returns <code>false</code>. Only when <code>_read()</code> is 41961cb0ef41Sopenharmony_cicalled again after it has stopped should it resume pushing additional data into 41971cb0ef41Sopenharmony_cithe queue.</p> 41981cb0ef41Sopenharmony_ci<p>Once the <a href="#readable_readsize"><code>readable._read()</code></a> method has been called, it will not be called 41991cb0ef41Sopenharmony_ciagain until more data is pushed through the <a href="#readablepushchunk-encoding"><code>readable.push()</code></a> 42001cb0ef41Sopenharmony_cimethod. Empty data such as empty buffers and strings will not cause 42011cb0ef41Sopenharmony_ci<a href="#readable_readsize"><code>readable._read()</code></a> to be called.</p> 42021cb0ef41Sopenharmony_ci<p>The <code>size</code> argument is advisory. For implementations where a "read" is a 42031cb0ef41Sopenharmony_cisingle operation that returns data can use the <code>size</code> argument to determine how 42041cb0ef41Sopenharmony_cimuch data to fetch. Other implementations may ignore this argument and simply 42051cb0ef41Sopenharmony_ciprovide data whenever it becomes available. There is no need to "wait" until 42061cb0ef41Sopenharmony_ci<code>size</code> bytes are available before calling <a href="#readablepushchunk-encoding"><code>stream.push(chunk)</code></a>.</p> 42071cb0ef41Sopenharmony_ci<p>The <a href="#readable_readsize"><code>readable._read()</code></a> method is prefixed with an underscore because it is 42081cb0ef41Sopenharmony_ciinternal to the class that defines it, and should never be called directly by 42091cb0ef41Sopenharmony_ciuser programs.</p> 42101cb0ef41Sopenharmony_ci<h5><code>readable._destroy(err, callback)</code><span><a class="mark" href="#readable_destroyerr-callback" id="readable_destroyerr-callback">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_destroy_err_callback"></a></h5> 42111cb0ef41Sopenharmony_ci<div class="api_metadata"> 42121cb0ef41Sopenharmony_ci<span>Added in: v8.0.0</span> 42131cb0ef41Sopenharmony_ci</div> 42141cb0ef41Sopenharmony_ci<ul> 42151cb0ef41Sopenharmony_ci<li><code>err</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" class="type"><Error></a> A possible error.</li> 42161cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A callback function that takes an optional error 42171cb0ef41Sopenharmony_ciargument.</li> 42181cb0ef41Sopenharmony_ci</ul> 42191cb0ef41Sopenharmony_ci<p>The <code>_destroy()</code> method is called by <a href="#readabledestroyerror"><code>readable.destroy()</code></a>. 42201cb0ef41Sopenharmony_ciIt can be overridden by child classes but it <strong>must not</strong> be called directly.</p> 42211cb0ef41Sopenharmony_ci<h5><code>readable.push(chunk[, encoding])</code><span><a class="mark" href="#readablepushchunk-encoding" id="readablepushchunk-encoding">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_push_chunk_encoding"></a></h5> 42221cb0ef41Sopenharmony_ci<div class="api_metadata"> 42231cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 42241cb0ef41Sopenharmony_ci<table> 42251cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 42261cb0ef41Sopenharmony_ci<tr><td>v8.0.0</td> 42271cb0ef41Sopenharmony_ci<td><p>The <code>chunk</code> argument can now be a <code>Uint8Array</code> instance.</p></td></tr> 42281cb0ef41Sopenharmony_ci</tbody></table> 42291cb0ef41Sopenharmony_ci</details> 42301cb0ef41Sopenharmony_ci</div> 42311cb0ef41Sopenharmony_ci<ul> 42321cb0ef41Sopenharmony_ci<li><code>chunk</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array" class="type"><Uint8Array></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type" class="type"><null></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> Chunk of data to push into the 42331cb0ef41Sopenharmony_ciread queue. For streams not operating in object mode, <code>chunk</code> must be a 42341cb0ef41Sopenharmony_cistring, <code>Buffer</code> or <code>Uint8Array</code>. For object mode streams, <code>chunk</code> may be 42351cb0ef41Sopenharmony_ciany JavaScript value.</li> 42361cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> Encoding of string chunks. Must be a valid 42371cb0ef41Sopenharmony_ci<code>Buffer</code> encoding, such as <code>'utf8'</code> or <code>'ascii'</code>.</li> 42381cb0ef41Sopenharmony_ci<li>Returns: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> <code>true</code> if additional chunks of data may continue to be 42391cb0ef41Sopenharmony_cipushed; <code>false</code> otherwise.</li> 42401cb0ef41Sopenharmony_ci</ul> 42411cb0ef41Sopenharmony_ci<p>When <code>chunk</code> is a <code>Buffer</code>, <code>Uint8Array</code>, or <code>string</code>, the <code>chunk</code> of data will 42421cb0ef41Sopenharmony_cibe added to the internal queue for users of the stream to consume. 42431cb0ef41Sopenharmony_ciPassing <code>chunk</code> as <code>null</code> signals the end of the stream (EOF), after which no 42441cb0ef41Sopenharmony_cimore data can be written.</p> 42451cb0ef41Sopenharmony_ci<p>When the <code>Readable</code> is operating in paused mode, the data added with 42461cb0ef41Sopenharmony_ci<code>readable.push()</code> can be read out by calling the 42471cb0ef41Sopenharmony_ci<a href="#readablereadsize"><code>readable.read()</code></a> method when the <a href="#event-readable"><code>'readable'</code></a> event is 42481cb0ef41Sopenharmony_ciemitted.</p> 42491cb0ef41Sopenharmony_ci<p>When the <code>Readable</code> is operating in flowing mode, the data added with 42501cb0ef41Sopenharmony_ci<code>readable.push()</code> will be delivered by emitting a <code>'data'</code> event.</p> 42511cb0ef41Sopenharmony_ci<p>The <code>readable.push()</code> method is designed to be as flexible as possible. For 42521cb0ef41Sopenharmony_ciexample, when wrapping a lower-level source that provides some form of 42531cb0ef41Sopenharmony_cipause/resume mechanism, and a data callback, the low-level source can be wrapped 42541cb0ef41Sopenharmony_ciby the custom <code>Readable</code> instance:</p> 42551cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// `_source` is an object with readStop() and readStart() methods,</span> 42561cb0ef41Sopenharmony_ci<span class="hljs-comment">// and an `ondata` member that gets called when it has data, and</span> 42571cb0ef41Sopenharmony_ci<span class="hljs-comment">// an `onend` member that gets called when the data is over.</span> 42581cb0ef41Sopenharmony_ci 42591cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">SourceWrapper</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Readable</span> { 42601cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">options</span>) { 42611cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>(options); 42621cb0ef41Sopenharmony_ci 42631cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">_source</span> = <span class="hljs-title function_">getLowLevelSourceObject</span>(); 42641cb0ef41Sopenharmony_ci 42651cb0ef41Sopenharmony_ci <span class="hljs-comment">// Every time there's data, push it into the internal buffer.</span> 42661cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">_source</span>.<span class="hljs-property">ondata</span> = <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> { 42671cb0ef41Sopenharmony_ci <span class="hljs-comment">// If push() returns false, then stop reading from source.</span> 42681cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (!<span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(chunk)) 42691cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">_source</span>.<span class="hljs-title function_">readStop</span>(); 42701cb0ef41Sopenharmony_ci }; 42711cb0ef41Sopenharmony_ci 42721cb0ef41Sopenharmony_ci <span class="hljs-comment">// When the source ends, push the EOF-signaling `null` chunk.</span> 42731cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">_source</span>.<span class="hljs-property">onend</span> = <span class="hljs-function">() =></span> { 42741cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(<span class="hljs-literal">null</span>); 42751cb0ef41Sopenharmony_ci }; 42761cb0ef41Sopenharmony_ci } 42771cb0ef41Sopenharmony_ci <span class="hljs-comment">// _read() will be called when the stream wants to pull more data in.</span> 42781cb0ef41Sopenharmony_ci <span class="hljs-comment">// The advisory size argument is ignored in this case.</span> 42791cb0ef41Sopenharmony_ci <span class="hljs-title function_">_read</span>(<span class="hljs-params">size</span>) { 42801cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">_source</span>.<span class="hljs-title function_">readStart</span>(); 42811cb0ef41Sopenharmony_ci } 42821cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 42831cb0ef41Sopenharmony_ci<p>The <code>readable.push()</code> method is used to push the content 42841cb0ef41Sopenharmony_ciinto the internal buffer. It can be driven by the <a href="#readable_readsize"><code>readable._read()</code></a> method.</p> 42851cb0ef41Sopenharmony_ci<p>For streams not operating in object mode, if the <code>chunk</code> parameter of 42861cb0ef41Sopenharmony_ci<code>readable.push()</code> is <code>undefined</code>, it will be treated as empty string or 42871cb0ef41Sopenharmony_cibuffer. See <a href="#readablepush"><code>readable.push('')</code></a> for more information.</p> 42881cb0ef41Sopenharmony_ci<h5>Errors while reading<span><a class="mark" href="#errors-while-reading" id="errors-while-reading">#</a></span><a aria-hidden="true" class="legacy" id="stream_errors_while_reading"></a></h5> 42891cb0ef41Sopenharmony_ci<p>Errors occurring during processing of the <a href="#readable_readsize"><code>readable._read()</code></a> must be 42901cb0ef41Sopenharmony_cipropagated through the <a href="#readable_destroyerr-callback"><code>readable.destroy(err)</code></a> method. 42911cb0ef41Sopenharmony_ciThrowing an <code>Error</code> from within <a href="#readable_readsize"><code>readable._read()</code></a> or manually emitting an 42921cb0ef41Sopenharmony_ci<code>'error'</code> event results in undefined behavior.</p> 42931cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 42941cb0ef41Sopenharmony_ci 42951cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myReadable = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Readable</span>({ 42961cb0ef41Sopenharmony_ci <span class="hljs-title function_">read</span>(<span class="hljs-params">size</span>) { 42971cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> err = <span class="hljs-title function_">checkSomeErrorCondition</span>(); 42981cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err) { 42991cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">destroy</span>(err); 43001cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 43011cb0ef41Sopenharmony_ci <span class="hljs-comment">// Do some work.</span> 43021cb0ef41Sopenharmony_ci } 43031cb0ef41Sopenharmony_ci }, 43041cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 43051cb0ef41Sopenharmony_ci<h5>An example counting stream<span><a class="mark" href="#an-example-counting-stream" id="an-example-counting-stream">#</a></span><a aria-hidden="true" class="legacy" id="stream_an_example_counting_stream"></a></h5> 43061cb0ef41Sopenharmony_ci 43071cb0ef41Sopenharmony_ci<p>The following is a basic example of a <code>Readable</code> stream that emits the numerals 43081cb0ef41Sopenharmony_cifrom 1 to 1,000,000 in ascending order, and then ends.</p> 43091cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 43101cb0ef41Sopenharmony_ci 43111cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">Counter</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Readable</span> { 43121cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">opt</span>) { 43131cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>(opt); 43141cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">_max</span> = <span class="hljs-number">1000000</span>; 43151cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">_index</span> = <span class="hljs-number">1</span>; 43161cb0ef41Sopenharmony_ci } 43171cb0ef41Sopenharmony_ci 43181cb0ef41Sopenharmony_ci <span class="hljs-title function_">_read</span>(<span class="hljs-params"></span>) { 43191cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> i = <span class="hljs-variable language_">this</span>.<span class="hljs-property">_index</span>++; 43201cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (i > <span class="hljs-variable language_">this</span>.<span class="hljs-property">_max</span>) 43211cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(<span class="hljs-literal">null</span>); 43221cb0ef41Sopenharmony_ci <span class="hljs-keyword">else</span> { 43231cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> str = <span class="hljs-title class_">String</span>(i); 43241cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> buf = <span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(str, <span class="hljs-string">'ascii'</span>); 43251cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(buf); 43261cb0ef41Sopenharmony_ci } 43271cb0ef41Sopenharmony_ci } 43281cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 43291cb0ef41Sopenharmony_ci<h4>Implementing a duplex stream<span><a class="mark" href="#implementing-a-duplex-stream" id="implementing-a-duplex-stream">#</a></span><a aria-hidden="true" class="legacy" id="stream_implementing_a_duplex_stream"></a></h4> 43301cb0ef41Sopenharmony_ci<p>A <a href="#class-streamduplex"><code>Duplex</code></a> stream is one that implements both <a href="#class-streamreadable"><code>Readable</code></a> and 43311cb0ef41Sopenharmony_ci<a href="#class-streamwritable"><code>Writable</code></a>, such as a TCP socket connection.</p> 43321cb0ef41Sopenharmony_ci<p>Because JavaScript does not have support for multiple inheritance, the 43331cb0ef41Sopenharmony_ci<code>stream.Duplex</code> class is extended to implement a <a href="#class-streamduplex"><code>Duplex</code></a> stream (as opposed 43341cb0ef41Sopenharmony_cito extending the <code>stream.Readable</code> <em>and</em> <code>stream.Writable</code> classes).</p> 43351cb0ef41Sopenharmony_ci<p>The <code>stream.Duplex</code> class prototypically inherits from <code>stream.Readable</code> and 43361cb0ef41Sopenharmony_ciparasitically from <code>stream.Writable</code>, but <code>instanceof</code> will work properly for 43371cb0ef41Sopenharmony_ciboth base classes due to overriding <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance"><code>Symbol.hasInstance</code></a> on 43381cb0ef41Sopenharmony_ci<code>stream.Writable</code>.</p> 43391cb0ef41Sopenharmony_ci<p>Custom <code>Duplex</code> streams <em>must</em> call the <code>new stream.Duplex([options])</code> 43401cb0ef41Sopenharmony_ciconstructor and implement <em>both</em> the <a href="#readable_readsize"><code>readable._read()</code></a> and 43411cb0ef41Sopenharmony_ci<code>writable._write()</code> methods.</p> 43421cb0ef41Sopenharmony_ci<h5><code>new stream.Duplex(options)</code><span><a class="mark" href="#new-streamduplexoptions" id="new-streamduplexoptions">#</a></span><a aria-hidden="true" class="legacy" id="stream_new_stream_duplex_options"></a></h5> 43431cb0ef41Sopenharmony_ci<div class="api_metadata"> 43441cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 43451cb0ef41Sopenharmony_ci<table> 43461cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 43471cb0ef41Sopenharmony_ci<tr><td>v8.4.0</td> 43481cb0ef41Sopenharmony_ci<td><p>The <code>readableHighWaterMark</code> and <code>writableHighWaterMark</code> options are supported now.</p></td></tr> 43491cb0ef41Sopenharmony_ci</tbody></table> 43501cb0ef41Sopenharmony_ci</details> 43511cb0ef41Sopenharmony_ci</div> 43521cb0ef41Sopenharmony_ci<ul> 43531cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Passed to both <code>Writable</code> and <code>Readable</code> 43541cb0ef41Sopenharmony_ciconstructors. Also has the following fields: 43551cb0ef41Sopenharmony_ci<ul> 43561cb0ef41Sopenharmony_ci<li><code>allowHalfOpen</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> If set to <code>false</code>, then the stream will 43571cb0ef41Sopenharmony_ciautomatically end the writable side when the readable side ends. 43581cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>true</code>.</li> 43591cb0ef41Sopenharmony_ci<li><code>readable</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Sets whether the <code>Duplex</code> should be readable. 43601cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>true</code>.</li> 43611cb0ef41Sopenharmony_ci<li><code>writable</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Sets whether the <code>Duplex</code> should be writable. 43621cb0ef41Sopenharmony_ci<strong>Default:</strong> <code>true</code>.</li> 43631cb0ef41Sopenharmony_ci<li><code>readableObjectMode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Sets <code>objectMode</code> for readable side of the 43641cb0ef41Sopenharmony_cistream. Has no effect if <code>objectMode</code> is <code>true</code>. <strong>Default:</strong> <code>false</code>.</li> 43651cb0ef41Sopenharmony_ci<li><code>writableObjectMode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type"><boolean></a> Sets <code>objectMode</code> for writable side of the 43661cb0ef41Sopenharmony_cistream. Has no effect if <code>objectMode</code> is <code>true</code>. <strong>Default:</strong> <code>false</code>.</li> 43671cb0ef41Sopenharmony_ci<li><code>readableHighWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets <code>highWaterMark</code> for the readable side 43681cb0ef41Sopenharmony_ciof the stream. Has no effect if <code>highWaterMark</code> is provided.</li> 43691cb0ef41Sopenharmony_ci<li><code>writableHighWaterMark</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type" class="type"><number></a> Sets <code>highWaterMark</code> for the writable side 43701cb0ef41Sopenharmony_ciof the stream. Has no effect if <code>highWaterMark</code> is provided.</li> 43711cb0ef41Sopenharmony_ci</ul> 43721cb0ef41Sopenharmony_ci</li> 43731cb0ef41Sopenharmony_ci</ul> 43741cb0ef41Sopenharmony_ci<!-- eslint-disable no-useless-constructor --> 43751cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Duplex</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 43761cb0ef41Sopenharmony_ci 43771cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyDuplex</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Duplex</span> { 43781cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">options</span>) { 43791cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>(options); 43801cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 43811cb0ef41Sopenharmony_ci } 43821cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 43831cb0ef41Sopenharmony_ci<p>Or, when using pre-ES6 style constructors:</p> 43841cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Duplex</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 43851cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> util = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:util'</span>); 43861cb0ef41Sopenharmony_ci 43871cb0ef41Sopenharmony_ci<span class="hljs-keyword">function</span> <span class="hljs-title function_">MyDuplex</span>(<span class="hljs-params">options</span>) { 43881cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (!(<span class="hljs-variable language_">this</span> <span class="hljs-keyword">instanceof</span> <span class="hljs-title class_">MyDuplex</span>)) 43891cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">MyDuplex</span>(options); 43901cb0ef41Sopenharmony_ci <span class="hljs-title class_">Duplex</span>.<span class="hljs-title function_">call</span>(<span class="hljs-variable language_">this</span>, options); 43911cb0ef41Sopenharmony_ci} 43921cb0ef41Sopenharmony_ciutil.<span class="hljs-title function_">inherits</span>(<span class="hljs-title class_">MyDuplex</span>, <span class="hljs-title class_">Duplex</span>);</code> <button class="copy-button">copy</button></pre> 43931cb0ef41Sopenharmony_ci<p>Or, using the simplified constructor approach:</p> 43941cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Duplex</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 43951cb0ef41Sopenharmony_ci 43961cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myDuplex = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Duplex</span>({ 43971cb0ef41Sopenharmony_ci <span class="hljs-title function_">read</span>(<span class="hljs-params">size</span>) { 43981cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 43991cb0ef41Sopenharmony_ci }, 44001cb0ef41Sopenharmony_ci <span class="hljs-title function_">write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 44011cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 44021cb0ef41Sopenharmony_ci }, 44031cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 44041cb0ef41Sopenharmony_ci<p>When using pipeline:</p> 44051cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Transform</span>, pipeline } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 44061cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 44071cb0ef41Sopenharmony_ci 44081cb0ef41Sopenharmony_ci<span class="hljs-title function_">pipeline</span>( 44091cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createReadStream</span>(<span class="hljs-string">'object.json'</span>) 44101cb0ef41Sopenharmony_ci .<span class="hljs-title function_">setEncoding</span>(<span class="hljs-string">'utf8'</span>), 44111cb0ef41Sopenharmony_ci <span class="hljs-keyword">new</span> <span class="hljs-title class_">Transform</span>({ 44121cb0ef41Sopenharmony_ci <span class="hljs-attr">decodeStrings</span>: <span class="hljs-literal">false</span>, <span class="hljs-comment">// Accept string input rather than Buffers</span> 44131cb0ef41Sopenharmony_ci <span class="hljs-title function_">construct</span>(<span class="hljs-params">callback</span>) { 44141cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">data</span> = <span class="hljs-string">''</span>; 44151cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 44161cb0ef41Sopenharmony_ci }, 44171cb0ef41Sopenharmony_ci <span class="hljs-title function_">transform</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 44181cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-property">data</span> += chunk; 44191cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 44201cb0ef41Sopenharmony_ci }, 44211cb0ef41Sopenharmony_ci <span class="hljs-title function_">flush</span>(<span class="hljs-params">callback</span>) { 44221cb0ef41Sopenharmony_ci <span class="hljs-keyword">try</span> { 44231cb0ef41Sopenharmony_ci <span class="hljs-comment">// Make sure is valid json.</span> 44241cb0ef41Sopenharmony_ci <span class="hljs-title class_">JSON</span>.<span class="hljs-title function_">parse</span>(<span class="hljs-variable language_">this</span>.<span class="hljs-property">data</span>); 44251cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(<span class="hljs-variable language_">this</span>.<span class="hljs-property">data</span>); 44261cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 44271cb0ef41Sopenharmony_ci } <span class="hljs-keyword">catch</span> (err) { 44281cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(err); 44291cb0ef41Sopenharmony_ci } 44301cb0ef41Sopenharmony_ci }, 44311cb0ef41Sopenharmony_ci }), 44321cb0ef41Sopenharmony_ci fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'valid-object.json'</span>), 44331cb0ef41Sopenharmony_ci <span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 44341cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err) { 44351cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(<span class="hljs-string">'failed'</span>, err); 44361cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 44371cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'completed'</span>); 44381cb0ef41Sopenharmony_ci } 44391cb0ef41Sopenharmony_ci }, 44401cb0ef41Sopenharmony_ci);</code> <button class="copy-button">copy</button></pre> 44411cb0ef41Sopenharmony_ci<h5>An example duplex stream<span><a class="mark" href="#an-example-duplex-stream" id="an-example-duplex-stream">#</a></span><a aria-hidden="true" class="legacy" id="stream_an_example_duplex_stream"></a></h5> 44421cb0ef41Sopenharmony_ci<p>The following illustrates a simple example of a <code>Duplex</code> stream that wraps a 44431cb0ef41Sopenharmony_cihypothetical lower-level source object to which data can be written, and 44441cb0ef41Sopenharmony_cifrom which data can be read, albeit using an API that is not compatible with 44451cb0ef41Sopenharmony_ciNode.js streams. 44461cb0ef41Sopenharmony_ciThe following illustrates a simple example of a <code>Duplex</code> stream that buffers 44471cb0ef41Sopenharmony_ciincoming written data via the <a href="#class-streamwritable"><code>Writable</code></a> interface that is read back out 44481cb0ef41Sopenharmony_civia the <a href="#class-streamreadable"><code>Readable</code></a> interface.</p> 44491cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Duplex</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 44501cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> kSource = <span class="hljs-title class_">Symbol</span>(<span class="hljs-string">'source'</span>); 44511cb0ef41Sopenharmony_ci 44521cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyDuplex</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Duplex</span> { 44531cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">source, options</span>) { 44541cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>(options); 44551cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>[kSource] = source; 44561cb0ef41Sopenharmony_ci } 44571cb0ef41Sopenharmony_ci 44581cb0ef41Sopenharmony_ci <span class="hljs-title function_">_write</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 44591cb0ef41Sopenharmony_ci <span class="hljs-comment">// The underlying source only deals with strings.</span> 44601cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (<span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">isBuffer</span>(chunk)) 44611cb0ef41Sopenharmony_ci chunk = chunk.<span class="hljs-title function_">toString</span>(); 44621cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>[kSource].<span class="hljs-title function_">writeSomeData</span>(chunk); 44631cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 44641cb0ef41Sopenharmony_ci } 44651cb0ef41Sopenharmony_ci 44661cb0ef41Sopenharmony_ci <span class="hljs-title function_">_read</span>(<span class="hljs-params">size</span>) { 44671cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>[kSource].<span class="hljs-title function_">fetchSomeData</span>(size, <span class="hljs-function">(<span class="hljs-params">data, encoding</span>) =></span> { 44681cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(<span class="hljs-title class_">Buffer</span>.<span class="hljs-title function_">from</span>(data, encoding)); 44691cb0ef41Sopenharmony_ci }); 44701cb0ef41Sopenharmony_ci } 44711cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 44721cb0ef41Sopenharmony_ci<p>The most important aspect of a <code>Duplex</code> stream is that the <code>Readable</code> and 44731cb0ef41Sopenharmony_ci<code>Writable</code> sides operate independently of one another despite co-existing within 44741cb0ef41Sopenharmony_cia single object instance.</p> 44751cb0ef41Sopenharmony_ci<h5>Object mode duplex streams<span><a class="mark" href="#object-mode-duplex-streams" id="object-mode-duplex-streams">#</a></span><a aria-hidden="true" class="legacy" id="stream_object_mode_duplex_streams"></a></h5> 44761cb0ef41Sopenharmony_ci<p>For <code>Duplex</code> streams, <code>objectMode</code> can be set exclusively for either the 44771cb0ef41Sopenharmony_ci<code>Readable</code> or <code>Writable</code> side using the <code>readableObjectMode</code> and 44781cb0ef41Sopenharmony_ci<code>writableObjectMode</code> options respectively.</p> 44791cb0ef41Sopenharmony_ci<p>In the following example, for instance, a new <code>Transform</code> stream (which is a 44801cb0ef41Sopenharmony_citype of <a href="#class-streamduplex"><code>Duplex</code></a> stream) is created that has an object mode <code>Writable</code> side 44811cb0ef41Sopenharmony_cithat accepts JavaScript numbers that are converted to hexadecimal strings on 44821cb0ef41Sopenharmony_cithe <code>Readable</code> side.</p> 44831cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Transform</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 44841cb0ef41Sopenharmony_ci 44851cb0ef41Sopenharmony_ci<span class="hljs-comment">// All Transform streams are also Duplex Streams.</span> 44861cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myTransform = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Transform</span>({ 44871cb0ef41Sopenharmony_ci <span class="hljs-attr">writableObjectMode</span>: <span class="hljs-literal">true</span>, 44881cb0ef41Sopenharmony_ci 44891cb0ef41Sopenharmony_ci <span class="hljs-title function_">transform</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 44901cb0ef41Sopenharmony_ci <span class="hljs-comment">// Coerce the chunk to a number if necessary.</span> 44911cb0ef41Sopenharmony_ci chunk |= <span class="hljs-number">0</span>; 44921cb0ef41Sopenharmony_ci 44931cb0ef41Sopenharmony_ci <span class="hljs-comment">// Transform the chunk into something else.</span> 44941cb0ef41Sopenharmony_ci <span class="hljs-keyword">const</span> data = chunk.<span class="hljs-title function_">toString</span>(<span class="hljs-number">16</span>); 44951cb0ef41Sopenharmony_ci 44961cb0ef41Sopenharmony_ci <span class="hljs-comment">// Push the data onto the readable queue.</span> 44971cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, <span class="hljs-string">'0'</span>.<span class="hljs-title function_">repeat</span>(data.<span class="hljs-property">length</span> % <span class="hljs-number">2</span>) + data); 44981cb0ef41Sopenharmony_ci }, 44991cb0ef41Sopenharmony_ci}); 45001cb0ef41Sopenharmony_ci 45011cb0ef41Sopenharmony_cimyTransform.<span class="hljs-title function_">setEncoding</span>(<span class="hljs-string">'ascii'</span>); 45021cb0ef41Sopenharmony_cimyTransform.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk)); 45031cb0ef41Sopenharmony_ci 45041cb0ef41Sopenharmony_cimyTransform.<span class="hljs-title function_">write</span>(<span class="hljs-number">1</span>); 45051cb0ef41Sopenharmony_ci<span class="hljs-comment">// Prints: 01</span> 45061cb0ef41Sopenharmony_cimyTransform.<span class="hljs-title function_">write</span>(<span class="hljs-number">10</span>); 45071cb0ef41Sopenharmony_ci<span class="hljs-comment">// Prints: 0a</span> 45081cb0ef41Sopenharmony_cimyTransform.<span class="hljs-title function_">write</span>(<span class="hljs-number">100</span>); 45091cb0ef41Sopenharmony_ci<span class="hljs-comment">// Prints: 64</span></code> <button class="copy-button">copy</button></pre> 45101cb0ef41Sopenharmony_ci<h4>Implementing a transform stream<span><a class="mark" href="#implementing-a-transform-stream" id="implementing-a-transform-stream">#</a></span><a aria-hidden="true" class="legacy" id="stream_implementing_a_transform_stream"></a></h4> 45111cb0ef41Sopenharmony_ci<p>A <a href="#class-streamtransform"><code>Transform</code></a> stream is a <a href="#class-streamduplex"><code>Duplex</code></a> stream where the output is computed 45121cb0ef41Sopenharmony_ciin some way from the input. Examples include <a href="zlib.html">zlib</a> streams or <a href="crypto.html">crypto</a> 45131cb0ef41Sopenharmony_cistreams that compress, encrypt, or decrypt data.</p> 45141cb0ef41Sopenharmony_ci<p>There is no requirement that the output be the same size as the input, the same 45151cb0ef41Sopenharmony_cinumber of chunks, or arrive at the same time. For example, a <code>Hash</code> stream will 45161cb0ef41Sopenharmony_cionly ever have a single chunk of output which is provided when the input is 45171cb0ef41Sopenharmony_ciended. A <code>zlib</code> stream will produce output that is either much smaller or much 45181cb0ef41Sopenharmony_cilarger than its input.</p> 45191cb0ef41Sopenharmony_ci<p>The <code>stream.Transform</code> class is extended to implement a <a href="#class-streamtransform"><code>Transform</code></a> stream.</p> 45201cb0ef41Sopenharmony_ci<p>The <code>stream.Transform</code> class prototypically inherits from <code>stream.Duplex</code> and 45211cb0ef41Sopenharmony_ciimplements its own versions of the <code>writable._write()</code> and 45221cb0ef41Sopenharmony_ci<a href="#readable_readsize"><code>readable._read()</code></a> methods. Custom <code>Transform</code> implementations <em>must</em> 45231cb0ef41Sopenharmony_ciimplement the <a href="#transform_transformchunk-encoding-callback"><code>transform._transform()</code></a> method and <em>may</em> 45241cb0ef41Sopenharmony_cialso implement the <a href="#transform_flushcallback"><code>transform._flush()</code></a> method.</p> 45251cb0ef41Sopenharmony_ci<p>Care must be taken when using <code>Transform</code> streams in that data written to the 45261cb0ef41Sopenharmony_cistream can cause the <code>Writable</code> side of the stream to become paused if the 45271cb0ef41Sopenharmony_cioutput on the <code>Readable</code> side is not consumed.</p> 45281cb0ef41Sopenharmony_ci<h5><code>new stream.Transform([options])</code><span><a class="mark" href="#new-streamtransformoptions" id="new-streamtransformoptions">#</a></span><a aria-hidden="true" class="legacy" id="stream_new_stream_transform_options"></a></h5> 45291cb0ef41Sopenharmony_ci<ul> 45301cb0ef41Sopenharmony_ci<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> Passed to both <code>Writable</code> and <code>Readable</code> 45311cb0ef41Sopenharmony_ciconstructors. Also has the following fields: 45321cb0ef41Sopenharmony_ci<ul> 45331cb0ef41Sopenharmony_ci<li><code>transform</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Implementation for the 45341cb0ef41Sopenharmony_ci<a href="#transform_transformchunk-encoding-callback"><code>stream._transform()</code></a> method.</li> 45351cb0ef41Sopenharmony_ci<li><code>flush</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> Implementation for the <a href="#transform_flushcallback"><code>stream._flush()</code></a> 45361cb0ef41Sopenharmony_cimethod.</li> 45371cb0ef41Sopenharmony_ci</ul> 45381cb0ef41Sopenharmony_ci</li> 45391cb0ef41Sopenharmony_ci</ul> 45401cb0ef41Sopenharmony_ci<!-- eslint-disable no-useless-constructor --> 45411cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Transform</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 45421cb0ef41Sopenharmony_ci 45431cb0ef41Sopenharmony_ci<span class="hljs-keyword">class</span> <span class="hljs-title class_">MyTransform</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_ inherited__">Transform</span> { 45441cb0ef41Sopenharmony_ci <span class="hljs-title function_">constructor</span>(<span class="hljs-params">options</span>) { 45451cb0ef41Sopenharmony_ci <span class="hljs-variable language_">super</span>(options); 45461cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 45471cb0ef41Sopenharmony_ci } 45481cb0ef41Sopenharmony_ci}</code> <button class="copy-button">copy</button></pre> 45491cb0ef41Sopenharmony_ci<p>Or, when using pre-ES6 style constructors:</p> 45501cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Transform</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 45511cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> util = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:util'</span>); 45521cb0ef41Sopenharmony_ci 45531cb0ef41Sopenharmony_ci<span class="hljs-keyword">function</span> <span class="hljs-title function_">MyTransform</span>(<span class="hljs-params">options</span>) { 45541cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (!(<span class="hljs-variable language_">this</span> <span class="hljs-keyword">instanceof</span> <span class="hljs-title class_">MyTransform</span>)) 45551cb0ef41Sopenharmony_ci <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">MyTransform</span>(options); 45561cb0ef41Sopenharmony_ci <span class="hljs-title class_">Transform</span>.<span class="hljs-title function_">call</span>(<span class="hljs-variable language_">this</span>, options); 45571cb0ef41Sopenharmony_ci} 45581cb0ef41Sopenharmony_ciutil.<span class="hljs-title function_">inherits</span>(<span class="hljs-title class_">MyTransform</span>, <span class="hljs-title class_">Transform</span>);</code> <button class="copy-button">copy</button></pre> 45591cb0ef41Sopenharmony_ci<p>Or, using the simplified constructor approach:</p> 45601cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Transform</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 45611cb0ef41Sopenharmony_ci 45621cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> myTransform = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Transform</span>({ 45631cb0ef41Sopenharmony_ci <span class="hljs-title function_">transform</span>(<span class="hljs-params">chunk, encoding, callback</span>) { 45641cb0ef41Sopenharmony_ci <span class="hljs-comment">// ...</span> 45651cb0ef41Sopenharmony_ci }, 45661cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 45671cb0ef41Sopenharmony_ci<h5>Event: <code>'end'</code><span><a class="mark" href="#event-end_1" id="event-end_1">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_end_1"></a></h5> 45681cb0ef41Sopenharmony_ci<p>The <a href="#event-end"><code>'end'</code></a> event is from the <code>stream.Readable</code> class. The <code>'end'</code> event is 45691cb0ef41Sopenharmony_ciemitted after all data has been output, which occurs after the callback in 45701cb0ef41Sopenharmony_ci<a href="#transform_flushcallback"><code>transform._flush()</code></a> has been called. In the case of an error, 45711cb0ef41Sopenharmony_ci<code>'end'</code> should not be emitted.</p> 45721cb0ef41Sopenharmony_ci<h5>Event: <code>'finish'</code><span><a class="mark" href="#event-finish_1" id="event-finish_1">#</a></span><a aria-hidden="true" class="legacy" id="stream_event_finish_1"></a></h5> 45731cb0ef41Sopenharmony_ci<p>The <a href="#event-finish"><code>'finish'</code></a> event is from the <code>stream.Writable</code> class. The <code>'finish'</code> 45741cb0ef41Sopenharmony_cievent is emitted after <a href="#writableendchunk-encoding-callback"><code>stream.end()</code></a> is called and all chunks 45751cb0ef41Sopenharmony_cihave been processed by <a href="#transform_transformchunk-encoding-callback"><code>stream._transform()</code></a>. In the case 45761cb0ef41Sopenharmony_ciof an error, <code>'finish'</code> should not be emitted.</p> 45771cb0ef41Sopenharmony_ci<h5><code>transform._flush(callback)</code><span><a class="mark" href="#transform_flushcallback" id="transform_flushcallback">#</a></span><a aria-hidden="true" class="legacy" id="stream_transform_flush_callback"></a></h5> 45781cb0ef41Sopenharmony_ci<ul> 45791cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A callback function (optionally with an error 45801cb0ef41Sopenharmony_ciargument and data) to be called when remaining data has been flushed.</li> 45811cb0ef41Sopenharmony_ci</ul> 45821cb0ef41Sopenharmony_ci<p>This function MUST NOT be called by application code directly. It should be 45831cb0ef41Sopenharmony_ciimplemented by child classes, and called by the internal <code>Readable</code> class 45841cb0ef41Sopenharmony_cimethods only.</p> 45851cb0ef41Sopenharmony_ci<p>In some cases, a transform operation may need to emit an additional bit of 45861cb0ef41Sopenharmony_cidata at the end of the stream. For example, a <code>zlib</code> compression stream will 45871cb0ef41Sopenharmony_cistore an amount of internal state used to optimally compress the output. When 45881cb0ef41Sopenharmony_cithe stream ends, however, that additional data needs to be flushed so that the 45891cb0ef41Sopenharmony_cicompressed data will be complete.</p> 45901cb0ef41Sopenharmony_ci<p>Custom <a href="#class-streamtransform"><code>Transform</code></a> implementations <em>may</em> implement the <code>transform._flush()</code> 45911cb0ef41Sopenharmony_cimethod. This will be called when there is no more written data to be consumed, 45921cb0ef41Sopenharmony_cibut before the <a href="#event-end"><code>'end'</code></a> event is emitted signaling the end of the 45931cb0ef41Sopenharmony_ci<a href="#class-streamreadable"><code>Readable</code></a> stream.</p> 45941cb0ef41Sopenharmony_ci<p>Within the <code>transform._flush()</code> implementation, the <code>transform.push()</code> method 45951cb0ef41Sopenharmony_cimay be called zero or more times, as appropriate. The <code>callback</code> function must 45961cb0ef41Sopenharmony_cibe called when the flush operation is complete.</p> 45971cb0ef41Sopenharmony_ci<p>The <code>transform._flush()</code> method is prefixed with an underscore because it is 45981cb0ef41Sopenharmony_ciinternal to the class that defines it, and should never be called directly by 45991cb0ef41Sopenharmony_ciuser programs.</p> 46001cb0ef41Sopenharmony_ci<h5><code>transform._transform(chunk, encoding, callback)</code><span><a class="mark" href="#transform_transformchunk-encoding-callback" id="transform_transformchunk-encoding-callback">#</a></span><a aria-hidden="true" class="legacy" id="stream_transform_transform_chunk_encoding_callback"></a></h5> 46011cb0ef41Sopenharmony_ci<ul> 46021cb0ef41Sopenharmony_ci<li><code>chunk</code> <a href="buffer.html#class-buffer" class="type"><Buffer></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types" class="type"><any></a> The <code>Buffer</code> to be transformed, converted from 46031cb0ef41Sopenharmony_cithe <code>string</code> passed to <a href="#writablewritechunk-encoding-callback"><code>stream.write()</code></a>. If the stream's 46041cb0ef41Sopenharmony_ci<code>decodeStrings</code> option is <code>false</code> or the stream is operating in object mode, 46051cb0ef41Sopenharmony_cithe chunk will not be converted & will be whatever was passed to 46061cb0ef41Sopenharmony_ci<a href="#writablewritechunk-encoding-callback"><code>stream.write()</code></a>.</li> 46071cb0ef41Sopenharmony_ci<li><code>encoding</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> If the chunk is a string, then this is the 46081cb0ef41Sopenharmony_ciencoding type. If chunk is a buffer, then this is the special 46091cb0ef41Sopenharmony_civalue <code>'buffer'</code>. Ignore it in that case.</li> 46101cb0ef41Sopenharmony_ci<li><code>callback</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type"><Function></a> A callback function (optionally with an error 46111cb0ef41Sopenharmony_ciargument and data) to be called after the supplied <code>chunk</code> has been 46121cb0ef41Sopenharmony_ciprocessed.</li> 46131cb0ef41Sopenharmony_ci</ul> 46141cb0ef41Sopenharmony_ci<p>This function MUST NOT be called by application code directly. It should be 46151cb0ef41Sopenharmony_ciimplemented by child classes, and called by the internal <code>Readable</code> class 46161cb0ef41Sopenharmony_cimethods only.</p> 46171cb0ef41Sopenharmony_ci<p>All <code>Transform</code> stream implementations must provide a <code>_transform()</code> 46181cb0ef41Sopenharmony_cimethod to accept input and produce output. The <code>transform._transform()</code> 46191cb0ef41Sopenharmony_ciimplementation handles the bytes being written, computes an output, then passes 46201cb0ef41Sopenharmony_cithat output off to the readable portion using the <code>transform.push()</code> method.</p> 46211cb0ef41Sopenharmony_ci<p>The <code>transform.push()</code> method may be called zero or more times to generate 46221cb0ef41Sopenharmony_cioutput from a single input chunk, depending on how much is to be output 46231cb0ef41Sopenharmony_cias a result of the chunk.</p> 46241cb0ef41Sopenharmony_ci<p>It is possible that no output is generated from any given chunk of input data.</p> 46251cb0ef41Sopenharmony_ci<p>The <code>callback</code> function must be called only when the current chunk is completely 46261cb0ef41Sopenharmony_ciconsumed. The first argument passed to the <code>callback</code> must be an <code>Error</code> object 46271cb0ef41Sopenharmony_ciif an error occurred while processing the input or <code>null</code> otherwise. If a second 46281cb0ef41Sopenharmony_ciargument is passed to the <code>callback</code>, it will be forwarded on to the 46291cb0ef41Sopenharmony_ci<code>transform.push()</code> method, but only if the first argument is falsy. In other 46301cb0ef41Sopenharmony_ciwords, the following are equivalent:</p> 46311cb0ef41Sopenharmony_ci<pre><code class="language-js">transform.<span class="hljs-property"><span class="hljs-keyword">prototype</span></span>.<span class="hljs-property">_transform</span> = <span class="hljs-keyword">function</span>(<span class="hljs-params">data, encoding, callback</span>) { 46321cb0ef41Sopenharmony_ci <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">push</span>(data); 46331cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(); 46341cb0ef41Sopenharmony_ci}; 46351cb0ef41Sopenharmony_ci 46361cb0ef41Sopenharmony_citransform.<span class="hljs-property"><span class="hljs-keyword">prototype</span></span>.<span class="hljs-property">_transform</span> = <span class="hljs-keyword">function</span>(<span class="hljs-params">data, encoding, callback</span>) { 46371cb0ef41Sopenharmony_ci <span class="hljs-title function_">callback</span>(<span class="hljs-literal">null</span>, data); 46381cb0ef41Sopenharmony_ci};</code> <button class="copy-button">copy</button></pre> 46391cb0ef41Sopenharmony_ci<p>The <code>transform._transform()</code> method is prefixed with an underscore because it 46401cb0ef41Sopenharmony_ciis internal to the class that defines it, and should never be called directly by 46411cb0ef41Sopenharmony_ciuser programs.</p> 46421cb0ef41Sopenharmony_ci<p><code>transform._transform()</code> is never called in parallel; streams implement a 46431cb0ef41Sopenharmony_ciqueue mechanism, and to receive the next chunk, <code>callback</code> must be 46441cb0ef41Sopenharmony_cicalled, either synchronously or asynchronously.</p> 46451cb0ef41Sopenharmony_ci<h5>Class: <code>stream.PassThrough</code><span><a class="mark" href="#class-streampassthrough" id="class-streampassthrough">#</a></span><a aria-hidden="true" class="legacy" id="stream_class_stream_passthrough"></a></h5> 46461cb0ef41Sopenharmony_ci<p>The <code>stream.PassThrough</code> class is a trivial implementation of a <a href="#class-streamtransform"><code>Transform</code></a> 46471cb0ef41Sopenharmony_cistream that simply passes the input bytes across to the output. Its purpose is 46481cb0ef41Sopenharmony_ciprimarily for examples and testing, but there are some use cases where 46491cb0ef41Sopenharmony_ci<code>stream.PassThrough</code> is useful as a building block for novel sorts of streams.</p> 46501cb0ef41Sopenharmony_ci</section><section><h3>Additional notes<span><a class="mark" href="#additional-notes" id="additional-notes">#</a></span><a aria-hidden="true" class="legacy" id="stream_additional_notes"></a></h3> 46511cb0ef41Sopenharmony_ci 46521cb0ef41Sopenharmony_ci<h4>Streams compatibility with async generators and async iterators<span><a class="mark" href="#streams-compatibility-with-async-generators-and-async-iterators" id="streams-compatibility-with-async-generators-and-async-iterators">#</a></span><a aria-hidden="true" class="legacy" id="stream_streams_compatibility_with_async_generators_and_async_iterators"></a></h4> 46531cb0ef41Sopenharmony_ci<p>With the support of async generators and iterators in JavaScript, async 46541cb0ef41Sopenharmony_cigenerators are effectively a first-class language-level stream construct at 46551cb0ef41Sopenharmony_cithis point.</p> 46561cb0ef41Sopenharmony_ci<p>Some common interop cases of using Node.js streams with async generators 46571cb0ef41Sopenharmony_ciand async iterators are provided below.</p> 46581cb0ef41Sopenharmony_ci<h5>Consuming readable streams with async iterators<span><a class="mark" href="#consuming-readable-streams-with-async-iterators" id="consuming-readable-streams-with-async-iterators">#</a></span><a aria-hidden="true" class="legacy" id="stream_consuming_readable_streams_with_async_iterators"></a></h5> 46591cb0ef41Sopenharmony_ci<pre><code class="language-js">(<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) { 46601cb0ef41Sopenharmony_ci <span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> chunk <span class="hljs-keyword">of</span> readable) { 46611cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk); 46621cb0ef41Sopenharmony_ci } 46631cb0ef41Sopenharmony_ci})();</code> <button class="copy-button">copy</button></pre> 46641cb0ef41Sopenharmony_ci<p>Async iterators register a permanent error handler on the stream to prevent any 46651cb0ef41Sopenharmony_ciunhandled post-destroy errors.</p> 46661cb0ef41Sopenharmony_ci<h5>Creating readable streams with async generators<span><a class="mark" href="#creating-readable-streams-with-async-generators" id="creating-readable-streams-with-async-generators">#</a></span><a aria-hidden="true" class="legacy" id="stream_creating_readable_streams_with_async_generators"></a></h5> 46671cb0ef41Sopenharmony_ci<p>A Node.js readable stream can be created from an asynchronous generator using 46681cb0ef41Sopenharmony_cithe <code>Readable.from()</code> utility method:</p> 46691cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> { <span class="hljs-title class_">Readable</span> } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 46701cb0ef41Sopenharmony_ci 46711cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> ac = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 46721cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> signal = ac.<span class="hljs-property">signal</span>; 46731cb0ef41Sopenharmony_ci 46741cb0ef41Sopenharmony_ci<span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> * <span class="hljs-title function_">generate</span>(<span class="hljs-params"></span>) { 46751cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-string">'a'</span>; 46761cb0ef41Sopenharmony_ci <span class="hljs-keyword">await</span> <span class="hljs-title function_">someLongRunningFn</span>({ signal }); 46771cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-string">'b'</span>; 46781cb0ef41Sopenharmony_ci <span class="hljs-keyword">yield</span> <span class="hljs-string">'c'</span>; 46791cb0ef41Sopenharmony_ci} 46801cb0ef41Sopenharmony_ci 46811cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> readable = <span class="hljs-title class_">Readable</span>.<span class="hljs-title function_">from</span>(<span class="hljs-title function_">generate</span>()); 46821cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'close'</span>, <span class="hljs-function">() =></span> { 46831cb0ef41Sopenharmony_ci ac.<span class="hljs-title function_">abort</span>(); 46841cb0ef41Sopenharmony_ci}); 46851cb0ef41Sopenharmony_ci 46861cb0ef41Sopenharmony_cireadable.<span class="hljs-title function_">on</span>(<span class="hljs-string">'data'</span>, <span class="hljs-function">(<span class="hljs-params">chunk</span>) =></span> { 46871cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(chunk); 46881cb0ef41Sopenharmony_ci});</code> <button class="copy-button">copy</button></pre> 46891cb0ef41Sopenharmony_ci<h5>Piping to writable streams from async iterators<span><a class="mark" href="#piping-to-writable-streams-from-async-iterators" id="piping-to-writable-streams-from-async-iterators">#</a></span><a aria-hidden="true" class="legacy" id="stream_piping_to_writable_streams_from_async_iterators"></a></h5> 46901cb0ef41Sopenharmony_ci<p>When writing to a writable stream from an async iterator, ensure correct 46911cb0ef41Sopenharmony_cihandling of backpressure and errors. <a href="#streampipelinesource-transforms-destination-callback"><code>stream.pipeline()</code></a> abstracts away 46921cb0ef41Sopenharmony_cithe handling of backpressure and backpressure-related errors:</p> 46931cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">const</span> fs = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:fs'</span>); 46941cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { pipeline } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream'</span>); 46951cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { <span class="hljs-attr">pipeline</span>: pipelinePromise } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'node:stream/promises'</span>); 46961cb0ef41Sopenharmony_ci 46971cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> writable = fs.<span class="hljs-title function_">createWriteStream</span>(<span class="hljs-string">'./file'</span>); 46981cb0ef41Sopenharmony_ci 46991cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> ac = <span class="hljs-keyword">new</span> <span class="hljs-title class_">AbortController</span>(); 47001cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> signal = ac.<span class="hljs-property">signal</span>; 47011cb0ef41Sopenharmony_ci 47021cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> iterator = <span class="hljs-title function_">createIterator</span>({ signal }); 47031cb0ef41Sopenharmony_ci 47041cb0ef41Sopenharmony_ci<span class="hljs-comment">// Callback Pattern</span> 47051cb0ef41Sopenharmony_ci<span class="hljs-title function_">pipeline</span>(iterator, writable, <span class="hljs-function">(<span class="hljs-params">err, value</span>) =></span> { 47061cb0ef41Sopenharmony_ci <span class="hljs-keyword">if</span> (err) { 47071cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 47081cb0ef41Sopenharmony_ci } <span class="hljs-keyword">else</span> { 47091cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(value, <span class="hljs-string">'value returned'</span>); 47101cb0ef41Sopenharmony_ci } 47111cb0ef41Sopenharmony_ci}).<span class="hljs-title function_">on</span>(<span class="hljs-string">'close'</span>, <span class="hljs-function">() =></span> { 47121cb0ef41Sopenharmony_ci ac.<span class="hljs-title function_">abort</span>(); 47131cb0ef41Sopenharmony_ci}); 47141cb0ef41Sopenharmony_ci 47151cb0ef41Sopenharmony_ci<span class="hljs-comment">// Promise Pattern</span> 47161cb0ef41Sopenharmony_ci<span class="hljs-title function_">pipelinePromise</span>(iterator, writable) 47171cb0ef41Sopenharmony_ci .<span class="hljs-title function_">then</span>(<span class="hljs-function">(<span class="hljs-params">value</span>) =></span> { 47181cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(value, <span class="hljs-string">'value returned'</span>); 47191cb0ef41Sopenharmony_ci }) 47201cb0ef41Sopenharmony_ci .<span class="hljs-title function_">catch</span>(<span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { 47211cb0ef41Sopenharmony_ci <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">error</span>(err); 47221cb0ef41Sopenharmony_ci ac.<span class="hljs-title function_">abort</span>(); 47231cb0ef41Sopenharmony_ci });</code> <button class="copy-button">copy</button></pre> 47241cb0ef41Sopenharmony_ci 47251cb0ef41Sopenharmony_ci<h4>Compatibility with older Node.js versions<span><a class="mark" href="#compatibility-with-older-nodejs-versions" id="compatibility-with-older-nodejs-versions">#</a></span><a aria-hidden="true" class="legacy" id="stream_compatibility_with_older_node_js_versions"></a></h4> 47261cb0ef41Sopenharmony_ci 47271cb0ef41Sopenharmony_ci<p>Prior to Node.js 0.10, the <code>Readable</code> stream interface was simpler, but also 47281cb0ef41Sopenharmony_ciless powerful and less useful.</p> 47291cb0ef41Sopenharmony_ci<ul> 47301cb0ef41Sopenharmony_ci<li>Rather than waiting for calls to the <a href="#readablereadsize"><code>stream.read()</code></a> method, 47311cb0ef41Sopenharmony_ci<a href="#event-data"><code>'data'</code></a> events would begin emitting immediately. Applications that 47321cb0ef41Sopenharmony_ciwould need to perform some amount of work to decide how to handle data 47331cb0ef41Sopenharmony_ciwere required to store read data into buffers so the data would not be lost.</li> 47341cb0ef41Sopenharmony_ci<li>The <a href="#readablepause"><code>stream.pause()</code></a> method was advisory, rather than 47351cb0ef41Sopenharmony_ciguaranteed. This meant that it was still necessary to be prepared to receive 47361cb0ef41Sopenharmony_ci<a href="#event-data"><code>'data'</code></a> events <em>even when the stream was in a paused state</em>.</li> 47371cb0ef41Sopenharmony_ci</ul> 47381cb0ef41Sopenharmony_ci<p>In Node.js 0.10, the <a href="#class-streamreadable"><code>Readable</code></a> class was added. For backward 47391cb0ef41Sopenharmony_cicompatibility with older Node.js programs, <code>Readable</code> streams switch into 47401cb0ef41Sopenharmony_ci"flowing mode" when a <a href="#event-data"><code>'data'</code></a> event handler is added, or when the 47411cb0ef41Sopenharmony_ci<a href="#readableresume"><code>stream.resume()</code></a> method is called. The effect is that, even 47421cb0ef41Sopenharmony_ciwhen not using the new <a href="#readablereadsize"><code>stream.read()</code></a> method and 47431cb0ef41Sopenharmony_ci<a href="#event-readable"><code>'readable'</code></a> event, it is no longer necessary to worry about losing 47441cb0ef41Sopenharmony_ci<a href="#event-data"><code>'data'</code></a> chunks.</p> 47451cb0ef41Sopenharmony_ci<p>While most applications will continue to function normally, this introduces an 47461cb0ef41Sopenharmony_ciedge case in the following conditions:</p> 47471cb0ef41Sopenharmony_ci<ul> 47481cb0ef41Sopenharmony_ci<li>No <a href="#event-data"><code>'data'</code></a> event listener is added.</li> 47491cb0ef41Sopenharmony_ci<li>The <a href="#readableresume"><code>stream.resume()</code></a> method is never called.</li> 47501cb0ef41Sopenharmony_ci<li>The stream is not piped to any writable destination.</li> 47511cb0ef41Sopenharmony_ci</ul> 47521cb0ef41Sopenharmony_ci<p>For example, consider the following code:</p> 47531cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// WARNING! BROKEN!</span> 47541cb0ef41Sopenharmony_cinet.<span class="hljs-title function_">createServer</span>(<span class="hljs-function">(<span class="hljs-params">socket</span>) =></span> { 47551cb0ef41Sopenharmony_ci 47561cb0ef41Sopenharmony_ci <span class="hljs-comment">// We add an 'end' listener, but never consume the data.</span> 47571cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> { 47581cb0ef41Sopenharmony_ci <span class="hljs-comment">// It will never get here.</span> 47591cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">end</span>(<span class="hljs-string">'The message was received but was not processed.\n'</span>); 47601cb0ef41Sopenharmony_ci }); 47611cb0ef41Sopenharmony_ci 47621cb0ef41Sopenharmony_ci}).<span class="hljs-title function_">listen</span>(<span class="hljs-number">1337</span>);</code> <button class="copy-button">copy</button></pre> 47631cb0ef41Sopenharmony_ci<p>Prior to Node.js 0.10, the incoming message data would be simply discarded. 47641cb0ef41Sopenharmony_ciHowever, in Node.js 0.10 and beyond, the socket remains paused forever.</p> 47651cb0ef41Sopenharmony_ci<p>The workaround in this situation is to call the 47661cb0ef41Sopenharmony_ci<a href="#readableresume"><code>stream.resume()</code></a> method to begin the flow of data:</p> 47671cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// Workaround.</span> 47681cb0ef41Sopenharmony_cinet.<span class="hljs-title function_">createServer</span>(<span class="hljs-function">(<span class="hljs-params">socket</span>) =></span> { 47691cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">on</span>(<span class="hljs-string">'end'</span>, <span class="hljs-function">() =></span> { 47701cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">end</span>(<span class="hljs-string">'The message was received but was not processed.\n'</span>); 47711cb0ef41Sopenharmony_ci }); 47721cb0ef41Sopenharmony_ci 47731cb0ef41Sopenharmony_ci <span class="hljs-comment">// Start the flow of data, discarding it.</span> 47741cb0ef41Sopenharmony_ci socket.<span class="hljs-title function_">resume</span>(); 47751cb0ef41Sopenharmony_ci}).<span class="hljs-title function_">listen</span>(<span class="hljs-number">1337</span>);</code> <button class="copy-button">copy</button></pre> 47761cb0ef41Sopenharmony_ci<p>In addition to new <code>Readable</code> streams switching into flowing mode, 47771cb0ef41Sopenharmony_cipre-0.10 style streams can be wrapped in a <code>Readable</code> class using the 47781cb0ef41Sopenharmony_ci<a href="#readablewrapstream"><code>readable.wrap()</code></a> method.</p> 47791cb0ef41Sopenharmony_ci<h4><code>readable.read(0)</code><span><a class="mark" href="#readableread0" id="readableread0">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_read_0"></a></h4> 47801cb0ef41Sopenharmony_ci<p>There are some cases where it is necessary to trigger a refresh of the 47811cb0ef41Sopenharmony_ciunderlying readable stream mechanisms, without actually consuming any 47821cb0ef41Sopenharmony_cidata. In such cases, it is possible to call <code>readable.read(0)</code>, which will 47831cb0ef41Sopenharmony_cialways return <code>null</code>.</p> 47841cb0ef41Sopenharmony_ci<p>If the internal read buffer is below the <code>highWaterMark</code>, and the 47851cb0ef41Sopenharmony_cistream is not currently reading, then calling <code>stream.read(0)</code> will trigger 47861cb0ef41Sopenharmony_cia low-level <a href="#readable_readsize"><code>stream._read()</code></a> call.</p> 47871cb0ef41Sopenharmony_ci<p>While most applications will almost never need to do this, there are 47881cb0ef41Sopenharmony_cisituations within Node.js where this is done, particularly in the 47891cb0ef41Sopenharmony_ci<code>Readable</code> stream class internals.</p> 47901cb0ef41Sopenharmony_ci<h4><code>readable.push('')</code><span><a class="mark" href="#readablepush" id="readablepush">#</a></span><a aria-hidden="true" class="legacy" id="stream_readable_push"></a></h4> 47911cb0ef41Sopenharmony_ci<p>Use of <code>readable.push('')</code> is not recommended.</p> 47921cb0ef41Sopenharmony_ci<p>Pushing a zero-byte string, <code>Buffer</code>, or <code>Uint8Array</code> to a stream that is not in 47931cb0ef41Sopenharmony_ciobject mode has an interesting side effect. Because it <em>is</em> a call to 47941cb0ef41Sopenharmony_ci<a href="#readablepushchunk-encoding"><code>readable.push()</code></a>, the call will end the reading process. 47951cb0ef41Sopenharmony_ciHowever, because the argument is an empty string, no data is added to the 47961cb0ef41Sopenharmony_cireadable buffer so there is nothing for a user to consume.</p> 47971cb0ef41Sopenharmony_ci<h4><code>highWaterMark</code> discrepancy after calling <code>readable.setEncoding()</code><span><a class="mark" href="#highwatermark-discrepancy-after-calling-readablesetencoding" id="highwatermark-discrepancy-after-calling-readablesetencoding">#</a></span><a aria-hidden="true" class="legacy" id="stream_highwatermark_discrepancy_after_calling_readable_setencoding"></a></h4> 47981cb0ef41Sopenharmony_ci<p>The use of <code>readable.setEncoding()</code> will change the behavior of how the 47991cb0ef41Sopenharmony_ci<code>highWaterMark</code> operates in non-object mode.</p> 48001cb0ef41Sopenharmony_ci<p>Typically, the size of the current buffer is measured against the 48011cb0ef41Sopenharmony_ci<code>highWaterMark</code> in <em>bytes</em>. However, after <code>setEncoding()</code> is called, the 48021cb0ef41Sopenharmony_cicomparison function will begin to measure the buffer's size in <em>characters</em>.</p> 48031cb0ef41Sopenharmony_ci<p>This is not a problem in common cases with <code>latin1</code> or <code>ascii</code>. But it is 48041cb0ef41Sopenharmony_ciadvised to be mindful about this behavior when working with strings that could 48051cb0ef41Sopenharmony_cicontain multi-byte characters.</p></section> 48061cb0ef41Sopenharmony_ci <!-- API END --> 48071cb0ef41Sopenharmony_ci </div> 48081cb0ef41Sopenharmony_ci </div> 48091cb0ef41Sopenharmony_ci </div> 48101cb0ef41Sopenharmony_ci</body> 48111cb0ef41Sopenharmony_ci</html> 4812