js-struct-compare

js-struct-compare

Javascript library to compare two (JSON-serializable) structures and return their differences.

Installation

This library can be installed from the NPM package registry. Using NPM:

npm install --save js-struct-compare

Or using Yarn:

yarn add js-struct-compare

Usage

This package is meant to be consumed as an ES module. Its default export is a comparison function that takes a left and a right instance and returns an array of differences between them. These can be seen as the operations needed to transform left into right. An example:

import compare from "js-struct-compare";

const left = {
    "foo": {
        "bar": [ 42, 0 ],
    },
    "qux": "quux",
    "corge": "grault",
    "garply": [],
};
const right = {
    "foo": {
        "bar": [ 43, 0 ],
        "baz": 99,
    },
    "corge": "grault",
    "garply": {},
};

const differences = compare(left, right);
// => [
//   Difference{path: ['foo', 'bar', 0], type: 'changed', left_value: 42, right_value: 43},
//   Difference{path: ['foo', 'baz'], type: 'added', left_value: undefined, right_value: 99},
//   Difference{path: ['qux'], type: 'deleted', left_value: 'quux', right_value: undefined}
//   Difference{path: ['garply'], type: 'changed', left_value: [], right_value: {}},
// ]

Each Difference object contains:

• A path: an array of path elements traversed to the location of the differences. The path elements are strings in case of object properties and numbers in case of array keys.
• A type: describes the kind of difference. Can be one of the following:
  • Difference.TYPE_CHANGED = 'changed': both the left and the right instance have a value at the given path, but these values are different.
  • Difference.TYPE_ADDED = 'added': the left instance does not have a value at the given path, but the right instance does, i.e. the value was added in the transition from left to right.
  • Difference.TYPE_DELETED = 'deleted': the left instance has a value at the given path, but the right instance does not, i.e. the value was deleted in the transition from left to right.
• A left_value: the value the left instance has at the given path. Is undefined in case of an addition. Can be a non-scalar value, i.e. a struct in itself.
• A right_value: the value the right instance has at the given path. Is undefined in case of a deletion. Can be a non-scalar value, i.e. a struct in itself.

The Difference and Comparator classes can be accessed separately as named exports:

import { Difference, Comparator } from "js-struct-compare";

Versioning

This project adheres to Semantic Versioning.

Contributing

Contributions to this project are more than welcome.

License

This project is released under the MIT license.

Made with love, coffee and fun by the Moxio team from Delft, The Netherlands. Interested in joining our awesome team? Check out our vacancies (in Dutch).