Object.observe(..)

One of the holy grails of front-end web development is data binding — listening for updates to a data object and syncing the DOM representation of that data. Most JS frameworks provide some mechanism for these sorts of operations.

It appears likely that post ES6, we’ll see support added directly to the language, via a utility called Object.observe(..). Essentially, the idea is that you can set up a listener to observe an object’s changes, and have a callback called any time a change occurs. You can then update the DOM accordingly, for instance.

There are six types of changes that you can observe:

• add
• update
• delete
• reconfigure
• setPrototype
• preventExtensions

By default, you’ll be notified of all these change types, but you can filter down to only the ones you care about.

Consider:

var obj = { a: 1, b: 2 };
Object.observe(
    obj,
    function(changes){
        for (var change of changes) {
            console.log( change );
        }
    },
    [ "add", "update", "delete" ]
);
obj.c = 3;
// { name: "c", object: obj, type: "add" }
obj.a = 42;
// { name: "a", object: obj, type: "update", oldValue: 1 }
delete obj.b;
// { name: "b", object: obj, type: "delete", oldValue: 2 }

In addition to the main "add", "update", and "delete" change types:

• The "reconfigure" change event is fired if one of the object’s properties is reconfigured with Object.defineProperty(..), such as changing its writable attribute. See the this & Object Prototypes title of this series for more information.

• The "preventExtensions" change event is fired if the object is made non-extensible via Object.preventExtensions(..).

  Because both Object.seal(..) and Object.freeze(..) also imply Object.preventExtensions(..), they’ll also fire its corresponding change event. In addition, "reconfigure" change events will also be fired for each property on the object.

• The "setPrototype" change event is fired if the [[Prototype]] of an object is changed, either by setting it with the __proto__ setter, or using Object.setPrototypeOf(..).

Notice that these change events are notified immediately after said change. Don’t confuse this with proxies (see Chapter 7) where you can intercept the actions before they occur. Object observation lets you respond after a change (or set of changes) occurs.

Custom Change Events

In addition to the six built-in change event types, you can also listen for and fire custom change events.

Consider:

function observer(changes){
    for (var change of changes) {
        if (change.type == "recalc") {
            change.object.c =
                change.object.oldValue +
                change.object.a +
                change.object.b;
        }
    }
}
function changeObj(a,b) {
    var notifier = Object.getNotifier( obj );
    obj.a = a * 2;
    obj.b = b * 3;
    // queue up change events into a set
    notifier.notify( {
        type: "recalc",
        name: "c",
        oldValue: obj.c
    } );
}
var obj = { a: 1, b: 2, c: 3 };
Object.observe(
    obj,
    observer,
    ["recalc"]
);
changeObj( 3, 11 );
obj.a;            // 12
obj.b;            // 30
obj.c;            // 3

The change set ("recalc" custom event) has been queued for delivery to the observer, but not delivered yet, which is why obj.c is still 3.

The changes are by default delivered at the end of the current event loop (see the Async & Performance title of this series). If you want to deliver them immediately, use Object.deliverChangeRecords(observer). Once the change events are delivered, you can observe obj.c updated as expected:

obj.c;            // 42

In the previous example, we called notifier.notify(..) with the complete change event record. An alternative form for queuing change records is to use performChange(..), which separates specifying the type of the event from the rest of event record’s properties (via a function callback). Consider:

notifier.performChange( "recalc", function(){
    return {
        name: "c",
        // `this` is the object under observation
        oldValue: this.c
    };
} );

In certain circumstances, this separation of concerns may map more cleanly to your usage pattern.

Ending Observation

Just like with normal event listeners, you may wish to stop observing an object’s change events. For that, you use Object.unobserve(..).

For example:

var obj = { a: 1, b: 2 };
Object.observe( obj, function observer(changes) {
    for (var change of changes) {
        if (change.type == "setPrototype") {
            Object.unobserve(
                change.object, observer
            );
            break;
        }
    }
} );

In this trivial example, we listen for change events until we see the "setPrototype" event come through, at which time we stop observing any more change events.