tree-changes

What is tree-changes?

The tree-changes npm package is a utility for detecting changes between two states of a JavaScript object. It helps in identifying added, updated, and removed properties, making it useful for state management and change detection in applications.

What are tree-changes's main functionalities?

Detect Added Properties

This feature allows you to detect properties that have been added to the new state compared to the previous state.

const TreeChanges = require('tree-changes');
const prevState = { a: 1 };
const nextState = { a: 1, b: 2 };
const changes = new TreeChanges(prevState, nextState);
console.log(changes.added()); // { b: 2 }

Detect Updated Properties

This feature allows you to detect properties that have been updated in the new state compared to the previous state.

const TreeChanges = require('tree-changes');
const prevState = { a: 1 };
const nextState = { a: 2 };
const changes = new TreeChanges(prevState, nextState);
console.log(changes.updated()); // { a: 2 }

Detect Removed Properties

This feature allows you to detect properties that have been removed from the new state compared to the previous state.

const TreeChanges = require('tree-changes');
const prevState = { a: 1, b: 2 };
const nextState = { a: 1 };
const changes = new TreeChanges(prevState, nextState);
console.log(changes.removed()); // { b: 2 }

Other packages similar to tree-changes

deep-diff

The deep-diff package provides a way to find the differences between two JavaScript objects. It supports nested objects and arrays, making it more versatile for complex data structures. Compared to tree-changes, deep-diff offers more granular control over the types of differences detected, such as additions, deletions, and modifications.

diff

The diff package is a general-purpose text and object diffing library. It can be used to compare strings, arrays, and objects, and provides detailed information about the differences. While it is more comprehensive than tree-changes, it may be overkill for simple state change detection.

immutability-helper

The immutability-helper package is designed to help with updating immutable data structures. It provides a set of commands to apply changes to an object without mutating it. While it doesn't directly compare states like tree-changes, it is useful for managing state updates in a predictable way.

README

tree-changes

Get changes between two versions of data with similar shape.

Setup

npm install tree-changes

Usage

import treeChanges from 'tree-changes';

const savedData = {
  actions: {},
  data: { a: 1 },
  hasData: false,
  items: [{ name: 'test' }],
  messages: [],
  missing: 'username',
  pristine: true,
  ratio: 0.9,
  retries: 0,
  sort: {
    data: [{ type: 'asc' }, { type: 'desc' }],
    status: 'idle',
  },
  switch: false,
  username: '',
};

const newData = {
  actions: { complete: true },
  data: {},
  hasData: true,
  items: [],
  messages: ['New Message'],
  missing: '',
  ratio: 0.5,
  retries: 1,
  sort: {
    data: [{ type: 'desc' }, { type: 'asc' }],
    status: 'success',
  },
  sudo: true,
  username: 'John',
};

const {
  added,
  changed,
  changedFrom,
  decreased,
  emptied,
  filled,
  increased,
  removed,
} = treeChanges(savedData, newData);

changed(); // true

changed('hasData'); // true
changed('hasData', true); // true
changed('hasData', true, false); // true
changed('actions', { complete: true }, {})

// support nested match
changed('sort.data.0.type', 'desc'); // true

changedFrom('hasData', false); // true
changedFrom('hasData', false, true); // true

changedFrom('retries', 0); // true
changedFrom('retries', 0, 1); // true

// works with array values too
changedFrom('sort.status', 'idle', ['done', 'success']); // true

added('actions'); // true
added('messages'); // true
added('sudo'); // true

removed(); // true
removed('data'); // true
removed('items'); // true
removed('switch'); // true

filled('actions'); // true
filled('messages'); // true
filled('username'); // true

emptied('data'); // true
emptied('items'); // true
emptied('missing'); // true

decreased('ratio'); // true

increased('retries'); // true

Works with arrays too.

import treeChanges from 'tree-changes';

const { changed } = treeChanges([0, { id: 2 }], [0, { id: 4 }]);

changed(); // true
changed(0); // false
changed(1); // true
changed('1.id', 4); // true

It uses deep-diff to compare objects/arrays and nested-property to get the nested key.

API

added(key: Key)
Check if something was added to the data (length has increased). Works with arrays and objects (using Object.keys).

changed(key?: Key, actual?: Value, previous?: Value)
Check if the data has changed.
It also can compare to the actual value or even with the previous.

changedFrom(key: Key, previous: Value, actual?: Value)
Check if the data has changed from previous or from previous to actual.

decreased(key: Key, actual?: Value, previous?: Value)
Check if both values are numbers and the value has decreased.
It also can compare to the actual value or even with the previous.

emptied(key: Key)
Check if the data was emptied. Works with arrays, objects and strings.

filled(key: Key)
Check if the data was filled (from a previous empty value). Works with arrays, objects and strings.

increased(key: Key, actual?: Value, previous?: Value)
Check if both values are numbers and the value has increased.
It also can compare to the actual value or even with the previous.

removed(key: Key)
Check if something was removed from the data (length has decreased). Works with arrays and objects (using Object.keys).

Types type Key = string | number;
type AcceptedTypes = string | boolean | number | { [key: string]: any };
type Value = AcceptedTypes | AcceptedTypes[];

With React

Class components

import treeChanges from 'tree-changes';

class Comp extends React.Component {
    ...
    componentDidUpdate(prevProps) {
        const { changed, changedFrom } = treeChanges(prevProps, this.props);
        
        if (changedFrom('retries', 0, 1) {
            // dispatch some error
        }
        
        if (changed('hasData', true)) {
            // send data to analytics or something.
        }
    }
    ...
}

Functional components with hooks

import React, { useEffect, useRef } from 'react';
import treeChanges from 'tree-changes';

function usePrevious(value) {
  const ref = useRef();

  useEffect(() => {
    ref.current = value;
  });

  return ref.current;
}

function useTreeChanges(props) {
  const prevProps = usePrevious(props) || {};

  return treeChanges(prevProps, props);
}

const Page = (props) => {
  const { changed } = useTreeChanges(props);

  if (changed('isLoaded', true)) {
    sendAnalyticsEvent('load', 'MySuperPage')
  }

  return <div>...</div>;
};

License

MIT