WatchOptions | V4Fire

Hierarchy

WatchOptions
- InternalWatchOptions

Index

Properties

Optional collapse

collapse?: boolean

The option enables or disables collapsing of mutation events. When it toggles to true, all mutation events fire as if they occur on top properties of the watchable object.

const {proxy} = watch({a: {b: {c: 1}}}, {collapse: true, deep: true}, (mutations) => {
  mutations.forEach(([value, oldValue, info]) => {
    console.log(value, oldValue, info.path);
  });
});

// {b: {c: 2}} {b: {c: 2}} ['a', 'b', 'c']
proxy.a.b.c = 2;

When it toggles to false, and the watcher binds to the specified path, the callback takes a list of mutations. Otherwise, the callback takes only the last mutation.

const {proxy} = watch({a: {b: {c: 1}}}, 'a.b', {collapse: false}, (mutations) => {
  mutations.forEach(([value, oldValue, info]) => {
    console.log(value, oldValue, info.path, info.originalPath);
  });
});

// 2 1 ['a', 'b'] ['a', 'b', 'c']
proxy.a.b.c = 2;

const {proxy: proxy2} = watch({a: {b: {c: 1}}}, 'a.b', (value, oldValue, info) => {
  console.log(value, oldValue, info.path, info.originalPath);
});

// {c: 2} {c: 2} ['a', 'b'] ['a', 'b', 'c']
proxy2.a.b.c = 2;

default: false

Optional deep

deep?: boolean

If true, then the callback of changing is also fired on mutations of nested properties

default

false

example

const {proxy} = watch({a: {b: {c: 1}}}, {deep: true}, (mutations) => {
  mutations.forEach(([value, oldValue, info]) => {
    console.log(value, oldValue, info.path);
  });
});

// 2 1 ['a', 'b', 'c']
proxy.a.b.c = 2;

// {c: 2} {e: 2} ['a', 'b']
proxy.a.b = {e: 2};

Optional dependencies

dependencies?: WatchDependencies

When providing the specific path to watch, this parameter can contain a list of dependencies for the watching path. This parameter can help to watch accessors.

const obj = {
  get foo() {
    return this.bla * this.baz;
  },

  bla: 2,
  baz: 3
};

const {proxy} = watch(obj, 'foo', {dependencies: ['bla', 'baz']}, (value, oldValue, info) => {
  console.log(value, oldValue, info.path, info.originalPath, info.parent);
});

// This mutation will invoke our callback
proxy.bla++;

When providing the specific path to watch, this parameter can contain an object or Map with lists of dependencies to watch.

const obj = {
  foo: {
    get value() {
      return this.bla * this.baz;
    }
  },

  bla: 2,
  baz: 3
};

const depsAsObj = {
  'foo.value': ['bla', 'baz']
};

const {proxy: proxy1} = watch(obj, {dependencies: depsAsObj}, (mutations) => {
  mutations.forEach(([value, oldValue, info]) => {
    console.log(value, oldValue, info.path, info.originalPath, info.parent);
  });
});

// This mutation will fire an additional event for `foo.value`
proxy1.bla++;

const depsAsMap = new Map([
  [
    // A path to the property with dependencies
    ['foo', 'value'],

    // Dependencies
    ['bla', 'baz']
  ]
]);

const {proxy: proxy2} = watch(obj, {dependencies: depsAsMap}, (mutations) => {
  mutations.forEach(([value, oldValue, info]) => {
    console.log(value, oldValue, info.path, info.originalPath, info.parent);
  });
});

proxy2.baz++;

Optional engine

engine?: WatchEngine

Watch engine to use. By default, will be used proxy if supported, otherwise accessors.

Optional eventFilter

eventFilter?: WatchHandler<unknown, unknown>

A filter function for mutation events. The function allows skipping some mutation events.

example

function eventFilter(value, oldValue, info) {
  return info.path[0] !== '_a';
}

const {proxy} = watch({a: 1, b: 2, _a: 1}, {eventFilter}, (mutations) => {
  mutations.forEach(([value, oldValue, info]) => {
    console.log(value, oldValue, info.path, info.originalPath);
  });
});

// This mutation won't invoke our callback
proxy._a = 2;

Optional immediate

immediate?: boolean

If true, then all mutation events will be fired immediately. Notice, with enabling this option, the callback changes its interface:

// Before
type Cb = (mutations: [[unknown, unknown, WatchHandlerParams]]) => any;

// After
type CbWithImmediate = (newValue: unknown, oldValue: unknown, info: WatchHandlerParams) => any;

default

false

example

const {proxy} = watch(a: 1}, {immediate: true}, (value, oldValue, info) => {
  console.log(value, oldValue, info.path);
});

// 2 1 ['a']
proxy.a = 2;

Optional pathModifier

pathModifier?: PathModifier

A function that takes a path of the mutation event and returns a new path. The function is used when you want to mask one mutation to another one.

example

function pathModifier(path) {
  return path.map((chunk) => chunk.replace(/^_/, ''));
}

const {proxy} = watch({a: 1, b: 2, _a: 1}, 'a', {pathModifier}, (mutations) => {
  mutations.forEach(([value, oldValue, info]) => {
    console.log(value, oldValue, info.path, info.originalPath);
  });
});

// 2 1 ['a'], ['_a']
proxy._a = 2;

Optional postfixes

postfixes?: string[]

List of postfixes for paths to watch. This parameter can help to watch accessors.

example

const obj = {
  get foo() {
    return this.fooStore * 2;
  },

  fooStore: 2
};

const {proxy} = watch(obj, 'foo', {postfixes: ['Store']}, (value, oldValue, info) => {
  console.log(value, oldValue, info.path, info.originalPath, info.parent);
});

// This mutation will invoke our callback
proxy.fooStore++;

Optional prefixes

prefixes?: string[]

List of prefixes for paths to watch. This parameter can help to watch accessors.

example

const obj = {
  get foo() {
    return this._foo * 2;
  },

  _foo: 2
};

const {proxy} = watch(obj, 'foo', {prefixes: ['_']}, (value, oldValue, info) => {
  console.log(value, oldValue, info.path, info.originalPath, info.parent);
});

// This mutation will invoke our callback
proxy._foo++;

Optional tiedWith

tiedWith?: object

Link to an object that should connect with the watched object, i.e., changing of properties of the tied object, will also emit mutation events

example

const data = {
  foo: 2
};

class Bla {
  data = data;

  constructor() {
    watch(this.data, {tiedWith: this}, (val) => {
      console.log(val);
    });
  }
}

const bla = new Bla();
bla.foo = 3;

Optional withProto

withProto?: boolean

If true, then the callback of changing is also fired on mutations of properties from prototypes

default

false

example

const {proxy} = watch(a: 1, {__proto__: {b: 1}}, {withProto: true}, (mutations) => {
  mutations.forEach(([value, oldValue, info]) => {
    console.log(value, oldValue, info.path, info.fromProto);
  });
});

// 2 1 ['a'] false
proxy.a = 2;

// 2 1 ['b'] true
proxy.b = 2;