A Proxy Based Implementation Of Object.observe plus Object.deepObserve
npm install proxy-observeObject.deepObserve` goes beyond the EcmaScript spec and implements the ability to observe an object and all its sub-objects with a single call.
A Proxy Based Implementation Of `Object.observe`, `Array.observe` plus `Object.deepObserve`. `Object.observe` and `Array.observe` have now been deprecated from Chrome and standards tracks, but some developers may still find them useful or require them for backward compatibility in Chrome applications.
Installation
`npm install proxy-observe`
The index.js and package.json files are compatible with https://github.com/anywhichway/node-require so that proxy-observe can be served directly to the browser from the node-modules/proxy-observe directory when using node Express. You can also use the files in the browser subdirectory directly.
In late April 2016 `Object.observe` disappeared from Chrome and Proxy appeared. As a result, the focus on supporting this library will go up so that can be used to replace what is now missing functionality in Chrome as well as support observers in other browsers.
Philosophy
This library exists because despite some people's reasonable philosophical concerns regarding the use of observers and the fact they have been deprecated from Chrome and were never fully supported in other JavaScript engines, some people still want to use them.
There is a slightly more complete EcmaScript implementation available at https://github.com/MaxArt2501/object-observe. This is probably the most popular `Object.observe` polyfill available at the moment. However, it has well documented and acknowledged shortcomings. It is based on polling which means some events get delivered out of order or even missed. It's author provides a reasonable rationale for not using Proxies to implement `Object.observe`.
The above being said, we had an application that could not afford to miss events or have them out of order and we also wanted something lighter and potentially faster. Hence, we built a Proxy based polyfill. As far as we know the sole shortcomings of our implementation are:
1. There are some less used functions not yet implemented, e.g. `deliverChangeRecords`.
2. The variables pointing to objects that are being observed must be re-assigned to point to a proxy returned by the call to `Object.observe`, e.g.
`javascript
var object = { foo: null };
object = Object.observe(object, function(changeset) {
console.log(changeset)
});
object.foo = "bar";
`
will result in `{foo: "bar"}` being printed to the console
Item one above can be re-mediated over time.
We believe item two is a small price to pay. Our implementation is also less than 200 lines of code and 4.5K minified including `Array.observe` and `Object.deepObserve` vs. over 500 lines of code and 28K for MaxArt2501 covering just `Object.observe`.
There is an additional implementation at https://github.com/joelgriffith/object-observe-es5. This implementation is synchronous and modifies all object properties to have custom getters and setters. This could really bind up your application if there are a lot of changes to objects. It also only monitors enumerable properties and like the MaxArt2501 implementation is several hundred lines of code.
Anyway, now you have a choice MaxArt2501, Joel Griffith or AnyWhichWay, and choice is good! They all have their pros and cons.
Usage and Enhancements
Object.observe = function(object,[callback[,acceptlist[,pausable[,pause[,delay]]])
Proxy-observe makes the second arguments to `Object.unobserve` and `Array.unobserve` optional so that an object can be completely un-observed in one call. Additionally, `.unobserve returns the original observed object or array "deproxied".
Object.observe
Proxy-observer supports a deepObserve capability on nested objects. It also allows the pausing and starting of observers using two additional optional arguments to `Object.observe`.
`pausable` - a boolean that indicates to create the observer so it can be paused. The argument `pausable` is optional to reduce the chance of shadowing a property or method on any existing code.
`pause` - a boolean that indicates to create the observer in paused state
If pausable is true then an additional method `deliver(ignorePrevious)` is available to start delivery.
To pause delivery, set a property called `pause` on the function `deliver` to true. Re-set it to false and call `deliver(ignorePrevious)` to re-start change handling. If `ignorePrevious` is set to true, then queued changes will not cause the invocation of observer callbacks.
What's Implemented and Not and Other Issues
`Array.observe` does not behave well in Chrome. It is the native implementation that does not behave well. We are looking to patch this in the future. Unit tests pass in Firefox, which uses our observe implementation.
You can observe for ["add", "update", "delete", "reconfigure", "setPrototype","preventExtensions"] using `Object.observe`.
You can observe for ["add", "update", "delete", "splice"] using `Array.observe`.
`Object.getNotifier` and `Object.deliverChangeRecords` are not implemented.
Currently `Object.deepObserve` does not support event type selectivity. All events are monitored. There is also no `Object.deepUnobserve`.
v0.0.12 setPrototypeOf observing does not work in Firefox.
Release History
v0.0.21 2017-02-06 Enhancements: check the type of objects (object, array, date, etc), check if the new object already have an proxy based on ('observers') Thanks @vitormsilva!
v0.0.20 2017-01-21 Fixed issue #16. Thanks @vitormsilva!
v0.0.19 2016-11-13 Fixed issue 15 where "delay" was undefined.
v0.0.18 2016-07-22 Ehanced to take a 6th argument, delay, to set delivery timeout on changes in milliseconds. Also reduced CPU load by making the delivery function "smart". Delivery no longer creates timeout calls if there is nothing to deliver. The next change to an object will restart the delivery function with the previous delay setting.
v0.0.17 2016-06-15 Fixed Issue 10 thanks to goodells. Updated unit test should support response to pop accordingly.
v0.0.16 2016-06-02 Modified delivery timeout from 0ms to 10ms to reduce CPU loading.
v0.0.15 2016-05-15 README updates. `Unobserve` added to Array corrected issue with `Object.unobserve` not working. Also made callback argument to unobserve optional, which eliminates all observations. Finally, added an `unobserve` method on on observed instances which returns the original object, i.e. de-proxies, Added more unit tests.
v0.0.13,14 2016-05-12 README and code style improvements.
v0.0.12 2016-05-11 Addressed issue 5. Added unit tests. Coverage over 90%. `Array.unobserve` still not implemented. `setPrototypeOf` observing does not work in Firefox.
v0.0.11 2016-05-06 Addressed issues 2,3,4 ... added some unit tests to address issue 4. Unsure how long issue 2 has been undiscovered. Issue 3 has been in all versions. Issue 4 is an enhancement. Started testing in NodeJS v6.0 now that Proxy is supported by NodeJS. `Array.unobserve` still not implemented.
v0.0.10 2016-01-26 Added browserified versions. Re-wrote unit tests to use blanket.js since unit tests will always pass on Chrome since it has native support for `Object.observe` and unit testing must be done in the browser until node.js support MS Chakra. However, the test coverage reporting is not working.
v0.0.9 2015-12-13 Added some unit tests and updated documentation. Consider this a BETA.
v0.0.8 2015-12-13 Codacy driven enhancements. Consider this a BETA.
v0.0.6 2015-11-07 Fixed another issue with testing for existence of Proxy object. Consider this a BETA.
v0.0.5 2015-11-07 Fixed issue with testing for existence of Proxy object. Consider this a BETA.
v0.0.4 2015-10-03 Fixed issue with `deepObserve` discovered during code walkthrough. Issue would have impacted non-Chrome browsers. Consider this a BETA.
v0.0.3 2015-10-01 Updated README. No unit tests yet. Consider this a BETA.
v0.0.2 2015-10-01 Added `Object.deepObserve` and `Array.observe``. No unit tests yet. Consider this a BETA.