README
diffter
diffter can be used to determine the difference between two list of any items and generate an HTML report about the results.
Prerequisites
- Node.js 10+
Usage
The following script generated the report can be seen below:
const {
diff,
saveReport
} = require('diffter');
const baseList = [1, 2, 3, 4];
const subjectList = [1, 3, 4, 5];
const results = diff(baseList, subjectList);
saveReport('./report', results);
The items are colored in the following way:
- Green items are the same in both list.
- Blue items are changed position in subject list.
- Red items in base list are those which are deleted in subject list.
- Yellow items in subject list are those which are new compared to the base list.
- Gray items are the ignored items.
CLI
After diffter
is installed globally or in local NPM scripts:
diffter-report --base path\to\base.json --subject path\to\subject.json --save report.html
diffter-results --base path\to\base.json --subject path\to\subject.json --save data.js --js
Options:
--help Show help [boolean]
--config Path to JS/JSON config file
--base Path of BASE results list JSON file. [required]
--subject Path of SUBJECT results list JSON file. [required]
--title Title of the report [default: "Report"]
--save Path of JSON file where DiffResults should be saved. [required]
--comparator Path of JS file which exports custom Comparator function. Config
could also contain actual Comparator function.
--filter Path of JS file which exports custom Filter function. Config
could also contain actual Filter function.
--modifier Path of JS file which exports custom function to transform
source data to display data. Config could also contain actual
Transform function.
--js Should the result be save to JS file which exports DiffResults
Object. [default: false]
The --config
can specify a JS/JSON file, which can contain all the above-listed options.
API
diff(baseList, subjectList[, options])
Params:
{SourceList|Array} baseList
- the list of items used as the base list{SourceList|Array} subjectList
- the list of subject items which are compared to the base list{DiffOptions} options
- options could be passed to the analyzer.
Returns: {DiffResults}
the results of the analysis
saveReport(filePath, title, results)
Params:
{string} filePath
- the path to the file, where report needs to be stored{string} title
- the title of the report{DiffResults} results
- the results needs to be displayed in report
saveResults(filePath, results[, type[, jsPrefix]])
Params:
{string} filePath
- the path to the file, where results needs to be stored{DiffResults} results
- the results needs to be stored in the file{string} type
- the type of the file to store the results,js
orjson
, default:json
{string} jsPrefix
- the prefix which needs to be used in case of storing to JS, default:module.exports =
Types
SourceList
Type of a list as input for given methods.
{string} title
- the title/name of the list{Array} items
- the actual items of the list
{
"title": "Souce List",
"items": [1, 2, 3]
}
DiffResults
Type of the diff-analysis results.
{DiffList} baseList
- the items of the base list{DiffList} subjectList
- the items of the subject list{Array<Array<number>>} indexes
- the list of indexes/states
{
"baseList": {
"title": "Base List",
"items": [
{"title": 1},
{"title": 2},
{"title": 3}
]
},
"subjectList": {
"title": "Subject List",
"items": [
{"title": 1},
{"title": 3},
{"title": 2}
]
},
"indexes": [
[0, 0],
[1, 2],
[2, 1]
]
}
DiffList
Type for a list to store result items.
{string} title
- the title/name of the list{Array<DiffListItem>} items
- the actual items of the list
{
"title": "Subject List",
"items": [
{"title": 1},
{"title": 3},
{"title": 2}
]
}
DiffListItem
Type for an item of a list.
{string} title
- the title/name of the actual item{Object} metadata
- any metadata (key-value pair) of the given item
{
"title": 2
}
DiffOptions
Type to define options of diff-analysis.
{Comparator} comparator
- the comparator function, by default: deep-eql{Filter} filter
- the filter funtion, by default:() => true
{Transform} transform
- the transform function, by default:item => item
module.exports = {
comparator: (a, b) => a === b,
filter: item => !item.ignore,
transform: item => ({
title: item
})
}
Comparator
Type for comparator function, to compare to items in the diff-analyzer.
Params:
{*} base
- the base item{*} subject
- the subject item
Returns: {boolean}
- true
if the two items are equal
Filter
Type for filter function, to determine items to ignore.
Params:
{*} item
- the item to check
Returns: {boolean}
- true
if the item should be kept
Transform
Type for transform function, to convert given items to DiffListItem
.
Params:
{*} item
- the item to transform
Returns: {DiffListItem}
- the transformed item