Watch.js Object Observer

Common errors

• ReferenceError: watch is not defined

  cause The Watch.js script was not correctly loaded or executed before attempting to call the 'watch' function.
  fix Ensure the watch.js file is included via a <script> tag in your HTML, placed before any code that attempts to use 'watch' or 'unwatch', e.g., <script src="path/to/watch.js"></script>.

• Unexpected behavior: watcher not firing for attribute change.

  cause Another watcher might have set `WatchJS.noMore = true;` or the object change is not being deeply observed as intended, or the 'level' parameter for deep watching is not set.
  fix Check if `WatchJS.noMore` is inadvertently set to `true` in a preceding watcher. For deep observation, ensure the correct 'level' parameter is passed to the `watch` function, or consider the library's limitations with deeply nested or dynamically added properties.

• TypeError: Cannot set property '<property>' of undefined

  cause Attempting to watch an object that is null, undefined, or not a plain JavaScript object.
  fix Ensure the first argument passed to the 'watch' function is a valid, instantiated JavaScript object before attempting to observe it.

Warnings

• breaking Watch.js is an abandoned library and has not been updated in approximately 9 years. It relies on modifying global object prototypes to detect changes, which can lead to conflicts and unexpected behavior with other libraries or modern JavaScript features. There are no plans for future updates or security patches.
  Fix: Migrate to a modern reactivity solution like ES6 Proxies or a maintained framework/library.
• gotcha The library pollutes the global scope by exposing 'watch', 'unwatch', and 'WatchJS' as global variables (e.g., window.watch). This can lead to naming collisions and make it difficult to integrate into modular JavaScript environments.
  Fix: Wrap the library in an IIFE or namespace if you must use it, though migration to a modern solution is strongly recommended.
• gotcha Watch.js uses deprecated browser mechanisms for object observation and may have 'some bugs with older browsers' as stated in its original README. It does not leverage modern browser APIs like MutationObserver for DOM changes, focusing solely on plain JavaScript objects.
  Fix: Thoroughly test in target environments. Consider browser compatibility polyfills or, ideally, migrate to a modern, actively maintained library.
• gotcha The `WatchJS.noMore = true` flag is a global state mechanism intended to prevent recursive watcher calls. Incorrect usage or failure to understand its lifecycle can lead to watchers not firing when expected or unexpected side effects across different parts of your application.
  Fix: Carefully manage the `WatchJS.noMore` flag within the scope of your watcher functions and ensure it is reset appropriately if you intend for subsequent watchers to execute.

Install

• npm install watchjs npm
• yarn add watchjs yarn
• pnpm add watchjs pnpm

Imports

• watch
  wrong:

  import { watch } from 'watchjs';

  correct:

  <script src="path/to/watch.js"></script>
  // Then access as `window.watch` or simply `watch` if in global scope

  Watch.js injects 'watch' and 'unwatch' as global functions (window.watch) and 'WatchJS' as a global object (window.WatchJS) when included via a script tag. It does not provide modern module exports like CommonJS or ESM.
• unwatch
  wrong:

  import { unwatch } from 'watchjs';

  correct:

  <script src="path/to/watch.js"></script>
  // Then access as `window.unwatch` or simply `unwatch` if in global scope

  See notes for the 'watch' function regarding global scope injection.
• WatchJS
  wrong:

  import { WatchJS } from 'watchjs';

  correct:

  <script src="path/to/watch.js"></script>
  // Then access as `window.WatchJS` or simply `WatchJS` if in global scope

  The global 'WatchJS' object contains utility properties like 'noMore' for controlling watcher behavior. See notes for the 'watch' function.

Quickstart

Demonstrates how to add and trigger watchers for specific or all attributes on a JavaScript object using the global 'watch' function.

// Include Watch.js via a script tag in your HTML:
// <script src="https://raw.githubusercontent.com/melanke/Watch.JS/master/src/watch.js"></script>

// defining our object however we like
var myObject = {
	attribute1: "initial value",
	attribute2: 123
};

// defining a 'watcher' for a specific attribute
watch(myObject, "attribute1", function(prop, action, newValue, oldValue){
	console.log(`Attribute '${prop}' changed from '${oldValue}' to '${newValue}'. Action: ${action}`);
});

// defining a 'watcher' for all attributes on the object
watch(myObject, function(){
    console.log("Any attribute of myObject changed!");
});

// when changing the attribute, its watcher will be invoked
myObject.attribute1 = "new value";

// changing another attribute will invoke the general object watcher
myObject.attribute2 = 456;