你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

Readable interface

扩展

Stream

属性

closed

它 true 之后 'close' 已经发射。

destroyed

true它之后readable.destroy()被叫到了。

errored

如果流被破坏并出现错误,则返回错误。

readable

是true是否可以安全地调用读取,这意味着该流尚未被销毁或发出'error'。'end'

readableAborted

返回 是否在发射 'end'前流被销毁或出错。

readableDidRead

返回是否 'data' 已发射。

readableEncoding

给定encoding流的性质Readable的取集子。 encoding该属性可以通过 setEncoding 方法进行设置。

readableEnded

当事件被发射时。true'end'

readableFlowing

该性质反映了“Readable”部分描述的溪流当前状态。

readableHighWaterMark

创建该 highWaterMark时返回 的 通过值Readable。

readableLength

该性质包含队列中准备读取的字节(或对象)数量。 该值提供了关于 状态 highWaterMark的内省数据。

readableObjectMode

给定objectMode流的性质Readable的取集子。

方法

addListener(string | symbol, (args: any[]) => void)
addListener<E>(E, (args: ReadableEventMap[E]) => void)

emitter.on(eventName, listener) 的别名。

compose(WritableStream | WritableStream | TransformStream | (source: any) => void, Abortable)
import { Readable } from 'node:stream';

async function* splitToWords(source) {
  for await (const chunk of source) {
    const words = String(chunk).split(' ');

    for (const word of words) {
      yield word;
    }
  }
}

const wordsStream = Readable.from(['text passed through', 'composed stream']).compose(splitToWords);
const words = await wordsStream.toArray();

console.log(words); // prints ['text', 'passed', 'through', 'composed', 'stream']

readable.compose(s) 等效于 stream.compose(readable, s)。

该方法还允许提供 , AbortSignal 当中止时会销毁已组合的流。

有关详细信息,请参阅 stream.compose(...streams)。

destroy(Error)

销毁流。 可选地 发射事件 'error' 和 发射事件 'close' (除非 emitClose 设置为 false)。 调用后,可读流将释放所有内部资源,后续调用 push() 将被忽略。

一旦 destroy() 被调用,任何后续调用都将是 no-op,除了 之外 _destroy() ,不会再发出错误,作为 'error'。

实现者不应覆盖该方法,而应实现 readable._destroy()。

drop(number, Abortable)

该方法返回一个新流,从一开始就丢弃了第一个 极限 块。

emit(string | symbol, any[])
emit<E>(E, ReadableEventMap[E])

同步调用为名为 eventName的事件注册的每个侦听器,按照注册的顺序,将提供的参数传递给每个侦听器。

如果事件具有侦听器,则返回 true,否则 false。

import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
every((data: any, options?: Abortable) => boolean | Promise<boolean>, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

该方法类似于 Array.prototype.every ,调用流中每个区块的 fn ,检查所有等待的返回值是否都是 fn 的真实值。 一旦 fn 调用 await块 ed 返回值为假值,流被销毁,承诺由 实现。false 如果所有对区块的 fn 调用都返回真值,则承诺满足于 true。

filter((data: any, options?: Abortable) => boolean | Promise<boolean>, ReadableOperatorOptions)

这种方法可以对流进行过滤。 对于流中的每个区块,都会调用 fn 函数,如果返回 truthy 值,该区块会传递给结果流。 如果 fn 函数返回一个承诺——那个承诺就是 awaited。

find((data: any, options?: Abortable) => boolean | Promise<boolean>, Pick<ReadableOperatorOptions, "concurrency" | "signal">)
find<T>((data: any, options?: Abortable) => data is T, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

这种方法类似于 Array.prototype.find ,并且调用流中每个区块的 fn ,以找到 fn 的真实值。 一旦 fn 调用的等待返回值为真值,流被销毁,承诺被满足, fn 返回真值的值。 如果所有fn调用区块都返回假值,则承诺由 实现。undefined

flatMap((data: any, options?: Abortable) => any, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

该方法通过对流的每个区块应用回调,然后将结果进行平坦化,返回一个新的流。

可以从 fn 返回一个流或其他可迭代或异步迭代流,结果流会合并(扁平化)到返回的流中。

forEach((data: any, options?: Abortable) => void | Promise<void>, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

该方法允许对流进行迭代。 对于流中的每个区块,都会调用 fn 函数。 如果 fn 函数返回一个承诺——那个承诺就是 awaited。

该方法与 for await...of 循环不同,可以选择并发处理块。 此外, forEach 迭代只能通过通过放弃 signal 选项并中止相关的中止控制器来停止,而 for await...of 可以以 break 或 return停止。 无论哪种情况,溪流都会被摧毁。

该方法与监听 'data' 事件不同,因为它使用 readable 底层机械中的事件,并可限制并发 fn 调用的数量。

isPaused()

该 readable.isPaused() 方法返回了当前的操作状态 Readable。 这主要由方法 readable.pipe() 背后的机制所利用。 在大多数情况下,没有理由直接使用这种方法。

const readable = new stream.Readable();

readable.isPaused(); // === false
readable.pause();
readable.isPaused(); // === true
readable.resume();
readable.isPaused(); // === false
iterator(ReadableIteratorOptions)

通过该方法创建的迭代器允许用户选择在循环被 for await...of、 return、 或 break退出时取消对流throw的销毁,或者如果流在迭代过程中出现错误,则如果迭代器应销毁流。

listenerCount(string | symbol, (args: any[]) => void)
listenerCount<E>(E, (args: ReadableEventMap[E]) => void)

返回侦听名为 eventName的事件的侦听器数。 如果提供了 listener,它将返回在事件的侦听器列表中找到的侦听器的次数。

listeners(string | symbol)
listeners<E>(E)

返回名为 eventName的事件的侦听器数组的副本。

server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]
map((data: any, options?: Abortable) => any, ReadableOperatorOptions)

该方法允许对流进行映射。 流中的每个区块都会调用 fn 函数。 如果 fn 函数返回承诺——该承诺将在传递给结果流之前先被 awaited 处理。

off(string | symbol, (args: any[]) => void)
off<E>(E, (args: ReadableEventMap[E]) => void)

emitter.removeListener() 的别名。

on(string | symbol, (args: any[]) => void)
on<E>(E, (args: ReadableEventMap[E]) => void)

将 listener 函数添加到名为 eventName的事件的侦听器数组的末尾。 不会进行检查,以查看是否已添加 listener。 传递 eventName 和 listener 相同组合的多个调用将导致添加 listener 并多次调用。

server.on('connection', (stream) => {
  console.log('someone connected!');
});

返回对 EventEmitter的引用,以便可以链接调用。

默认情况下,以添加事件侦听器的顺序调用事件侦听器。 emitter.prependListener() 方法可用作将事件侦听器添加到侦听器数组开头的替代方法。

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
once(string | symbol, (args: any[]) => void)
once<E>(E, (args: ReadableEventMap[E]) => void)

为名为 的事件添加 listenereventName 函数。 下次触发 eventName 时,将删除此侦听器,然后调用。

server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

返回对 EventEmitter的引用,以便可以链接调用。

默认情况下,以添加事件侦听器的顺序调用事件侦听器。 emitter.prependOnceListener() 方法可用作将事件侦听器添加到侦听器数组开头的替代方法。

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
pause()

该 readable.pause() 方法会使处于流动模式的溪流停止发射 'data' 事件,从而退出流动模式。 任何可用数据都会保留在内部缓冲区中。

const readable = getReadableStreamSomehow();
readable.on('data', (chunk) => {
  console.log(`Received ${chunk.length} bytes of data.`);
  readable.pause();
  console.log('There will be no additional data for 1 second.');
  setTimeout(() => {
    console.log('Now data will start flowing again.');
    readable.resume();
  }, 1000);
});

如果存在readable.pause()事件监听器,该'readable'方法无效。

prependListener(string | symbol, (args: any[]) => void)
prependListener<E>(E, (args: ReadableEventMap[E]) => void)

将 函数添加到名为 的事件的侦听器数组的开始 。 不会进行检查,以查看是否已添加 listener。 传递 eventName 和 listener 相同组合的多个调用将导致添加 listener 并多次调用。

server.prependListener('connection', (stream) => {
  console.log('someone connected!');
});

返回对 EventEmitter的引用,以便可以链接调用。

prependOnceListener(string | symbol, (args: any[]) => void)
prependOnceListener<E>(E, (args: ReadableEventMap[E]) => void)

将名为 的事件 一次性 函数添加到侦听器数组 开始 。 下次触发 eventName 时,将删除此侦听器,然后调用。

server.prependOnceListener('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

返回对 EventEmitter的引用,以便可以链接调用。

push(any, BufferEncoding)
rawListeners(string | symbol)
rawListeners<E>(E)

返回名为 eventName的事件的侦听器数组的副本,包括任何包装器(如由 .once()创建的包装器)。

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');
read(number)

该 readable.read() 方法读取内部缓冲区的数据并返回。 如果没有可读取的数据,则 null 返回。 默认情况下,除非使用Buffer该方法指定编码或流处于对象模式,否则数据会以对象形式返回readable.setEncoding()。

可选 size 参数指定要读取的特定字节数。 如果 size 无法读取字节, null 则会返回, 除非 流已结束,此时内部缓冲区内剩余的所有数据将被返回。

如果 size 参数未指定,内部缓冲区中的所有数据都会被返回。

该 size 参数必须小于或等于 1 GiB。

readable.read()该方法应仅在Readable暂停模式下运行的流中调用。 在流动模式下, readable.read() 自动调用,直到内部缓冲区完全放空。

const readable = getReadableStreamSomehow();

// 'readable' may be triggered multiple times as data is buffered in
readable.on('readable', () => {
  let chunk;
  console.log('Stream is readable (new data received in buffer)');
  // Use a loop to make sure we read all currently available data
  while (null !== (chunk = readable.read())) {
    console.log(`Read ${chunk.length} bytes of data...`);
  }
});

// 'end' will be triggered once when there is no more data available
readable.on('end', () => {
  console.log('Reached end of stream.');
});

每次调用 返回 readable.read() 一块数据,或 null。 这些区块不是串接的。 需要一个 while 循环来消耗缓冲区中当前所有的数据。 读取大文件 .read() 时,可能返回 null,已经用尽了所有缓冲内容,但仍有更多数据尚未缓冲。 在这种情况下,当缓冲区中数据更多时,会发出新的 'readable' 事件。 最后 'end' ,当没有更多数据时,事件才会被发射。

因此,要从一个 readable读取文件的全部内容,需要在多个 'readable' 事件中收集块:

const chunks = [];

readable.on('readable', () => {
  let chunk;
  while (null !== (chunk = readable.read())) {
    chunks.push(chunk);
  }
});

readable.on('end', () => {
  const content = chunks.join('');
});

对象模式中的 Readable 流总是会从调用中 readable.read(size)返回单个元素,无论参数值如何 size 。

如果 readable.read() 方法返回数据块,也会发出事件 'data' 。

事件发出后呼叫'end'将返回null。 运行时不会有错误。

reduce<T>((previous: any, data: any, options?: Abortable) => T)

该方法按顺序调用流的每个区块 fn ,并将前一个元素的计算结果传递给它。 它返回约简最终值的承诺。

如果没有提供 初始 值,则使用流的第一个区块作为初始值。 如果流为空,则用 a TypeError 拒绝承诺,且代码性质为 ERR_INVALID_ARGS 。

约简函数逐元素迭代流,这意味着不存在 并发 参数或并行性。 要同时执行约简,可以提取异步函数到 readable.map 方法。

reduce<T>((previous: T, data: any, options?: Abortable) => T, T, Abortable)
removeAllListeners(string | symbol)
removeAllListeners<E>(E)

删除所有侦听器或指定 eventName的侦听器。

删除代码中的其他位置添加的侦听器是错误的做法,尤其是在由其他组件或模块(例如套接字或文件流)创建 EventEmitter 实例时。

返回对 EventEmitter的引用,以便可以链接调用。

removeListener(string | symbol, (args: any[]) => void)
removeListener<E>(E, (args: ReadableEventMap[E]) => void)

从名为 listener的事件的侦听器数组中删除指定的 eventName。

const callback = (stream) => {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

removeListener() 最多会从侦听器数组中删除侦听器的一个实例。 如果为指定的 eventName向侦听器数组添加了多次单个侦听器,则必须多次调用 removeListener() 才能删除每个实例。

发出事件后,在发出时附加到该事件的所有侦听器将按顺序调用。 这意味着在发射removeListener()且最后一个监听者removeAllListeners()的任何调用都不会将其从emit()进行中移除。 后续事件的行为与预期相同。

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

由于监听器通过内部数组管理,调用该数组会改变监听器被移除 后 注册的任何监听者的位置索引。 这不会影响调用侦听器的顺序,但这意味着需要重新创建 emitter.listeners() 方法返回的侦听器数组的任何副本。

将单个函数添加为单个事件的处理程序多次(如以下示例所示),removeListener() 将删除最近添加的实例。 在示例中,删除 once('ping') 侦听器:

import { EventEmitter } from 'node:events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

返回对 EventEmitter的引用,以便可以链接调用。

resume()

该 readable.resume() 方法使显式暂停 Readable 的流恢复发射 'data' 事件,使流切换到流模式。

该 readable.resume() 方法可以在不实际处理数据的情况下,完全消耗流中的数据:

getReadableStreamSomehow()
  .resume()
  .on('end', () => {
    console.log('Reached the end, but did not read anything.');
  });

如果存在readable.resume()事件监听器,该'readable'方法无效。

setEncoding(BufferEncoding)

该 readable.setEncoding() 方法为从流中读取 Readable 数据设置字符编码。

默认情况下,不分配编码,流数据将以对象形式返回 Buffer 。 设置编码会使流数据以指定编码的字符串形式返回,而非对象 Buffer 。 例如,调用 readable.setEncoding('utf8') 时输出数据会被解释为 UTF-8 数据,并以字符串形式传递。 调用 readable.setEncoding('hex') 会使数据编码为十六进制字符串格式。

Readable流将正确处理通过流传递的多字节字符,否则如果仅作为Buffer对象从流中拉取,这些字符会被错误解码。

const readable = getReadableStreamSomehow();
readable.setEncoding('utf8');
readable.on('data', (chunk) => {
  assert.equal(typeof chunk, 'string');
  console.log('Got %d characters of string data:', chunk.length);
});
some((data: any, options?: Abortable) => boolean | Promise<boolean>, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

该方法类似于 Array.prototype.some ,并且在流中的每个区块调用 fn ,直到等待的返回值为( true 或任何真实值)。 一旦 fn 调用区块 awaited 返回值为真值,流被销毁,承诺被满足。true 如果区块上的fn调用都不返回真值,则承诺满足。false

take(number, Abortable)

该方法返回一个包含首 批极限 块的新流。

toArray(Abortable)

这种方法可以轻松获取流的内容。

由于该方法将整个流读取到内存中,从而抵消了流的优势。 它旨在实现互操作性和便利性,而不是主要的观看流的方式。

unpipe(WritableStream)

该 readable.unpipe() 方法是将 Writable 之前用 管子 法连接的水流分离。

如果未指定, destination 则 所有 管道均为分离。

如果指定了, destination 但没有为它设置管道,那么该方法就不做任何事。

import fs from 'node:fs';
const readable = getReadableStreamSomehow();
const writable = fs.createWriteStream('file.txt');
// All the data from readable goes into 'file.txt',
// but only for the first second.
readable.pipe(writable);
setTimeout(() => {
  console.log('Stop writing to file.txt.');
  readable.unpipe(writable);
  console.log('Manually close the file stream.');
  writable.end();
}, 1000);
unshift(any, BufferEncoding)

传递 chunk 为 null 信号流的终点(EOF),行为与 readable.push(null),之后无法再写入数据。 EOF信号会放在缓冲区末端,任何缓冲的数据仍会被冲洗。

该 readable.unshift() 方法将一块数据推回内部缓冲区。 这在某些情况下非常有用,比如流被需要“取回”其乐观地从源端提取的部分数据“恢复消耗”,以便将数据传递给其他方。

事件发出后stream.unshift(chunk)不能调用该'end'方法,否则会抛出运行时错误。

经常使用 stream.unshift() 的用户应考虑改用 Transform 流。 更多信息请参见本 API for stream implementers 节。

// Pull off a header delimited by \n\n.
// Use unshift() if we get too much.
// Call the callback with (error, header, stream).
import { StringDecoder } from 'node:string_decoder';
function parseHeader(stream, callback) {
  stream.on('error', callback);
  stream.on('readable', onReadable);
  const decoder = new StringDecoder('utf8');
  let header = '';
  function onReadable() {
    let chunk;
    while (null !== (chunk = stream.read())) {
      const str = decoder.write(chunk);
      if (str.includes('\n\n')) {
        // Found the header boundary.
        const split = str.split(/\n\n/);
        header += split.shift();
        const remaining = split.join('\n\n');
        const buf = Buffer.from(remaining, 'utf8');
        stream.removeListener('error', callback);
        // Remove the 'readable' listener before unshifting.
        stream.removeListener('readable', onReadable);
        if (buf.length)
          stream.unshift(buf);
        // Now the body of the message can be read from the stream.
        callback(null, header, stream);
        return;
      }
      // Still reading the header.
      header += str;
    }
  }
}

与 推送不同,不会 stream.unshift(chunk) 通过重置流的内部读取状态来终止读取过程。 如果 readable.unshift() 在读取过程中调用(即在自定义流的 _read 实现内调用),可能会导致意想不到的结果。 在调用 后立即readable.unshift() 会适当重置读取状态,但最好在执行读取过程中避免调用readable.unshift()。

wrap(ReadableStream)

在 Node.js 0.10 之前,streams 并未实现当前定义的整个 node:stream 模块 API。 (更多信息请参见 Compatibility 。)

当使用较老的 Node.js 库,该库会发出 'data' 事件 且暂停方法 仅为咨询时, readable.wrap() 该方法可以用来创建 Readable 以旧流为数据源的流。

虽然很少需要使用 readable.wrap() ,但该方法是为了方便与旧 Node.js 应用和库交互。

import { OldReader } from './old-api-module.js';
import { Readable } from 'node:stream';
const oreader = new OldReader();
const myReader = new Readable().wrap(oreader);

myReader.on('readable', () => {
  myReader.read(); // etc.
});
[asyncDispose]()

调用 readable.destroy() 和 AbortError 返回一个承诺,当流结束时该承诺会被履行。

[asyncIterator]()
[toAsyncStreamable]()

当 --experimental-stream-iter 该标志被启用时, Readable 流会实现该 Stream.toAsyncStreamable 协议,从而使API能够高效地使用 stream/iter 。

这提供了一个批量异步迭代器,将流的内部缓冲区分成 Uint8Array[] 批量处理,从而摊销标准 Symbol.asyncIterator 路径的每个区块Promise开销。 对于字节模式流,块直接 Buffer 以实例形式生成(即 Uint8Array 子类)。 对于对象模式或编码流,每个区块在批处理前都会归一化。Uint8Array

返回的迭代器被标记为验证源,因此 from() 无需额外规范化即可通过。

import { Readable } from 'node:stream';
import { text, from } from 'node:stream/iter';

const readable = new Readable({
  read() { this.push('hello'); this.push(null); },
});

// Readable is automatically consumed via toAsyncStreamable
console.log(await text(from(readable))); // 'hello'

没有该 --experimental-stream-iter 标志时,调用该方法会 ERR_STREAM_ITER_MISSING_FLAG抛出 。

继承的方法

eventNames()

返回一个数组,其中列出发出器已注册侦听器的事件。

import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
getMaxListeners()

返回由 EventEmitter 设置的 emitter.setMaxListeners(n) 的当前最大侦听器值,或默认值为 events.defaultMaxListeners。

pipe<T>(T, PipeOptions)
setMaxListeners(number)

默认情况下,如果为特定事件添加了多个 EventEmitter 侦听器,10将打印警告。 这是一个有用的默认值,可帮助查找内存泄漏。 emitter.setMaxListeners() 方法允许修改此特定 EventEmitter 实例的限制。 该值可以设置为 Infinity(或 0),以指示无限数量的侦听器。

返回对 EventEmitter的引用,以便可以链接调用。

[captureRejectionSymbol](Error, string | symbol, any[])

Symbol.for('nodejs.rejection')该方法用于在发射事件时发生承诺拒绝,并且captureRejections在发射端被启用时调用。 可以用 events.captureRejectionSymbol 代替 Symbol.for('nodejs.rejection')。

import { EventEmitter, captureRejectionSymbol } from 'node:events';

class MyClass extends EventEmitter {
  constructor() {
    super({ captureRejections: true });
  }

  [captureRejectionSymbol](err, event, ...args) {
    console.log('rejection happened for', event, 'with', err, ...args);
    this.destroy(err);
  }

  destroy(err) {
    // Tear the resource down here.
  }
}

属性详细信息

closed

它 true 之后 'close' 已经发射。

closed: boolean

属性值

boolean

destroyed

true它之后readable.destroy()被叫到了。

destroyed: boolean

属性值

boolean

errored

如果流被破坏并出现错误,则返回错误。

errored: Error | null

属性值

Error | null

readable

是true是否可以安全地调用读取,这意味着该流尚未被销毁或发出'error'。'end'

readable: boolean

属性值

boolean

readableAborted

返回 是否在发射 'end'前流被销毁或出错。

readableAborted: boolean

属性值

boolean

readableDidRead

返回是否 'data' 已发射。

readableDidRead: boolean

属性值

boolean

readableEncoding

给定encoding流的性质Readable的取集子。 encoding该属性可以通过 setEncoding 方法进行设置。

readableEncoding: BufferEncoding | null

属性值

BufferEncoding | null

readableEnded

当事件被发射时。true'end'

readableEnded: boolean

属性值

boolean

readableFlowing

该性质反映了“Readable”部分描述的溪流当前状态。

readableFlowing: boolean | null

属性值

boolean | null

readableHighWaterMark

创建该 highWaterMark时返回 的 通过值Readable。

readableHighWaterMark: number

属性值

number

readableLength

该性质包含队列中准备读取的字节(或对象)数量。 该值提供了关于 状态 highWaterMark的内省数据。

readableLength: number

属性值

number

readableObjectMode

给定objectMode流的性质Readable的取集子。

readableObjectMode: boolean

属性值

boolean

方法详细信息

addListener(string | symbol, (args: any[]) => void)

function addListener(eventName: string | symbol, listener: (args: any[]) => void): this

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

this

addListener<E>(E, (args: ReadableEventMap[E]) => void)

emitter.on(eventName, listener) 的别名。

function addListener<E>(eventName: E, listener: (args: ReadableEventMap[E]) => void): this

参数

eventName

E

listener

(args: ReadableEventMap[E]) => void

返回

this

compose(WritableStream | WritableStream | TransformStream | (source: any) => void, Abortable)

import { Readable } from 'node:stream';

async function* splitToWords(source) {
  for await (const chunk of source) {
    const words = String(chunk).split(' ');

    for (const word of words) {
      yield word;
    }
  }
}

const wordsStream = Readable.from(['text passed through', 'composed stream']).compose(splitToWords);
const words = await wordsStream.toArray();

console.log(words); // prints ['text', 'passed', 'through', 'composed', 'stream']

readable.compose(s) 等效于 stream.compose(readable, s)。

该方法还允许提供 , AbortSignal 当中止时会销毁已组合的流。

有关详细信息,请参阅 stream.compose(...streams)。

function compose(stream: WritableStream | WritableStream | TransformStream | (source: any) => void, options?: Abortable): Duplex

参数

stream

WritableStream | WritableStream | TransformStream | (source: any) => void

options

Abortable

返回

Duplex

一个由 stream的流组成的流。

destroy(Error)

销毁流。 可选地 发射事件 'error' 和 发射事件 'close' (除非 emitClose 设置为 false)。 调用后,可读流将释放所有内部资源,后续调用 push() 将被忽略。

一旦 destroy() 被调用,任何后续调用都将是 no-op,除了 之外 _destroy() ,不会再发出错误,作为 'error'。

实现者不应覆盖该方法,而应实现 readable._destroy()。

function destroy(error?: Error): this

参数

error

Error

错误将在事件中 'error' 传递为有效载荷

返回

this

drop(number, Abortable)

该方法返回一个新流,从一开始就丢弃了第一个 极限 块。

function drop(limit: number, options?: Abortable): Readable

参数

limit

number

从可读区块中剔除的数量。

options

Abortable

返回

一个从一开始就有 限制 区块的流。

emit(string | symbol, any[])

function emit(eventName: string | symbol, args: any[]): boolean

参数

eventName

string | symbol

args

any[]

返回

boolean

emit<E>(E, ReadableEventMap[E])

同步调用为名为 eventName的事件注册的每个侦听器,按照注册的顺序,将提供的参数传递给每个侦听器。

如果事件具有侦听器,则返回 true,否则 false。

import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
function emit<E>(eventName: E, args: ReadableEventMap[E]): boolean

参数

eventName

E

args

ReadableEventMap[E]

返回

boolean

every((data: any, options?: Abortable) => boolean | Promise<boolean>, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

该方法类似于 Array.prototype.every ,调用流中每个区块的 fn ,检查所有等待的返回值是否都是 fn 的真实值。 一旦 fn 调用 await块 ed 返回值为假值,流被销毁,承诺由 实现。false 如果所有对区块的 fn 调用都返回真值,则承诺满足于 true。

function every(fn: (data: any, options?: Abortable) => boolean | Promise<boolean>, options?: Pick<ReadableOperatorOptions, "concurrency" | "signal">): Promise<boolean>

参数

fn

(data: any, options?: Abortable) => boolean | Promise<boolean>

一个用于调用流中每个区块的函数。 不管是不是异步。

options

Pick<ReadableOperatorOptions, "concurrency" | "signal">

返回

Promise<boolean>

一个承诺,评估 truefn 是否对每个区块返回真值。

filter((data: any, options?: Abortable) => boolean | Promise<boolean>, ReadableOperatorOptions)

这种方法可以对流进行过滤。 对于流中的每个区块,都会调用 fn 函数,如果返回 truthy 值,该区块会传递给结果流。 如果 fn 函数返回一个承诺——那个承诺就是 awaited。

function filter(fn: (data: any, options?: Abortable) => boolean | Promise<boolean>, options?: ReadableOperatorOptions): Readable

参数

fn

(data: any, options?: Abortable) => boolean | Promise<boolean>

一个用来过滤流块的函数。 不管是不是异步。

options

ReadableOperatorOptions

返回

一个用谓词 fn 过滤的流。

find((data: any, options?: Abortable) => boolean | Promise<boolean>, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

function find(fn: (data: any, options?: Abortable) => boolean | Promise<boolean>, options?: Pick<ReadableOperatorOptions, "concurrency" | "signal">): Promise<any>

参数

fn

(data: any, options?: Abortable) => boolean | Promise<boolean>

options

Pick<ReadableOperatorOptions, "concurrency" | "signal">

返回

Promise<any>

find<T>((data: any, options?: Abortable) => data is T, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

这种方法类似于 Array.prototype.find ,并且调用流中每个区块的 fn ,以找到 fn 的真实值。 一旦 fn 调用的等待返回值为真值,流被销毁,承诺被满足, fn 返回真值的值。 如果所有fn调用区块都返回假值,则承诺由 实现。undefined

function find<T>(fn: (data: any, options?: Abortable) => data is T, options?: Pick<ReadableOperatorOptions, "concurrency" | "signal">): Promise<T | undefined>

参数

fn

(data: any, options?: Abortable) => data is T

一个用于调用流中每个区块的函数。 不管是不是异步。

options

Pick<ReadableOperatorOptions, "concurrency" | "signal">

返回

Promise<T | undefined>

对第一个 fn 值为真值的 Promise 进行评估,或者 undefined 如果没有发现元素。

flatMap((data: any, options?: Abortable) => any, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

该方法通过对流的每个区块应用回调,然后将结果进行平坦化,返回一个新的流。

可以从 fn 返回一个流或其他可迭代或异步迭代流,结果流会合并(扁平化)到返回的流中。

function flatMap(fn: (data: any, options?: Abortable) => any, options?: Pick<ReadableOperatorOptions, "concurrency" | "signal">): Readable

参数

fn

(data: any, options?: Abortable) => any

一个映射流中每个区块的函数。 可能是异步。 可能是水流或发电机。

options

Pick<ReadableOperatorOptions, "concurrency" | "signal">

返回

一个用 函数fn平映的流。

forEach((data: any, options?: Abortable) => void | Promise<void>, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

该方法允许对流进行迭代。 对于流中的每个区块,都会调用 fn 函数。 如果 fn 函数返回一个承诺——那个承诺就是 awaited。

该方法与 for await...of 循环不同,可以选择并发处理块。 此外, forEach 迭代只能通过通过放弃 signal 选项并中止相关的中止控制器来停止,而 for await...of 可以以 break 或 return停止。 无论哪种情况,溪流都会被摧毁。

该方法与监听 'data' 事件不同,因为它使用 readable 底层机械中的事件,并可限制并发 fn 调用的数量。

function forEach(fn: (data: any, options?: Abortable) => void | Promise<void>, options?: Pick<ReadableOperatorOptions, "concurrency" | "signal">): Promise<void>

参数

fn

(data: any, options?: Abortable) => void | Promise<void>

一个用于调用流中每个区块的函数。 不管是不是异步。

options

Pick<ReadableOperatorOptions, "concurrency" | "signal">

返回

Promise<void>

等直播结束后才会有承诺。

isPaused()

该 readable.isPaused() 方法返回了当前的操作状态 Readable。 这主要由方法 readable.pipe() 背后的机制所利用。 在大多数情况下,没有理由直接使用这种方法。

const readable = new stream.Readable();

readable.isPaused(); // === false
readable.pause();
readable.isPaused(); // === true
readable.resume();
readable.isPaused(); // === false
function isPaused(): boolean

返回

boolean

iterator(ReadableIteratorOptions)

通过该方法创建的迭代器允许用户选择在循环被 for await...of、 return、 或 break退出时取消对流throw的销毁,或者如果流在迭代过程中出现错误,则如果迭代器应销毁流。

function iterator(options?: ReadableIteratorOptions): AsyncIterator<any>

参数

options

ReadableIteratorOptions

返回

AsyncIterator<any>

listenerCount(string | symbol, (args: any[]) => void)

function listenerCount(eventName: string | symbol, listener?: (args: any[]) => void): number

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

number

listenerCount<E>(E, (args: ReadableEventMap[E]) => void)

返回侦听名为 eventName的事件的侦听器数。 如果提供了 listener,它将返回在事件的侦听器列表中找到的侦听器的次数。

function listenerCount<E>(eventName: E, listener?: (args: ReadableEventMap[E]) => void): number

参数

eventName

E

正在侦听的事件的名称

listener

(args: ReadableEventMap[E]) => void

事件处理程序函数

返回

number

listeners(string | symbol)

function listeners(eventName: string | symbol): (args: any[]) => void[]

参数

eventName

string | symbol

返回

(args: any[]) => void[]

listeners<E>(E)

返回名为 eventName的事件的侦听器数组的副本。

server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]
function listeners<E>(eventName: E): (args: ReadableEventMap[E]) => void[]

参数

eventName

E

返回

(args: ReadableEventMap[E]) => void[]

map((data: any, options?: Abortable) => any, ReadableOperatorOptions)

该方法允许对流进行映射。 流中的每个区块都会调用 fn 函数。 如果 fn 函数返回承诺——该承诺将在传递给结果流之前先被 awaited 处理。

function map(fn: (data: any, options?: Abortable) => any, options?: ReadableOperatorOptions): Readable

参数

fn

(data: any, options?: Abortable) => any

一个映射流中每个区块的函数。 不管是不是异步。

options

ReadableOperatorOptions

返回

一个用函数 fn 映射的流。

off(string | symbol, (args: any[]) => void)

function off(eventName: string | symbol, listener: (args: any[]) => void): this

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

this

off<E>(E, (args: ReadableEventMap[E]) => void)

emitter.removeListener() 的别名。

function off<E>(eventName: E, listener: (args: ReadableEventMap[E]) => void): this

参数

eventName

E

listener

(args: ReadableEventMap[E]) => void

返回

this

on(string | symbol, (args: any[]) => void)

function on(eventName: string | symbol, listener: (args: any[]) => void): this

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

this

on<E>(E, (args: ReadableEventMap[E]) => void)

将 listener 函数添加到名为 eventName的事件的侦听器数组的末尾。 不会进行检查,以查看是否已添加 listener。 传递 eventName 和 listener 相同组合的多个调用将导致添加 listener 并多次调用。

server.on('connection', (stream) => {
  console.log('someone connected!');
});

返回对 EventEmitter的引用,以便可以链接调用。

默认情况下,以添加事件侦听器的顺序调用事件侦听器。 emitter.prependListener() 方法可用作将事件侦听器添加到侦听器数组开头的替代方法。

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
function on<E>(eventName: E, listener: (args: ReadableEventMap[E]) => void): this

参数

eventName

E

事件名称。

listener

(args: ReadableEventMap[E]) => void

回调函数

返回

this

once(string | symbol, (args: any[]) => void)

function once(eventName: string | symbol, listener: (args: any[]) => void): this

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

this

once<E>(E, (args: ReadableEventMap[E]) => void)

为名为 的事件添加 listenereventName 函数。 下次触发 eventName 时,将删除此侦听器,然后调用。

server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

返回对 EventEmitter的引用,以便可以链接调用。

默认情况下,以添加事件侦听器的顺序调用事件侦听器。 emitter.prependOnceListener() 方法可用作将事件侦听器添加到侦听器数组开头的替代方法。

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
function once<E>(eventName: E, listener: (args: ReadableEventMap[E]) => void): this

参数

eventName

E

事件名称。

listener

(args: ReadableEventMap[E]) => void

回调函数

返回

this

pause()

该 readable.pause() 方法会使处于流动模式的溪流停止发射 'data' 事件,从而退出流动模式。 任何可用数据都会保留在内部缓冲区中。

const readable = getReadableStreamSomehow();
readable.on('data', (chunk) => {
  console.log(`Received ${chunk.length} bytes of data.`);
  readable.pause();
  console.log('There will be no additional data for 1 second.');
  setTimeout(() => {
    console.log('Now data will start flowing again.');
    readable.resume();
  }, 1000);
});

如果存在readable.pause()事件监听器,该'readable'方法无效。

function pause(): this

返回

this

prependListener(string | symbol, (args: any[]) => void)

function prependListener(eventName: string | symbol, listener: (args: any[]) => void): this

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

this

prependListener<E>(E, (args: ReadableEventMap[E]) => void)

将 函数添加到名为 的事件的侦听器数组的开始 。 不会进行检查,以查看是否已添加 listener。 传递 eventName 和 listener 相同组合的多个调用将导致添加 listener 并多次调用。

server.prependListener('connection', (stream) => {
  console.log('someone connected!');
});

返回对 EventEmitter的引用,以便可以链接调用。

function prependListener<E>(eventName: E, listener: (args: ReadableEventMap[E]) => void): this

参数

eventName

E

事件名称。

listener

(args: ReadableEventMap[E]) => void

回调函数

返回

this

prependOnceListener(string | symbol, (args: any[]) => void)

function prependOnceListener(eventName: string | symbol, listener: (args: any[]) => void): this

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

this

prependOnceListener<E>(E, (args: ReadableEventMap[E]) => void)

将名为 的事件 一次性 函数添加到侦听器数组 开始 。 下次触发 eventName 时,将删除此侦听器,然后调用。

server.prependOnceListener('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

返回对 EventEmitter的引用,以便可以链接调用。

function prependOnceListener<E>(eventName: E, listener: (args: ReadableEventMap[E]) => void): this

参数

eventName

E

事件名称。

listener

(args: ReadableEventMap[E]) => void

回调函数

返回

this

push(any, BufferEncoding)

function push(chunk: any, encoding?: BufferEncoding): boolean

参数

chunk

any

encoding

BufferEncoding

返回

boolean

rawListeners(string | symbol)

function rawListeners(eventName: string | symbol): (args: any[]) => void[]

参数

eventName

string | symbol

返回

(args: any[]) => void[]

rawListeners<E>(E)

返回名为 eventName的事件的侦听器数组的副本,包括任何包装器(如由 .once()创建的包装器)。

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');
function rawListeners<E>(eventName: E): (args: ReadableEventMap[E]) => void[]

参数

eventName

E

返回

(args: ReadableEventMap[E]) => void[]

read(number)

该 readable.read() 方法读取内部缓冲区的数据并返回。 如果没有可读取的数据,则 null 返回。 默认情况下,除非使用Buffer该方法指定编码或流处于对象模式,否则数据会以对象形式返回readable.setEncoding()。

可选 size 参数指定要读取的特定字节数。 如果 size 无法读取字节, null 则会返回, 除非 流已结束,此时内部缓冲区内剩余的所有数据将被返回。

如果 size 参数未指定,内部缓冲区中的所有数据都会被返回。

该 size 参数必须小于或等于 1 GiB。

readable.read()该方法应仅在Readable暂停模式下运行的流中调用。 在流动模式下, readable.read() 自动调用,直到内部缓冲区完全放空。

const readable = getReadableStreamSomehow();

// 'readable' may be triggered multiple times as data is buffered in
readable.on('readable', () => {
  let chunk;
  console.log('Stream is readable (new data received in buffer)');
  // Use a loop to make sure we read all currently available data
  while (null !== (chunk = readable.read())) {
    console.log(`Read ${chunk.length} bytes of data...`);
  }
});

// 'end' will be triggered once when there is no more data available
readable.on('end', () => {
  console.log('Reached end of stream.');
});

每次调用 返回 readable.read() 一块数据,或 null。 这些区块不是串接的。 需要一个 while 循环来消耗缓冲区中当前所有的数据。 读取大文件 .read() 时,可能返回 null,已经用尽了所有缓冲内容,但仍有更多数据尚未缓冲。 在这种情况下,当缓冲区中数据更多时,会发出新的 'readable' 事件。 最后 'end' ,当没有更多数据时,事件才会被发射。

因此,要从一个 readable读取文件的全部内容,需要在多个 'readable' 事件中收集块:

const chunks = [];

readable.on('readable', () => {
  let chunk;
  while (null !== (chunk = readable.read())) {
    chunks.push(chunk);
  }
});

readable.on('end', () => {
  const content = chunks.join('');
});

对象模式中的 Readable 流总是会从调用中 readable.read(size)返回单个元素,无论参数值如何 size 。

如果 readable.read() 方法返回数据块,也会发出事件 'data' 。

事件发出后呼叫'end'将返回null。 运行时不会有错误。

function read(size?: number): any

参数

size

number

可选参数来指定要读取多少数据。

返回

any

reduce<T>((previous: any, data: any, options?: Abortable) => T)

该方法按顺序调用流的每个区块 fn ,并将前一个元素的计算结果传递给它。 它返回约简最终值的承诺。

如果没有提供 初始 值,则使用流的第一个区块作为初始值。 如果流为空,则用 a TypeError 拒绝承诺,且代码性质为 ERR_INVALID_ARGS 。

约简函数逐元素迭代流,这意味着不存在 并发 参数或并行性。 要同时执行约简,可以提取异步函数到 readable.map 方法。

function reduce<T>(fn: (previous: any, data: any, options?: Abortable) => T): Promise<T>

参数

fn

(previous: any, data: any, options?: Abortable) => T

一个缩减函数,用于调用流中的每个区块。 不管是不是异步。

返回

Promise<T>

对最终减免价值的承诺。

reduce<T>((previous: T, data: any, options?: Abortable) => T, T, Abortable)

function reduce<T>(fn: (previous: T, data: any, options?: Abortable) => T, initial: T, options?: Abortable): Promise<T>

参数

fn

(previous: T, data: any, options?: Abortable) => T

initial

T

options

Abortable

返回

Promise<T>

removeAllListeners(string | symbol)

function removeAllListeners(eventName?: string | symbol): this

参数

eventName

string | symbol

返回

this

removeAllListeners<E>(E)

删除所有侦听器或指定 eventName的侦听器。

删除代码中的其他位置添加的侦听器是错误的做法,尤其是在由其他组件或模块(例如套接字或文件流)创建 EventEmitter 实例时。

返回对 EventEmitter的引用,以便可以链接调用。

function removeAllListeners<E>(eventName?: E): this

参数

eventName

E

返回

this

removeListener(string | symbol, (args: any[]) => void)

function removeListener(eventName: string | symbol, listener: (args: any[]) => void): this

参数

eventName

string | symbol

listener

(args: any[]) => void

返回

this

removeListener<E>(E, (args: ReadableEventMap[E]) => void)

从名为 listener的事件的侦听器数组中删除指定的 eventName。

const callback = (stream) => {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

removeListener() 最多会从侦听器数组中删除侦听器的一个实例。 如果为指定的 eventName向侦听器数组添加了多次单个侦听器,则必须多次调用 removeListener() 才能删除每个实例。

发出事件后,在发出时附加到该事件的所有侦听器将按顺序调用。 这意味着在发射removeListener()且最后一个监听者removeAllListeners()的任何调用都不会将其从emit()进行中移除。 后续事件的行为与预期相同。

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

由于监听器通过内部数组管理,调用该数组会改变监听器被移除 后 注册的任何监听者的位置索引。 这不会影响调用侦听器的顺序,但这意味着需要重新创建 emitter.listeners() 方法返回的侦听器数组的任何副本。

将单个函数添加为单个事件的处理程序多次(如以下示例所示),removeListener() 将删除最近添加的实例。 在示例中,删除 once('ping') 侦听器:

import { EventEmitter } from 'node:events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

返回对 EventEmitter的引用,以便可以链接调用。

function removeListener<E>(eventName: E, listener: (args: ReadableEventMap[E]) => void): this

参数

eventName

E

listener

(args: ReadableEventMap[E]) => void

返回

this

resume()

该 readable.resume() 方法使显式暂停 Readable 的流恢复发射 'data' 事件,使流切换到流模式。

该 readable.resume() 方法可以在不实际处理数据的情况下,完全消耗流中的数据:

getReadableStreamSomehow()
  .resume()
  .on('end', () => {
    console.log('Reached the end, but did not read anything.');
  });

如果存在readable.resume()事件监听器,该'readable'方法无效。

function resume(): this

返回

this

setEncoding(BufferEncoding)

该 readable.setEncoding() 方法为从流中读取 Readable 数据设置字符编码。

默认情况下,不分配编码,流数据将以对象形式返回 Buffer 。 设置编码会使流数据以指定编码的字符串形式返回,而非对象 Buffer 。 例如,调用 readable.setEncoding('utf8') 时输出数据会被解释为 UTF-8 数据,并以字符串形式传递。 调用 readable.setEncoding('hex') 会使数据编码为十六进制字符串格式。

Readable流将正确处理通过流传递的多字节字符,否则如果仅作为Buffer对象从流中拉取,这些字符会被错误解码。

const readable = getReadableStreamSomehow();
readable.setEncoding('utf8');
readable.on('data', (chunk) => {
  assert.equal(typeof chunk, 'string');
  console.log('Got %d characters of string data:', chunk.length);
});
function setEncoding(encoding: BufferEncoding): this

参数

encoding

BufferEncoding

要使用的编码。

返回

this

some((data: any, options?: Abortable) => boolean | Promise<boolean>, Pick<ReadableOperatorOptions, "concurrency" | "signal">)

该方法类似于 Array.prototype.some ,并且在流中的每个区块调用 fn ,直到等待的返回值为( true 或任何真实值)。 一旦 fn 调用区块 awaited 返回值为真值,流被销毁,承诺被满足。true 如果区块上的fn调用都不返回真值,则承诺满足。false

function some(fn: (data: any, options?: Abortable) => boolean | Promise<boolean>, options?: Pick<ReadableOperatorOptions, "concurrency" | "signal">): Promise<boolean>

参数

fn

(data: any, options?: Abortable) => boolean | Promise<boolean>

一个用于调用流中每个区块的函数。 不管是不是异步。

options

Pick<ReadableOperatorOptions, "concurrency" | "signal">

返回

Promise<boolean>

一个评估 true 是否对至少一个区块返回真值的承诺。

take(number, Abortable)

该方法返回一个包含首 批极限 块的新流。

function take(limit: number, options?: Abortable): Readable

参数

limit

number

从可读部分中提取的片段数量。

options

Abortable

返回

一个 被限制 区块的流。

toArray(Abortable)

这种方法可以轻松获取流的内容。

由于该方法将整个流读取到内存中,从而抵消了流的优势。 它旨在实现互操作性和便利性,而不是主要的观看流的方式。

function toArray(options?: Abortable): Promise<any[]>

参数

options

Abortable

返回

Promise<any[]>

一个包含流内容数组的承诺。

unpipe(WritableStream)

该 readable.unpipe() 方法是将 Writable 之前用 管子 法连接的水流分离。

如果未指定, destination 则 所有 管道均为分离。

如果指定了, destination 但没有为它设置管道,那么该方法就不做任何事。

import fs from 'node:fs';
const readable = getReadableStreamSomehow();
const writable = fs.createWriteStream('file.txt');
// All the data from readable goes into 'file.txt',
// but only for the first second.
readable.pipe(writable);
setTimeout(() => {
  console.log('Stop writing to file.txt.');
  readable.unpipe(writable);
  console.log('Manually close the file stream.');
  writable.end();
}, 1000);
function unpipe(destination?: WritableStream): this

参数

destination

WritableStream

可选的特定流路可拆卸

返回

this

unshift(any, BufferEncoding)

传递 chunk 为 null 信号流的终点(EOF),行为与 readable.push(null),之后无法再写入数据。 EOF信号会放在缓冲区末端,任何缓冲的数据仍会被冲洗。

该 readable.unshift() 方法将一块数据推回内部缓冲区。 这在某些情况下非常有用,比如流被需要“取回”其乐观地从源端提取的部分数据“恢复消耗”,以便将数据传递给其他方。

事件发出后stream.unshift(chunk)不能调用该'end'方法,否则会抛出运行时错误。

经常使用 stream.unshift() 的用户应考虑改用 Transform 流。 更多信息请参见本 API for stream implementers 节。

// Pull off a header delimited by \n\n.
// Use unshift() if we get too much.
// Call the callback with (error, header, stream).
import { StringDecoder } from 'node:string_decoder';
function parseHeader(stream, callback) {
  stream.on('error', callback);
  stream.on('readable', onReadable);
  const decoder = new StringDecoder('utf8');
  let header = '';
  function onReadable() {
    let chunk;
    while (null !== (chunk = stream.read())) {
      const str = decoder.write(chunk);
      if (str.includes('\n\n')) {
        // Found the header boundary.
        const split = str.split(/\n\n/);
        header += split.shift();
        const remaining = split.join('\n\n');
        const buf = Buffer.from(remaining, 'utf8');
        stream.removeListener('error', callback);
        // Remove the 'readable' listener before unshifting.
        stream.removeListener('readable', onReadable);
        if (buf.length)
          stream.unshift(buf);
        // Now the body of the message can be read from the stream.
        callback(null, header, stream);
        return;
      }
      // Still reading the header.
      header += str;
    }
  }
}

与 推送不同,不会 stream.unshift(chunk) 通过重置流的内部读取状态来终止读取过程。 如果 readable.unshift() 在读取过程中调用(即在自定义流的 _read 实现内调用),可能会导致意想不到的结果。 在调用 后立即readable.unshift() 会适当重置读取状态,但最好在执行读取过程中避免调用readable.unshift()。

function unshift(chunk: any, encoding?: BufferEncoding)

参数

chunk

any

一块数据,从读取队列中恢复。 对于非对象模式运行的流, chunk 必须是{string}、{Buffer}、{TypedArray}、{DataView}或 null。 对于对象模式流,可以 chunk 是任意JavaScript值。

encoding

BufferEncoding

字符串块的编码。 必须是有效的Buffer编码,例如'utf8''ascii'或。

wrap(ReadableStream)

在 Node.js 0.10 之前,streams 并未实现当前定义的整个 node:stream 模块 API。 (更多信息请参见 Compatibility 。)

当使用较老的 Node.js 库,该库会发出 'data' 事件 且暂停方法 仅为咨询时, readable.wrap() 该方法可以用来创建 Readable 以旧流为数据源的流。

虽然很少需要使用 readable.wrap() ,但该方法是为了方便与旧 Node.js 应用和库交互。

import { OldReader } from './old-api-module.js';
import { Readable } from 'node:stream';
const oreader = new OldReader();
const myReader = new Readable().wrap(oreader);

myReader.on('readable', () => {
  myReader.read(); // etc.
});
function wrap(stream: ReadableStream): this

参数

stream

ReadableStream

一个“老式”可读流

返回

this

[asyncDispose]()

调用 readable.destroy() 和 AbortError 返回一个承诺,当流结束时该承诺会被履行。

function [asyncDispose](): Promise<void>

返回

Promise<void>

[asyncIterator]()

function [asyncIterator](): AsyncIterator<any>

返回

AsyncIterator<any>

AsyncIterator 完全吞噬了这条流。

[toAsyncStreamable]()

当 --experimental-stream-iter 该标志被启用时, Readable 流会实现该 Stream.toAsyncStreamable 协议,从而使API能够高效地使用 stream/iter 。

这提供了一个批量异步迭代器,将流的内部缓冲区分成 Uint8Array[] 批量处理,从而摊销标准 Symbol.asyncIterator 路径的每个区块Promise开销。 对于字节模式流,块直接 Buffer 以实例形式生成(即 Uint8Array 子类)。 对于对象模式或编码流,每个区块在批处理前都会归一化。Uint8Array

返回的迭代器被标记为验证源,因此 from() 无需额外规范化即可通过。

import { Readable } from 'node:stream';
import { text, from } from 'node:stream/iter';

const readable = new Readable({
  read() { this.push('hello'); this.push(null); },
});

// Readable is automatically consumed via toAsyncStreamable
console.log(await text(from(readable))); // 'hello'

没有该 --experimental-stream-iter 标志时,调用该方法会 ERR_STREAM_ITER_MISSING_FLAG抛出 。

function [toAsyncStreamable](): ByteReadableStream

返回

ByteReadableStream

继承的方法详细信息

eventNames()

返回一个数组,其中列出发出器已注册侦听器的事件。

import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
function eventNames(): (string | symbol)[]

返回

(string | symbol)[]

继承自 Stream.eventNames(流媒体)事件名称

getMaxListeners()

返回由 EventEmitter 设置的 emitter.setMaxListeners(n) 的当前最大侦听器值,或默认值为 events.defaultMaxListeners。

function getMaxListeners(): number

返回

number

继承自 Stream.getMaxListeners

pipe<T>(T, PipeOptions)

function pipe<T>(destination: T, options?: PipeOptions): T

参数

destination

T

options

PipeOptions

返回

T

继承自 Stream.pipe

setMaxListeners(number)

默认情况下,如果为特定事件添加了多个 EventEmitter 侦听器,10将打印警告。 这是一个有用的默认值,可帮助查找内存泄漏。 emitter.setMaxListeners() 方法允许修改此特定 EventEmitter 实例的限制。 该值可以设置为 Infinity(或 0),以指示无限数量的侦听器。

返回对 EventEmitter的引用,以便可以链接调用。

function setMaxListeners(n: number): this

参数

n

number

返回

this

继承自 Stream.setMaxListeners

[captureRejectionSymbol](Error, string | symbol, any[])

Symbol.for('nodejs.rejection')该方法用于在发射事件时发生承诺拒绝,并且captureRejections在发射端被启用时调用。 可以用 events.captureRejectionSymbol 代替 Symbol.for('nodejs.rejection')。

import { EventEmitter, captureRejectionSymbol } from 'node:events';

class MyClass extends EventEmitter {
  constructor() {
    super({ captureRejections: true });
  }

  [captureRejectionSymbol](err, event, ...args) {
    console.log('rejection happened for', event, 'with', err, ...args);
    this.destroy(err);
  }

  destroy(err) {
    // Tear the resource down here.
  }
}
function [captureRejectionSymbol](error: Error, event: string | symbol, args: any[])

参数

error

Error

event

string | symbol

args

any[]

继承自 Stream。[捕获拒绝符号]