io-node

This is a Node-specific transport for heya-io based on built-in http and https modules. The main purpose of the module is to provide an ergonomic simple light-weight HTTP I/O on Node leveraging existing customization facilities of heya-io where appropriate.

Following heya-io services are supported as is out of the box:

• io.track — tracks I/O requests to eliminate duplicates, register an interest without initiating I/O requests, and much more.
• io.mock — mocks responses to I/O requests without writing a special server courtesy of Mike Wilcox. Very useful for rapid prototyping and writing tests.
• io.bust — a simple pseudo plugin to generate a randomized query value to bust cache.
• io.retry — a flexible way to retry requests, e.g., to deal with unreliable servers or to watch for changing values.

Additionally it supports:

• Completely transparent compression/decompression.
  • gzip and deflate are supported out of the box with no extra dependencies using built-in modules.
  • More compressions can be easily plugged in.
    • brotli is automatically supported if an underlying Node has it.
  • The compression is supported both ways.
• Streaming.
  • Both streaming a server request and a server response are supported.

Examples

Plain vanilla GET:

const io = require('heya-io-node');

io.get('http://example.com/hello').then(function (value) {
  console.log(value);
});

io.get('/hello', {to: 'world', times: 5}).then(value => {
  // GET /hello?to=world&times=5
  console.log(value);
});

Some other verbs (REST example):

function done() { console.log('done'); }

io.post('/things', {name: 'Bob', age: 42}).then(done);
io.put('/things/5', {name: 'Alice', age: 33}).then(done);
io.patch('/things/7', {age: 14}).then(done);
io.remove('/things/3').then(done);

Streaming (since 1.1.0) + encoding a payload (since 1.2.0):

const ios = require('heya-io-node/stream');
fs.createReadStream('sample.json')
  .pipe(ios.post({
    url: 'https://example.com/analyze',
    headers: {
      'Content-Type': 'application/json',
      '$-Content-Encoding': 'gzip',
      'Accept: plain/text'
    }
  }))
  .pipe(process.stdout);

// or it can be done more granularly:

io.post({
  url: 'https://example.com/analyze',
  headers: {
    'Content-Type': 'application/json',
    '$-Content-Encoding': 'gzip',
    'Accept: plain/text'
  },
  responseType: '$tream'
}, fs.createReadStream('sample.json'))
.then(res => res.pipe(process.stdout));

Mock in action:

// set up a mock handler
io.mock('/a*', (options, prep) => {
  console.log('Got call: ' + options.method + ' ' + prep.url);
  return 42;
});

// let's make a call
io.get('/a/x').then(value => {
  console.log(value); // 42
});

// set up a redirect /b => /a/b
io.mock('/b', options => io.get('/a/b', options.query || options.data || null));

// let's make another call
io.get('/b', {q: 1}).then(value => console.log(value)); // 42

Using url template to sanitize URLs (ES6):

const url = require('heya-io/url');

const client = 'Bob & Jordan & Co';
io.get(url`/api/${client}/details`).then(value => {
  // GET /api/Bob%20%26%20Jordan%20%26%20Co/details
  console.log(value);
});

See more examples in heya-io's Wiki, heya-io-node's Wiki, and the cookbooks of heya-io:

• Cookbook: main
• Services:
  • Cookbook: bust
  • Cookbook: mock
  • Cookbook: track
  • Cookbook: retry

How to install

npm install --save heya-io-node
# or: yarn add heya-io-node

Documentation

All documentation can be found in project's wiki.

Working on this project

In order to run tests locally, you should start the test server first:

npm start

Then (likely in a different command line window) run tests:

npm test

The server runs indefinitely, and can be stopped by Ctrl+C.

Versions

• 1.3.0 Replaced obsolete url module with WHATWG URL.
• 1.2.0 Fixed a bug with large UTF-8 documents, updated dependencies.
• 1.1.7 Technical release: updated dependencies.
• 1.1.6 Technical release: added Greenkeeper and removed yarn.lock.
• 1.1.5 Updated dependencies and added a test suite for io.retry.
• 1.1.4 Updated dependencies.
• 1.1.3 Added experimental IncomeMessage support.
• 1.1.2 Exposed getData() and getHeaders() on stream and error objects.
• 1.1.1 Added support for Buffer, replaced failure objects with Error-based objects.
• 1.1.0 Getting rid of request, use native http/https, support compression and streaming.
• 1.0.3 Bugfix: custom headers. Thx Bryan Pease!
• 1.0.2 Added custom body processors.
• 1.0.1 New dependencies.
• 1.0.0 The initial release.

License

BSD or AFL — your choice.