promise-readable
This module allows to convert
Readable
stream into its promisified version, which returns
Promise
object fulfilled when open
,
data
,
close
,
end
or
error
events
occurred.
The promisified stream provides an async iterator so it is possible to use it
with for await...of
statement.
Requirements
This module requires Node >= 16.
Installation
npm install promise-readable
Additionally for Typescript:
npm install -D @types/node
Usage
import PromiseReadable from "promise-readable"
constructor
const promiseReadable = new PromiseReadable(stream)
PromiseReadable
object requires Readable
object to work.
Example:
import fs from "fs"
import PromiseReadable from "promise-readable"
const stream = fs.createReadStream("/etc/hosts")
const promiseReadable = new PromiseReadable(stream)
stream
const stream = promiseReadable.stream
Original stream object.
Example:
console.log(promiseReadable.stream.flags)
read
const chunk = await promiseReadable.read(chunkSize)
This method returns Promise
which is fulfilled when the stream can return
one chunk (by read
method or data
event) or the stream is ended (end
or
close
events).
Example:
const chunk = await promiseReadable.read(1024)
Promise returns chunk data if something has been read or undefined
value if
it is an end of the stream.
Example:
for (let chunk; (chunk = await promiseReadable.read()); ) {
console.log(chunk.length)
}
console.log("stream is ended")
readAll
const content = await promiseReadable.readAll()
This method returns Promise
which is fulfilled when the stream is ended or
closed. It is resolved to undefined
value if the stream is already ended or
closed.
The content from the stream is buffered and then Promise
returns this
concatenated content.
setEncoding
promiseReadable = promiseReadable.setEncoding(encoding)
By default read
and readAll
methods return Buffer
objects.
This method sets the character encoding for data read from the stream. It
might be used if the original stream does not provide encoding
option.
The method returns this object.
Example:
const asBuffer = await promiseReadable.read()
promiseReadable.setEncoding("utf8")
const asString = await promiseReadable.read()
once
const result = await promiseReadable.once(event)
This method returns Promise
which is fulfilled when the stream emits
event
. The result of this event is returned or `undefined`` value if the
stream has already ended.
The promise will be rejected on error.
Example:
const fd = await promiseReadable.once("open")
promiseReadable.stream.pipe(process.stdout)
await promiseReadable.once("close")
promiseReadable.stream.on("data", chunk => console.log(chunk.length))
await promiseReadable.once("end")
await promiseReadable.once("error")
iterate
for await (const chunk of promiseReadable.iterate(chunkSize)) {
}
This method returns an async iterator which returns the content of the stream
chunk-by-chunk with a defined chunkSize
.
Symbol.asyncIterator
for await (const chunk of promiseReadable) {
}
The PromiseReadable
object is an async iterator that returns the content of
the stream chunk-by-chunk with the default chunkSize
.
destroy
promiseReadable.destroy()
This method calls destroy
method on stream and cleans up all own handlers.
See also
PromiseWritable
,
PromiseDuplex
,
PromiseSocket
,
PromisePiping
.
License
Copyright (c) 2017-2024 Piotr Roszatycki mailto:piotr.roszatycki@gmail.com
MIT