# @mobdata/little-differ
> A library that diffs two JSON documents and output one JSON document describing both documents and their diffs
Latest version **1.0.0** (published 2021-01-08) · MIT license · 0 weekly downloads
## Install
```sh
npm install @mobdata/little-differ
pnpm add @mobdata/little-differ
yarn add @mobdata/little-differ
bun add @mobdata/little-differ
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 1.0.0 |
| Published | 2021-01-08 |
| First published | 2021-01-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 182.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | glake, timbitsandbytes, cturner5, mrcarballo |
## Links
- npm: https://www.npmjs.com/package/@mobdata/little-differ
- Repository: https://github.com/mobdata/little-differ
- Homepage: https://github.com/mobdata/little-differ#readme
- Issues: https://github.com/mobdata/little-differ/issues
- npm.io page: https://npm.io/package/@mobdata/little-differ
## Recent versions
- 1.0.0 (latest) — 2021-01-08
- 0.0.0 — 2021-01-07
## README
# little-differ
Little Differ contains two Modules for comparing JSON documents. The module called littleDiffer compares two JSON documents, and the one called tripleDiffer compares three. Both modules create a JSON representation of the differences between the documents.
## Installation
`npm install --save '@mobdata/little-differ'`
To build the project, run `npm run build`. To run the tests available for littleDiffer and tripleDiffer, run `npm run test`. This will compare expected module output with set document inputs for testing.
## Usage
Add to your `package.json` dependencies:
````json
...
"dependencies": {
"@mobdata/little-differ": "^1.0.0",
},
...
````
Then run `npm install`.
To use littleDiffer, call compareJSON in your js file with two documents:
````javascript
import { compareJSON } from '@mobdata/little-differ'
const docA = { a:1 }
const docB = { a:2 }
const diffDoc = compareJSON(docA, docB)
console.log(diffDoc)
````
The output will be:
````javascript
{
a: [{ match: false }, { a: 1 }, { a: 2 }]
}
````
To use tripleDiffer, call compareTripleJSON in your js file with three documents, including an original document, document A, and document B.
````javascript
import { compareTripleJSON } from '@mobdata/little-differ'
const orig = { a:1 }
const docA = { a:1 }
const docB = { a:2 }
const diffDoc = compareTripleJSON(orig, docA, docB)
console.log(diffDoc)
````
The output will be:
````javascript
{
a: [{ match: origMatchA }, { a: 1 }, { a: 1 }, { a: 2 }]
}
````
# Understanding the Output format in the Little Differ module
Any two JSON docs can have two types of differences: different keys, and different values for common keys.
`little-differ` lists all keys, and within each key lists a match tag followed by the values. The match tag has a boolean value indicating if the values for that key are equal.
These two documents have the same key, `a`, but the value in each is different. `little-differ` returns that key's name, `a`, followed by an array with the match tag and the key/value pairs for each document.
These next two documents have a key named `b` instead of `a`. The output is very similar to the above.
These next documents have different keys, `a` and `b`. The output will show `null` for the document that's missing the key.
The next output shows you how key `a` is in both documents and both documents have the same value, `1`. Then for key `b`, the output `b: [{ b: 2 }, null]` shows you Document A has value `2`, and Document B has no key `b` at all.
## Using `null`
In the above examples, null is used to identify when a key is missing from a document, but exists in the other document. It can also be used if null is the assigned value of a key. Here's how the output differs with a missing key versus an assigned `null` value.
## Defining `undefined`
`little-differ` can also distinguish between a missing key and a key's value set to `undefined`.
But wait, `undefined` isn't valid JSON...this is true, but it's very easy to programmatically assigned `undefined` to a value when creating JSON. Here's how the output differs with a missing key versus an `undefined` value.
# Understanding the Output format in the Triple Differ module
The output of Triple Differ is very similar to Little Differ, but contains the output of three documents. Also, the match tag that is provided for each key is not a boolean value. It provides more detail as to which document's values match. There are 5 possible values of the match tag: `allEqual`, `allDiff`, `origMatchA`, `origMatchB`, and `modsMatch`. Triple Differ also assumes the positioning of the three documents when the compareTripleJSON function is called. The original document will be in the first position, document A in the second, and document B in the third. In the results, the output for each key will be in the same order with the addition of the match tag.
Lets see some examples:
Here is a simple mismatch of values.
## Using `null`
Again, `null` is used to identify when a key is missing from one of the documents, and also is used if `null` is the assigned value of a key. The following example demonstrates both cases of how `null` is used. Seen here, the first document has the assigned value of `null` for key `a`, the second has an assigned value for key `a`, and the third is missing key `a` all together.
## Nested values
Both modules identify when an object is nested inside another object. If all three documents contain the nested key, the code will recursively step into the object, and once a key is found, it will identify if the three documents match for that key and assign a match value. See the following examples of nested objects.
Simple Nested Object example with equal value among all three documents:
Nested Object where one of the documents does not contain the nested key. This is where the output gets more complicated, but the colors help identify where the data is coming from:
## Understanding Match tags
`allEqual` - all three documents contain equal values for the given key
`allDiff` - all three documents contain a different value for the given key
The next three match tags assume the three documents are in a particular order. The first document is assumed to be the original of the following two modified documents, the second is assumed to be document A, and the third is assumed to be document B.
`origMatchA` - the first and second documents contain equal values, but differ from the third document for the given key
`origMatchB` - the first and third documents contain equal values, but differ from the second document for the given key
`modsMatch` - the second and third documents (both modified docs) contain equal values, but differ from the first document for the given key
---
_Source: https://npm.io/package/@mobdata/little-differ · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._