promise-piping
Version:
Return promise for streams piping
125 lines (88 loc) • 3.21 kB
Markdown
# promise-piping
<!-- markdownlint-disable MD013 -->
[](http://travis-ci.org/dex4er/js-promise-piping) [](https://coveralls.io/github/dex4er/js-promise-piping) [](https://www.npmjs.com/package/promise-piping)
<!-- markdownlint-enable MD013 -->
This module allows to convert stacked streams into one
[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
object.
The piping object can be open-ended
[`PromiseReadable`](https://www.npmjs.com/package/promise-readable) object or
[`PromiseWritable`](https://www.npmjs.com/package/promise-writable) object or
close-ended.
The piping object can be build from streams: standard objects or promisified
versions or another piping objects.
## Requirements
This module requires Node >= 4. For Node < 6 `--harmony` flag is required.
## Installation
```shell
npm install promise-piping
```
## Usage
```js
const {
PromiseReadablePiping,
PromiseWritablePiping,
PromisePiping
} = require('promise-piping')
```
or:
```js
const PromisePiping = require('promise-piping')
```
_Typescript:_
```js
import {
PromiseReadablePiping,
PromiseWritablePiping,
PromisePiping
} from 'promise-piping'
```
or:
```js
import PromisePiping from 'promise-piping'
```
### constructor
```js
const readablePiping = new PromiseReadablePiping(readable, duplex...)
const writablePiping = new PromiseWritablePiping(duplex..., writable)
const piping = new PromisePiping(readable, duplex..., writable)
```
_Example:_
```js
const fs = require('fs')
const zlib = require('zlib')
const filein = fs.createReadStream('/etc/hosts')
const fileout = fs.createWriteStream('/tmp/hosts.gz')
const gzip = zlib.createGzip()
const gunzip = zlib.createGunzip()
const readablePiping = new PromiseReadablePiping(filein, gzip, gunzip)
const writablePiping = new PromiseWritablePiping(gzip, fileout)
const piping = new PromisePiping(filein, gzip, fileout)
```
### once
```js
const result = await piping.once(event)
```
This method returns `Promise` which is fulfilled when last stream (first
stream for `end` event) emits event. The result of this event is returned
or `undefined` value if stream is already ended.
The promise will reject on error. Errors in piping are propagated from
intermediate streams to the first stream and the last stream. It means that
operation on piping will be rejected if an error occurs in any of its streams.
_Example:_
```js
await piping.once('finish')
```
### destroy
```js
piping.destroy()
```
This method calls destroy method on stream and cleans up all own handlers.
## See also
[`PromiseReadable`](https://www.npmjs.com/package/promise-readable),
[`PromiseWritable`](https://www.npmjs.com/package/promise-writable),
[`PromiseDuplex`](https://www.npmjs.com/package/promise-duplex),
[`PromiseSocket`](https://www.npmjs.com/package/promise-socket).
## License
Copyright (c) 2017-2018 Piotr Roszatycki <mailto:piotr.roszatycki@gmail.com>
[MIT](https://opensource.org/licenses/MIT)