Flow-to-geckoboard NPM

Geckoboard

Creates a writable stream for pushing data to Geckoboard.

Installation

$ npm install flow-to-geckoboard

For use in the browser, use browserify.

Usage

var stream = require( 'flow-to-geckoboard' );

stream( options )

Creates a writable stream for pushing data to Geckoboard.

var oStream = stream({
	'key': '<your_key_goes_here>',
	'id': '<your_widget_id_goes_here>'
});

// Data for a Geck-o-Meter widget:
var data = {
	'item': Math.random() * 100,
	'min': {
		'value': 0
	},
	'max': {
		'value': 100
	}
};

// Write the data to the stream:
oStream.write( JSON.stringify( data ) );

// End the stream:
oStream.end();

The function accepts the following options:

objectMode: boolean which specifies whether a stream should operate in object mode. Default: false.
decodeStrings: boolean which specifies whether written strings should be decoded into Buffer objects. Default: true.
highWaterMark: specifies the Buffer level at which write() calls start returning false. Default: 16 (16KB).

To set stream options,

var opts = {
	'key': '<your_key_goes_here>',
	'id': '<your_widget_id_goes_here>',
	'objectMode': true,
	'decodeStrings': false,
	'highWaterMark': 64	
};

var oStream = stream( opts );

stream.factory( options )

Creates a reusable stream factory. The factory method ensures streams are configured identically by using the same set of provided options.

var opts = {
	'key': '<your_key_goes_here>',
	'id': '<your_widget_id_goes_here>'
};

var factory = stream.factory( opts );

// Create 10 identically configured streams...
var streams = [];
for ( var i = 0; i < 10; i++ ) {
	streams.push( factory() );
}

stream.objectMode( options )

This method is a convenience function to create streams which always operate in objectMode. The method will always override the objectMode option in options.

var opts = {
	'key': '<your_key_goes_here>',
	'id': '<your_widget_id_goes_here>'
};

var data = {
	'item': Math.random() * 100,
	'min': {
		'value': 0
	},
	'max': {
		'value': 100
	}
};

var oStream = stream.objectMode( opts );
oStream.write( data );
oStream.end();

Examples

var Stream = require( 'flow-to-geckoboard' );

var oStream,
	data,
	i;

oStream = new Stream({
	'key': '<your_key_goes_here>', // INSERT KEY HERE //
	'id': '<your_widget_id_goes_here>' // INSERT WIDGET ID HERE //
});

function write( data ) {
	return function() {
		oStream.write( JSON.stringify( data ) );
	};
}

function end() {
	oStream.end();
}

for ( i = 0; i < 100; i++ ) {
	data = {
		'item': Math.random() * 100,
		'min': {
			'value': 0
		},
		'max': {
			'value': 100
		}
	};
	// Stagger posting values to Geckoboard:
	setTimeout( write( data ), i*1000 );
}

// Close the stream:
setTimeout( end, i*1000 );

To run the example code from the top-level application directory,

$ node ./examples/index.js

CLI

Installation

To use the module as a general utility, install the module globally

$ npm install -g flow-to-geckoboard

Usage

Usage: flow-to-geckoboard --key <key> --widget <widget_id> [options]

Options:

  -h,   --help                 Print this message.
  -V,   --version              Print the package version.
        --key [key]            Geckoboard API key.
        --widget [widget]      Geckoboard widget id.
  -hwm, --highwatermark [hwm]  Specify how much data can be buffered into memory
                               before applying back pressure. Default: 16KB.
  -nds, --no-decodestrings     Prevent strings from being converted into buffers
                               before streaming to destination. Default: false.
  -om,  --objectmode           Write any value rather than only buffers and strings.
                               Default: false.

The flow-to-geckoboard command is available as a standard stream.

$ <stdout> | flow-to-geckoboard --key <key> --widget <widget_id>

Notes

In addition to the command-line key and widget options, the key and widget options may be specified via environment variables: GECKOBOARD_API_KEY and GECKOBOARD_WIDGET_ID. The command-line options always take precedence.

Examples

$ echo '{"item":50,"min":{"value":0},"max":{"value":100}}' | flow-to-geckboard --key <key> --widget <widget_id>

Setting credentials using environment variables:

$ GECKOBOARD_API_KEY=<key> GECKOBOARD_WIDGET_ID=<widget_id> echo '{"item":67,"min":{"value":0},"max":{"value":100}}' | flow-to-geckboard

For local installations, modify the above command to point to the local installation directory; e.g.,

$ echo '{"item":32,"min":{"value":0},"max":{"value":100}}' | ./node_modules/.bin/flow-to-geckoboard --key <key> --widget <widget_id>

Or, if you have cloned this repository and run npm install, modify the command to point to the executable; e.g.,

$ echo '{"item":49,"min":{"value":0},"max":{"value":100}}' | node ./bin/cli --key <key> --widget <widget_id>

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory: