Watch-in-depth

This library can watch any properties from nested objects, json files and even objects with property of executable function , such as.

var obj = {
  prop1: {
    prop2: ["a", "b", "c"],
  },
  prop3: [{ a: 1 }, { b: 2 }],
  prop4: {
    prop5: {
      prop6: {
        value: "value",
      },
    },
  },
  prop7: () => {
    console.log("running");
  },
};

As you know, in Javascript, Array is an instance of Object. That means the library can watch Array as well, such as

var arr = [
    [1, 2, 3],
    ['a', 'b', {c:3}]
    {a:1},
]

Basically the data structure mixed with all kinds of Object and Array can be watched, so as to watch the whole json file.

Download

npm install watch-in-depth

Usage in Browser

Find watch-in-depth.js in folder of dist

<script src="watch-in-depth.js"></script>
<script>
      let watchable = watchInDepth();
       // watch a new empty object
      let newObj = watchable.createProxy();
      //watch an existing object
      let obj = {a:{b:1}};
      obj = watchable.createProxy(obj);
      //or watch an existing object but don't pollute it.
      let objProxy = watchable.createProxy(obj);
      //add listener
      watchable.on('updated', ()=> console.log('updated'));
      //trigger the event.
      objProxy.a.b = 2 //'updated' in console panel.

</script>

Usage in Node

let watchInDepth = require("./watch-in-depth.js");
let watchable = watchInDepth();
//codes below are same with usage in browser

Events

There are 8 kinds of events that trigger the listener.

Events	Description	Triggered by
beforeRead	emit events before property being read	obj.prop
read	emit events after property being read	obj.prop
beforeUpdated	emit events before value of property being updated	obj.prop ="newValue"
updated	emit events after value of property being updated	obj.prop = "newValue"
beforeChanged	emit events before value of property being changed, pls note that once beforeChanged triggered, the old value and new value of property is different for sure, while beforeUpdated triggered, it only means value is updated, not sure if old value and new value is the same or different. it is the same for update and changed as well	obj.prop = "newValue" && "newValue" != "oldValue"
changed	emit events after value of property being changed.	obj.prop = "newValue" && "newValue" != "oldValue"
beforeRun	if property value is a function, emit events before function property being executed	obj.fn()
run	if property value is a function, emit events after function property being executed	obj.fn()

Watch multiple objects

let watchable1 = watchInDepth();
let watchable2 = watchInDepth();

let obj1 = watchable1.createProxy();
let obj2 = watchable2.createProxy();

watchable1.on("updated", callback1);
watchable2.on("updated", callback2);

obj1.a = 1; //callback1 executed
obj2.b = 2; //callback2 executed

Event object (e) in callback

In order to make sure that browser and node use the same event object. so all properties are defined in e.detail

Property	Description	Comments
eTarget	createProxy(obj)	proxy target
fnTriggered	{ctx: context, args:[], fn: ƒ}	currently triggred by function execution
fnTriggeredPrevious	{ctx: context, args: Array(0), fn: ƒ}	previously triggered by function execution
setTriggered	{property: "propertyName", oldValue: "oldValue", value: "newValue"}	currently triggered by property value setting
setTriggeredPrevious	{property: "propertyName", oldValue: "oldValue", value: "newValue"}	previously triggered by property value setting
getTriggered	{property: "propertyName"}	currently triggered by property get operation
getTriggeredPrevious	{property: "propertyName"}	previously triggered by property get operation

For example

let watchable = watchInDepth();
let obj = { b: {a: 1} };
obj = watchable.createProxy(obj);
watchable.on("updated", (e) => {
  console.log(e.detail.setTriggered);
  console.log(e.detail.setTriggeredPrevious);
});

obj.b.a = 2;
// {"property":"a","value":2,"oldValue":1}
// "undefined"
obj.b.a = 3;
// {"property":"a","value":3,"oldValue":2}
// {"property":"a","value":2,"oldValue":1}

Another way to write listener

You also can write listener in this way below for esay usage if you want, so that you don't have to write so many watchable.on functions.

let fn1 = () =>console.log('updatedCallback');
let fn2 = () =>console.log('readCallback');
let fn3 = () =>console.log('changedCallback'); 
watchable.on('updated, read, changed', fn1, fn2, fn3)

Revoke watch-in-depth

You can stop the watch so that no events trigger any more.

obj = watchable.revoke(obj)