LiveMonitor - Asynchronous Property Monitor

Today I would like to introduce you a quite uncommon JavaScript trick, a trapped Live Object or, generally speaking, a lightweight monitor able to understand when a generic property has been changed.

About Live Objects

A live object could be described as a particular object able to change without our interaction. The most common live object example is this:

// this is the most common live object
// the HTMLCollection
var divs = document.getElementsByTagName("div");
divs.length; // let's say 4

// let's add another div inside a generic node
document.body.appendChild(
    document.createElement("div")
);

divs.length; // 5!

In few words DOM searches are dynamic, which is the reason almost every selector library needs to transform the current result into a static Array.

About LiveMonitor

Specially suited for live objects, LiveMonitor is a function which aim is to notify us when the specified property change:

// LiveMonitor example
var lm = new LiveMonitor(
    // the entire list of elements trapped
    document.getElementsByTagName("*"),
    // the property to monitor
    "length"
);

// add one or more notifier
lm.onchange(function(collection){
    // this, will be the lm object
    this.value; // will be collection.length
    collection.length; // is the new length

    alert([
        "All nodes collection contained ",
        this.value,
        " nodes but now there are ",
        collection.length
    ].join("\n"));
});

The example is quite silly, but the concept is that as soon as the monitor will check the "length" property, in this case in the one of the trapped collection, it will fire the onchange event, notifying us that somebody did something somewhere, and this something changed our monitored property.

LiveMonitor Code

var LiveMonitor = (function(){

/** LiveMonitor :: Asynchronous Property Monitor
 * @author      Andrea Giammarchi
 * @license     Mit Style
 * @blog        http://WebReflection.blogspot.com/
 */

function LiveMonitor(object, property){
    this.value = object[property];
    this._property = property;
    this._object = object;
    this._event = [];
    this._i = 0;
};

LiveMonitor.prototype.onchange = function onchange(callback){
    this._event.push(callback);
    if(this._i === 0){
        var _property   = this._property,
            _object     = this._object,
            _event      = this._event,
            self        = this
        ;
        this._i = setTimeout(function _i(){
            if(self.value !== _object[_property]){
                for(var i = 0, length = _event.length; i < length; ++i){
                    if(_event[i].call(self, _object) === false)
                        break
                    ;
                };
                self.value = _object[_property];
            };
            if(0 < self._i)
                self._i = setTimeout(_i, 15)
            ;
        }, 15);
    };
};

LiveMonitor.prototype.offchange = function offchange(callback){
    for(var _event  = this._event, i = 0, length = _event.length; i < length; ++i){
        if(_event[i] === callback)
            _event.splice(i, 1)
        ;
    };
    if(_event.length === 0){
        clearTimeout(this._i);
        this._i = 0;
    };
};

LiveMonitor.prototype.clear = function clear(){
    this._event = [];
    this.offchange(null);
    this.value = this._object[this._property];
};

return LiveMonitor;

})();

Not Only DOM Searches

LiveMonitor could be actually used as asynchronous notifier for any kind of variable.
Let's say we have an environment able to load runtime scripts but we cannot change loaded scripts (external source inclusion).
At some point we press the "load jQuery" button and we would like to be able to be notiied when it is available ...

if(!window.jQuery){

    // create a LiveMonitor instance over
    // jQuery property
    var jqlm = new LiveMonitor(window, "jQuery");

    // add onchange event
    jqlm.onchange(function(window){

        // remove this event
        this.offchange(arguments.callee);
        // remove jqlm as well, it is not useful
        // anymore for this example

        // use jQuery, it's here for sure!
        $("body").html("Hello LiveMonitor!");
    });

    // load external script
    loadScript("http://external/jQuery.js");
};

Conclusion

With a cross-browser, portable, and lightweight function, we can use notifications without effort over objects, HTMLCollections, Arrays, or everything else we would like to monitor. Let's say this is a sort of asynchronous cross browser Object.prototype.watch, but this time without alchemy.

Internet Explorer Object watch

Update
As Luke suggested, there is a method remove in the watcher that should solver leaks problem while the new version should be supported by most recent Opera, Safari, FireFox, and Internet Explorer.
Main updates:

• the watcher is always another object and not the original one


• to safely destroy the watcher use its destroy method and then delete it

----------------------------------------------


We all complain about IE and its non-standard attitude, this time I would like to introduce a non standard feature, as Object.prototype.watch is, for Internet Explorer.

What is watch and why we need it

The watch method allows validation, control, monitoring, over a generic object.
This means that we can control properties assignment with one, or more, callbacks.

var man = {};
man.watch("name", function(propertyName, oldValue, newValue){
    // propertyName: name
    // oldValue:     undefined if it is the first time, the old one otherwise
    // newValue:     new assigned value
    return "Mr " + newValue;
});

man.name = "Andrea";
alert(man.name); // Mr Andrea

watch for Internet Explorer, about my implementation

I used a weird strategy to implement this feature in Internet Explorer and it is based on DOM and its IE feature called onpropertychange.
Accordingly, it was not possible to create an Object.prototype.watch, while it was simple to implement a createWatcher callback.

(function(watch, unwatch){
createWatcher = watch && unwatch ?
    // Andrea Giammarchi - Mit Style License
    function(Object){
        var handlers = [];
        return {
            destroy:function(){
                handlers.forEach(function(prop){
                    unwatch.call(this, prop);
                }, this);
                delete handlers;
            },
            watch:function(prop, handler){
                if(-1 === handlers.indexOf(prop))
                    handlers.push(prop);
                watch.call(this, prop, function(prop, prevValue, newValue){
                    return Object[prop] = handler.call(Object, prop, prevValue, newValue);
                });
            },
            unwatch:function(prop){
                var i = handlers.indexOf(prop);
                if(-1 !== i){
                    unwatch.call(this, prop);
                    handlers.splice(i, 1);
                };
            }
        }
    }:(Object.prototype.__defineSetter__?
    function(Object){
        var handlers = [];
        return {
            destroy:function(){
                handlers.forEach(function(prop){
                    delete this[prop];
                }, this);
                delete handlers;
            },
            watch:function(prop, handler){
                if(-1 === handlers.indexOf(prop))
                    handlers.push(prop);
                if(!this.__lookupGetter__(prop))
                    this.__defineGetter__(prop, function(){return Object[prop]});
                this.__defineSetter__(prop, function(newValue){
                    Object[prop] = handler.call(Object, prop, Object[prop], newValue);
                });
            },
            unwatch:function(prop){
                var i = handlers.indexOf(prop);
                if(-1 !== i){
                    delete this[prop];
                    handlers.splice(i, 1);
                };
            }
        };
    }:
    function(Object){
        function onpropertychange(){
            var prop = event.propertyName,
                newValue = empty[prop]
                prevValue = Object[prop],
                handler = handlers[prop];
            if(handler)
                attachEvent(detachEvent()[prop] = Object[prop] = handler.call(Object, prop, prevValue, newValue));
        };
        function attachEvent(){empty.attachEvent("onpropertychange", onpropertychange)};
        function detachEvent(){empty.detachEvent("onpropertychange", onpropertychange);return empty};
        var empty = document.createElement("empty"), handlers = {};
        empty.destroy = function(){
            detachEvent();
            empty.parentNode.removeChild(empty);
            empty = handlers = null;
        };
        empty.watch = function(prop, handler){handlers[prop] = handler};
        empty.unwatch = function(prop){delete handlers[prop]};
        attachEvent();
        return (document.getElementsByTagName("head")[0] || document.documentElement).appendChild(empty);
    }
    )
;
})(Object.prototype.watch, Object.prototype.unwatch);

A first example, based on precedent one, is this one:

var // original object
    man = {},
    
    // create its watcher
    manWatcher = createWatcher(man);

manWatcher.watch("name", function(propertyName, oldValue, newValue){
    return "Mr " + newValue;
});

// assign name property
manWatcher.name = "Andrea";

// retrieve original object property
alert(man.name); // Mr Andrea

Another example is based on validation, or better, a one shot assignment over the watcher:

var obj = {},
    watcher = createWatcher(obj);

watcher.watch("test", function(prop, oldValue, newValue){
        return oldValue === undefined ? newValue : oldValue;
});

watcher.test = "one assignment";
watcher.test = "never again";

alert(obj.test); // one assignment

Cool?

About limits

The main one is that the for in loop will not work as expected over a watcher element because it is a DOM node and it will expose every property.
Another one could be about memory leaks and/or low execution, since there are a couple of things to do during assignment.
The good part is that the watcher and the watched will have the same property value, except for those attributes that we cannot modify in a DOM node (style, for example).

Last but not least, happy new year! :D