Rewrote readme and improve api

I would need rubber duck debugging for the only test failing please :(
I can't see why it never receives a response :|
we should use `self` everywhere, here you're using `this` just after defining `var self = this`.