Git Like Audit Trail

A library that handling audit trail like git. Using Elasticsearch (allow using custom client later) to store audit-trail data.

Installation

yarn add git-like-audit-trail

Screenshot

Demo

• Backend
• FrontEnd

Usage:

1import auditTrail from "git-like-audit-trail"
2
3// content of below 3 function depends on database type
4const databaseAddOneRowFunction = async ({
5    data,
6    auditTrail = true,
7    parentTrail
8}) => {
9    ...
10}
11
12const databaseDeleteOneRowFunction = async ({
13    data,
14    auditTrail = true,
15    parentTrail
16}) => {
17    ...
18}
19
20const databaseUpdateOneRowFunction = async ({
21    data,
22    changedObj,
23    addChangedObj,
24    deleteChangedObj,
25    revert = true,
26    auditTrail = true,
27    parentTrail
28}) => {
29    ...
30}
31
32const _auditTrail = new auditTrail({
33    DBType: "elasticsearch", // default
34    host: "http://localhost:9200", //default
35    ESinfo: { //default
36        indexName: "audit-trail",
37    },
38    databaseAddOneRowFunction,
39    databaseDeleteOneRowFunction,
40    databaseUpdateOneRowFunction,
41    // databaseCustomActionFunction, // custom action function
42})

Function available:

• createData: Create audit trail data
• appendCommitMap: Append commitHash (obtained after createData) into CommitMap
• query: Query git tree structure
• queryD3: Query git tree structure in D3 hierarchy
• queryByCommitHash: Query commit info by commitHash
• batchQueryByCommitHash: Query commit info by commitHashArray
• revertCommit: Revert commit like git
• cherryPick: Cherry Pick like git
• checkout: checkout to other commit/branch

Function usage

await need to execute in async function

createData:

1const trail = await _auditTrail.createData({
2    categoryId: "testTable", // target table name
3    userId: "awcjack", // user id
4    dataId: "1", // changes target data id
5    name: "1", // extra info
6    before: {}, // data before change
7    after: {
8        id: "1",
9        name: "test1"
10    }, // data after change
11    parent, // parent commit id (for large trail that change multiple data)
12    action: "CREATE", // "CREATE" || "UPDATE" || "DELETE" (allow extra action type but have to handled in databaseCustomActionFunction)
13    ignore: [], // ignore in diff
14    ...otherArgs // other args that want to log into this audit trail
15})
16console.log(trail)
17
18/*
19{
20    categoryId: "testTable",
21    userId: "awcjack",
22    dataId: "1",
23    name: "1",
24    parent,
25    action: "CREATE",
26    ...otherArgs,
27    change: "{\"added\":{\"id\":{\"after\":\"1\"},\"name\":{\"after\":\"test\"}},\"deleted\":{},\"updated\":{}}",
28    time: 1613749903586,
29    parentTrail: "04353794-da94-468d-abd9-1080426007a4",
30    commitHash: "834cb604b1ce6ae0eb77b8a52aab60d913e4ede2
31}
32// commitHash work as index
33*/

appendCommitMap:

1const { commitHash } = trail // trail object from createData
2const commitMap = _auditTrail.appendCommitMap({
3    currentCommitMap: "{}", // existing commit map ("{}" for init)
4    currentCommitHash: "", // current commit hash in category
5    newCommitHash: commitHash //new commit hash from createData
6})
7console.log(commitMap)
8/*
9"{^0_834cb604b1ce6ae0eb77b8a52aab60d913e4ede2:834cb604b1ce6ae0eb77b8a52aab60d913e4ede2}"
10// string type for storing into db
11*/

query:

1const tree = _auditTrail.query({
2    commitHashMap: "{}", // existing commit map
3    commitHash: "", // query from hash (user current commit)
4    before: 5, // include 5 commit (level) before
5    after: 5,// include 5 commit (level) after
6    onlyCurrentBranch: false, //only reveal current branch
7    getCommitInfo: false // query commit info
8})
9console.log(tree)
10/*
11[{"834cb604b1ce6ae0eb77b8a52aab60d913e4ede2":{"3e4c25f224e435372b9c1f92bc050fd3a9840d91":{},"34fc46d4e871605dcf1f3519f5f4ee0124dac4ed":{}}}]
12// removed commit info prevent too long
13*/

queryD3:

1const tree = _auditTrail.queryD3({
2    commitHashMap: "{}", // existing commit map
3    commitHash: "", // query from hash (user current commit)
4    before: 5, // include 5 commit (level) before
5    after: 5,// include 5 commit (level) after
6    onlyCurrentBranch: false, //only reveal current branch
7    getCommitInfo: false, // query commit info
8    ignore: [], // ignore array of commit info object (delete from object)
9    format, // commit info format, "test" (commit info parse to key: value pair and concat with \n), "object" (commit info)
10})
11console.log(tree)
12/*
13[{"children":[{"children":{"name":"da498b3a30a06db903cc25cfac07517e3e08216c", "info": {...}, "currentCommit": true})],"name":"2a599a5d724d659b8ebb6565a626de40d52db10a","info":{"categoryId":"testTable","userId":"awcjack","dataId":"1","name":"test","action":"CREATE","change":"{\"added\":{\"id\":{\"after\":\"1\"},\"name\":{\"after\":\"test\"}},\"deleted\":{},\"updated\":{}}","time":1614433429834,"parentTrail":"b343ac62-7807-4d68-8518-f4d18e59e781","commitHash":"2a599a5d724d659b8ebb6565a626de40d52db10a"}}]
14*/

queryByCommitHash:

1const commit = _auditTrail.queryByCommitHash({
2    commitHash: "b11b50b366f8477e8e9f5dea5344fc42eac63b06",
3})
4console.log(commit)
5/*
6{
7    "categoryId": "testTable",
8    "userId": "awcjack",
9    "dataId": "3",
10    "name": "test3",
11    "action": "CREATE",
12    "ignore": [],
13    "change": "{\"added\":{\"id\":{\"after\":\"3\"},\"name\":{\"after\":\"test3\"}},\"deleted\":{},\"updated\":{}}",
14    "time": 1613815197218,
15    "parentTrail": "9aaf9a1c-7ccc-453a-9d3f-bd70a5e49c58",
16    "commitHash": "b11b50b366f8477e8e9f5dea5344fc42eac63b06"
17}
18*/

batchQueryByCommitHash:

1const commits = _auditTrail.batchQueryByCommitHash({
2    commitHashArray: ["b11b50b366f8477e8e9f5dea5344fc42eac63b06"],
3})
4console.log(commits)
5/*
6[{
7    "categoryId": "testTable",
8    "userId": "awcjack",
9    "dataId": "3",
10    "name": "test3",
11    "action": "CREATE",
12    "ignore": [],
13    "change": "{\"added\":{\"id\":{\"after\":\"3\"},\"name\":{\"after\":\"test3\"}},\"deleted\":{},\"updated\":{}}",
14    "time": 1613815197218,
15    "parentTrail": "9aaf9a1c-7ccc-453a-9d3f-bd70a5e49c58",
16    "commitHash": "b11b50b366f8477e8e9f5dea5344fc42eac63b06"
17}]
18*/

revertCommit:

1const result = await _auditTrail.revertCommit({
2    commitHash: req.params.hash,
3})
4console.log(result)
5/*
6{
7    "added": {
8        "error": false,
9        "content": {
10            "id": "1",
11            "name": "test"
12        },
13        "commitHash": "834cb604b1ce6ae0eb77b8a52aab60d913e4ede2"
14    }
15}
16*/

cherryPick:

1const result = await _auditTrail.cherryPick({
2    commitHash: req.params.hash,
3})
4console.log(result)
5/*
6{
7    "added": {
8        "error": false,
9        "content": {
10            "id": "1",
11            "name": "test"
12        },
13        "commitHash": "834cb604b1ce6ae0eb77b8a52aab60d913e4ede2"
14    }
15}
16*/

checkout:

1const result = await _auditTrail.checkout({
2    commitHashMap: commitHashMap.commitMap,
3    currentCommit: currentCommit.commitHash,
4    commitHash: req.params.hash,
5})
6console.log(result)
7/*
8[{"deleted":{"error":false,"content":{"id":"23","name":"test23"}}}]
9*/

To do

• verify tree structure & logic
• handle checkout
• handle merge (may or may not implement)
• custom client
• provide frontend demo
• handle batch CUD in demo