Monitor property additions and deletions, and even more changes

[bllanos]

Current behaviour

• Wrapper objects (produced by src/wrapper/wrapper.coffee) have accessor properties corresponding to each own property of the source object at the time of their creation.
• New properties added to a wrapper object are not given usage monitoring functions (to record accesses and value changes).
  • The addition of a new property is not recorded as an observation event, and there is no mechanism in place for detecting such a change.
• When properties are deleted from the object, their deletion is not recorded/detected.
  • If the property a function or object and happens to be saved in another variable by the client, the wrapper will continue to receive observation data from it, because the property is also a wrapper object.

    Possible solutions

The idea solution would be to use Object.observe(), which is part of ECMAScript 7 and not yet available in all environments.

In the meantime, there are many polyfills and full-blown libraries that approximate Object.observe(). After searching the NPM website for "object.observe" and "observe", I have a few favourites so far:

• (Best option) observe-js seems to be quite popular, and will work without Object.observe.
• observe-plus, can recursively observe objects (Object.observe only observes the top-level properties of an object).
  • Unfortunately, it requires that Object.observe already exists.
  • I don't actually need recursive observation of objects, because the wrapper code is already recursive (in that it wraps properties when they are accessed).
• object.observe is a straight-forward polyfill.

Note that polyfills perform "dirty checking", which is expensive and can be easily misused to cause memory leaks.

Details and Validation

• Check if changes made to the object using Object.defineProperty() are recorded. (Such changes bypass the current wrapper code.)
  • Redefinitions may possibly appear under the "reconfigure" event type?
• Make use of the currently unused event types (OBSERVATION_CATEGORIES) in src/util/constants.coffee

  Resources

• Introduction to Object.observe at HTML 5 Rocks
• MDN page mentioned above on Object.observe
  • Includes a link to the specification proposal

[ghost]

There are a few problems with object.observe (v0.2.4) and observe-js (v0.4.2). The main issue with both libraries is that they do not guarantee that they report operations in the order they occurred. This means that some operations can even not be reported at all (if a delete was reported before a change or add, for example). It seems there is nothing that can be done about this in a Javascript polyfill. While the native implementation of Object.observe seems to preserve order, the Node's Javascript runtime does not support it yet.

There are also some likely bugs with both libraries. The object.observe library seems to continue monitoring objects even when unobserved is called (thus never terminating the script). The objserve-js library seem to have an issue where, if any property of an object that is being observed contains the value 'NaN', then it will over-report on the variable even when it doesn't change.

@bllanos and I have decided that this issue can remain for now. This documentation was provided to aid me or future developers attempting to fix the issue of addition and deletion monitoring.

[bllanos]

For future reference, added properties should not have their accesses checked, as it is possible for them to be accessed before the wrapper code receives notification of their existence (and has a chance to wrap them in getter/setter functions).

This should be mentioned in the documentation of the project.