Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dex4er/js-promise-readable
Return promise for readable stream
https://github.com/dex4er/js-promise-readable
Last synced: about 2 months ago
JSON representation
Return promise for readable stream
- Host: GitHub
- URL: https://github.com/dex4er/js-promise-readable
- Owner: dex4er
- License: mit
- Created: 2017-03-08T19:36:57.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-10-23T17:13:19.000Z (2 months ago)
- Last Synced: 2024-10-25T12:04:08.132Z (2 months ago)
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/promise-readable
- Size: 183 KB
- Stars: 10
- Watchers: 2
- Forks: 4
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# promise-readable
[](https://github.com/dex4er/js-promise-readable)
[](https://github.com/dex4er/js-promise-readable/actions/workflows/ci.yaml)
[](https://github.com/dex4er/js-promise-readable/actions/workflows/trunk.yaml)
[](https://coveralls.io/github/dex4er/js-promise-readable)
[](https://www.npmjs.com/package/promise-readable)
This module allows to convert
[`Readable`](https://nodejs.org/api/stream.html#stream_class_stream_readable)
stream into its promisified version, which returns
[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
object fulfilled when [`open`](https://nodejs.org/api/fs.html#fs_event_open),
[`data`](https://nodejs.org/api/stream.html#stream_event_data),
[`close`](https://nodejs.org/api/fs.html#fs_event_close),
[`end`](https://nodejs.org/api/stream.html#stream_event_end) or
[`error`](https://nodejs.org/api/stream.html#stream_event_error_1) events
occurred.
The promisified stream provides an async iterator so it is possible to use it
with [`for await...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of)
statement.
## Requirements
This module requires Node >= 16.
## Installation
```shell
npm install promise-readable
```
_Additionally for Typescript:_
```shell
npm install -D @types/node
```
## Usage
```js
import PromiseReadable from "promise-readable"
```
### constructor
```js
const promiseReadable = new PromiseReadable(stream)
```
`PromiseReadable` object requires `Readable` object to work.
_Example:_
```js
import fs from "node:fs"
import PromiseReadable from "promise-readable"
const stream = fs.createReadStream("/etc/hosts")
const promiseReadable = new PromiseReadable(stream)
```
### stream
```js
const stream = promiseReadable.stream
```
Original stream object.
_Example:_
```js
console.log(promiseReadable.stream.flags)
```
### read
```js
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:_
```js
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:_
```js
for (let chunk; (chunk = await promiseReadable.read()); ) {
console.log(chunk.length)
}
console.log("stream is ended")
```
### readAll
```js
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
```js
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:_
```js
const asBuffer = await promiseReadable.read()
promiseReadable.setEncoding("utf8")
const asString = await promiseReadable.read()
```
### once
```js
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:_
```js
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") // throws error, undefined if ended
```
### iterate
```js
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
```js
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
```js
promiseReadable = promiseReadable.destroy()
```
This method calls `destroy` method on stream and cleans up all own handlers.
The method returns this object.
## See also
[`PromiseWritable`](https://www.npmjs.com/package/promise-writable),
[`PromiseDuplex`](https://www.npmjs.com/package/promise-duplex),
[`PromiseSocket`](https://www.npmjs.com/package/promise-socket),
[`PromisePiping`](https://www.npmjs.com/package/promise-piping).
## License
Copyright (c) 2017-2024 Piotr Roszatycki
[MIT](https://opensource.org/licenses/MIT)