deep-observer
v1.1.7
Published
Tiny Object Observe library, to deep watch and track changes in Objects and Arrays.
Downloads
9
Maintainers
Readme
Deep Observer
Tiny Object Observe library ( < 100bytes gziped), to deep watch and track changes in Objects and Arrays. The provided callback to the Constuctor is executed each time a change is deteced, recieving a complete set of data relative to the detected change.
- Deep Observation ( configurable Depth )
- Optional construction observe
- Compatible with all JS primitive types
- No dependencies
- Wide platform support :
- Node
- Chrome 49
- Firefox 34
- Edge 14
- Opera 36
- Safari 10
Syntax
1. Constructor
When at least two arguments are passed to Observer()
, it behaves as a Constructor :
new Observer( object , callback [, config] )
object
: Object to observecallback
: Function to be invoked on object changesconfig
: (optional) Objectid
: Unique string to use as identifier to the Observable. (if not provided is generated automatically)observeConstruction
: Boolean. If true callback will be executed also in construction stage. (default: false)depth
: Integer. Sets the observing depth limit. When set to 0, no limit is applied (default : 0 )ignoreSameValueReassign
: Boolean. By default callback is only executed when the assigned value differs from the previous one. When this option is set to false, callback function is executed always ( default : true )
Returns : an Observable (Proxy)
Note : deep-observer DOES NOT perform changes in the original provided Object. The observation is performed in the Observable returned Object.
2. Getter
When only a String is provided to Observer()
it behaves as a getter :
Observer( id )
ìd
: String provided previously in the constructor config object
Returns : the matching Observable (Proxy) or undefined
3. Callback function
The function called each time changes are made, will receive an event object containng the following properties :
action
: String containing one of the following values : add|update|deleteobject
: Affected property parent's Objectname
: Name of the modified property (or array index)oldValue
: Value of the property before the changekeypath
: String representing the internal path to the affected property.
Basic usage example
Provide to the constructor an object
and a callback
, and perform a change on the object, to see how the callback
is triggered:
// create an observable object
const myObserved = new Observer( { a : 12 } , e=>console.log('changed!' , e) );
// perform a modification
myObserved.a = 14;
// console outputs : 'changed!' { action:'update', oldValue:12, object:{a:14}, name:'a' }
Advanced usage example
An example of new Observer using all the configuration parameters
// create an observable object
const myObserved = new Observer(
{ a : 12 } , // object to abserve
e=>console.log('changed!' , e) , // callback
{
id : 'observed_1', // observable internal id
depth : 5, // observe maximum 6 levels of depth
observeConstruction : true , // execute callback on construction
ignoreSameValueReassign : false // call callback always
}
);
// because observeConstruction=true, callback fuction is executed...
// console outputs : 'changed!' { action:'add', keypath : 'observed_1.a.' , oldValue:undefined, object:{a:12}, name:'a' }
// perform a modification...
myObserved.a = 14;
// console outputs : 'changed!' { action:'update', keypath : 'observed_1.a.' , oldValue:12, object:{a:14}, name:'a' }
// retrieve the observable...
const sameObserved = Observer('observed_1');
console.log( myObserved === sameObserved );
// console outputs : true
Package distribution :
In browser enviroment you can include this library using the jsdelivr CDN ...
<script src='https://cdn.jsdelivr.net/gh/colxi/deep-observer@latest/src/deep-observer.min.js'></script>
If you are in the NodeJs enviroment, can install the package via:
$ npm install deep-observer --save
Licence
GPL 3