macro-command

A node module to chain multiple configurable commands, run them in a predefined order and access their results afterwards.

Installation

$ npm install macro-command

Features

• Run commands in sync
• Promise based
• Command pattern
• Namespace support
• Highly configurable & flexible

Related links

• Github repo - The official repo on Github.
• Documentation - The auto-build inline documentation of the latest release.
• Demo project - See the macro-command in action.
• Tutorial - A detailed walk-through of the code below.
• Use-case - Read more about the background of this package.
• Youtube tutorials - A playlist with tutorials to get you up and running.
• npm package - The macro-command package on npmjs.org.

Example usage

1 - Create a command.

//The first command to be executed by the macro
Command = require('macro-command').Command;
 
class FirstCommand extends Command {
 
execute(context) {
 
        this.context = context;
        var self = this;
 
        return new Promise(function (resolve, reject) {
            
            var n = self.context.parameters.cmdConfiguration.n;
            var x = n * 100;
 
            self.result.data.push(x);
            self.result.msg = "the result of (" + n + " * 100).";
            
            resolve(self.result);
 
        });
    }
}
 
module.exports = FirstCommand;

2 - Create a another command.

//The second command to be executed by the macro.
//It uses input from its own configuration +
//the output of command 1
Command = require('macro-command').Command;
 
class secondCommand extends Command {
 
execute(context) {
 
        this.context = context;
        var cfg = context.parameters.cmdConfiguration;
        var self = this;
 
        return new Promise(function (resolve, reject) {
            
            var a = cfg.a;
            var b = self.findPrevResult(cfg.prevCmdName).data[0];
            var c = a + b;
 
            self.result.data.push(c);
            self.result.msg = "the result of (" + a + " + " + b + ").";
            
            resolve(self.result);
 
        });
    }
}
 
module.exports = secondCommand;
 

3 - Chain both commands by defining a macro and a configuration for each command.

//The configuration of your macro
{
    "macros": [
        {
            "id": 1,
            "label": "tutorial",
            "comment": "Running 2 commands",
            "namespace": false,
            "cmdSequence": [
                "firstCommand",
                "secondCommand"
            ],
            "firstCommand":{
                "n":500
            },
            "secondCommand":{
                "a": 8,
                "prevCmdName": "FirstCommand"
            }
        }
    ]
}

4 - Run the macro in your application.

//The application that runs the macro
var Kickstarter = require('macro-command').Kickstarter;
var ks = new Kickstarter(1);
 
ks.run()
.then((value)=>{
    console.log(JSON.stringify(value));
});

And this will be the output:

{
    "cmd": "Macro",
    "data": [
        {
            "cmd": "FirstCommand",
            "data": [
                50000
            ],
            "msg": "the result of (500 * 100)."
        },
        {
            "cmd": "secondCommand",
            "data": [
                50008
            ],
            "msg": "the result of (8 + 50000)."
        }
    ],
    "msg": "The macro has finished successfully!"
}

Build the documentation for the macro-command module:

The documentation of the current release v1.0.11 is hosted on github. This can be a bit tricky, because the process depends on how you have installed the package. I can only give a few suggestions here:

Situation 1 - You have cloned the macro-command repo from github

Open a command prompt and go to the root of the application. Then run the following commands:

$ npm install
$ ./node_modules/.bin/jsdoc -c ./jsdoc-conf.json -r -d mcdocs

Situation 2 - You have installed the macro-command into your project via npm.

Open a command prompt and go to the root of the application. Then run the following commands:

$ cd node_modules/macro-command
$ ../.bin/jsdoc -c ./jsdoc-conf.json -r -d mcdocs

In both situations, this will auto-create a directory called "mcdocs" in the root directory of the macro-command package. After the build has completed, it contains a lot of files. Just open the index.html in your webbrowser to view the documentation. Note: If the build fails, you might try the following:

• run 'npm install'. This will install JSDOC. After the installation has completed try to build the documentation again.
• If you are on Windows, you'll probably have to change all the forward slashes into backslashes.
• If you already have JSDOC installed globally, you can just run:

$ jsdoc -c ./jsdoc-conf.json -r -d mcdocs

If you still can't build the #$%* thing, it is best to go visit the JSDOC website and search for a solution. Also this link might help: configuring jsdoc

Tests

To run the test suite, first install the dependencies, then run npm test:

$ npm install
$ npm test

Examples

To view some examples, clone the mcdemo repo and install the dependencies:

$ git clone https://github.com/ruckola/mcdemo.git
$ cd mcdemo
$ npm install

Then run one of the example apps:

$ node app-single-mode.js
$ node app-macro-mode1.js
$ node app-macro-mode2.js