stream-throttle

A simple Node.js stream throttler.

Installation

Using yarn:

$ yarn add @kldzj/stream-throttle

Using npm:

$ npm i -S @kldzj/stream-throttle

Usage

Options

• rate: The sustained rate in bytes per second at which to emit data. Must be greater than 0.
• burst: The maximum number of bytes that may be emitted in a single burst (the token bucket size). Must be greater than or equal to rate. Defaults to rate.
• chunkSize: The size in bytes of the chunks the received data is split into. Must be between 1 and rate. Defaults to rate / 10, but never less than 1.

All three values are floored to whole bytes. Invalid values throw rather than being silently corrected.

Throttle

Used to throttle the output rate of a single stream.

import { Throttle } from '@kldzj/stream-throttle';

const throttle = new Throttle({ rate: 10 });
process.stdin.pipe(throttle).pipe(process.stdout);

ThrottleGroup

Used to throttle the output rate across multiple streams.

import { createConnection } from 'net';
import { ThrottleGroup } from '@kldzj/stream-throttle';

const group = new ThrottleGroup({ rate: 1024 * 1024 });
const addr = { host: 'www.google.com', port: 80 };
const throttled1 = createConnection(addr).pipe(group.createThrottle());
const throttled2 = createConnection(addr).pipe(group.createThrottle());
// ...

Changing the rate on-the-fly

const group = new ThrottleGroup({ rate: 1024 * 1024 });
// or group = new Throttle({ rate: 1024 * 1024 }).group;
// ...

group.setRate(4 * 1024 * 1024);
// in case you calculate the chunkSize differently
// you should call `setChunkSize` as well, as `setRate`
// recalculates `chunkSize`
group.setChunkSize(group.rate / 6);
// in addition, you can also call `setBurst` if
// you want to change the burst rate
group.setBurst(group.rate * 1.5);

// ...

Cancelling a stream

Destroying a Throttle stops it from consuming any further bandwidth from its group, so cancelling one transfer does not hold up the others sharing the rate.

const group = new ThrottleGroup({ rate: 1024 * 1024 });
const download = createConnection(addr).pipe(group.createThrottle());

download.destroy(); // releases the group's bandwidth for the remaining streams

Special thanks

• @tjgq for the initial implementation (stream-throttle).