convojs

a simple stream wrapper for chatty protocols

npm install convojs
12 downloads in the last month

ConvoJS: making chatty protocols easier

ConvoJS is made to make chatty protocols over streams easier, now you are able to create a protocol with an object.

How it works

Step 1: Install ConvoJS

you can include the convo.js file or install it via NPM

npm install convojs

Step 2: Code

now you need to load ConvoJS first in an var,

var convojs = require('convojs');

ConvoJS only returns a function this is the constructor so creating a new ConvoJS object is done like this

var convo = new convojs();

now this will obviously throw errors because there are no arguments, ConvoJS only needs one arguments and that is the options object which usually looks like this

var convo = new convojs({
    // the stream we need to listen AND write to
    stream  : serialPort,
    // the commands for this convo
    commands: [
        {
            // the solver of this command, can be a string,regex,function or array
            // with those things
            solver:/Hai/,
            // response can be everything, if its not a function it will be directly
            // be written to the stream when this command is called
            response:"Hey gtg kthxbye",
            // the commands that can be executed after this command
            commands:[
                {
                    // solver as regex
                    solver:/.*/,
                    // if the solver is regex and the repsonse a string, the string
                    // will be formatted with the matches
                    // for example if you send 'hello' this command will respond with
                    // You told me 'hello'
                    response:"You told me '{0}'",
                    commands:[
                        {
                            solver:'cant get in',
                            response:"nope",
                            // if commands is false we will not scope deeper and
                            // stay in the current command collection
                            commands:false
                        },
                        {
                            // solver also can be a function
                            // there will be passed 1 argument and thats the data
                            // solver must return something truety or falsy
                            solver:function(data){
                                return !!data;
                            },
                            // repsonse also can be a function
                            // there will be passed 3 arguments
                            // - writer: the stream to write to
                            // - data: the data received from the stream
                            // - solver: the solver
                            response:function(writer,data,solver){

                            },
                            // commands can be a negative number,
                            // when commands is a negative number it will go up
                            // that amount of times so in this example the
                            // command collection will be set to the collection
                            // it started with
                            commands:-2
                        }
                    ]
                }
            ]
        }
    ],
    // [optional] works just like the command collection but will always be fired
    // BEFORE the standard command collection, if a command is matched
    // it will immeditially stop looking for others
    globalCommands:[],
    // [optional] where ConvoJS has to write the reponses to
    //  writer has an higher priority then stream
    writer:false,
    // [optional] where ConvoJS has to read from
    //  reader has an higher priority then stream
    reader:false
});

ConvoJS will automagicly hook to the data event so you only need to build the object and (if needed) open the stream

Object Reference

ConvoJS.unbind()

this will unbind the ConvoJS from the stream and release all events hooked to it

ConvoJS.options

the given options, merged with the default options object

ConvoJS.writer

the stream where ConvoJS writes to

ConvoJS.reader

the stream where ConvoJS reads from

ConvoJS.globalCommands

all the global commands in this ConvoJS

ConvoJS.commands

the given commands object

ConvoJS.selectedCommand

the at the moment selected command

npm loves you