Track Changes To JS Objects & DOM Elements – Observe.js

Observe.js is a lightweight JavaScript library that allows developers to keep track of changes to JavaScript objects/arrays and/or DOM elements.

It checks for changes every 250ms by default, but you can customize this interval. When changes occur, Observe.js can fire callback functions you define to respond to the change.

How to use it:

1. Download and load the main script ‘observe.min.js’ from the dist folder.

<script src="/dist/observe.min.js"></script>

2. Apply the observer to JavaScript objects or DOM elements:

<div data-observe-js="{ OPTIONS AND CALLBACKS HERE}">
  ...
</div>

var instance = $observe.watch(yourObjectOrArray, {
    // options and callbacks here
} );

3. All possible options and callbacks.

var instance = $observe.watch(yourObjectOrArray, {
    // check delay in ms
    timeout: 250,
    // start date/time
    starts: null,
    // expiration date/time
    expires: null,
    // reset the value when a change is detected
    reset: false,
    // cancel the observer when the first change is detected
    cancelOnChange: false,
    // 0 = off
    maximumChangesBeforeCanceling: 0,
    // pause delay in ms
    // 0 = off
    pauseTimeoutOnChange: 0,
    // the property names that should be watched for changes
    propertyNames: [],
    // determine if the observer can be cancelled
    allowCanceling: true,
    // determine if the observer can be paused
    allowPausing: true,
    // remove binding attribute
    removeAttribute: true,
    // callbacks
    events: {
      onChange: function(oldValue, newValue){},
      onPropertyChange: function(propertyName, oldValue, newValue){},
      onCancel: function(id){},
      onRemove: function(id){},
      onStart: function(originalValue){},
    }
    
});

4. Global settings.

$observe.setConfiguration({
  safeMode: true,
  domElementTypes: '*',
  text: {
    objectErrorText: 'Errors in object: {{error_1}}, {{error_2}}',
    attributeNotValidErrorText: 'The attribute '{{attribute_name}}' is not a valid object.',
    attributeNotSetErrorText: 'The attribute '{{attribute_name}}' has not been set correctly.',
  }
});

5. API methods.

// add an object
$observe.watch(object, options):
// cancel the observer on an element
$observe.cancelWatch(id);
// cancel all observers
$observe.cancelWatches();
// pause the observer for a specific number of milliseconds
$observe.pauseWatch(id, milliseconds);
// pause all observers for a specific number of milliseconds
$observe.pauseWatches(milliseconds);
// resume the observer
$observe.resumeWatch(id);
// resume all observers
$observe.resumeWatches();
// get the object being watched
$observe.getWatch(id);
// get all observers
$observe.getWatches();
// searche the DOM for new elements to observe
searchDomForNewWatches();

Changelog:

v1.1.0 (09/11/2024)

• Code improvement

v1.0.1 (07/16/2024)

• Updated package

v1.0.0 (07/16/2024)

• Rewritten in TypeScript

v0.8.2 (06/18/2024)

• Renamed the binding attribute “data-observe-watch-options” to “data-observe-js”.
• Added export support for the global “$observe” object, which can now be imported as “observe.js”.

v0.8.1 (03/20/2024)

• General improvements

v0.8.0 (03/14/2024)

• Added more options
• Improvement

v0.7.1 (02/20/2024)

• Bugfix

v0.7.0 (02/07/2024)

• Added more callbacks

v0.6.1 (01/17/2024)

• Bugfix

v0.6.0 (01/08/2024)

• Minor internal refactoring to make things a little clearer.
• Added more options and methods.
• Fixed bugs.

v0.5.1 (01/06/2024)

• Fixed a small fault that prevented the total changes from being handled correctly when a watch was stopped.
• Added support to watch array objects for changes.