# stream-interceptor

> Intercept, modify and ignore chunks data and events in any readable stream

Latest version **0.1.1** (published 2015-09-26) · MIT license · 0 weekly downloads

## Install

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

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2015-09-26 |
| First published | 2015-09-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.12 |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Tomas Aparicio |
| Maintainers | h2non |
| Keywords | stream, intercept, interceptor, control, modify, capture, sniff, sniffer, spy, events, emitter, readable, pipe, http, transform |

## Links

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

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 0.1.1 (latest) — 2015-09-26
- 0.1.0 — 2015-09-26

## README

# stream-interceptor [![Build Status](https://api.travis-ci.org/h2non/stream-interceptor.svg?branch=master&style=flat)](https://travis-ci.org/h2non/stream-interceptor) [![NPM](https://img.shields.io/npm/v/stream-interceptor.svg)](https://www.npmjs.org/package/stream-interceptor)

Tiny [node.js](https://nodejs.org) module to **intercept**, **modify** and/or **ignore** chunks of data and events in any [readable compatible stream](https://nodejs.org/api/stream.html#stream_class_stream_readable) before it's processed by other stream consumers (e.g: via `pipe()`).

It becomes particularly useful to deal with net/http/fs streams.

## Installation

```bash
npm install stream-interceptor
```

## Examples

##### Existent stream

```js
var Readable = require('stream').Readable
var interceptor = require('stream-interceptor')

// Create a new Readable stream
var stream = new Readable
stream._read = function () { /* ... */ }

// Make it interceptable
interceptor(stream)

// Prepare to capture chunks
stream.capture(function (chunk, next) {
  next(chunk + chunk)
})

// We gonna handle strings
stream.setEncoding('utf8')

// Push chunks to the stream
stream.push('Foo')
stream.push('Bar')
stream.push(null) // we're done!

// Listen for events like a stream consumer
stream.on('data', function (chunk) {
  console.log('Modified chunk:', chunk)
})

stream.on('end', function () {
  console.log('We are done!')
})
```

##### Capture HTTP response

```js
var http = require('http')
var interceptor = require('stream-interceptor')

// Test server
var server = http.createServer(function (req, res) {
  res.writeHead(200)
  res.write('Foo')
  res.write('Bar')
  res.end()
}).listen(3000)

http.get('http://localhost:3000', function (response) {
  // http.IncomingMessage implements a Readable stream
  var stream = interceptor(response)

  stream.capture(function (chunk, next) {
    next(chunk + chunk + '\n')
  })

  stream.on('end', function () {
    console.log('Response status:', response.statusCode)
    server.close()
  })

  stream.pipe(process.stdout)
})
```

##### Capture asynchronously

```js
var Readable = require('stream').Readable
var interceptor = require('stream-interceptor')

// Create a new Readable stream
var stream = new Readable
stream._read = function () { /* ... */ }

// Make it interceptable
interceptor(stream)

// Prepare to capture chunks asyncronously
// Chunks will be processed always as FIFO queue
stream.capture(function (chunk, next) {
  setTimeout(function () {
    next(chunk + chunk + '\n')
  }, Math.random() * 1000)
})

// We gonna handle strings
stream.setEncoding('utf8')

// Push chunks to the stream
stream.push('Slow Foo')
stream.push('Slow Bar')
stream.push(null) // we're done!

stream.pipe(process.stdout)
```

##### Ignore chunks

```js
var Readable = require('stream').Readable
var interceptor = require('stream-interceptor')

// Create a new Readable stream
var stream = new Readable
stream._read = function () { /* ... */ }

// Make it interceptable
interceptor(stream)

// Prepare to capture chunks
stream.capture(function (chunk, next) {
  if (chunk === 'Bad') {
    return next(true) // Ignore chunk
  }
  next(chunk + '\n')
})

// We gonna handle strings
stream.setEncoding('utf8')

// Push chunks to the stream
stream.push('Bad')
stream.push('Ugly')
stream.push('Good')
stream.push(null) // we're done!

stream.pipe(process.stdout)
```

##### Interceptable stream

```js
var Interceptable = require('stream-interceptor').Interceptable

// Implements both Readable and Interceptable stream
var stream = new Interceptable
stream._read = function () { /* ... */ }

// Prepate to capture chunks
stream.capture(function (chunk, next) {
  next(chunk + chunk + '\n')
})

// Push chunks to the stream
stream.push('Foo')
stream.push('Bar')
stream.push(null) // we're done!

stream.pipe(process.stdout)
```

##### Event interceptor

```js
var Interceptable = require('stream-interceptor').Interceptable

// Implements both Readable and Interceptable stream
var stream = new Interceptable
stream._read = function () { /* ... */ }

// Prepate to capture events
stream.captureEvent('error', function (err, next) {
  next(true) // always ignore errors
})

// Prepate to capture chunks
stream.capture(function (chunk, next) {
  next(chunk + chunk + '\n')
})

stream.on('error', function (err) {
  console.error('Error:', err) // won't be called
})

// Push data in the stream
stream.push('Foo')
stream.push('Bar')
stream.push(null)

// Simulate an error
stream.emit('error', 'Damn!')

stream.pipe(process.stdout)
```

## API

### streamIntercept(readableStream) => Interceptable

Wraps any readable stream turning it an interceptable stream.
`Interceptable` stream implements the same interface as `Readable`.

### Interceptable([ options ])
Alias: `Interceptor`

Creates a new `Interceptable` stream. Inherits from `Readable` stream.

#### Interceptable#interceptable => `boolean`

Property to determine if the stream is interceptable.

#### Interceptable#capture(fn) => `Interceptable`

Subscribe to capture chunks of data emitted by the stream.

#### Interceptable#captureEvent(event, fn) => `Interceptable`

Capture data emitted by a specific event.
`fn` argument expects two arguments: `chunk, callback`.

When you're done, **you must call the callback** passing the new argument: `callback(chunk)`

You can optionally ignore chunks passing `true` to the callback: `callback(true)`.

### isInterceptor(stream) => `boolean`

### Hook()

Hook layer internally used capture and handle events of the stream.

### Queue()

FIFO queue implementation internally used.

### Chunk()

Internal chunk event structure.

## License

MIT - Tomas Aparicio

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