deep-state-observer for high performance apps

Deep state observer is an state management library which will trigger an update only when specified object node was changed. You don't need to reevaluate or re-render whole app/component when only one portion of the state was modified.

Used in the right hands can significantly increase performance!

Deep state observer is framework agnostic with node and browser support, so you can use it in most of your projects.

Install

npm i deep-state-observer

Examples

here and here

Usage

Svelte example

1import { onDestroy } from 'svelte';
2import State from 'deep-state-observer'; // const State = require('deep-state-observer');
3
4// first parameter is an object that hold the state, and the second one is just options
5const state = new State({
6  some: 'value',
7  someOther: {
8      nested: 'value'
9    }
10  },
11  // options
12  { delimiter:'.' , notRecursive:';',  param: ':', log: console.log }
13);
14
15// store some unsubscribe methods
16let subscribers = [];
17
18// change local variable - it can be vueComponent.data property or react function with setState in react
19let nestedValue;
20subscribers.push(
21  state.subscribe('someOther.nested', (value, eventInfo) => {
22    nestedValue = value;
23  })
24);
25
26let some;
27subscribers.push(
28  state.subscribeAll(['some', 'someOther'], (value, eventInfo) => {
29    if (eventInfo.path.resolved === 'some') {
30      some = value;
31    } else if (eventInfo.path.resolved === 'someOther') {
32      nestedValue = value.nested;
33    }
34  })
35);
36
37state.update('someOther.nested', (currentValue) => {
38  return 'new value';
39});
40
41// you can use function to modify data
42subscribers.push(
43  state.subscribe('some', (value, eventInfo) => {
44    state.update('someOther.nested', (oldValue) => {
45      return 'nested changed too';
46    });
47  })
48);
49
50// or you can just set the value (it cannot be function :) )
51subscribers.push(
52  state.subscribe('some', (value, eventInfo) => {
53    state.update('someOther.nested', 'nested changed too');
54);
55
56onDestroy(() => {
57  subscribers.forEach((unsubscribe) => unsubscribe());
58});

Wildcards

1import { onDestroy } from "svelte";
2import State from "deep-state-observer"; // const State = require('deep-state-observer');
3
4// first parameter is an object that hold the state, and the second one is just options (optional - for now it hold just delimiter :P )
5const state = new State({
6  some: { thing: { test: 0 } },
7  someOther: { nested: { node: "ok" } },
8});
9
10// store some unsubscribe methods
11let subscribers = [];
12
13subscribers.push(
14  state.subscribe("someOther.*.n*e", (value, eventInfo) => {
15    // fired only once with
16    // value = 'ok'
17    // eventInfo.path.resolved = 'someOther.nested.node'
18  })
19);
20
21// you can update wildcarded values too
22state.update("some.*.test", "test");
23
24onDestroy(() => {
25  subscribers.forEach((unsubscribe) => unsubscribe());
26});

Named wildcards (parameters)

1import { onDestroy } from "svelte";
2import State from "deep-state-observer"; // const State = require('deep-state-observer');
3
4// first parameter is an object that hold the state, and the second one is just options (optional - for now it hold just delimiter :P )
5const state = new State({
6  items: [{ val: 1 }, { val: 2 }, { val: 3 }],
7  byId: {
8    1: { val: 1 },
9    2: { val: 2 },
10    3: { val: 3 },
11  },
12});
13
14// store some unsubscribe methods
15let subscribers = [];
16
17subscribers.push(
18  state.subscribe("items.:index.val", (value, eventInfo) => {
19    // fired three times
20    //
21    // #1
22    // value = 1
23    // eventInfo.path.resolved = 'items.0.val'
24    // eventInfo.params = { index: 0 }
25    //
26    // #2
27    // value = 2
28    // eventInfo.path.resolved = 'items.1.val'
29    // eventInfo.params = { index: 1 }
30    //
31    // #3
32    // value = 3
33    // eventInfo.path.resolved = 'items.2.val'
34    // eventInfo.params = { index: 2 }
35  })
36);
37
38subscribers.push(
39  state.subscribe("byId.:id.val", (value, eventInfo) => {
40    // fired three times
41    //
42    // #1
43    // value = 1
44    // eventInfo.path.resolved = 'byId.1.val'
45    // eventInfo.params = { id: 1 }
46    //
47    // #2
48    // value = 2
49    // eventInfo.path.resolved = 'byId.2.val'
50    // eventInfo.params = { id: 2 }
51    //
52    // #3
53    // value = 3
54    // eventInfo.path.resolved = 'byId.3.val'
55    // eventInfo.params = { id: 3 }
56  })
57);
58onDestroy(() => {
59  subscribers.forEach((unsubscribe) => unsubscribe());
60});

Wildcard bulk operations (better performance)

1import { onDestroy } from "svelte";
2import State from "deep-state-observer"; // const State = require('deep-state-observer');
3
4// first parameter is an object that hold the state, and the second one is just options (optional - for now it hold just delimiter :P )
5const state = new State({
6  byId: {
7    1: { val: 1 },
8    2: { val: 2 },
9    3: { val: 3 },
10  },
11});
12
13// store some unsubscribe methods
14let subscribers = [];
15
16subscribers.push(
17  state.subscribe(
18    "byId.:id.val",
19    (bulk, eventInfo) => {
20      // fired only once where bulk = [
21      //  {
22      //    value: 1,
23      //    eventInfo.path.resovled: 'byId.1.val',
24      //    eventInfo.params: { id: 1 }
25      //  },
26      //  {
27      //    value: 2,
28      //    eventInfo.path.resovled: 'byId.2.val',
29      //    eventInfo.params: { id: 2 }
30      //  },
31      //  {
32      //    value: 3,
33      //    eventInfo.path.resovled: 'byId.3.val',
34      //    eventInfo.params: { id: 3 }
35      //  },
36      // ]
37    },
38    { bulk: true }
39  )
40);
41
42subscribers.push(
43  state.subscribe(
44    "byId.*.val",
45    (bulk, eventInfo) => {
46      // fired only once where bulk = [
47      //  {
48      //    value: 1,
49      //    eventInfo.path.resolved: 'byId.1.val',
50      //    eventInfo.params: undefined
51      //  },
52      //  {
53      //    value: 2,
54      //    eventInfo.path.resolved: 'byId.2.val',
55      //    eventInfo.params: undefined
56      //  },
57      //  {
58      //    value: 3,
59      //    eventInfo.path.resolved: 'byId.3.val',
60      //    eventInfo.params: undefined
61      //  },
62      // ]
63    },
64    { bulk: true }
65  )
66);
67
68onDestroy(() => {
69  subscribers.forEach((unsubscribe) => unsubscribe());
70});

Wildcard bulk without bulk values (even better performance)

1import { onDestroy } from "svelte";
2import State from "deep-state-observer"; // const State = require('deep-state-observer');
3
4// first parameter is an object that hold the state, and the second one is just options (optional - for now it hold just delimiter :P )
5const state = new State({
6  byId: {
7    1: { val: 1 },
8    2: { val: 2 },
9    3: { val: 3 },
10  },
11});
12
13// store some unsubscribe methods
14let subscribers = [];
15
16subscribers.push(
17  state.subscribe(
18    "byId.:id.val",
19    (bulk, eventInfo) => {
20      // fired only once where bulk = [
21      //  {
22      //    value: undefined,
23      //    eventInfo.params: { id: 1 }
24      //  },
25      //  {
26      //    value: undefined,
27      //    eventInfo.params: { id: 2 }
28      //  },
29      //  {
30      //    value: 3,
31      //    eventInfo.params: { id: 3 }
32      //  },
33      // ]
34    },
35    { bulk: true, bulkValue: false }
36  )
37);
38
39subscribers.push(
40  state.subscribe(
41    "byId.*.val",
42    (bulk, eventInfo) => {
43      // fired only once where bulk = [
44      //  {
45      //    value: undefined,
46      //    eventInfo.params: undefined
47      //  },
48      //  {
49      //    value: undefined,
50      //    eventInfo.params: undefined
51      //  },
52      //  {
53      //    value: undefined,
54      //    eventInfo.params: undefined
55      //  },
56      // ]
57    },
58    { bulk: true, bulkValue: false }
59  )
60);
61
62onDestroy(() => {
63  subscribers.forEach((unsubscribe) => unsubscribe());
64});

Observe only chosen node changes (not recursive, not nested, for immutable data)

1import { onDestroy } from "svelte";
2import State from "deep-state-observer"; // const State = require('deep-state-observer');
3
4const state = new State({
5  some: "value",
6  someOther: { nested: { node: "ok" } },
7});
8
9// store some unsubscribe methods
10let subscribers = [];
11
12subscribers.push(
13  state.subscribe("someOther;", (value, eventInfo) => {
14    // fired once
15    //
16    // #1 - immediately with
17    // value = { nested: { node: 'ok' } }
18    // eventInfo.path.resovled = 'someOther'
19  })
20);
21
22subscribers.push(
23  state.subscribe("someOther.nested;", (value, eventInfo) => {
24    // fired once
25    //
26    // #1 - immediately with
27    // value =  { node: 'ok' }
28    // eventInfo.path.resolved = 'someOther'
29  })
30);
31
32state.update("someOther.nested.node", "modified"); // subscribers aren't fired
33
34onDestroy(() => {
35  subscribers.forEach((unsubscribe) => unsubscribe());
36});

Update and notify only specified listeners

1const state = new State({
2  one: { two: { three: { four: 4 } } },
3});
4state.subscribe("one.two", (val, eventInfo) => {
5  // trigerred only once - immediately
6  // because update have option 'only' wich will update only selected nested paths even i you are updating whole 'one.two' object
7  // 'only' option works for object and arrays and it is usefull when you have changed only 'four'-th node of the object
8  // and don't want to listeners from 'one.two' be notified (it is kind of performance improvement hack)
9  // you can bypass those huge operation that is executed here because it is not needed (we are changing only one 'four'th leaf)
10});
11state.subscribe("one.two.three.four", (val, eventInfo) => {
12  // trigerred two times immediately and after update
13});
14state.update("one.two", { three: { four: 44 } }, { only: ["*.four"] });

mute / unmute changes

It will work with wildcards as update values, as muted paths or both.

1const state = new State({ x: { z: "z", i: { o: "o" } }, y: "y" });
2const values = [];
3state.subscribe("x.i.o", (val) => {
4  values.push(val);
5});
6// values.length === 1
7state.mute("x.*.o");
8state.update("x.i.o", "oo");
9// values.length === 1 (x.i.o listener was not fired)
10state.unmute("x.*.o");
11state.update("x.i.o", "ooo");
12// values.length === 2 (x.i.o listener was fired)
13
14state.mute("x");
15state.update("x.i.o", "oooo");
16// values.length === 2 (x.i.o listener was not fired)
17
18state.unmute("x");
19state.mute("x;"); // mute only x (not nested)
20state.update("x.i.o", "oooo");
21// values.length === 3 (x.i.o listener was fired)

You can also mute specific listeners (functions)

1const state = new State({ x: { z: "z", i: { o: "o" } }, y: "y" });
2const values = [];
3
4function listener1() {
5  values.push("1");
6}
7function listener2() {
8  values.push("2");
9}
10
11state.subscribe("x.i.o", listener1);
12state.subscribe("x.i.o", listener2);
13// values = ['1', '2']
14
15state.mute(listener2); // from now on listener2 will not fire
16
17values.length = 0;
18state.update("x.i.o", "oo");
19// values = ['1']
20
21state.unmute(listener2);
22
23values.length = 0;
24state.update("x.i.o", "oo");
25// values = ['1','2']

ignore

You can watch for object changes but also at the same time ignore specified nodes. Ignore option will work with wildcards.

1const state = new State({ one: { two: { three: { four: { five: 0 } } } } });
2const values = [];
3
4state.subscribe(
5  "one.two.three",
6  (val) => {
7    values.push(val);
8  },
9  { ignore: ["one.two.three.four"] }
10);
11// values.length === 1 & values[0] === { four: { five: 0 } }
12state.update("one.two.three.four.five", 1);
13// values.length === 1 because all nodes after four was ignored
14state.update("one.two.three.*.five", 1);
15// values.length === 1 because all nodes after four was ignored
16state.update("one.two.three.four", 1);
17// values.length === 1 because all nodes after four was ignored
18state.update("one.two.*.four", 2);
19// values.length === 1 because all nodes after four was ignored
20state.update("one.two.three", 1);
21// values.length === 1 & values[1] === 1

multi

You can collect updates and execute them at once later - useful when used with groups.

1const state = new State({
2  x: { y: { z: { a: { b: "b" } } } },
3  c: { d: { e: "e" } },
4});
5const values = [];
6state.subscribe("x.y.z.a.b", (val, eventInfo) => {
7  values.push(val);
8});
9state.subscribeAll(
10  ["x.y.*.a.b", "c.d.e"],
11  (val, eventInfo) => {
12    values.push("all");
13  },
14  { group: true }
15);
16// values.length === 2
17// values[0] = 'b'
18// values[1] = 'all'
19
20const multi = state.multi(true); // true if you want to execute all changes for specific group only once otherwise each update will cause group to be fired
21// from now on collect updates but do not notify any listener yet
22multi.update("x.y.z.a.b", "bb");
23multi.update("c.d.e", "ee");
24// values.length === 2
25
26multi.done(); // notify all listeners about updates - fire only once grouped listeners
27// values.length === 4
28// values[2] === 'bb'
29// values[3] === 'all'

group - very useful if you want to join couple of changes into one

With subscribeAll you can group listeners to fire only once if one of the path is changed. Grouped listeners always are bulk listeners.

1const state = new State({
2  "n-1": {
3    "n-1-1": {
4      id: "1-1",
5      val: "v1-1",
6    },
7    "n-1-2": {
8      id: "1-2",
9      val: "v1-2",
10    },
11  },
12});
13const results = [];
14function fn(bulk, eventInfo) {
15  results.push(eventInfo.path);
16}
17state.subscribeAll(["n-1.n-1-1.id", "n-1.n-1-2.val"], fn, {
18  group: true,
19});
20// results.length = 1
21state.subscribeAll(["n-1"], fn);
22// results.length = 2  // not 3
23state.update("n-1.*.id", "new id");
24// results.length = 4 // not 6
25state.update("n-1.*.id", "new id 2");
26// results.length = 6 // not 9

collect

You can start collecting changes and execute it as multi later - performance optimization for groups. It is just global multi.

1const state = new State({
2  x: { y: { z: { a: { b: "b" } } } },
3  c: { d: { e: "e" } },
4});
5const values = [];
6state.subscribe("x.y.z.a.b", (val, eventInfo) => {
7  values.push(val);
8});
9state.subscribeAll(
10  ["x.y.*.a.b", "c.d.e"],
11  (val, eventInfo) => {
12    values.push("all");
13  },
14  { group: true }
15);
16// values.length === 2
17// values[0] = 'b'
18// values[1] = 'all'
19
20state.collect(); // from now on collect updates but do not notify any listener yet
21state.update("x.y.z.a.b", "bb");
22state.update("c.d.e", "ee");
23// values.length === 2
24
25state.executeCollected(); // notify all listeners about updates - fire only once grouped listeners
26// values.length === 4
27// values[2] === 'bb'
28// values[3] === 'all'

Trace

You can easily track traces

state.startTrace(name: string, additionalData: any = null): string start tracing

state.stopTrace(id:string): Trace get current trace

state.saveTrace(id:string):Trace save trace on the stack

state.getSavedTraces(): Trace[] get all traces from the stack

1const state = new State({
2  p1: "p1v",
3  p2: "p2v",
4  x1: "x1v",
5  x2: "x2v",
6});
7state.subscribe("p1", (val, eventInfo) => {
8  const trackId = state.startTrace("p1", eventInfo);
9  state.update("p2", "p2v-");
10  state.saveTrace(trackId);
11});
12state.subscribe("p2", (val, eventInfo) => {
13  const trackId = state.startTrace("p2", eventInfo);
14  state.update("x2", "x2v-");
15  state.saveTrace(trackId);
16});
17const result = state.getSavedTraces();
18console.log(result);

Debug

1// you can debug listeners and updates with 'debug' and 'source' options
2state.subscribe("something", () => {}, {
3  debug: true,
4  source: "your.component.name.or.something",
5});
6state.update("something", "someValue", {
7  debug: true,
8  source: "your.component.name.or.something",
9});

Vue example

1// main component
2import State from 'deep-state-observer';
3
4const state = new State({ test: 1 });
5const subscribers = [];
6
7export default {
8  provide: { state },
9};
10
11// child component
12export default {
13  template: `<div>test is equal to: {{test}}</div>`,
14  inject: ['state'],
15  data() {
16    return {
17      test: 0,
18    };
19  },
20  created() {
21    subscribers.push(
22      this.state.subscribe('test', (test) => {
23        this.test = test; // assign to local variable
24      })
25    );
26  },
27  beforeDestroy() {
28    subscribers.forEach((unsubscribe) => unsubscribe());
29  },
30};