singleton-watcher v1.0.4

singleton-watcher

Overview

This is a Non-native timer based watcher for any value, which will use your cpu time, and not with a event based approach. It will be useful when the aim is to observe values for which there is no native support so far, and we have to take timer base approach. For example, if we want to watch height change of a particular DOM element that can be changed from anywhere. Note, if you are sure that You are using inline style/height attribute or changing the class from where the height is affecting then its better use MutationObserver or DOMSubtreeModified. It is recommended to use this watcher when there is no native support for that event delegation. Using this watcher its possible to watch any objects/array or any primitive value as well.

Why preferred SingletonWatcher instead of manually starting a timer (interval/timeout)

When you have to watch a value, and you don't have a native support, and you don't know the possible reasons of change as well,you could have start a recursive timeout or interval from your side. But the only difference is in that case you need to manipulate the entire life cycle of that.Also if you want to watch multiple values, you will run multiple timers. Instead of that we tried to run a single timer (only when there is atleast 1 item to watch) logically. It provides the flexibility of event proxy object, custom comparator, remove of watcher(s) previously added and so on. We believe that this logical layers can be written by you as well, but its just a step to reduce those work, and maintain a common library that can be shared across multiple projects, and this repo will be better day by day.

How to use

Either you clone it from https://github.com/koushikmagic/singleton-watcher.git or you can do npm install singleton-watcher and then simply add a script src to the node-modules/singleton-watcher/singleton-watcher.js file or you can do bower install singleton-watcher and add the script src as bower_components/singleton-watcher/singleton-watcher.js file. Once added, you will get a refernce to this lib object as SingletonWatcher (in case of browser), for node.js just get a reference to it with require('singleton-watcher'). Check the followings for features available

• SingletonWatcher comes with mainly 2 methods, addWatch(itemToWatch, eventCallback or config) and removeWatch(watchItemId or itemToWatch)
• addWatch will return a object as response having 2 mandatory fields status and state, status will be true in case of successful addition of watcher, and state is nothing but an integer value, mapped with a Enum object comes under SingletonWatcher.RESPONSE_STATES. In case of success another property will come as id as id of the watcher, later it can be used to remove it from the watcher by using removeWatcher(id or itemToWatch) .In case of removal success it will return true otherwise false.
• The first argument of addWatch is the item to watch. it can be object/array/or a callback, that evaluates the value, if you want to watch for a primitive value you need to pass a callback that will return the value. also you can use callback for other types of value too.
• If you are passing an object/array, and want to monitor any change on that, then either you can pass a compare callback as a compare key of the next argument (config) which will take 2 arguments compare(newVal, oldVal) and return true if there is no change in the perspective of your compare. Otherwise you need to use underscore.js or any such libraries that contains a deep checking algo of two objects. As of now, we didn't implement any default deep checking algo.
• You cannot pass string or primitive type for watch. As string is immutable and primitives are passed by value, once it is passed to the watcher, what the watcher is pointing to cannot be changed. If you really want to monitor any string value or any primitive value, pass a callback instead which will return string or primitive value.
• If you are passing a callback as the watch item, it will watch the evaluated value of that callback. If you want to specify the object monitor under what your callback will execute (even with the argument lists as well) to evaluate the value dynamically, you can pass it in the property of config (second argument) like {objectMonitor: <object>, args: <Array>}. If your callback is returning a object by default it will check for the change by its reference. If you want a deep checking (all nested values), in config argument you can pass deep key as value true. But, be sure if you are passing deep as true then either pass a compare key as acompare algo or use underscore or any such libraries having a deep comparing algo, as we don't have an implementation of an default deep checking algo so far.
• In the second argument of addWatch, you can pass detail config object instead of a callback as an event listener. In that config you can pass the followings keys:
  • event (mandatory) as the event callback you want to register.
  • objectMonitor (optional) as an object. If you are passing a callback as watch item, then that callback will execute on this object monitor. This is useful only when the watchItem is a callback to evaluate the actual watchItem.
  • args (optional) as an Array (or even any type of data as the only argument) of argument that will be passed to the watchItem callback before its execution to evaluate current value. Like objectMonitor, this is also useful only when the watchItem is a callback to evaluate the actual watchItem.
  • compare (optional) You can provide a callback as a value of this key. If you pass this key, the callback will be used to compare with last value, to track for change, with the first argument as the current value and the second argument as the last value. You can implement your own comparison algo with this key. The signature is compare(newVal, oldVal). Return true if newVal and oldVal is same, return false in case they are not same and there is some change according to your perspective of watching.
  • deep (optional) if you passing deep as true or true equivalent, and if your watchItem is a callback and also returning object/array, then it will check for a deep coparison to track for any changes. But, the deep comparison depends on either any library you loaded (like underscorejs, ...) or you provided a coparisonalso (as compare key). If your callback returns an object and you don't ask the watcher for deep coparison and also don't provide any comparison then it will compare by reference. Note that if your watchItem is not a callback, deep will be always true. In that case either need some library for deep comparison or u must provide a comparison as compare key.
  • proxy (optional) you can pass either an object as proxy oject monitor of the event callback or you can pass just true as boolean value.That will execute the event under the object monitor of your current value after change. In case you don't want any proxy for you event callback, either don't pass any value against the key proxy or explicitly pass false as boolean or a false equivalent value.