# hybrix-jslib

This Javascript library can be used to connect software to leverage the capabilities of the hybrix platform. It serves two purposes: first to facilitate the logistics of interfacing with the hybrixd API, secondly to handle all client-side operations securely and privately. This ensures that keys required for transactions never leave the users device and communication happens over an encrypted channel.

Download for web <script src="./hybrix-lib.web.js"></script>
Download for NodeJS const Hybrix = require('./hybrix-lib.nodejs');
Install using NPM $ npm install hybrix-jslib
const Hybrix = require('./hybrix-lib');

## Quick start

There are two flavours of the library: the web version to include in your webpage or front-end, and the node js version to include when you are building back-end software.

Here is a Hello World example of how to use hybrix-lib.js in your front-end. First include the library using script tags.

    <html>
     <head>
      <script src='hybrix-lib.web.js'></script>
     </head>
     <body>
      <script>
       var hybrix = new Hybrix.Interface();
       hybrix.sequential(
        [
         {host:'https://api.hybrix.io/'}, 'addHost'                     //  Connect to host
        ],
        host => alert('Connected to '+ host),                           // Define action to execute on successfull completion
        error => alert('Oops, something went wrong: '+error)           // Define action to exectue when an error is encountered
       );
      </script>
     </body>
    </html>

For nodejs projects:

    const Hybrix = require('./hybrix-lib.nodejs.js');
    const hybrix = new Hybrix.Interface();
    hybrix.sequential(
      [
       {host:'https://api.hybrix.io/'}, 'addHost'                     //  Connect to host
      ],
      host => console.log('Connected to '+ host),                     // Define action to execute on successfull completion
      error => console.error('Oops, something went wrong: ' + error)  // Define action to exectue when an error is encountered
    );

Or using npm:

Install the package using npm `npm install hybrix-jslib`

    const Hybrix = require('hybrix-jslib');
    const hybrix = new Hybrix.Interface();
    hybrix.sequential(
      [
       {host:'https://api.hybrix.io/'}, 'addHost'                     //  Connect to host
      ],
      host => console.log('Connected to '+ host),                     // Define action to execute on successfull completion
      error => console.error('Oops, something went wrong: ' + error)  // Define action to exectue when an error is encountered
    );

## Callbacks

Each command is implemented as a member function of the Hybrix.Interface class. Adding a host can be done as follows.

    hybrix.addHost({host:'https://www.example.com'});

Here only one parameter is passed but each member function has four parameters: data, onSuccess, onError and onProgress.

The first is used to pass parameter data to the function. The last three are callback functions. onSuccess is called once when the method has finished successfully. onError is called once when an error is encountered. onProgress is called whenever a progress update is available, passing a number between 0 and 1, and 1 upon completion.

To first add a host and then query for asset balance one could try the following:

    hybrix.addHost({host:'https://www.example.com'});  // This is an asynchronous function. It can take some time to complete.
    hybrix.rout({query: 'Query for asset balance'});   // Problem! This will try to request routing before the addition of the host is done.

This results in serious problems due to asynchronicity. One could use the callbacks to ensure the execution order.

    hybrix.addHost({host:'https://www.example.com'},
      function(){
        hybrix.rout({query:'/asset/btc/balance/32FCGFdRGeho2HBeWQPaAYawJfPqHHvsCJ'});     //  This will now be called after the addition of the host is successfully completed.
      }
    );

But adding more steps or error handling will end up with code that is both very hard to read and maintain. (This is sometimes dubbed callback hell.) To mitigate this the library comes equiped with a sequential and a parallel command to handle these asynchronious call flows. With an added bonus of handling the progress for combined commands as well.

    hybrix.sequential([
    {host: 'http://localhost:1111/'}, 'addHost',                   // Add and initialize the host
    {query: '/asset/btc/balance/32FCGFdRGeho2HBeWQPaAYawJfPqHHvsCJ'}, 'rout'  // Query for asset balance
    ],
    onSuccess,                                                      // Define action to execute on successfull completion
    onError,                                                        // Define action to execute when an error is encountered
    onProgress                                                      // Define action to execute whenever there is a progress update
    );

    hybrix.sequential([
    {host: 'http://localhost:1111/'}, 'addHost',                   // Add and initialize the host
    {query: '/asset/btc/balance/32FCGFdRGeho2HBeWQPaAYawJfPqHHvsCJ'}, 'rout'  // Query for asset balance
    ],
    onSuccess,                                                      // Define action to execute on successfull completion
    onError,                                                        // Define action to execute when an error is encountered
    onProgress                                                      // Define action to execute whenever there is a progress update
    );

For even more complex behaviour we advice you to implement your own favourite flavour method of handling the call flow, be it promises, streams, or async, etc.

## Live example

Progress

Result

...

## Reference