Skip to content
Watch an object or array for changes
JavaScript TypeScript
Branch: master
Clone or download

Latest commit

Latest commit 186dfda Mar 18, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Create funding.yml May 28, 2019
bench Path as array (#52) Mar 14, 2020
lib Path as array (#52) Mar 14, 2020
tests Path as array (#52) Mar 14, 2020
.editorconfig Init Dec 11, 2017
.gitattributes
.gitignore Init Dec 11, 2017
.npmrc Init Dec 11, 2017
.travis.yml Update travis and dependencies Feb 28, 2020
index.d.ts Path as array (#52) Mar 14, 2020
index.js Path as array (#52) Mar 14, 2020
index.test-d.ts Meta tweaks Jul 12, 2019
karma.bench.conf.js Path as array (#52) Mar 14, 2020
license Require Node.js 10 Mar 14, 2020
package.json 2.0.1 Mar 17, 2020
readme.md Path as array (#52) Mar 14, 2020

readme.md

on-change Build Status

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

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

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

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

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

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'

// 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 three arguments:

  1. A path to the value that was changed. A change to c in the above example would return a.b.0.c.
  2. The new value at the path.
  3. The previous value at the path.

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

options

Type: object

isShallow

Type: boolean
Default: false

Deep changes will not trigger the callback. Only changes to the immediate properties of the original object.

equals

Type: Function
Default: Object.is

The function receives two arguments to be compared for equality. Should return true if the two values are determined to be equal. Useful if you only need a more loose form of equality.

ignoreSymbols

Type: boolean
Default: false

Setting properties as Symbol won't trigger the callback.

ignoreKeys

Type: Array<string | symbol>
Default: undefined

Setting properties in this array won't trigger the callback.

ignoreUnderscores

Type: boolean
Default: false

Setting properties with an underscore as the first character won't trigger the callback.

pathAsArray

Type: boolean
Default: false

The path will be provided as an array of keys instead of a delimited string.

onChange.target(object)

Returns the original unwatched object.

object

Type: object

Object that is already being watched for changes.

onChange.unsubscribe(object)

Cancels all future callbacks on a watched object and returns the original unwatched object.

object

Type: object

Object that is already being watched for changes.

Use-case

I had some code that was like:

const foo = {
	a: 0,
	b: 0
};

//

foo.a = 3;
save(foo);

//

foo.b = 7;
save(foo);


//

foo.a = 10;
save(foo);

Now it can be simplified to:

const foo = onChange({
	a: 0,
	b: 0
}, () => save(foo));

//

foo.a = 3;

//

foo.b = 7;

//

foo.a = 10;

Related

  • known - Allow only access to known object properties (Uses Proxy too)
  • negative-array - Negative array index support array[-1] (Uses Proxy too)
  • statux - State manager (Uses Proxy too)
  • introspected - Never-ending Proxy with multiple observers (Uses Proxy too)

Maintainers

You can’t perform that action at this time.