I'm writing a JavaScript API and for a particular case, I'm wondering which approach is the sexiest. Let's take an example: writing a VideoPlayer, I add a getCurrentTime method which gives the elapsed time since the start.

  1. The first approach simply declares getCurrentTime as follows:


    where number is the native number type. This approach includes a CURRENT_TIME_CHANGED event so that API users can add callbacks to be aware of time changes. Listening to this event would look like the following:

    myVideoPlayer.addEventListener(CURRENT_TIME_CHANGED, function(evt){
        console.log ("current time = "+evt.getDispatcher().getCurrentTime());
  2. The second approach declares getCurrentTime differently:


    where CustomNumber is a custom number object, not the native one. This custom object dispatches a VALUE_CHANGED event when its value changes, so there is no need for the CURRENT_TIME_CHANGED event! Just listen to the returned object for value changes! Listening to this event would look like the following:

    myVideoPlayer.getCurrentTime().addEventListener(VALUE_CHANGED, function(evt){
        console.log ("current time = "+evt.getDispatcher().valueOf());

    Note that CustomNumber has a valueOf method which returns a native number that lets the returned CustomNumber object being used as a number, so:

    var result = myVideoPlayer.getCurrentTime()+5;

    will work!

So in the first approach, we listen to an object for a change in its property's value. In the second one we directly listen to the property for a change on its value. There are multiple pros and cons for each approach, I just want to know which one the developers would prefer to use!

1 Answer 1


Go with the first approach. When people use a method like getCurrentTime() and store the returned value, they expect that that value will remain the time at the moment they called the method. Having that value suddenly change is going to be a source of great confusion:

prevTime = myVideoPlayer.getCurrentTime();
//...at some later point
timeElapsed = myVideoPlayer.getCurrentTime() - prevTime;

Now timeElapsed is 0, which is wrong. The correct code for that API would be:

prevTime = myVideoPlayer.getCurrentTime().valueOf();
//...at some later point
timeElapsed = myVideoPlayer.getCurrentTime() - prevTime;

But this way is very uncommon, and most people will instinctively use the first method and get confusing bugs.

  • Thank you! I'm agree with you, that is what i anticipate but i wasn't able to find an exemple that show why it is better. I cannot vote yet since my reputation here is not enough... Whatever, thank you!
    – Clem
    May 28, 2014 at 15:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.