GithubHelp home page GithubHelp logo

lukasz-pluszczewski / differrer Goto Github PK

View Code? Open in Web Editor NEW
0.0 1.0 0.0 264 KB

Utility to perform deep diff on any data types with smart order detection in arrays and different views implemented for convenience

License: MIT License

CSS 3.51% JavaScript 5.96% HTML 49.03% TypeScript 41.50%

differrer's Introduction

Differrer

Utility to perform deep diff on any data types with smart order detection in arrays and different views implemented for convenience

Differrer is a JavaScript library that provides a set of tools for performing deep-diff operations on any data type, including nested arrays and objects. It enables the developer to pass a custom function to detect the order of objects in arrays.

Several views are implemented to create a more human-readable version of the diff results.

Getting started

Install the library

npm i differrer

Basic usage

import createDiff, { getType } from 'differrer';

const diff = createDiff({
  sortArrayItems: true, // default false
  getArrayElementId: (item: any) => getType(item) === 'object' ? item.id : item,
});

const source = [{ id: 10, value: 'foo' }, { id: 1, value: 'bar' }];
const compare = [{ id: 1, value: 'bar' }, { id: 10, value: 'foo' }];

const diffResult = diff(source, compare);

The diffResult will look like this:

{
  sourcePath: [],
  targetPath: [],
  sourceValue: [
    {
      id: 10,
      value: 'foo',
    },
    {
      id: 1,
      value: 'bar',
    },
  ],
  targetValue: [
    {
      id: 1,
      value: 'barr',
    },
    {
      id: 10,
      value: 'foo',
    },
  ],
  sameValue: false,
  sameValueZero: false,
  retrievedId: null,
  sourceOrder: null,
  targetOrder: null,
  sameOrder: null,
  sourceType: 'array',
  targetType: 'array',
  sameType: true,
  added: false,
  removed: false,
  changed: true,
  children: [
    {
      sourcePath: [
        1,
      ],
      targetPath: [
        0,
      ],
      sourceValue: {
        id: 1,
        value: 'bar',
      },
      targetValue: {
        id: 1,
        value: 'barr',
      },
      sameValue: false,
      sameValueZero: false,
      retrievedId: '1',
      sourceOrder: 1,
      targetOrder: 0,
      sameOrder: false,
      sourceType: 'object',
      targetType: 'object',
      sameType: true,
      added: false,
      removed: false,
      changed: true,
      children: {
        id: {
          sourcePath: [
            1,
            'id',
          ],
          targetPath: [
            0,
            'id',
          ],
          sourceValue: 1,
          targetValue: 1,
          sameValue: true,
          sameValueZero: true,
          retrievedId: null,
          sourceOrder: 0,
          targetOrder: 0,
          sameOrder: true,
          sourceType: 'number',
          targetType: 'number',
          sameType: true,
          added: false,
          removed: false,
          changed: false,
          children: null,
        },
        value: {
          sourcePath: [
            1,
            'value',
          ],
          targetPath: [
            0,
            'value',
          ],
          sourceValue: 'bar',
          targetValue: 'barr',
          sameValue: false,
          sameValueZero: false,
          retrievedId: null,
          sourceOrder: 1,
          targetOrder: 1,
          sameOrder: true,
          sourceType: 'string',
          targetType: 'string',
          sameType: true,
          added: false,
          removed: false,
          changed: true,
          children: null,
        },
      },
    },
    {
      sourcePath: [
        0,
      ],
      targetPath: [
        1,
      ],
      sourceValue: {
        id: 10,
        value: 'foo',
      },
      targetValue: {
        id: 10,
        value: 'foo',
      },
      sameValue: true,
      sameValueZero: false,
      retrievedId: '10',
      sourceOrder: 0,
      targetOrder: 1,
      sameOrder: false,
      sourceType: 'object',
      targetType: 'object',
      sameType: true,
      added: false,
      removed: false,
      changed: false,
      children: {
        id: {
          sourcePath: [
            0,
            'id',
          ],
          targetPath: [
            1,
            'id',
          ],
          sourceValue: 10,
          targetValue: 10,
          sameValue: true,
          sameValueZero: true,
          retrievedId: null,
          sourceOrder: 0,
          targetOrder: 0,
          sameOrder: true,
          sourceType: 'number',
          targetType: 'number',
          sameType: true,
          added: false,
          removed: false,
          changed: false,
          children: null,
        },
        value: {
          sourcePath: [
            0,
            'value',
          ],
          targetPath: [
            1,
            'value',
          ],
          sourceValue: 'foo',
          targetValue: 'foo',
          sameValue: true,
          sameValueZero: true,
          retrievedId: null,
          sourceOrder: 1,
          targetOrder: 1,
          sameOrder: true,
          sourceType: 'string',
          targetType: 'string',
          sameType: true,
          added: false,
          removed: false,
          changed: false,
          children: null,
        },
      },
    },
  ],
}

Config

createDiff function accepts the following arguments

  • sortArrayItems: boolean (default: false) - if true diff will sort arrays (different data types will appear in the following order: numbers (sorted), strings (sorted), true, false, null, undefined, objects, arrays)
  • getArrayElementId: function (optional) - function that allows diff to detect the order of objects in arrays. It accepts an array element and returns the id of the element. If not provided, the order of objects in arrays will not be detected. Keep in mind that it may get any type of item depending on the input data you provided to the diff function.
    • item: any - the element to get the id from
    • returns: string|number|any - the id of the element, anything other than string or number will be ignored
  • returns: function - the diff function

Diff function

The diff function accepts two arguments: source and compare. Both arguments can be of any type (number, string, boolean, null, undefined, object, array).

Diff result

The diff function returns a tree diff result objects. They contain the following properties:

  • sourcePath: string[] - the path to the source value in the source object

  • targetPath: string[] - the path to the target value in the target object

  • sourceValue: any - the value from the source object

  • targetValue: any - the value from the target object

  • sameValue: boolean - true if the source and target values are the same

  • sameValueZero: boolean - true if the source and target values are the same (using SameValueZero comparison)

  • retrievedId: string|number - the id of the object if it was retrieved from the source object

  • sourceOrder: number - the order of the element in the source (if the value is a field in an object or element of the array)

  • targetOrder: number - the order of the element in the target (if the value is a field in an object or element of the array)

  • sameOrder: boolean - true if the source and target orders are the same

  • sourceType: string - the type of the source value (one of the following: 'undefined', 'null', 'boolean', 'number', 'string', 'object', 'array', 'unknown')

  • targetType: string - the type of the target value (one of the following: 'undefined', 'null', 'boolean', 'number', 'string', 'object', 'array', 'unknown')

  • sameType: boolean - true if the source and target types are the same

  • added: boolean - true if the value was added in the target

  • removed: boolean - true if the value was removed in the target

  • changed: boolean - true if the value was changed in the target

  • children: object|array - the children of the value (if the value is an object or an array)

Supported data types

The diff function understands the following types: undefined, null, boolean, number, string, array and object (only plain JS objects are considered objects). Anything else will have "unknown" type.

Views

The diff result is not very readable in it's raw form. You can use one of the provided views functions to turn it into something more pleasant. The views functions accept the diff result object and return a string.

Usage example

import createDiff, { getType, diffJsView, diffSortedView } from 'differrer';

const diff = createDiff({ getArrayElementId: (item: any) => getType(item) === 'object' ? item.id : item });

const source = [{ id: 10, value: 'foo' }, { id: 1, value: 'bar' }];
const compare = [{ id: 1, value: 'bar' }, { id: 10, value: 'foo' }];

const diffResult = diff(source, compare);

const jsView = diffJsView(diffResults);
const sortedView = diffSortedView(diffResults);

jsView

A view that will generate valid javascript (or JSON5) representation of source with changes marked in comments (change // ~, add // +, remove // -).

Here are a few examples:

SourceCompareResult
{
  foo: 123,
  bar: 456,
}
 
{
  foo: 123,
  bar: '457',
  baz: 789,
}
 
{
  foo: 123,
  bar: 456, // ~ '457'
  baz: 789, // +
} // ~
 
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'bar',
  },
]
 
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'barr',
  },
]
 
[
  {
    id: 1,
    value: 'bar', // ~ 'barr'
  }, // ~
  {
    id: 10,
    value: 'foo',
  },
] // ~
 
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'bar',
  },
  {
    id: 2,
    value: 'baz',
  },
]
 
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'barr',
  },
  {
    id: 3,
    value: 'baz',
  },
]
 
[
  {
    id: 1,
    value: 'bar', // ~ 'barr'
  }, // ~
  {
    id: 2, // -
    value: 'baz', // -
  }, // -
  {
    id: 3, // +
    value: 'baz', // +
  }, // +
  {
    id: 10,
    value: 'foo',
  },
] // ~
 
[
  {
    id: 'ten',
    value: {
      foo: 'foo',
      bar: 'bar',
    },
  },
  {
    id: 'one',
    value: 'bar',
  },
  {
    id: 'two',
    value: 'baz',
  },
]
 
[
  {
    id: 'ten',
    value: {
      foo: 'foo',
      bar: 'nieBar',
    },
  },
  {
    id: 'one',
    value: 'barr',
  },
  {
    id: 'three',
    value: 'baz',
  },
]
 
[
  {
    id: 'one',
    value: 'bar', // ~ 'barr'
  }, // ~
  {
    id: 'ten',
    value: {
      foo: 'foo',
      bar: 'bar', // ~ 'nieBar'
    }, // ~
  }, // ~
  {
    id: 'three', // +
    value: 'baz', // +
  }, // +
  {
    id: 'two', // -
    value: 'baz', // -
  }, // -
] // ~

You can save the result to a file and have a valid JS code (or valid JSON5):

import fs from 'fs';

// ...

const jsView = diffJsView(diffResults);

writeFileSync('results.js', `const diff = ${jsView};`);

sortedView

View that allows easier comparison in text diff tools that compare strings line by line (like diffchecker.com, diffmerge or diff view in JetBrains IDEs). It will align source and target objects in arrays according to provided getArrayElementId and leave empty lines for a diff tool to pick up easily.

Here are a few examples:

Data:
SourceCompare
{
  foo: 123,
  bar: 456,
}
 
{
  foo: 123,
  bar: '457',
  baz: 789,
}

Results:
SourceCompare
{
  foo: 123,
  bar: 456,

}
 
{
  foo: 123,
  bar: '457',
  baz: 789,
}

Data:
SourceCompare
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'bar',
  },
]
 
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'barr',
  },
]

Results:
SourceCompare
[
  {
    id: 1,
    value: 'bar',
  },
  {
    id: 10,
    value: 'foo',
  },
]
 
[
  {
    id: 1,
    value: 'barr',
  },
  {
    id: 10,
    value: 'foo',
  },
]

Data:
SourceCompare
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'bar',
  },
  {
    id: 2,
    value: 'baz',
  },
]
 
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'barr',
  },
  {
    id: 3,
    value: 'baz',
  },
]

Results:
SourceCompare
[
  {
    id: 1,
    value: 'bar',
  },
  {
    id: 2,
    value: 'baz',
  },




  {
    id: 10,
    value: 'foo',
  },
]
 
[
  {
    id: 1,
    value: 'barr',
  },




  {
    id: 3,
    value: 'baz',
  },
  {
    id: 10,
    value: 'foo',
  },
]

Data:
SourceCompare
[
  {
    id: 'ten',
    value: {
      foo: 'foo',
      bar: 'bar',
    },
  },
  {
    id: 'one',
    value: 'bar',
  },
  {
    id: 'two',
    value: 'baz',
  },
]
 
[
  {
    id: 'ten',
    value: {
      foo: 'foo',
      bar: 'nieBar',
    },
  },
  {
    id: 'one',
    value: 'barr',
  },
  {
    id: 'three',
    value: 'baz',
  },
]

Results:
SourceCompare
[
  {
    id: 'one',
    value: 'bar',
  },
  {
    id: 'ten',
    value: {
      foo: 'foo',
      bar: 'bar',
    },
  },




  {
    id: 'two',
    value: 'baz',
  },
]
 
[
  {
    id: 'one',
    value: 'barr',
  },
  {
    id: 'ten',
    value: {
      foo: 'foo',
      bar: 'nieBar',
    },
  },
  {
    id: 'three',
    value: 'baz',
  },




]

diffChangesView

View that displays only differences, useful for terminal output.

Here are a few examples:

SourceCompareResult
{
  foo: 123,
  bar: 456,
}
 
{
  foo: 123,
  bar: '457',
  baz: 789,
}

/assets/changesConsoleViewExample0.png

 
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'bar',
  },
]
 
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'barr',
  },
]

/assets/changesConsoleViewExample1.png

 
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'bar',
  },
  {
    id: 2,
    value: 'baz',
  },
]
 
[
  {
    id: 10,
    value: 'foo',
  },
  {
    id: 1,
    value: 'barr',
  },
  {
    id: 3,
    value: 'baz',
  },
]

/assets/changesConsoleViewExample2.png

 
[
  {
    id: 'ten',
    value: {
      foo: 'foo',
      bar: 'bar',
    },
  },
  {
    id: 'one',
    value: 'bar',
  },
  {
    id: 'two',
    value: 'baz',
  },
]
 
[
  {
    id: 'ten',
    value: {
      foo: 'foo',
      bar: 'nieBar',
    },
  },
  {
    id: 'one',
    value: 'barr',
  },
  {
    id: 'three',
    value: 'baz',
  },
]

/assets/changesConsoleViewExample3.png

differrer's People

Contributors

lukasz-pluszczewski avatar

Watchers

avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.