View in GitHub
What's it?

CocktailJS is a small library for NodeJS to help developers defining classes and modules in a better, more readable and organised way. It also explores other technics to reuse code such as Annotations, Traits and Talents.

For Who?

For those developers who likes Object Oriented Programming, CocktailJS helps to extend your classes without utils, to define modules, and to keep code structure more visually appealing making the code easier to understand and debug.


There is one principle behind CocktailJS's design: Keep code simple, readable and reusable. Simplicity is key in any design, and writing code is not an exception to that rule.


The entry point in Cocktail is a method named mix(). As in any cocktail, you mix things up. In the mix we can use an existing Object, Module or Class reference and mix it to add more value, like adding more properties or even methods.

Mix Object Example

var cocktail = require('cocktail'),
    obj = {
        name: 'My Object'

cocktail.mix(obj, {
    value: 10,
    print: function() {
        console.log( + ' ' + this.value);

obj.print(); //MyObject 10

Read more: Quick Start


Annotations are meta-data CocktailJS uses to apply some processes. As meta-data, they are not part of the resulting mix, they are declarative and they bring readability on your code.

A Class Example (Car.js)

var cocktail = require('cocktail');

    '@exports': module,
    '@as': 'class',

    '@properties': {
        make: '',
        model: '',
        year: null

    constructor: function(make, model, year) {

Read more: Class Definitions


Traits are Composable Units of Behaviour (You can read more from this paper). Basically, a Trait is a Class, but a special type of Class that has only behaviour (methods) and no state. Traits are an alternative to reuse behaviour in a more predictable manner. They are more robust than Mixins, or Multiple Inheritance since name collisions must be solved by the developer beforehand. If you compose your class with one or more Traits and you have a method defined in more than one place, your program will fail giving no magic rule or any kind of precedence definition.

var cocktail = require('cocktail'),
    Login    = require('./trait/login');

    '@exports': module,
    '@as': 'class',
    '@traits': [Login]

Read More: Starting with Traits


Talents are very similar to Traits, in fact a Trait can be applied as a Talent in CocktailJS. The main difference is that a Talent can be applied to an object or module. So we can define a Talent as a Dynamically Composable Unit of Reuse (you can read more from this paper).

Note: While almost all functionality is implemented, the only missing part from the original paper is the ability to remove a Talent from a given instance.

var cocktail = require('cocktail'),
    Login    = require('./trait/login'),
    user     = require('./user');

cocktail.mix(user, {
    '@talents': [Login]

Read More: Exploring Talents

Install CocktailJS Now!

Use npm to install and save it to your project.

$ npm install cocktail --save

Discuss & Share: Recent Posts

Properties & Non Primitive Values

11 Dec 2013
javascript oop properties

Javascript has five primitive data types: String, Number, Boolean, Null and Undefined. All of these are inmutable, meaning that their values cannot be changed, while Objects, Array, Date, and others are mutable.

This post is intended to show a very subtle difference while defining properties values for a Class inside a prototype versus in the constructor.

TL;DR Do not define mutable properties (Object, Array, Date, etc) in the prototype.

CocktailJS v0.5.0 Released

28 Nov 2013

We are happy to announce a new version of CocktailJS! CocktailJS v0.5.0 is available on npm!

A new version and more!

With this new release we added more functionality to cocktail by adding a new way to create, use and share custom annotations. We also improved the code by refactoring some internals to avoid duplicated code, fixed some issues and we have added some tests too. But that's not all. We have created a few CocktailJS Extensions and you can expect more of them to be released in a near future.

EventEmitter as Delegate using Traits

11 Oct 2013
traits node javascript

One of the most used modules in NodeJS is events. This module exposes a class called EventEmitter that allows you to listen to events in your application using the on or addListener methods. You can, as well, emit or fire your own custom events using emit.

Commonly, you would create an instance of EventEmitter or you could extend from it when you want to give your class the ability to listen to or fire events.