TCDC Audit Backend Library

Overview

The TCDC Audit Backend Library provides tools to track changes to data records, including field-level modifications, record creation, and deletion events. It is designed for seamless integration with MongoDB and includes features for both user and system-generated audit trails.

The library supports:

• Field-Level Changes: Captures old and new values for individual fields.
• Record-Level Metadata: Tracks overarching changes with timestamps, user/system information, and optional notes.
• Utility Functions: Simplifies the process of creating, updating, and deleting audit trail records.
• Testing and Extensibility: Includes robust testing and an extensible schema for customization.

Getting Started

Prerequisites

• Node.js (v14+ recommended)
• MongoDB (local or in-memory using mongodb-memory-server for testing)

Installation

1. Clone the repository:

   git clone <repository-url> && cd tcdc-audit-backend-lib

2. Install dependencies:

   npm install

3. Compile the library:

   npm run build

4. Run tests:

   npm test

Basic Usage

The library provides utility functions to handle common audit trail operations: trackCreation, trackUpdate, and trackDeletion. These functions generate structured audit records that can be stored in MongoDB.

Importing Functions

All functions are exported from the same file:

import { trackCreation, trackUpdate, trackDeletion } from './src/functions/audit-track-changes';

trackCreation

Tracks the initial values of a record when it is created.

Example Usage:

const auditRecord = trackCreation({
  data: { name: 'John Doe', age: 30 },
  changedBy: { profileId: 'admin123', name: 'Admin User' },
  notes: ['Initial record creation'],
});

console.log(auditRecord);

trackUpdate

Tracks changes between the old and new states of a record.

Example Usage:

const auditRecord = trackUpdate({
  oldState: { name: 'John Doe', age: 30 },
  newState: { name: 'Jane Doe', age: 30 },
  changedBy: { profileId: 'user456', name: 'Editor User' },
  notes: ['Name correction'],
  ignoreKeys: ['age'],
});

console.log(auditRecord);

trackDeletion

Logs metadata for a record deletion event.

Example Usage:

const auditRecord = trackDeletion({
  changedBy: { profileId: 'admin123', name: 'Admin User' },
  notes: ['Record deleted for compliance'],
});

console.log(auditRecord);

Testing

The library uses Jest for unit and integration tests, with mongodb-memory-server for testing database interactions.

Running Tests

1. Run all tests:

   npm test

2. Run tests in watch mode:

   npm run test:watch

3. Generate a coverage report:

   npm run test:coverage

License

See LICENSE.txt.

Documentation

Detailed documentation, including the schema structure and advanced use cases, is available in the docs/ directory.