Experimental function to transparently override nested JS objects.
AG_defineProperty(path_to_the_property:string, descriptor:ExtendedPropertyDescriptor, base?:object):void
In short, whenever a nested property path_to_the_property of an object base (defaults to window) can be accessed, it will already have a property descriptor provided by you with AG_defineProperty call.
AG_defineProperty works by defining getters and setters on objects in the nested property.
If a property was already defined when AG_defineProperty call was made, it will try to re-define property descriptors with getters and setters, keeping the original value.
If such a property was non-configurable, we cannot re-define it, and instead it will try to directly mutate the property's value. If it was an accessor property, AG_defineProperty will invoke the getter once in order to obtain property's value.
If a property is defined after AG_defineProperty call with Object.defineProperty, such operation is likely to fail, since AG_defineProperty attaches a non-configurable property descriptor (This limitation can be overcomed with ES6 Proxy, but this approach has its own limitations).
Defining properties on a single object multiple times will succeed as long as it does not attempt to define a descriptor provided by you with configurable: false more than once on a single object.
AG_defineProperty supports Access side-effect descriptors, as an extension of ECMAScript Property descriptors.
Recall that a property descriptor is an accessor descriptor if it owns either a property get or set, and a data descriptor if it owns eiter a property value or writable, and a generic descriptor otherwise.
A property descriptor is an access side-effect descriptor if it owns either a property beforeGet or beforeSet. It can have additionally configurable, enumerable properties. Those callbacks are called just before the original getter/setter, with some arguments: beforeGet is called with the original owner of the property, and beforeSet is called with the incoming value and the original owner of the property. In addition, a value returned from beforeSet is fed to the original setter.
AG_defineProperty('onerror', {
beforeGet: function() {
console.log('retrieving global error event handler');
},
beforeSet: function(i) {
console.log('setting global error event handler');
return function wrapper(evt) {
console.error(evt);
i.apply(this, arguments);
}
}
});
Install dependencies by running:
yarn install
The dev build without minification can be built with:
yarn run build-dev
The minified build is available with:
yarn run build
Run tests with build output with:
yarn run test