The on-change package is a utility for watching changes in JavaScript objects and arrays. It allows you to execute a callback function whenever a change is detected, making it useful for state management, debugging, and reactive programming.

What are on-change's main functionalities?

Watch for changes in objects

This feature allows you to watch for changes in an object's properties. When a property changes, the callback function is triggered, providing the path of the changed property, the new value, and the previous value.

const onChange = require('on-change');

const object = {
  foo: 'bar'
};

const watchedObject = onChange(object, function (path, value, previousValue) {
  console.log('Object changed:', path, value, previousValue);
});

watchedObject.foo = 'baz'; // Console: Object changed: foo baz bar

Watch for changes in arrays

This feature allows you to watch for changes in arrays. The callback function is triggered whenever the array is modified, such as when elements are added or removed.

const onChange = require('on-change');

const array = [1, 2, 3];

const watchedArray = onChange(array, function (path, value, previousValue) {
  console.log('Array changed:', path, value, previousValue);
});

watchedArray.push(4); // Console: Array changed: 3 4 undefined

Nested property change detection

This feature allows you to detect changes in nested properties of objects. The callback function provides the full path to the changed property, making it easy to track changes deep within an object structure.

const onChange = require('on-change');

const nestedObject = {
  level1: {
    level2: {
      foo: 'bar'
    }
  }
};

const watchedNestedObject = onChange(nestedObject, function (path, value, previousValue) {
  console.log('Nested object changed:', path, value, previousValue);
});

watchedNestedObject.level1.level2.foo = 'baz'; // Console: Nested object changed: level1.level2.foo baz bar

Other packages similar to on-change

on-change

Watch an object or array for changes

It works recursively, so it will even detect if you modify a deep property like obj.a.b[0].c = true.

Uses the Proxy API.

Install

npm install on-change

Usage

import onChange from 'on-change';

const object = {
	foo: false,
	a: {
		b: [
			{
				c: false
			}
		]
	}
};

let index = 0;
const watchedObject = onChange(object, function (path, value, previousValue, applyData) {
	console.log('Object changed:', ++index);
	console.log('this:', this);
	console.log('path:', path);
	console.log('value:', value);
	console.log('previousValue:', previousValue);
	console.log('applyData:', applyData);
});

watchedObject.foo = true;
//=> 'Object changed: 1'
//=> 'this: {
//   	foo: true,
//   	a: {
//   		b: [
//   			{
//   				c: false
//   			}
//   		]
//   	}
//   }'
//=> 'path: "foo"'
//=> 'value: true'
//=> 'previousValue: false'
//=> 'applyData: undefined'

watchedObject.a.b[0].c = true;
//=> 'Object changed: 2'
//=> 'this: {
//   	foo: true,
//   	a: {
//   		b: [
//   			{
//   				c: true
//   			}
//   		]
//   	}
//   }'
//=> 'path: "a.b.0.c"'
//=> 'value: true'
//=> 'previousValue: false'
//=> 'applyData: undefined'

watchedObject.a.b.push(3);
//=> 'Object changed: 3'
//=> 'this: {
//   	foo: true,
//   	a: {
//   		b: [
//   			{
//   				c: true
//   			},
//   			3
//   		]
//   	}
//   }'
//=> 'path: "a.b"'
//=> 'value: [{c: true}, 3]'
//=> 'previousValue: [{c: true}]'
//=> 'applyData: {
//       name: "push",
//       args: [3],
//       result: 2,
//   }'

// Access the original object
onChange.target(watchedObject).foo = false;
// Callback isn't called

// Unsubscribe
onChange.unsubscribe(watchedObject);
watchedObject.foo = 'bar';
// Callback isn't called

API

onChange(object, onChange, options?)

Returns a version of object that is watched. It's the exact same object, just with some Proxy traps.

object

Type: object

Object to watch for changes.

onChange

Type: Function

Function that gets called anytime the object changes.

The function receives four arguments:

A path to the value that was changed. A change to c in the above example would return a.b.0.c.
The new value at the path.
The previous value at the path. Changes in WeakSets and WeakMaps will return undefined.
An object with the name of the method that produced the change, the args passed to the method, and the result of the method.

The context (this) is set to the original object passed to onChange (with Proxy).