Trainwreck.js : chaining made easy

https://github.com/millermedeiros/trainwreck.js/

Why?

Chaining can be an useful feature when you want to perform multiple actions in sequence, but implementing it manually can be tiresome and returning this at each function seems awkward - there is a "better" way of doing it.

A lot of people don't understand how chaining works, they think it's something "magical" which can't be easily replicated, and because of that they augment jQuery or underscore.js just to be able to use chaining. - Modifying objects you don't own is considered a bad practice!

Haven't I seen this before?

Nothing groundbreaking about this library. I've done the same thing a couple times before and I'm sure a lot of people have done it as well, sharing it just because it can be useful and because I couldn't find a library which the only purpose was to provide chaining.

Why name it Train Wreck?

The name is a homage to Robert C. Martin book Clean Code. The author uses the term on the Chapter 6 (Objects and Data Structure) to name a sample code that appears to violate the Law of Demeter. According to the author "it look like a bunch of coupled train cars." and it is "generally considered to be sloppy style and should be avoided".

I'm also not a huge fan of chaining and think it should be used with care, if abused it can make code harder to read and to refactor, but sometimes it can make code cleaner and depending on the API it makes total sense to use it.

Examples

Chaining all the properties and methods of an Object

//base object
var base = {
    val : 'lorem',
    trace : function(){
        console.log(this.val);
    }
};
 
//create a new object that wrap calls to the "base" object
var foo = trainwreck.create(base);
 
//"chain, chain, chain.."
foo.trace().val('ipsum').trace();
 
//note that `base` is modified, `foo` is just an alias.
console.log(base.val); //log "ipsum"

Chaining individual members

//`bar` should be defined before calling the `prop` and `fn`
//passing it as parameter.
var bar = {};
 
//chainable alias to "base" methods
bar.msg = trainwreck.prop('val', base, bar);
bar.log = trainwreck.fn('trace', base, bar);
 
//"chain, chain, chain.."
bar.log().msg('awsum').log();
 
//note that `base` is modified, `bar` is just an alias.
console.log(base.val); //log "awsum"

Changelog

v0.1.0 (2010/10/19)

• initial release.

Author

Miller Medeiros

License

Released under the WTFPL.