Wondering what’s next for npm?Check out our public roadmap! »

    js-struct-compare

    1.1.0 • Public • Published

    NPM version

    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).

    Install

    npm i js-struct-compare

    DownloadsWeekly Downloads

    20

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    19.9 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar