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:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

---

License

MIT license.

Copyright

Copyright © 2015. The Flow.io Authors.