# it-pair <!-- omit in toc -->

[![codecov](https://img.shields.io/codecov/c/github/alanshaw/it-pair.svg?style=flat-square)](https://codecov.io/gh/alanshaw/it-pair)
[![CI](https://img.shields.io/github/actions/workflow/status/alanshaw/it-pair/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/alanshaw/it-pair/actions/workflows/js-test-and-release.yml?query=branch%3Amaster)

> pair a source async iterable stream and a sink async iterable stream

## Table of contents <!-- omit in toc -->

- [Install](#install)
  - [Browser `<script>` tag](#browser-script-tag)
- [API Docs](#api-docs)
- [License](#license)
- [Contribution](#contribution)

## Install

```console
$ npm i it-pair
```

### Browser `<script>` tag

Loading this module through a script tag will make it's exports available as `ItPair` in the global namespace.

```html
<script src="https://unpkg.com/it-pair/dist/index.min.js"></script>
```

A pair of {source, sink} streams that are internally connected,
(what goes into the sink comes out the source)

This can be used to construct pipelines that are connected.

```js
import { pipe } from 'it-pipe'
import { pair } from 'it-pair'

var p = pair()

//read values into this sink...
pipe([1, 2, 3], p.sink)

//but that should become the source over here.
const values = await pipe(p.source, async source => {
  const values = []
  for await (const value of source) {
    values.push(value)
  }
  return value
})

console.log(values) //[1, 2, 3]
```

This is particularly useful for creating duplex streams especially
around servers. Use `it-pair/duplex` to get two duplex streams
that are attached to each other.

```js
import { duplexPair } from 'it-pair/duplex'

var d = duplexPair()

//the "client": pipe to the first duplex and get the response.
pipe(
  [1,2,3],
  d[0],
  source => {
    for await (value of source) {
      console.log(value) // => 10, 20, 30
    }
  }
)

//the "server": pipe from the second stream back to itself
//(in this case) appling a transformation.
pipe(
  d[1],
  source => (async function * () {
    for await (const e of source) {
      yield e*10
    }
  })(),
  d[1]
)
```

## API Docs

- <https://alanshaw.github.io/it-pair>

## License

Licensed under either of

- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.