iz-utils

DEPRECATED: Utility modules for working with Node.js streams and HTTP response assertions.

Installation

npm install iz-utils

This package uses CommonJS modules.

var utils = require('iz-utils');

var BufferStream = utils.BufferStream;
var StreamCatcher = utils.StreamCatcher;

Individual modules can also be required directly from lib/.

var StreamRecorder = require('iz-utils/lib/StreamRecorder');

API

The package entrypoint exports:

• BufferStream
• NullStream
• StreamRecorder
• StreamEater
• StreamCatcher
• StreamSearcher
• StreamTee

HTTPEvaluator is available as require('iz-utils/lib/HTTPEvaluator').

BufferStream

Creates a readable stream from a Buffer.

var BufferStream = require('iz-utils').BufferStream;

var source = new BufferStream({
  buffer: Buffer.from('hello world')
});

source.on('data', function(chunk) {
  console.log(chunk.toString());
});

Options

• buffer: buffer to expose as a readable stream. Defaults to a 1024-byte buffer.

NullStream

A readable stream that ends immediately without emitting data.

var NullStream = require('iz-utils').NullStream;

var stream = new NullStream();

stream.on('end', function() {
  console.log('done');
});

Use this when an API expects a readable stream but there is no data to provide.

StreamEater

A transform stream that consumes all input and emits no output.

var fs = require('fs');
var StreamEater = require('iz-utils').StreamEater;

fs.createReadStream('large-file.txt')
  .pipe(new StreamEater())
  .on('finish', function() {
    console.log('input consumed');
  });

Use this to drain a stream when the data is no longer needed.

StreamRecorder

A transform stream that passes data through while optionally recording stream data, events, and timestamps.

var fs = require('fs');
var StreamRecorder = require('iz-utils').StreamRecorder;
var StreamEater = require('iz-utils').StreamEater;

var recorder = new StreamRecorder({
  capture_data: true,
  capture_events: true,
  capture_time: true
});

recorder.on('finished', function() {
  var data = recorder.get_all_data();
  var events = recorder.get_events();

  console.log(data.length);
  console.log(events);
});

fs.createReadStream('input.txt')
  .pipe(recorder)
  .pipe(new StreamEater());

Options

• capture_data: record data chunks for later retrieval. Defaults to false.
• capture_events: record selected stream events. Defaults to false.
• capture_time: add a timestamp to event records. Defaults to false.
• events_to_record: event names to record when capture_events is enabled. Defaults to ['end', 'close', 'drain', 'pipe', 'unpipe'].
• transform_args: options passed to the underlying stream.Transform constructor.

Methods

• get_events(): returns a copy of the recorded event list.
• get_all_data(): returns recorded data as a single Buffer, or an array when transform_args.objectMode is true.
• clear_captured_data(): clears references to captured data buffers.

StreamCatcher

A StreamRecorder configured to capture all data. It emits finished with the captured data.

var fs = require('fs');
var StreamCatcher = require('iz-utils').StreamCatcher;

var catcher = new StreamCatcher({ catch_only: true });

catcher.on('finished', function(data) {
  console.log(data.toString());
});

fs.createReadStream('input.txt').pipe(catcher);

Options

• catch_only: when true, consumes the stream itself and does not require an output pipe. Defaults to false.

Methods

• catch_now(): starts consuming the stream internally so no downstream pipe is required.
• get_all_data(): inherited from StreamRecorder.

StreamTee

A transform stream that passes data through and duplicates it to additional readable streams.

var fs = require('fs');
var StreamTee = require('iz-utils').StreamTee;

var tee = new StreamTee();
var copy = tee.tee();

fs.createReadStream('input.txt').pipe(tee);

tee.pipe(fs.createWriteStream('primary.txt'));
copy.pipe(fs.createWriteStream('copy.txt'));

Methods

• tee(): returns a readable PassThrough stream that receives the same chunks as the main output.

StreamSearcher

Creates transform streams that search for data between begin and end tags and replace each match asynchronously.

var fs = require('fs');
var StreamSearcher = require('iz-utils').StreamSearcher;

var searcher = new StreamSearcher();
var transform = searcher.get_searcher('<!--', '-->', false, function(found, replace) {
  console.log('found:', found.toString());
  replace('[replacement]');
});

fs.createReadStream('template.html')
  .pipe(transform)
  .pipe(fs.createWriteStream('output.html'));

Methods

• get_searcher(begin, end, inclusive, callback): returns a transform stream.

Callback

The callback receives (found, replace).

• found: a Buffer containing the matched region.
• replace(replacement): writes replacement data and resumes searching.

replacement may be a string, Buffer, or readable stream. Use inclusive: true to include the begin and end tags in the matched data; use false to replace only the content between the tags.

HTTPEvaluator

Performs HTTP or HTTPS requests and captures the response body for assertions. This utility is intended for integration tests against a running server.

var HTTPEvaluator = require('iz-utils/lib/HTTPEvaluator');

var evaluator = new HTTPEvaluator();

evaluator.request({
  protocol: 'https:',
  host: 'www.example.com',
  path: '/',
  method: 'GET'
}, function(res) {
  console.log(res.has_header('content-type'));
  console.log(res.body_contains('Example Domain'));
});

Methods

• request(options, callback): performs an HTTP request and calls back with an evaluator for the captured response.
• request_with_data(options, data, callback): sends a request with a string, Buffer, or readable stream body.
• capture_http_response(response, encoding, callback): captures an existing HTTP response stream.
• has_header(name): returns true when the response includes a header.
• has_header_value(name, value): returns true when the response includes a specific header value.
• has_headers(headers): accepts an array of header names or an object of header/value pairs.
• body_contains(text, encoding): returns true when the response body contains text.
• body_matches(regex, encoding): returns true when the response body matches a regular expression.
• body_identical_to_buffer(buffer): returns true when the response body matches a buffer byte-for-byte.
• body_identical_to_file(filename): compares the response body to a file read from disk.

request accepts standard Node http.request options plus:

• params: object of request parameters. For POST requests without explicit data, parameters are sent as application/x-www-form-urlencoded.
• post_data: pre-encoded POST body data.
• ignore_proxy_settings: skips proxy handling when set to true.
• proxy_options: overrides environment-derived proxy configuration.

By default, proxy settings are read from NO_PROXY, http_proxy, HTTPS_PROXY, and host_override.

Tests

npm test

License

LGPL