Readable interface

Pacote:: @azure/storage-common

Extends: Stream

Propriedades

closed	É `true` depois `'close'` de ter sido emitido.
destroyed	É `true` depois `readable.destroy()` de ter sido chamado.
errored	Devolve erro se o fluxo tiver sido destruído com um erro.
readable	É `true` se for seguro chamar read, o que significa que o fluxo não foi destruído ou emitido `'error'` ou `'end'`.
readableAborted	Devolve se o fluxo foi destruído ou cometeu erro antes de emitir `'end'`.
readableDidRead	Devolve se `'data'` foi emitido.
readableEncoding	Getter para a propriedade `encoding` de um dado `Readable` riacho. A `encoding` propriedade pode ser definida usando o método setEncoding .
readableEnded	Torna-se `true` quando `'end'` o evento é emitido.
readableFlowing	Esta propriedade reflete o estado atual de um `Readable` curso de água conforme descrito na secção dos Três estados .
readableHighWaterMark	Devolve o valor de `highWaterMark` passado ao criar este `Readable`.
readableLength	Esta propriedade contém o número de bytes (ou objetos) na fila prontos para serem lidos. O valor fornece dados de introspeção relativamente ao estado do `highWaterMark`.
readableObjectMode	Getter para a propriedade `objectMode` de um dado `Readable` riacho.

Métodos

addListener(string \| symbol, (args: any[]) => void)
addListener<E>(E, (args: ReadableEventMap[E]) => void)	Alias para `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)` é equivalente a `stream.compose(readable, s)`. Este método também permite fornecer um `AbortSignal` , que destruirá o fluxo composto quando abortado. Veja `stream.compose(...streams)` para obter mais informações.
destroy(Error)	Destrua o fluxo. Opcionalmente, emita um `'error'` evento e emita um `'close'` evento (a menos que `emitClose` esteja definido para `false`). Após esta chamada, o fluxo legível libertará quaisquer recursos internos e as chamadas subsequentes serão `push()` ignoradas. Uma vez `destroy()` chamado, quaisquer chamadas adicionais serão no-op e nenhum erro adicional, exceto from, `_destroy()` poderá ser emitido como `'error'`. Os implementadores não devem sobrepor este método, mas sim implementar `readable._destroy()`.
drop(number, Abortable)	Este método devolve um novo fluxo com os primeiros blocos de limite eliminados desde o início.
emit(string \| symbol, any[])
emit<E>(E, ReadableEventMap[E])	Chama de forma síncrona cada um dos ouvintes registrados para o evento chamado `eventName`, na ordem em que foram registrados, passando os argumentos fornecidos para cada um. Retorna `true` se o evento teve ouvintes `false` caso contrário. 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">)	Este método é semelhante a `Array.prototype.every` e chama fn em cada bloco do fluxo para verificar se todos os valores de retorno aguardados são valores truthy para fn. Uma vez que uma chamada fn num valor de retorno ed `await`chunk for falsa, o fluxo é destruído e a promessa é cumprida com `false`. Se todas as chamadas fn nos chunks devolverem um valor truthy, a promessa é cumprida com `true`.
filter((data: any, options?: Abortable) => boolean \| Promise<boolean>, ReadableOperatorOptions)	Este método permite filtrar o fluxo. Para cada chunk no fluxo, a função fn será chamada e, se devolver um valor truthy, o chunk será passado para o fluxo resultante. Se a função fn devolver uma promessa – essa promessa será `await`ed.
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">)	Este método é semelhante a `Array.prototype.find` e chama fn em cada bloco do fluxo para encontrar um bloco com um valor truthy para fn. Quando o valor de retorno aguardado de uma chamada fn é truthy, o stream é destruído e a promessa é cumprida com valor para o qual fn devolveu um valor truthy. Se todas as chamadas fn nos chunks devolverem um valor falso, a promessa é cumprida com `undefined`.
flatMap((data: any, options?: Abortable) => any, Pick<ReadableOperatorOptions, "concurrency" \| "signal">)	Este método devolve um novo fluxo aplicando o callback dado a cada bloco do fluxo e depois achatando o resultado. É possível devolver um fluxo ou outro iterável iterável ou assíncrono a partir do fn e os fluxos resultantes serão fundidos (achatados) no fluxo devolvido.
forEach((data: any, options?: Abortable) => void \| Promise<void>, Pick<ReadableOperatorOptions, "concurrency" \| "signal">)	Este método permite iterar um fluxo. Para cada bloco no fluxo, a função fn será chamada. Se a função fn devolver uma promessa – essa promessa será `await`ed. Este método é diferente dos `for await...of` loops porque pode, opcionalmente, processar chunks em simultâneo. Além disso, uma `forEach` iteração só pode ser interrompida passando uma `signal` opção e abortando o AbortController relacionado, enquanto `for await...of` pode ser interrompida com `break` ou `return`. Em qualquer dos casos, o riacho será destruído. Este método difere de ouvir o `'data'` evento, pois utiliza o `readable` evento na maquinaria subjacente e pode limitar o número de chamadas fn simultâneas.
isPaused()	O `readable.isPaused()` método devolve o estado operacional atual do `Readable`. Isto é usado principalmente pelo mecanismo que sustenta o `readable.pipe()` método. Na maioria dos casos típicos, não haverá razão para usar este método diretamente. `const readable = new stream.Readable(); readable.isPaused(); // === false readable.pause(); readable.isPaused(); // === true readable.resume(); readable.isPaused(); // === false`
iterator(ReadableIteratorOptions)	O iterador criado por este método dá aos utilizadores a opção de cancelar a destruição do fluxo se o `for await...of` ciclo for encerrado por `return`, `break`, ou `throw`, ou se o iterador destruir o fluxo caso este emitisse um erro durante a iteração.
listenerCount(string \| symbol, (args: any[]) => void)
listenerCount<E>(E, (args: ReadableEventMap[E]) => void)	Retorna o número de ouvintes ouvindo o evento chamado `eventName`. Se `listener` for fornecido, ele retornará quantas vezes o ouvinte é encontrado na lista dos ouvintes do evento.
listeners(string \| symbol)
listeners<E>(E)	Retorna uma cópia da matriz de ouvintes para o evento chamado `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)	Este método permite mapear sobre o riacho. A função fn será chamada para cada bloco do fluxo. Se a função fn devolver uma promessa - essa promessa será `await`ed antes de ser passada para o fluxo de resultados.
off(string \| symbol, (args: any[]) => void)
off<E>(E, (args: ReadableEventMap[E]) => void)	Alias para `emitter.removeListener()`.
on(string \| symbol, (args: any[]) => void)
on<E>(E, (args: ReadableEventMap[E]) => void)	Adiciona a função `listener` ao final da matriz de ouvintes do evento chamado `eventName`. Nenhuma verificação é feita para ver se o `listener` já foi adicionado. Várias chamadas que passam a mesma combinação de `eventName` e `listener` resultarão no `listener` sendo adicionado e chamado várias vezes. `server.on('connection', (stream) => { console.log('someone connected!'); });` Retorna uma referência ao `EventEmitter`, para que as chamadas possam ser encadeadas. Por padrão, os ouvintes de eventos são invocados na ordem em que são adicionados. O método `emitter.prependListener()` pode ser usado como uma alternativa para adicionar o ouvinte de eventos ao início da matriz de ouvintes. `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)	Adiciona uma função`listener` única para o evento chamado `eventName`. Na próxima vez que `eventName` for acionado, esse ouvinte será removido e, em seguida, invocado. `server.once('connection', (stream) => { console.log('Ah, we have our first user!'); });` Retorna uma referência ao `EventEmitter`, para que as chamadas possam ser encadeadas. Por padrão, os ouvintes de eventos são invocados na ordem em que são adicionados. O método `emitter.prependOnceListener()` pode ser usado como uma alternativa para adicionar o ouvinte de eventos ao início da matriz de ouvintes. `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()	O `readable.pause()` método fará com que um fluxo em modo de fluxo pare de emitir `'data'` eventos, saindo do modo de fluxo. Quaisquer dados que fiquem disponíveis permanecerão no buffer interno. 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); }); O `readable.pause()` método não tem efeito se houver um `'readable'` ouvinte de eventos.
prependListener(string \| symbol, (args: any[]) => void)
prependListener<E>(E, (args: ReadableEventMap[E]) => void)	Adiciona a função ao inicial da matriz listeners para o evento chamado . Nenhuma verificação é feita para ver se o `listener` já foi adicionado. Várias chamadas que passam a mesma combinação de `eventName` e `listener` resultarão no `listener` sendo adicionado e chamado várias vezes. `server.prependListener('connection', (stream) => { console.log('someone connected!'); });` Retorna uma referência ao `EventEmitter`, para que as chamadas possam ser encadeadas.
prependOnceListener(string \| symbol, (args: any[]) => void)
prependOnceListener<E>(E, (args: ReadableEventMap[E]) => void)	Adiciona uma função de única para o evento chamado ao inicial da matriz de ouvintes. Na próxima vez que `eventName` for acionado, esse ouvinte será removido e, em seguida, invocado. `server.prependOnceListener('connection', (stream) => { console.log('Ah, we have our first user!'); });` Retorna uma referência ao `EventEmitter`, para que as chamadas possam ser encadeadas.
push(any, BufferEncoding)
rawListeners(string \| symbol)
rawListeners<E>(E)	Retorna uma cópia da matriz de ouvintes para o evento chamado `eventName`, incluindo quaisquer wrappers (como os criados por `.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)	O `readable.read()` método lê dados do buffer interno e devolve-os. Se não houver dados disponíveis para leitura, `null` é devolvido. Por defeito, os dados são devolvidos como objeto `Buffer` , a menos que uma codificação tenha sido especificada usando o `readable.setEncoding()` método ou que o fluxo esteja a operar em modo objeto. O argumento opcional `size` especifica um número específico de bytes a ler. Se `size` os bytes não estiverem disponíveis para leitura, `null` serão devolvidos a menos que o fluxo tenha terminado, caso em que todos os dados restantes no buffer interno serão devolvidos. Se o `size` argumento não for especificado, todos os dados contidos no buffer interno serão devolvidos. O `size` argumento deve ser menor ou igual a 1 GiB. O `readable.read()` método deve ser chamado apenas em `Readable` fluxos que operam em modo pausado. No modo de fluxo, `readable.read()` é chamado automaticamente até que o buffer interno esteja totalmente drenado. 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.'); }); Cada chamada para `readable.read()` devolve um bloco de dados, ou `null`. Os chunks não são concatenados. É necessário um `while` ciclo para consumir todos os dados atualmente no buffer. Ao ler, um ficheiro `.read()` grande pode devolver `null`, tendo consumido todo o conteúdo armazenado até agora, mas ainda há mais dados por vir, ainda não armazenados. Neste caso, um novo `'readable'` evento será emitido quando houver mais dados no buffer. Finalmente, o `'end'` evento será emitido quando não houver mais dados disponíveis. Portanto, para ler todo o conteúdo de um ficheiro a partir de um `readable`, é necessário recolher blocos de múltiplos `'readable'` eventos: `const chunks = []; readable.on('readable', () => { let chunk; while (null !== (chunk = readable.read())) { chunks.push(chunk); } }); readable.on('end', () => { const content = chunks.join(''); });` Um `Readable` fluxo em modo objeto devolverá sempre um único item de uma chamada para `readable.read(size)`, independentemente do valor do `size` argumento. Se o `readable.read()` método devolver um bloco de dados, também será emitido um `'data'` evento. A chamada de leitura após o `'end'` evento ter sido emitido retornará `null`. Não será apresentado nenhum erro de execução.
reduce<T>((previous: any, data: any, options?: Abortable) => T)	Este método chama fn em cada bloco do fluxo por ordem, passando-lhe o resultado do cálculo no elemento anterior. Devolve uma promessa do valor final da redução. Se não for fornecido valor inicial , o primeiro bloco do fluxo é usado como valor inicial. Se o fluxo estiver vazio, a promessa é rejeitada com a `TypeErrorERR_INVALID_ARGS` propriedade de código. A função redutora itera o fluxo elemento a elemento, o que significa que não existe parâmetro de concorrência nem paralelismo. Para realizar uma redução simultaneamente, pode extrair a função assíncrona do `readable.map` método.
reduce<T>((previous: T, data: any, options?: Abortable) => T, T, Abortable)
removeAllListeners(string \| symbol)
removeAllListeners<E>(E)	Remove todos os ouvintes ou os do `eventName`especificado. É uma má prática remover ouvintes adicionados em outro lugar no código, particularmente quando a instância `EventEmitter` foi criada por algum outro componente ou módulo (por exemplo, soquetes ou fluxos de arquivos). Retorna uma referência ao `EventEmitter`, para que as chamadas possam ser encadeadas.
removeListener(string \| symbol, (args: any[]) => void)
removeListener<E>(E, (args: ReadableEventMap[E]) => void)	Remove o `listener` especificado da matriz de ouvinte do evento chamado `eventName`. `const callback = (stream) => { console.log('someone connected!'); }; server.on('connection', callback); // ... server.removeListener('connection', callback);` `removeListener()` removerá, no máximo, uma instância de um ouvinte da matriz do ouvinte. Se qualquer ouvinte tiver sido adicionado várias vezes à matriz de ouvinte para o `eventName`especificado, `removeListener()` deverá ser chamado várias vezes para remover cada instância. Uma vez que um evento é emitido, todos os ouvintes ligados a ele no momento da emissão são chamados em ordem. Isto implica que quaisquer `removeListener()` chamadas `removeAllListeners()`de ou após a emissão e antes do último ouvinte terminar a execução não as removerá do `emit()` processo em andamento. Os acontecimentos subsequentes comportam-se como esperado. 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 Como os ouvintes são geridos através de um array interno, chamar isto altera os índices de posição de qualquer ouvinte registado após a remoção do ouvinte. Isso não afetará a ordem na qual os ouvintes são chamados, mas significa que todas as cópias da matriz de ouvintes retornadas pelo método `emitter.listeners()` precisarão ser recriadas. Quando uma única função tiver sido adicionada como manipulador várias vezes para um único evento (como no exemplo abaixo), `removeListener()` removerá a instância adicionada mais recentemente. No exemplo, o ouvinte `once('ping')` é removido: `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');` Retorna uma referência ao `EventEmitter`, para que as chamadas possam ser encadeadas.
resume()	O `readable.resume()` método faz com que um fluxo explicitamente `Readable` pausado retome a `'data'` emissão de eventos, mudando o fluxo para modo de fluxo. O `readable.resume()` método pode ser usado para consumir totalmente os dados de um fluxo sem realmente processar nenhum desses dados: `getReadableStreamSomehow() .resume() .on('end', () => { console.log('Reached the end, but did not read anything.'); });` O `readable.resume()` método não tem efeito se houver um `'readable'` ouvinte de eventos.
setEncoding(BufferEncoding)	O `readable.setEncoding()` método define a codificação de caracteres para os dados lidos do `Readable` fluxo. Por defeito, não é atribuída codificação e os dados do fluxo serão devolvidos como `Buffer` objetos. Definir uma codificação faz com que os dados do fluxo sejam devolvidos como cadeias da codificação especificada em vez de como `Buffer` objetos. Por exemplo, ao chamar `readable.setEncoding('utf8')` , os dados de saída são interpretados como dados UTF-8 e passados como strings. A chamada `readable.setEncoding('hex')` fará com que os dados sejam codificados em formato de string hexadecimal. O `Readable` fluxo lida corretamente com caracteres multibyte entregues através do fluxo que, de outra forma, seriam decodificados incorretamente se simplesmente puxados do fluxo como `Buffer` objetos. `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">)	Este método é semelhante a `Array.prototype.some` e chama fn em cada bloco do fluxo até que o valor de retorno aguardado seja `true` (ou qualquer valor truthy). Uma vez que uma chamada fn num valor de retorno de chunk `await`ed é verdadeira, o fluxo é destruído e a promessa é cumprida com `true`. Se nenhum dos fn calls nos chunks devolver um valor truthy, a promessa é cumprida com `false`.
take(number, Abortable)	Este método devolve um novo fluxo com os primeiros blocos limite .
toArray(Abortable)	Este método permite obter facilmente o conteúdo de um fluxo. Como este método lê todo o fluxo na memória, anula os benefícios dos fluxos. Destina-se à interoperabilidade e conveniência, não a principal forma de consumir streams.
unpipe(WritableStream)	O `readable.unpipe()` método destaca um `Writable` jato previamente ligado usando o método do tubo . Se o `destination` não for especificado, então todos os tubos são destacados. Se o `destination` for especificado, mas não estiver configurado nenhum tubo para isso, então o método não faz nada. `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)	Passar `chunk` como `null` sinaliza o fim do fluxo (EOF) e comporta-se da mesma forma que `readable.push(null)`, após o que não podem ser escritos mais dados. O sinal EOF é colocado no final do buffer e quaisquer dados armazenados em buffer continuam a ser eliminados. O `readable.unshift()` método empurra um pedaço de dados de volta para o buffer interno. Isto é útil em certas situações em que um fluxo está a ser consumido por código que precisa de "desconsumir" uma certa quantidade de dados que otimisticamente retirou da fonte, para que os dados possam ser transmitidos a outra parte. O `stream.unshift(chunk)` método não pode ser chamado depois de o `'end'` evento ter sido emitido, caso contrário será lançado um erro em tempo de execução. Os programadores que usam `stream.unshift()` frequentemente devem considerar mudar para o uso de um `Transform` stream em vez disso. Consulte a `API for stream implementers` secção para mais informações. // 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; } } } Ao contrário do push, `stream.unshift(chunk)` não termina o processo de leitura ao reiniciar o estado interno de leitura do fluxo. Isto pode causar resultados inesperados se `readable.unshift()` for chamado durante uma leitura (ou seja, a partir de uma implementação _read num fluxo personalizado). Seguir a chamada `readable.unshift()` com um push imediato irá reiniciar o estado de leitura corretamente, no entanto, é melhor simplesmente evitar ligar `readable.unshift()` durante o processo de leitura.
wrap(ReadableStream)	Antes do Node.js 0.10, os fluxos não implementavam toda `node:stream` a API do módulo tal como está atualmente definida. (Ver `Compatibility` para mais informações.) Ao usar uma biblioteca Node.js antiga que emite `'data'` eventos e tem um método de pausa apenas consultivo, o `readable.wrap()` método pode ser usado para criar um `Readable` fluxo que utiliza o fluxo antigo como fonte de dados. Raramente será necessário utilizá-lo `readable.wrap()` , mas o método foi disponibilizado como uma conveniência para interagir com aplicações e bibliotecas Node.js mais antigas. `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]()	Liga `readable.destroy()` com um `AbortError` e retorna uma promessa que se cumpre quando a transmissão termina.
[asyncIterator]()
[toAsyncStreamable]()	Quando a `--experimental-stream-iter` flag está ativada, `Readable` os fluxos implementam o `Stream.toAsyncStreamable` protocolo, permitindo um consumo eficiente pela `stream/iter` API. Isto fornece um iterador assíncrono em lote que drena o buffer interno do fluxo em `Uint8Array[]` lotes, amortizando a sobrecarga Promise por bloco do caminho padrão `Symbol.asyncIterator` . Para fluxos em modo byte, os chunks são fornecidos diretamente como `Buffer` instâncias (que são `Uint8Array` subclasses). Para fluxos em modo objeto ou codificados, cada bloco é normalizado para `Uint8Array` antes de ser agrupado. O iterador devolvido é marcado como fonte validada, pelo que `from()` o passa sem normalização adicional. `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'` Sem a `--experimental-stream-iter` bandeira, chamar este método lança `ERR_STREAM_ITER_MISSING_FLAG`.

Métodos Herdados

eventNames()	Retorna uma matriz listando os eventos para os quais o emissor registrou ouvintes. `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()	Retorna o valor máximo de ouvinte atual para o `EventEmitter` que é definido por `emitter.setMaxListeners(n)` ou padrão como `events.defaultMaxListeners`.
pipe<T>(T, PipeOptions)
setMaxListeners(number)	Por padrão`EventEmitter`s imprimirá um aviso se mais de `10` ouvintes forem adicionados para um evento específico. Este é um padrão útil que ajuda a encontrar vazamentos de memória. O método `emitter.setMaxListeners()` permite que o limite seja modificado para esta instância `EventEmitter` específica. O valor pode ser definido como `Infinity` (ou `0`) para indicar um número ilimitado de ouvintes. Retorna uma referência ao `EventEmitter`, para que as chamadas possam ser encadeadas.
[captureRejectionSymbol](Error, string \| symbol, any[])	O `Symbol.for('nodejs.rejection')` método é chamado caso ocorra uma rejeição de promessa ao emitir um evento e `captureRejections` está ativado no emissor. É possível usar `events.captureRejectionSymbol` em vez de `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. } }`

Detalhes de Propriedade

closed

É true depois 'close' de ter sido emitido.

closed: boolean

Valor de Propriedade

boolean

destroyed

É true depois readable.destroy() de ter sido chamado.

destroyed: boolean

Valor de Propriedade

boolean

errored

Devolve erro se o fluxo tiver sido destruído com um erro.

errored: Error | null

Valor de Propriedade

Error | null

readable

É true se for seguro chamar read, o que significa que o fluxo não foi destruído ou emitido 'error' ou 'end'.

readable: boolean

Valor de Propriedade

boolean

readableAborted

Devolve se o fluxo foi destruído ou cometeu erro antes de emitir 'end'.

readableAborted: boolean

Valor de Propriedade

boolean

readableDidRead

Devolve se 'data' foi emitido.

readableDidRead: boolean

Valor de Propriedade

boolean

readableEncoding

Getter para a propriedade encoding de um dado Readable riacho. A encoding propriedade pode ser definida usando o método setEncoding .

readableEncoding: BufferEncoding | null

Valor de Propriedade

BufferEncoding | null

readableEnded

Torna-se true quando 'end' o evento é emitido.

readableEnded: boolean

Valor de Propriedade

boolean

readableFlowing

Esta propriedade reflete o estado atual de um Readable curso de água conforme descrito na secção dos Três estados .

readableFlowing: boolean | null

Valor de Propriedade

boolean | null

readableHighWaterMark

Devolve o valor de highWaterMark passado ao criar este Readable.

readableHighWaterMark: number

Valor de Propriedade

number

readableLength

Esta propriedade contém o número de bytes (ou objetos) na fila prontos para serem lidos. O valor fornece dados de introspeção relativamente ao estado do highWaterMark.

readableLength: number

Valor de Propriedade

number

readableObjectMode

Getter para a propriedade objectMode de um dado Readable riacho.

readableObjectMode: boolean

Valor de Propriedade

boolean

Detalhes de Método

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

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

Parâmetros

eventName: string | symbol

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

Devoluções

this

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

Alias para emitter.on(eventName, listener).

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

Parâmetros

eventName: E

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

Devoluções

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) é equivalente a stream.compose(readable, s).

Este método também permite fornecer um AbortSignal , que destruirá o fluxo composto quando abortado.

Veja stream.compose(...streams) para obter mais informações.

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

Parâmetros

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

options: Abortable

Devoluções

Duplex

um curso de água composto pelo fluxo stream.

destroy(Error)

Destrua o fluxo. Opcionalmente, emita um 'error' evento e emita um 'close' evento (a menos que emitClose esteja definido para false). Após esta chamada, o fluxo legível libertará quaisquer recursos internos e as chamadas subsequentes serão push() ignoradas.

Uma vez destroy() chamado, quaisquer chamadas adicionais serão no-op e nenhum erro adicional, exceto from, _destroy() poderá ser emitido como 'error'.

Os implementadores não devem sobrepor este método, mas sim implementar readable._destroy().

function destroy(error?: Error): this

Parâmetros

error: Error

Erro que será transmitido como carga útil em 'error' caso de

Devoluções

this

drop(number, Abortable)

Este método devolve um novo fluxo com os primeiros blocos de limite eliminados desde o início.

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

Parâmetros

limit: number

O número de blocos a eliminar do legível.

options: Abortable

Devoluções

Readable

um stream com blocos de limite descartados desde o início.

emit(string | symbol, any[])

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

Parâmetros

eventName: string | symbol

args: any[]

Devoluções

boolean

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

Chama de forma síncrona cada um dos ouvintes registrados para o evento chamado eventName, na ordem em que foram registrados, passando os argumentos fornecidos para cada um.

Retorna true se o evento teve ouvintes false caso contrário.

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

Parâmetros

eventName: E

args: ReadableEventMap[E]

Devoluções

boolean

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

Este método é semelhante a Array.prototype.every e chama fn em cada bloco do fluxo para verificar se todos os valores de retorno aguardados são valores truthy para fn. Uma vez que uma chamada fn num valor de retorno ed awaitchunk for falsa, o fluxo é destruído e a promessa é cumprida com false. Se todas as chamadas fn nos chunks devolverem um valor truthy, a promessa é cumprida com true.

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

Parâmetros

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

uma função para chamar cada pedaço do fluxo. Assíncrono ou não.

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

Devoluções

Promise<boolean>

Uma promessa que avalia se truea FN devolveu um valor de verdade para cada um dos blocos.

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

Este método permite filtrar o fluxo. Para cada chunk no fluxo, a função fn será chamada e, se devolver um valor truthy, o chunk será passado para o fluxo resultante. Se a função fn devolver uma promessa – essa promessa será awaited.

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

Parâmetros

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

uma função para filtrar blocos do fluxo. Assíncrono ou não.

options: ReadableOperatorOptions

Devoluções

Readable

um fluxo filtrado com o predicado 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>

Parâmetros

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

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

Devoluções

Promise<any>

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

Este método é semelhante a Array.prototype.find e chama fn em cada bloco do fluxo para encontrar um bloco com um valor truthy para fn. Quando o valor de retorno aguardado de uma chamada fn é truthy, o stream é destruído e a promessa é cumprida com valor para o qual fn devolveu um valor truthy. Se todas as chamadas fn nos chunks devolverem um valor falso, a promessa é cumprida com undefined.

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

Parâmetros

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

uma função para chamar cada pedaço do fluxo. Assíncrono ou não.

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

Devoluções

Promise<T | undefined>

uma promessa avaliada para o primeiro bloco para o qual fn avaliou com um valor truthy, ou undefined se não foi encontrado nenhum elemento.

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

Este método devolve um novo fluxo aplicando o callback dado a cada bloco do fluxo e depois achatando o resultado.

É possível devolver um fluxo ou outro iterável iterável ou assíncrono a partir do fn e os fluxos resultantes serão fundidos (achatados) no fluxo devolvido.

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

Parâmetros

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

uma função para mapear cada bloco do fluxo. Pode ser assíncrono. Pode ser um fluxo de água ou gerador.

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

Devoluções

Readable

um fluxo mapeado planamente com a função fn.

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

Este método permite iterar um fluxo. Para cada bloco no fluxo, a função fn será chamada. Se a função fn devolver uma promessa – essa promessa será awaited.

Este método é diferente dos for await...of loops porque pode, opcionalmente, processar chunks em simultâneo. Além disso, uma forEach iteração só pode ser interrompida passando uma signal opção e abortando o AbortController relacionado, enquanto for await...of pode ser interrompida com break ou return. Em qualquer dos casos, o riacho será destruído.

Este método difere de ouvir o 'data' evento, pois utiliza o readable evento na maquinaria subjacente e pode limitar o número de chamadas fn simultâneas.

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

Parâmetros

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

uma função para chamar cada pedaço do fluxo. Assíncrono ou não.

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

Devoluções

Promise<void>

uma promessa para quando a transmissão terminar.

isPaused()

O readable.isPaused() método devolve o estado operacional atual do Readable. Isto é usado principalmente pelo mecanismo que sustenta o readable.pipe() método. Na maioria dos casos típicos, não haverá razão para usar este método diretamente.

const readable = new stream.Readable();

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

function isPaused(): boolean

Devoluções

boolean

iterator(ReadableIteratorOptions)

O iterador criado por este método dá aos utilizadores a opção de cancelar a destruição do fluxo se o for await...of ciclo for encerrado por return, break, ou throw, ou se o iterador destruir o fluxo caso este emitisse um erro durante a iteração.

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

Parâmetros

options: ReadableIteratorOptions

Devoluções

AsyncIterator<any>

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

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

Parâmetros

eventName: string | symbol

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

Devoluções

number

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

Retorna o número de ouvintes ouvindo o evento chamado eventName. Se listener for fornecido, ele retornará quantas vezes o ouvinte é encontrado na lista dos ouvintes do evento.

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

Parâmetros

eventName: E

O nome do evento que está sendo escutado

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

A função de manipulador de eventos

Devoluções

number

listeners(string | symbol)

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

Parâmetros

eventName: string | symbol

Devoluções

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

listeners<E>(E)

Retorna uma cópia da matriz de ouvintes para o evento chamado 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[]

Parâmetros

eventName: E

Devoluções

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

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

Este método permite mapear sobre o riacho. A função fn será chamada para cada bloco do fluxo. Se a função fn devolver uma promessa - essa promessa será awaited antes de ser passada para o fluxo de resultados.

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

Parâmetros

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

uma função para mapear cada bloco do fluxo. Assíncrono ou não.

options: ReadableOperatorOptions

Devoluções

Readable

um fluxo mapeado com a função fn.

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

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

Parâmetros

eventName: string | symbol

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

Devoluções

this

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

Alias para emitter.removeListener().

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

Parâmetros

eventName: E

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

Devoluções

this

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

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

Parâmetros

eventName: string | symbol

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

Devoluções

this

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

Adiciona a função listener ao final da matriz de ouvintes do evento chamado eventName. Nenhuma verificação é feita para ver se o listener já foi adicionado. Várias chamadas que passam a mesma combinação de eventName e listener resultarão no listener sendo adicionado e chamado várias vezes.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

Por padrão, os ouvintes de eventos são invocados na ordem em que são adicionados. O método emitter.prependListener() pode ser usado como uma alternativa para adicionar o ouvinte de eventos ao início da matriz de ouvintes.

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

Parâmetros

eventName: E

O nome do evento.

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

A função de retorno de chamada

Devoluções

this

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

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

Parâmetros

eventName: string | symbol

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

Devoluções

this

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

Adiciona uma funçãolistener única para o evento chamado eventName. Na próxima vez que eventName for acionado, esse ouvinte será removido e, em seguida, invocado.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

Por padrão, os ouvintes de eventos são invocados na ordem em que são adicionados. O método emitter.prependOnceListener() pode ser usado como uma alternativa para adicionar o ouvinte de eventos ao início da matriz de ouvintes.

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

Parâmetros

eventName: E

O nome do evento.

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

A função de retorno de chamada

Devoluções

this

pause()

O readable.pause() método fará com que um fluxo em modo de fluxo pare de emitir 'data' eventos, saindo do modo de fluxo. Quaisquer dados que fiquem disponíveis permanecerão no buffer interno.

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);
});

O readable.pause() método não tem efeito se houver um 'readable' ouvinte de eventos.

function pause(): this

Devoluções

this

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

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

Parâmetros

eventName: string | symbol

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

Devoluções

this

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

Adiciona a função ao inicial da matriz listeners para o evento chamado . Nenhuma verificação é feita para ver se o listener já foi adicionado. Várias chamadas que passam a mesma combinação de eventName e listener resultarão no listener sendo adicionado e chamado várias vezes.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

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

Parâmetros

eventName: E

O nome do evento.

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

A função de retorno de chamada

Devoluções

this

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

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

Parâmetros

eventName: string | symbol

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

Devoluções

this

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

Adiciona uma função de única para o evento chamado ao inicial da matriz de ouvintes. Na próxima vez que eventName for acionado, esse ouvinte será removido e, em seguida, invocado.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

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

Parâmetros

eventName: E

O nome do evento.

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

A função de retorno de chamada

Devoluções

this

push(any, BufferEncoding)

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

Parâmetros

chunk: any

encoding: BufferEncoding

Devoluções

boolean

rawListeners(string | symbol)

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

Parâmetros

eventName: string | symbol

Devoluções

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

rawListeners<E>(E)

Retorna uma cópia da matriz de ouvintes para o evento chamado eventName, incluindo quaisquer wrappers (como os criados por .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[]

Parâmetros

eventName: E

Devoluções

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

read(number)

O readable.read() método lê dados do buffer interno e devolve-os. Se não houver dados disponíveis para leitura, null é devolvido. Por defeito, os dados são devolvidos como objeto Buffer , a menos que uma codificação tenha sido especificada usando o readable.setEncoding() método ou que o fluxo esteja a operar em modo objeto.

O argumento opcional size especifica um número específico de bytes a ler. Se size os bytes não estiverem disponíveis para leitura, null serão devolvidos a menos que o fluxo tenha terminado, caso em que todos os dados restantes no buffer interno serão devolvidos.

Se o size argumento não for especificado, todos os dados contidos no buffer interno serão devolvidos.

O size argumento deve ser menor ou igual a 1 GiB.

O readable.read() método deve ser chamado apenas em Readable fluxos que operam em modo pausado. No modo de fluxo, readable.read() é chamado automaticamente até que o buffer interno esteja totalmente drenado.

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.');
});

Cada chamada para readable.read() devolve um bloco de dados, ou null. Os chunks não são concatenados. É necessário um while ciclo para consumir todos os dados atualmente no buffer. Ao ler, um ficheiro .read() grande pode devolver null, tendo consumido todo o conteúdo armazenado até agora, mas ainda há mais dados por vir, ainda não armazenados. Neste caso, um novo 'readable' evento será emitido quando houver mais dados no buffer. Finalmente, o 'end' evento será emitido quando não houver mais dados disponíveis.

Portanto, para ler todo o conteúdo de um ficheiro a partir de um readable, é necessário recolher blocos de múltiplos 'readable' eventos:

const chunks = [];

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

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

Um Readable fluxo em modo objeto devolverá sempre um único item de uma chamada para readable.read(size), independentemente do valor do size argumento.

Se o readable.read() método devolver um bloco de dados, também será emitido um 'data' evento.

A chamada de leitura após o 'end' evento ter sido emitido retornará null. Não será apresentado nenhum erro de execução.

function read(size?: number): any

Parâmetros

size: number

Argumento opcional para especificar quantos dados ler.

Devoluções

any

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

Este método chama fn em cada bloco do fluxo por ordem, passando-lhe o resultado do cálculo no elemento anterior. Devolve uma promessa do valor final da redução.

Se não for fornecido valor inicial , o primeiro bloco do fluxo é usado como valor inicial. Se o fluxo estiver vazio, a promessa é rejeitada com a TypeErrorERR_INVALID_ARGS propriedade de código.

A função redutora itera o fluxo elemento a elemento, o que significa que não existe parâmetro de concorrência nem paralelismo. Para realizar uma redução simultaneamente, pode extrair a função assíncrona do readable.map método.

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

Parâmetros

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

uma função redutora para chamar todos os blocos do fluxo. Assíncrono ou não.

Devoluções

Promise<T>

uma promessa do valor final da redução.

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>

Parâmetros

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

initial: T

options: Abortable

Devoluções

Promise<T>

removeAllListeners(string | symbol)

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

Parâmetros

eventName: string | symbol

Devoluções

this

removeAllListeners<E>(E)

Remove todos os ouvintes ou os do eventNameespecificado.

É uma má prática remover ouvintes adicionados em outro lugar no código, particularmente quando a instância EventEmitter foi criada por algum outro componente ou módulo (por exemplo, soquetes ou fluxos de arquivos).

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

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

Parâmetros

eventName: E

Devoluções

this

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

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

Parâmetros

eventName: string | symbol

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

Devoluções

this

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

Remove o listener especificado da matriz de ouvinte do evento chamado eventName.

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

removeListener() removerá, no máximo, uma instância de um ouvinte da matriz do ouvinte. Se qualquer ouvinte tiver sido adicionado várias vezes à matriz de ouvinte para o eventNameespecificado, removeListener() deverá ser chamado várias vezes para remover cada instância.

Uma vez que um evento é emitido, todos os ouvintes ligados a ele no momento da emissão são chamados em ordem. Isto implica que quaisquer removeListener() chamadas removeAllListeners()de ou após a emissão e antes do último ouvinte terminar a execução não as removerá do emit() processo em andamento. Os acontecimentos subsequentes comportam-se como esperado.

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

Como os ouvintes são geridos através de um array interno, chamar isto altera os índices de posição de qualquer ouvinte registado após a remoção do ouvinte. Isso não afetará a ordem na qual os ouvintes são chamados, mas significa que todas as cópias da matriz de ouvintes retornadas pelo método emitter.listeners() precisarão ser recriadas.

Quando uma única função tiver sido adicionada como manipulador várias vezes para um único evento (como no exemplo abaixo), removeListener() removerá a instância adicionada mais recentemente. No exemplo, o ouvinte once('ping') é removido:

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');

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

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

Parâmetros

eventName: E

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

Devoluções

this

resume()

O readable.resume() método faz com que um fluxo explicitamente Readable pausado retome a 'data' emissão de eventos, mudando o fluxo para modo de fluxo.

O readable.resume() método pode ser usado para consumir totalmente os dados de um fluxo sem realmente processar nenhum desses dados:

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

O readable.resume() método não tem efeito se houver um 'readable' ouvinte de eventos.

function resume(): this

Devoluções

this

setEncoding(BufferEncoding)

O readable.setEncoding() método define a codificação de caracteres para os dados lidos do Readable fluxo.

Por defeito, não é atribuída codificação e os dados do fluxo serão devolvidos como Buffer objetos. Definir uma codificação faz com que os dados do fluxo sejam devolvidos como cadeias da codificação especificada em vez de como Buffer objetos. Por exemplo, ao chamar readable.setEncoding('utf8') , os dados de saída são interpretados como dados UTF-8 e passados como strings. A chamada readable.setEncoding('hex') fará com que os dados sejam codificados em formato de string hexadecimal.

O Readable fluxo lida corretamente com caracteres multibyte entregues através do fluxo que, de outra forma, seriam decodificados incorretamente se simplesmente puxados do fluxo como Buffer objetos.

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

Parâmetros

encoding: BufferEncoding

A codificação a usar.

Devoluções

this

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

Este método é semelhante a Array.prototype.some e chama fn em cada bloco do fluxo até que o valor de retorno aguardado seja true (ou qualquer valor truthy). Uma vez que uma chamada fn num valor de retorno de chunk awaited é verdadeira, o fluxo é destruído e a promessa é cumprida com true. Se nenhum dos fn calls nos chunks devolver um valor truthy, a promessa é cumprida com false.

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

Parâmetros

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

uma função para chamar cada pedaço do fluxo. Assíncrono ou não.

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

Devoluções

Promise<boolean>

Uma promessa que avalia se trueo FN devolveu um valor truthy para pelo menos um dos chunks.

take(number, Abortable)

Este método devolve um novo fluxo com os primeiros blocos limite .

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

Parâmetros

limit: number

O número de blocos a retirar do legível.

options: Abortable

Devoluções

Readable

um stream com blocos de limite ocupados.

toArray(Abortable)

Este método permite obter facilmente o conteúdo de um fluxo.

Como este método lê todo o fluxo na memória, anula os benefícios dos fluxos. Destina-se à interoperabilidade e conveniência, não a principal forma de consumir streams.

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

Parâmetros

options: Abortable

Devoluções

Promise<any[]>

uma promessa contendo um array com o conteúdo do fluxo.

unpipe(WritableStream)

O readable.unpipe() método destaca um Writable jato previamente ligado usando o método do tubo .

Se o destination não for especificado, então todos os tubos são destacados.

Se o destination for especificado, mas não estiver configurado nenhum tubo para isso, então o método não faz nada.

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

Parâmetros

destination: WritableStream

Fluxo específico opcional para despipear

Devoluções

this

unshift(any, BufferEncoding)

Passar chunk como null sinaliza o fim do fluxo (EOF) e comporta-se da mesma forma que readable.push(null), após o que não podem ser escritos mais dados. O sinal EOF é colocado no final do buffer e quaisquer dados armazenados em buffer continuam a ser eliminados.

O readable.unshift() método empurra um pedaço de dados de volta para o buffer interno. Isto é útil em certas situações em que um fluxo está a ser consumido por código que precisa de "desconsumir" uma certa quantidade de dados que otimisticamente retirou da fonte, para que os dados possam ser transmitidos a outra parte.

O stream.unshift(chunk) método não pode ser chamado depois de o 'end' evento ter sido emitido, caso contrário será lançado um erro em tempo de execução.

Os programadores que usam stream.unshift() frequentemente devem considerar mudar para o uso de um Transform stream em vez disso. Consulte a API for stream implementers secção para mais informações.

// 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;
    }
  }
}

Ao contrário do push, stream.unshift(chunk) não termina o processo de leitura ao reiniciar o estado interno de leitura do fluxo. Isto pode causar resultados inesperados se readable.unshift() for chamado durante uma leitura (ou seja, a partir de uma implementação _read num fluxo personalizado). Seguir a chamada readable.unshift() com um push imediato irá reiniciar o estado de leitura corretamente, no entanto, é melhor simplesmente evitar ligar readable.unshift() durante o processo de leitura.

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

Parâmetros

chunk: any

Pedaço de dados para deslocar para a fila de leitura. Para fluxos que não operam em modo objeto, chunk deve ser uma {string}, {Buffer}, {TypedArray}, {DataView} ou null. Para fluxos em modo objeto, chunk pode ser qualquer valor JavaScript.

encoding: BufferEncoding

Codificação de blocos de cadeia. Deve ser uma codificação válida Buffer , como 'utf8' ou 'ascii'.

wrap(ReadableStream)

Antes do Node.js 0.10, os fluxos não implementavam toda node:stream a API do módulo tal como está atualmente definida. (Ver Compatibility para mais informações.)

Ao usar uma biblioteca Node.js antiga que emite 'data' eventos e tem um método de pausa apenas consultivo, o readable.wrap() método pode ser usado para criar um Readable fluxo que utiliza o fluxo antigo como fonte de dados.

Raramente será necessário utilizá-lo readable.wrap() , mas o método foi disponibilizado como uma conveniência para interagir com aplicações e bibliotecas Node.js mais antigas.

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

Parâmetros

stream: ReadableStream

Um fluxo legível de "estilo antigo"

Devoluções

this

[asyncDispose]()

Liga readable.destroy() com um AbortError e retorna uma promessa que se cumpre quando a transmissão termina.

function [asyncDispose](): Promise<void>

Devoluções

Promise<void>

[asyncIterator]()

function [asyncIterator](): AsyncIterator<any>

Devoluções

AsyncIterator<any>

AsyncIterator para consumir totalmente o fluxo.

[toAsyncStreamable]()

Quando a --experimental-stream-iter flag está ativada, Readable os fluxos implementam o Stream.toAsyncStreamable protocolo, permitindo um consumo eficiente pela stream/iter API.

Isto fornece um iterador assíncrono em lote que drena o buffer interno do fluxo em Uint8Array[] lotes, amortizando a sobrecarga Promise por bloco do caminho padrão Symbol.asyncIterator . Para fluxos em modo byte, os chunks são fornecidos diretamente como Buffer instâncias (que são Uint8Array subclasses). Para fluxos em modo objeto ou codificados, cada bloco é normalizado para Uint8Array antes de ser agrupado.

O iterador devolvido é marcado como fonte validada, pelo que from() o passa sem normalização adicional.

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'

Sem a --experimental-stream-iter bandeira, chamar este método lança ERR_STREAM_ITER_MISSING_FLAG.

function [toAsyncStreamable](): ByteReadableStream

Devoluções

ByteReadableStream

Detalhes do Método Herdado

eventNames()

Retorna uma matriz listando os eventos para os quais o emissor registrou ouvintes.

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)[]

Devoluções

(string | symbol)[]

Herdado de Stream.eventNames

getMaxListeners()

Retorna o valor máximo de ouvinte atual para o EventEmitter que é definido por emitter.setMaxListeners(n) ou padrão como events.defaultMaxListeners.

function getMaxListeners(): number

Devoluções

number

Herdado de Stream.getMaxListeners

pipe<T>(T, PipeOptions)

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

Parâmetros

destination: T

options: PipeOptions

Devoluções

Herdado de Stream.pipe

setMaxListeners(number)

Por padrãoEventEmitters imprimirá um aviso se mais de 10 ouvintes forem adicionados para um evento específico. Este é um padrão útil que ajuda a encontrar vazamentos de memória. O método emitter.setMaxListeners() permite que o limite seja modificado para esta instância EventEmitter específica. O valor pode ser definido como Infinity (ou 0) para indicar um número ilimitado de ouvintes.

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

function setMaxListeners(n: number): this

Parâmetros

n: number

Devoluções

this

Herdado de Stream.setMaxOuvintes

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

O Symbol.for('nodejs.rejection') método é chamado caso ocorra uma rejeição de promessa ao emitir um evento e captureRejections está ativado no emissor. É possível usar events.captureRejectionSymbol em vez de 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[])

Parâmetros

error: Error

event: string | symbol

args: any[]

Herdado de Stream. [capturaSímboloRejeição]