README.md

What is obj-watcher.js ?

watcher.js is a small library that allows you to take action when a watched variable changes and to execute callbacks when it happens.

Why obj-watcher.js ?

With ECMA 2015 you can easily do this using a Proxy, however this approach has some problems:

1. When you use a Proxy every time you change an object, the Proxy fires. This is good if you change the object one property at a time, but in cases were you change multiple properties at the same time, you get spammed with repeated events and there is nothing you can do about it. Alternative libraries exist which try to deal with this via timers, but the solution is overall cluncky and error prone. obj-watcher.js makes sure that each time you modify an object, no matter how many properties change, you only get one event fired.
2. To use Proxies you must change the variable directly. This is prone to having a lot of side effects in your code. obj-watcher.js makes use of getters and setters and it promotes a declarative programming style via Object.assign.
3. Once you create a Proxy for a variable, you no longer know about it. In fact, you just forget the proxy exists, which makes debugging harder. obj-watcher.js makes you aware that you are dealing with a watched object.

How to use obj-watcher.js ?

Install

Run:

• npm install obj-watcher --save

API

obj-watcher.js offers the following methods that you can use.

• watch
• unwatch
• onChange
• get
• set
• reset

For more information about them you can read the documentation on the library's official page.

Example

Watch an object and console.log a message when it changes:

    const watcher = require("obj-watcher");

    watcher.watch("food", {fruit: "bananas"}); //watch it!
    watcher.onChange("food", (oldObj, newObj) => console.log(`I like ${newObj.fruit} better!`));

    watcher.set("food", {fruit: "oranges"});
    //I like oranges better!

Bugs and issues

If you have any trouble or find any issues with the package, feel free to let me know in our issue tracker:

• https://github.com/Fl4m3Ph03n1x/obj-watcher/issues