# stream-gen

> Create streams from generators and test them

Latest version **2.0.1** (published 2019-10-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install stream-gen
pnpm add stream-gen
yarn add stream-gen
bun add stream-gen
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2019-10-05 |
| First published | 2018-04-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8.3.0 |
| Dependencies | 0 |
| Unpacked size | 16.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Overlook Motel |
| Maintainers | overlookmotel |
| Keywords | stream, generator, iterator, test, spec, readable, writable |

## Links

- npm: https://www.npmjs.com/package/stream-gen
- Repository: https://github.com/overlookmotel/stream-gen
- Homepage: https://github.com/overlookmotel/stream-gen#readme
- Issues: https://github.com/overlookmotel/stream-gen/issues
- npm.io page: https://npm.io/package/stream-gen

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 2.0.1 (latest) — 2019-10-05
- 2.0.0 — 2019-10-05
- 1.0.1 — 2018-04-27
- 1.0.0 — 2018-04-27

## README

# stream-gen.js

# Create streams from generators and test them

## Current status

[![NPM version](https://img.shields.io/npm/v/stream-gen.svg)](https://www.npmjs.com/package/stream-gen)
[![Build Status](https://img.shields.io/travis/overlookmotel/stream-gen/master.svg)](http://travis-ci.org/overlookmotel/stream-gen)
[![Dependency Status](https://img.shields.io/david/overlookmotel/stream-gen.svg)](https://david-dm.org/overlookmotel/stream-gen)
[![Dev dependency Status](https://img.shields.io/david/dev/overlookmotel/stream-gen.svg)](https://david-dm.org/overlookmotel/stream-gen)
[![Greenkeeper badge](https://badges.greenkeeper.io/overlookmotel/stream-gen.svg)](https://greenkeeper.io/)
[![Coverage Status](https://img.shields.io/coveralls/overlookmotel/stream-gen/master.svg)](https://coveralls.io/r/overlookmotel/stream-gen)

## Purpose

Streams can be hard to test.

You want to test transform streams etc with large batches of data to ensure they're robust, but you don't want to include big files to test with in the repo.

This module provides:

* Readable stream which streams out data of whatever size you need
* Writable stream which receives data and checks it's what it should be

This is achieved entirely in memory (no file streams etc) but with minimal memory use.

The streams are created from a generator function you provide, which can produce streams of whatever content and size you require.

## Usage

### Installation

```
npm install stream-gen
```

### Classes

#### GeneratorReadStream( gen [, options] )

Readable stream that gets its content from a generator.

The generator must `yield` a byte value (0-255) each time it is called. The content of the stream is made up of these bytes.

```js
const { GeneratorReadStream } = require('stream-gen');

// Data generator - creates 1KB of data
function* gen() {
  for (let i = 0; i < 1024; i++) {
    yield i % 256;
  }
}

const producer = new GeneratorReadStream( gen );

producer.pipe( destination );
```

You can also use a generator which produces 2-byte or 4-byte values (i.e. 16 bit or 32 bit) using `options.byte`.

#### GeneratorWriteStream( gen [, options], callback )

Writable stream that receives content and compares it to result of a generator. It calls `callback` with result of the comparison.

The generator must be of same type as for `GeneratorReadStream`.

```js
const { GeneratorWriteStream } = require('stream-gen');

const checker = new GeneratorWriteStream( gen, function(err) {
  if (err) return console.log('Stream differed');
  console.log('Stream as expected');
} );

source.pipe( checker );
```

### Putting it together

The two parts work together to test that a transfer of data has been completed without altering the data.

Let's say you are testing a lossless compression component:

```
Input -> Compress -> Decompress -> Output
```

Input and output should be the same.

You can test this with:

```js
const { GeneratorReadStream, GeneratorWriteStream } = require('stream-gen');
const zlib = require('zlib');

// Data generator - creates 100MB of data
function* gen() {
	for (let i = 0; i < 100 * 1024 * 1024; i++) {
		yield i % 256;
	}
}

// Create producer and checker
const producer = new GeneratorReadStream( gen ),
const checker = new GeneratorWriteStream( gen, function(err) {
  if (err) throw err;
  console.log('It works!');
} );

// Create compressor and decompressor
const compressor = zlib.createDeflate();
const decompressor = zlib.createInflate();

// Pipe them all together
producer.pipe(compressor).pipe(decompressor).pipe(checker);
```

The callback on `checker` tells us if data after compression and decompression is the same at it started off as.

There we go! We tested ZLIB on 100MB of data, using hardly any memory and no disc access.

### Options

#### `bytes`

To use a generator which outputs 16 bit or 32 bit numbers rather than 8 bit, set `options.bytes` to `2` or `4`.

Default is `1` (i.e. 8 bit).

```js
function* gen() {
	for (let i = 0; i < 100 * 1024 * 1024; i++) {
		yield i % (256 * 256);
	}
}

const stream = new GeneratorReadStream( gen, { bytes: 2 } );
```

#### `maxSize` (read stream only)

`maxSize` option determines largest size chunk stream will emit.

```js
const stream = new GeneratorReadStream( gen, { maxSize: 1024 } );
```

#### `highWaterMark`

Passed to Node's Stream constructor.

#### `encoding`

Passed to Node's Stream constructor.

## Tests

Use `npm test` to run the tests. Use `npm run cover` to check coverage.

## Changelog

See [changelog.md](https://github.com/overlookmotel/stream-gen/blob/master/changelog.md)

## Issues

If you discover a bug, please raise an issue on Github. https://github.com/overlookmotel/stream-gen/issues

## Contribution

Pull requests are very welcome. Please:

* ensure all tests pass before submitting PR
* add an entry to changelog
* add tests for new features
* document new functionality/API additions in README

---
_Source: https://npm.io/package/stream-gen · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._