Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dex4er/js-promise-writable
Return promise for writable stream
https://github.com/dex4er/js-promise-writable
Last synced: about 2 months ago
JSON representation
Return promise for writable stream
- Host: GitHub
- URL: https://github.com/dex4er/js-promise-writable
- Owner: dex4er
- License: mit
- Created: 2017-03-10T14:43:52.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-10-23T16:44:34.000Z (2 months ago)
- Last Synced: 2024-10-23T23:28:59.562Z (2 months ago)
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/promise-writable
- Size: 131 KB
- Stars: 5
- Watchers: 2
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# promise-writable
[](https://github.com/dex4er/js-promise-writable)
[](https://github.com/dex4er/js-promise-writable/actions/workflows/ci.yaml)
[](https://github.com/dex4er/js-promise-writable/actions/workflows/trunk.yaml)
[](https://coveralls.io/github/dex4er/js-promise-writable)
[](https://www.npmjs.com/package/promise-writable)
This module allows conversion `Writable` 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),
[`close`](https://nodejs.org/api/fs.html#fs_event_close),
[`pipe`](https://nodejs.org/api/stream.html#stream_event_pipe),
[`unpipe`](https://nodejs.org/api/stream.html#stream_event_unpipe),
[`finish`](https://nodejs.org/api/stream.html#stream_event_finish) or
[`error`](https://nodejs.org/api/stream.html#stream_event_error) events
occurred.
## Requirements
This module requires Node >= 16.
## Installation
```shell
npm install promise-writable
```
_Additionally for Typescript:_
```shell
npm install -D @types/node
```
## Usage
```js
import PromiseWritable from "promise-writable"
```
### constructor
```js
const promiseWritable = new PromiseWritable(stream)
```
`PromiseWritable` object requires `Writable` object to work.
_Example:_
```js
import PromiseWritable from "promise-writable"
import fs from "node:fs"
const stream = fs.createWriteStream("/tmp/test.txt")
const promiseWritable = new PromiseWritable(stream)
```
### stream
```js
const stream = promiseWritable.stream
```
Original stream object.
_Example:_
```js
console.log(promiseWritable.stream.flags)
```
### write
```js
const written = await promiseWritable.write(chunk)
```
This method returns `Promise` which is fulfilled when the stream accepted a
chunk (`write` method returned that stream is still writable or `drain` event
occured) or stream is ended (`finish` event).
Promise resolves to number that counts written bytes.
_Example:_
```js
const written = await promiseWritable.write(new Buffer("foo"))
```
### writeAll
```js
const total = await promiseWritable.writeAll(content, chunkSize)
```
This method returns `Promise` which is fulfilled when the stream accepts
content. This method writes the content chunk by chunk. The default chunk
size is 64 KiB.
Promise resolves to a number that counts written bytes.
_Example:_
```js
const total = await promiseWritable.writeAll(new Buffer("foobarbaz"), 3)
```
### once
```js
await promiseWritable.once(event)
```
This method returns `Promise` which is fulfilled when stream emits `event`. The
result of this event is returned.
Promise resolves to `undefined` value if the stream is already closed or
destroyed.
_Example:_
```js
const fd = await promiseWritable.once("open")
process.stdin(promiseWritable.stream)
await promiseWritable.once("close")
const promise = promiseWritable.once("pipe")
process.stdin.pipe(promiseWritable.stream)
const src = await promise
const promise = promiseWritable.once("unpipe")
process.stdin.unpipe(promiseWritable.stream)
const src = await promise
```
### end
```js
await promiseWritable.end()
```
This method ends the stream and returns `Promise` which is fulfilled when stream
is finished. No value is returned.
### destroy
```js
promiseWritable = promiseWritable.destroy()
```
This method calls `destroy` method on stream and cleans up all own handlers.
The method returns this object.
## See also
[`PromiseReadable`](https://www.npmjs.com/package/promise-readable),
[`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)