command-bus v0.0.1

Command Bus

Command handling service to help abstract functional commands and promote command reuse

Hello world example

First you need to acquire the Command Bus library, this is usually done via a package manager such as npm or bower:

npm install commandBus --save

Once you have access to the library you can use 'requireJs' to load the module at any point in your application.

var commandBus = require('../src/main');

Alternately if you can load the file directly via the script tag, the commandBus will then be accessible via a 'commandBus' global variable

To use a command you must first register it, to do this you invoke the "registerCommand" method on the command bus:

commandBus.registerCommand('hello-world', function(callback) {
    callback('Hello World');
});

As you can see the 'registerCommand' method accepts two arguments, the first is the name of the command and the second is the command itself. The command function accepts a 'callback' argument this argument is used to return data back to the caller.

Now we have a registered command, from this point on we can access it anywhere in our application as long as we have access to a Command Bus reference:

var helloCommand = commandBus.command('hello-world');

We can now invoke this command by using the 'success' method:

helloCommand.success(function(result) {
    alert(result);
});

For simple commands it is sometimes best to access the 'command; directly:

commandBus.command('hello-world').success(function(result) {
    alert(result);
});

Passing arguments

We can modify our 'hello-world' command to accept arguments:

commandBus.registerCommand('hello-world', function(callback, callbackArguments) {
    callback('Hello ' + callbackArguments.name);
});

Now the 'hello-world' function also checks for a attribute 'callbackArguments' this is a object that stores command arguments.

We can call the 'hello-world' command with arguments by passing a object into the 'command' method:

var helloCommand = commandBus.command('hello-world', {name: 'Leo'});

commandBus.command('hello-world').success(function(result) {
    alert(result);
});

This can also be called inline:

commandBus.command('hello-world', {name: 'Leo'}).success(function(result) {
    alert(result);
});

Handling errors

The Command Bus also allows you to handle errors, you can ask for the 'errorHandler' object in your registered command, you can then use this object to throw a error.

commandBus.registerCommand('hello-world', function(callback, callbackArguments, errorHandler) {

    if(callbackArguments.name) {
        errorHandler.throwError('I can\'t do that dave');
    }

    callback('Hello ' + callbackArguments.name);
});

Now when we can use the command 'error' event for our 'hello-world' command to catch the error.

var helloCommand = commandBus.command('hello-world', {name: undefined})

helloCommand.error(function(errorResult) {
    alert(errorResult.message);
});

helloCommand.success(function(result) {
    alert(result);
});

We have provided the 'helloCommand' with a undefined name, this will cause the command to throw a error. Next we have called the commands 'error' method and passed it a function, this function is executed if a error is thrown.

Finally the 'helloCommand' is called, please note you can also perform the same commands inline.

 commandBus.command('hello-world', {name: undefined})
    .success(function(result) {
         alert(result);
     })
    .error(function(errorResult){
        alert(errorResult.message);
    });

Error id's

It is also possible to pass error id's to the error handler when registering a command, this id can be in any data format.

commandBus.registerCommand('hello-world', function(callback, callbackArguments, errorHandler) {

    if(callbackArguments.name) {
        errorHandler.throwError('I can\'t do that dave', '101');
    }

    callback('Hello ' + callbackArguments.name);
});

To access the id simply reference it in the 'error' callback.

commandBus.command('hello-world', {name: undefined})
    .success(function(result) {
         alert(result);
     })
    .error(function(errorResult){
        alert(errorResult.message + ' Error id: ' + errorResult.id);
    });