conversation

Conversation

v0.1a

Highlights

• Added JS Docs


• Added Build Tools (configuration required)


• Added "Hallways" - Communcation channels between client Rooms and server Rooms

What is Conversation?

Conversation is an architectural platform that allows you to develop loosely coupled, dynamic applications by giving you a new way to call functions, access objects,
modify datamembers, and much more. Traditionally, explicit calls coupled segments of your software together. Components would access and call on one another directly within their scope.


Conversation will allow your application will make calls in an entirely new and dynamic fashion. Rather than coupling your components together into an unmaintainable nightmare,
you can abstract away components from one another, allowing you to write more code and worry less about down the road.

The Traditional Way

Lets look at a quick example of a typical status-quo application:

var speak = function(params){
console.log(params.text); //function coupled to bare-metal
};
var shout = function(params){
console.error(params.text); //function coupled to bare-metal
};
var sayGoodbye = function(params){
console.log('Goodbye!'); //function coupled to bare-metal
};
var error = function(str){
shout('Error!->'+str); //function coupled to function
sayGoodbye(); //function coupled to function
};
var okay = function(str){
speak('Everything is okay->!'+str); //function coupled to function
sayGoodbye(); //function coupled to function
};

Then you would use these functions when certain things happen within your software:

function thereIsAProblem(problem){
error(problem); //nested coupling (VERY bad)
}
function everythingIsOkay(thing){
okay(thing); //nested coupling (VERY bad)
}

While a gorilla could tell that this example is an over-complicated way of using the console object, this also serves
as a good example of the status-quo spaghetti code that most web applications will evolve into if left to their own demise
without proper planning.

The problem with this methodology (explicit function calls) is that you end up with hard references between different components in your application.
Sure, it is familiar and anything familiar seems simple, but you cannot easily swap out the error function with a function of a different
name that performs a different task; nor, can you inject and execute a second function on the fly(like reporting the error via AJAX) when
thereIsAProblem is executed. Worse yet, such implementation tends to lead to chains of dependency, and on large projects
all it takes is a single developer changing the way a single function behaves to damage your application in a way that not only brings
it to its knees, but is incredibly difficult to trace. In order to write better code, you have to use a better methodology.

The 'Conversation' Way - 100% Pure, Well-designed JS Goodness

Now, lets look at how we could accomplish this same static task with a Conversation:


//First, we create a Conversation Room
var convo = require('Conversation'); //Load the package
var ConvoRoom = convo.newRoom(); //this creates a new 'Room' for a conversation



//Now, we create the functions the same way as before!
var speak = function(params){
console.log(params.text); //function coupled to bare-metal
return 'said'; //said will get loaded into the return object
};
var shout = function(params){
console.error(params.text);
return 'shouted';
};
var sayGoodbye = function(params){
console.log('Goodbye!');
return 'exited';
};




//Finally, we tell the functions to listen for a word
ConvoRoom.listen('error',shout,'shout'); //this tells 'shout' to listen for the word 'error' and dump its return into 'shout'
ConvoRoom.listen('error',goodbye,'bye'); //this tells 'goodbye' to listen for the word 'error' and dump its return into 'bye'

/*The third parameter tells Conversation to load any value that shout returns
into a JSO which is returned to the speaker after all calls have been invoked*/

ConvoRoom.listen('okay',speak,'speak'); //this tells 'speak' to listen for the word 'okay' and dump its return into 'speak'
ConvoRoom.listen('okay',goodbye,'bye'); //this tells 'goodbye' to listen for the word 'okay' and dump its return into 'bye'


//Here, these two functions speak.
var error = function(str){
var result = ConvoRoom.speak('error',{text: "Error! ->"+str}); //shout and goodbye just heard this and dumped their returns into result
console.log(result.shout,result,bye); //you can access returned types this way
};
var okay = function(str){
var result = ConvoRoom.speak('okay',{text: "Everything is okay -> "+str}) //speak and goodbye just heard this and dumped their returns into result
console.log(result.speak,result,bye); //you can access returned types this way
};

Aha! Now none of our functions are bound to anything but the Conversation that they participate in. They don't care who/what handles their request,
as long as they are served satisfaction.

With Conversation, components no longer reference each other at all. In fact, they don't need to know that anything but themselves exist!
Components listen to Conversations and react to Words spoken by other Components. Each component acts as a Listener, and is
bound to one or more Words. If a Component needs to access external functionality or pass information along, it simply Speaks a word
within its Conversation. Any other components that are listening for that word will then react to it and perform a job.
If any of the Listeners return any output, it is collected and passed back en-masse to the Speaker in the form of an Object.

Conversation is ready for include with NodeJS, and extends jQuery for front end usage:

var conv = require('Conversation'); //NodeJS
var room = conv.newRoom();


var room = $.Conversation.newRoom(); //jQuery

Learn More - The "Next" Next big thing...

The uses for Conversation are not only limited to function calls, but can be used in any situation where a function,
data member, object, or even an entire architectural segment needs to be accessed or manipulated in some way. If you cannot yet
decide whether or not the Conversation way is right for you, head on over to our Wiki and take a look at some other ways to
take advantage of our methodology.

Conversation is, and always will be, 100% compatible with NodeJS as well as front-end frameworks.


Copyright (c) 2012 The Jupiter Project, Andrew E. Rhyne

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
Software, and to permit persons to whom the Software is furnished to do so, subject
to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.

For more information regarding this software, feel free to drop me a line:
rhyneandrew@gmail.com