Thursday, September 26, 2013

Compose, don't inherit (not a lot anyway).

Lately I've seen a lot about JavaScript Inheritance and in particular different github projects that allow you to do inheritance in a certain way. Most of these solutions are about trying to use some form of classical inheritance and with good reason. If you're used to any other language then that is probably what you learned and so it makes sense. Also there can be performance gains as using a "class" means you won't be mutating an object's signature and as such a JavaScript runtime can make optimizations for that "type".

There are also some good articles about what JavaScript inheritance is really about and if you only read one, make sure to read Kyle Simpsons: JS Objects.

But do we really need long inheritance chains where we link up lots of objects and have lookups going up a chain? As JavaScript is so flexible can we learn things from Functional and Aspect Oriented styles of programming? I think we can.

At Dataminr we've begun the journey of rewiring (it's like rewriting from scratch but using most of the old code, putting it in different places and changing how it's all passed through) our code. It turns out that combining some ideas gives us an easy way to keep a flat inheritance structure where we can compose together objects that we need. To do this though we have to take functionality away from the objects and put them in services that we can pass our objects in to, split some objects apart and with the rest cut them in to little packets of functionality that can be added when necessary. This leaves us with simple objects and a toolbelt of features we can add on as needed in the main file - we get closer to configuring a product rather than actually coding it.

We're currently using Backbone.Advice which I introduced in this blog post. Since starting with that we've learnt a lot about how to structure the application using the AOP approach. Instead of having the inheritance through the constuctors we moved most inheritance over in to the mixins. From the original blog post I mention that you can build ever more complex mixins by adding in other mixins. Doing this we can do things like make a clickToSelect mixin that will call upon the clickable and selectable mixins.

But won't all these mixins get in each other's way and run when they're not supposed to? Perhaps the most important thing when using these mixins is a naming convention. Inside the Backbone.Advice repository there is a mixins.js file that gives some examples in to using mixins. I wouldn't go ahead and use these in production as they're a bit stale from the version we use in production, but looking in to them you can see there is a very deliberate naming convention. We use very simple, very clear names that describe the current action precisely. We do something similar with the options that are passed in to the mixin (as all mixins will share a common options object). For instance we decided there would only be one scrollable element per view so whenever a mixin needs a handle to the element it exists as options.scrollEl - no matter which mixin needs it.

The one thing that we kept coming up against though (as we still have legacy code being used) is that older classes that extend from these base classes were overwriting functions. Sometimes we wanted to overwrite the base function but we always wanted to keep the mixins applied. To fix this we had to come up with a new way of defining the inheritance. So after all this I get to introduce Backbone.AdviceFactory.

Now all we do is register how something is built by defining it's base (if it's been registered before you just call it's string name) and we can go ahead and add in all the functionality through extends or mixins (though it will automatically put functions as "after", extend existing objects and clobber everything else) and the factory will go back through all the bases, work out the extends and then put the mixins on last. This means all the mixins are kept. We can then Instantiate the object through the factory.

It might be better to see an example - I've commented the code so you can see how it works:

define(['Backbone.AdviceFactory'], function(Factory) {

    // register a base:
    Factory.register('view', {
        base: Backbone.View
    });

    // you can extend and mixin
    // it will pass back the new constructor
    var myView = Factory.register('myView', {
        base: 'view',

        // non reserved keywords are mixed in as after if functions
        // or clobber if not
        defaultSize: 10,
        onSelect: function() {console.log('selected')},

        // or you can pass in the extends
        // such as constructors (as they're functions you don't want mixed in)
        extend: {
            // actually itemView is already a special keyword that will extend
            // but it's here for demonstration purposes
            itemView: itemView
        },

        // functional mixins go here
        mixins: [
            myMixin1,
            myMixin2
        ],

        // options for mixins
        options: {
            scrollEl: '.scroll'
        }

        // also any other advice keywords such as after, before & clobber
        addToObj: {
            events: {
                'click': 'onClick'
            }
        }
    });

    var MyView2 = Factory.register('myView2', {
        base: 'myView',

        // this will mixin as "after" automatically
        initialize: function() {}
    });

    // register returns the constructor
    var myView2inst = new MyView2(arg1);

    // to get the finished product:
    var myView2inst2 = new Factory.get('myView2')(arg1);

    // or better yet
    var myView2inst3 = Factory.inst('myView2', arg1);

});

It's an incredibly powerful way of defining objects. As we write more we tend to find that more functionality can go in to mixins and these structures get a lot flatter, and with a lot less functions given to the factory. The functions mostly come from the mixins and only configuration goes in to the objects (though most of that is passed through at instantiation).

The last piece of advice (no pun intended) we could give is that you will come up against recurring structures in your code. Perhaps you have a widget that will always have a list that will always have a header. To deal with these we create factories that will do all the instantiation for you and wire up everything that needs to talk to each other, just pass in the data and any constructors that are different to the default. This leaves us with simple units we can call upon and just pass in the data. We do all this in the main file so all the data is available to use meaning we can setup complex relationships without having to jump through hoops.

I hope this helps some people out there - we've been using this approach and it works extremely well. It has allowed us to cut down on our development time and spend more time at the pub - which really is what development is all about.

Wednesday, September 11, 2013

Incrementing date to next friday

Saw this on google+ and here is my explanation on how to do it. It should be easy enough to alter the code for any other day, but the question wanted it to go to friday so here is my explanation:

tricky one, but doable. You do want to get the number day, but setting date may not work because of the end of the month...

so get the day:

var date = new Date();
var day = date.getDay();

now we need to normalize those numbers to see how many days forward we need to move. Friday is day 5, but we really want it at day 7 (or 0). so we add 2 and take the modulus of 7.

var normalizedDay = (day + 2) % 7;


now we have the days of the week where we want them. the number of days to go forward by will be 7 minus the normaized day:

var daysForward = 7 - normalizedDay;


if you don't want friday to skip to the next friday then take the modulus of 7 again. Now we just add that many days to the date:

var nextFriday = new Date(+date + (daysForward * 24 * 60 * 60 * 1000));


if you want the start of the day then you have to turn back the hours, minutes and milliseconds to zero:

nextFriday.setHours(0);
nextFriday.setMinutes(0);
nextFriday.setMilliseconds(0);

or for the lazy:

jumpToNextFriday = function(date) {
  return new Date(+date+(7-(date.getDay()+2)%7)*86400000);
}

Promise patterns

Promises are great for giving us a way of writing asynchronous code without having to indent our code but if that's the only thing you're using them for then you're missing the point of promises. Promises are an abstraction that make doing several things easier. They have two properties that make them easier to work with:
  1. You can attach more than one callback to a single promise
  2. values and states (errors) get passed along
Because of these properties it makes common asynchronous patterns using callbacks easy. Here are some cases which may pop up from time to time:

NOTE: For the below I'm going to use APlus which is an implementation of the Promises/A+ spec that we walked through the development of in Promises/A+ - Understanding the spec through implementation. Some of the code below will also be available in the repository under aplus.extras.js. Also we will be using the "Node way" of defining async functions where the first argument takes a function to be run on error and the second function takes the success callback.

Converting callback functions to return promises

We don't want to rewrite all our already written functions to return promises and there are lots of useful libraries out there that already use callbacks. In fact we probably don't want to write and functions that we may share in external libraries later to use promises either. This is because there is no native implementation of promises at the moment. Because of the spec, promises are largely compatible but if we're using one implementation for the library the user might be using a different one for their code. Instead it's better to keep using callbacks for the definition of asynchronous functions as they're the base building block and let the user convert them to use promises if they wish. This can easily be acheived and below is an example of how you can convert a node.js style callback function to use the Aplus implementation of promises:

// take a callback function and change it to return a promise
Aplus.toPromise = function(fn) {
 return function() {

  // promise to return
  var promise = Aplus();

  //on error we want to reject the promise
  var errorFn = function(data) {
   promise.reject(data);
  };
  // fulfill on success
  var successFn = function(data) {
   promise.fulfill(data);
  };

  // run original function with the error and success functions
  // that will set the promise state when done
  fn.apply(this,
   [errorFn, successFn].concat([].slice.call(arguments, 0)));

  return promise;
 };
};

Sometimes a library will already have functions that have their own callback chains setup. In this case you only have to wrap the top function if that is all you need.

Sequential Calls

This is where promises excel. As the return value of a "then" is a promise that gets fulfilled with the value returned by the given function we only have to chain together to get the next value. That's great if your function can return a value directly but if it's asynchronous (which is the whole reason you're using a promise in the first place)  then you'll want to return a promise which then gets used as the basis for firing the next chained "then" method.

an example of promises:

var asyncAddOne = Aplus.toPromise(function(err, cb, val) {
 setTimeout(function() {
  cb(val + 1);
 });
});

var asyncMultiplyTwo = APlus.toPromise(function(err, cb, val) {
 setTimeout(function() {
  cb(val * 2);
 });
});

var asyncInverse = APlus.toPromise(function(err, cb, val) {
 setTimeout(function() {
  if (val === 0) {
   return err('value is zero');
  }
  cb(1 / val);
 });
});

var alertResult = function(value) {
 alert(value);
};

asyncAddOne(1)
 .then(asyncMultiplyTwo)
 .then(asyncInverse)
 .then(alertResult);

You can see that I wrote the asynchronous methods using normal callback style and converted them to return promises. You could Instead write them directly to use a promise like this:

var asyncAddOne = function(val) {
 var promise = APlus();
 setTimeout(function() {
  promise.fulfill(val + 1);
 });
 return promise;
};

Error Handling

If you are calling several services and want any error to short circuit then promises excel at this. If doing this with callbacks we only have to declare each function in turn and put our single error handling function at the end. In the previous example we have an inverse function that can call an error function, if we wanted to write this as a promise directly we could have just thrown an error like so:

var asyncInverse = function(val) {
 var promise = APlus();
 if (val === 0) {
  promise.reject('can not inverse zero');
 }
 setTimeout(function() { 
  APlus.fulfill(1 / val);
 });
 return promise;
};

Though we also have the option of just throwing an error instead which will pass along the value as the error thrown. To add a single error handling function we just need to tack it on to the end of our call:

var onError = function(err) {
 console.error(err);
};

asyncAddOne(1)
 .then(asyncMultiplyTwo)
 .then(asyncInverse)
 .then(alertResult)
 .then(undefined, onError);

Note how the first argument is undefined as the second argument is used for the error. We could just have easily put the onError with the alertResult call, but then we wouldn't catch any error from the alertResult function.

Pool

Sometimes you want the result of several operations before you continue. Instead of waiting for each one to finish before going on with the next we can save some time by firing them all off at once. Basically we have to catch when a promise is finished (through both it's success and error callbacks) and save it's value to an array. Once they're all done then we can fulfill or reject the promise with the given values. We'll first need some code that can do this for us - here is a method that we can use:

// resolve all given promises to a single promise
Aplus.pool = function() {

 // get promises
 var promises = [].slice.call(arguments, 0);
 var state = 1;
 var values = new Array(promises.length);
 var toGo = promises.length;

 // promise to return
 var promise = Aplus();

 // whenever a promise completes
 var checkFinished = function() {
  // check if all the promises have returned
  if (toGo) {
   return;
  }
  // set the state with all values if all are complete
  promise.changeState(state, values);
 };

 // whenever a promise finishes check to see if they're all finished
 for (var i = 0; i < promises.length; i++) {
  (function(index) {
   promises[index].then(function(value) {
    // on success
    values[index] = value;
    toGo--;
    checkFinished();
   }, function(value) {
    // on error
    values[index] = value;
    toGo--;
    // set error state
    state = 2;
    checkFinished();
   });
  })(i);
 };

 // promise at the end
 return promise;
};

Now all we need to do is pass in all the promises we need:

Aplus.pool(
 getName(),
 getAddress()
).then(function(value) {
 var name = value[0];
 var address = value[1];
 alert(name + ' lives at ' + address);
}, function() {
 alert('unable to retrieve details');
});

In the above getName and getAddress both return promises - though it is possible to tweak the pool function logic so that any non-promise return value is just passed through directly. There are some implementations that do this such as jQuery's $.when

Some fun

Okay, there are some common patterns. Let's see if we can build on top of those. Let's say I'm racing some functions. The fastest to return wins the race. They also may error. Let's write such a function that will return a promise that is only fulfilled or rejected after a timeout:

var racer = function(err, success, value) {
 setTimeout(function() {
  if (Math.random() < 0.05) {
   err(value);
  } else {
   success(value);
  }
 }, Math.random() * 2000);
};

var promiseRacer = Aplus.toPromise(racer);

We've given it a 5% chance of error (or if you're like me and pretending it's a horse race - breaking it's leg and not finishing). Now we need to write a function that will run them all:

// return the value of the first succesful promise
Aplus.first = function() {

 // get all promises
 var promises = [].slice.call(arguments, 0);

 // promise to return
 var promise = Aplus();

 // if all promises error out then we want to return an error
 Aplus.pool.apply(Aplus, promises).then(undefined, function(value) {
  promise.reject(value);
 });

 // when there is a success we want to fulfill the promise
 var success = function(value) {
  promise.fulfill(value);
 };

 // listen for success on all promises
 for (var i = 0; i < promises.length; i++) {
  promises[i].then(success);
 }

 return promise;
};

I simple have to hook up the "then" success function to a single promise, as it can only be fulfilled once. You'll also see that I'm using Aplus.pool as well. This is for error handling, we need to handle the case when all the "horses" break their leg. Now let's race them!

Aplus.first(
 promiseRacer('Binky'),
 promiseRacer('Phar Lap'),
 promiseRacer('Sea Biscuit'),
 promiseRacer('Octagonal'),
 promiseRacer('My Little Pony'),
).then(function(value) {
 alert(value + ' wins!');
}, function() {
 alert('no function finished');
});

And there you have it, a simple racing game made with promises.