JSON diff audit

json-diff-audit is a Node.js library that compares JSON objects consecutively, identifies differences, and generates detailed audit records for easy reporting and tracking changes.

Table of Contents

• Install
• Usage
  • Node
• How it Works
• Logging
• Notes

Install

npm:

npm install json-diff-audit

Usage

Node

const { auditEventTransformer } = require('json-diff-audit')

const record1 = { 
  employee : {
    name: "John Smith",
  },
  date: "04-17-2023 9:16:2 pm",
  userId: "klewis",
}

const record2 = {
  employee : {
    name: "Jane Thomas",
  },
  date: "04-21-2023 10:23:2 am",
  userId: "mtimms",
}

const result = auditEventTransformer.process([record1, record2], "employee")

console.info(JSON.stringify(result))

Input

auditEventTransformer.process(arg1, arg2) 

arg1:  Collection of domain objects to compare

arg2:  Domain field for comparisons, defaults to "data"

Output

[
  {
    "path":"name",
    "user":"mtimms",
    "dateAndTime":"04-21-2023 10:23:2 am",
    "field":"name",
    "action":"update",
    "oldValue":"John Smith",
    "newValue":"Jane Thomas"
  }
]

The output shows that an update was made to the name field, going from John Smith to Jane Thomas, and was made by user mtimms on 04-21-2023 at 10:23:2 am.

How it works

The input is a collection of records. Each record should have 3 fields

Field	Description
userId	the user that made the changes to the current object
date	the date and time the change was made
< domain object >	the key name to the domain object that will be compared, defaults to 'data'

The processing will compare each record in the collection to the next, they are assumed to be ordered by date. A list of deltas is calculated and turned into a collection of audit records. Each audit record will contain the following fields:

Field	Description
user	the user that made the changes to the current object
dateAndTime	the date and time the change was made
field	the field key name that was affected
action	the field in question was either an add, update, or delete
oldValue	if an action is either update or delete, this field indicates the previous value
newValue	if an action is either an update or add, this field indicates the new value
path	the full path in dot notation to the affected field

Logging

By default, json-diff-audit will only log errors encountered during it's function execution. Additional debugging output can be conditionally triggered by setting the environment variable json_diff_audit__debug = true.

Notes

1. The path in the response is experimental at this time, certain cases with arrays are still being considered
2. Comparison of domain objects is currently done by order in the collection, not by date.