cnd-audit-history

Complete audit trail system with decorators for NestJS/TypeORM applications.

Features

✅ @Auditable() decorator for entities ✅ @SkipAudit() decorator for sensitive fields ✅ @UserTrace() decorator for controllers ✅ Automatic INSERT/UPDATE/DELETE tracking ✅ Field-level change tracking (old value → new value) ✅ User context tracking (userId, IP, user agent) ✅ Request tracing with trace IDs ✅ AsyncLocalStorage for thread-safe context ✅ TypeORM integration with subscribers

Installation

npm install cnd-audit-history

Quick Start

1. Import the Module

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AuditHistoryModule } from 'cnd-audit-history';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      // your database config
    }),
    AuditHistoryModule,  // Add this
  ],
})
export class AppModule {}

2. Decorate Your Entities

import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
import { Auditable, SkipAudit } from 'cnd-audit-history/decorators';

@Auditable({ name: 'User' })
@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  email: string;

  @SkipAudit()  // Skip sensitive fields
  @Column()
  password: string;

  @Column()
  firstName: string;

  @Column()
  lastName: string;
}

3. Decorate Your Controllers (Optional)

import { Controller } from '@nestjs/common';
import { UserTrace } from 'cnd-audit-history/decorators';

@UserTrace()  // Automatically track user context
@Controller('users')
export class UserController {
  // Your controller methods
}

4. Run Migrations

# Generate migration
npm run typeorm migration:generate src/migrations/CreateAuditTables

# Run migration
npm run typeorm migration:run

Usage

Query Audit Logs

import { Injectable } from '@nestjs/common';
import { AuditHistoryService } from 'cnd-audit-history/services';

@Injectable()
export class MyService {
  constructor(private readonly auditService: AuditHistoryService) {}

  async getUserAuditHistory(userId: number) {
    // Get all audit logs for a specific user entity
    return this.auditService.findByEntity('User', userId);
  }

  async getRecentChanges() {
    // Get recent audit logs
    return this.auditService.findRecent(10);
  }
}

Audit Log Structure

{
  id: 1,
  entityType: 'User',
  entityId: '123',
  action: 'UPDATE',  // INSERT | UPDATE | DELETE
  userId: 456,
  ipAddress: '192.168.1.1',
  userAgent: 'Mozilla/5.0...',
  requestId: 'abc-123',
  createdAt: '2025-01-01T10:00:00Z',
  details: [
    {
      fieldName: 'email',
      oldValue: '[email protected]',
      newValue: '[email protected]'
    },
    {
      fieldName: 'firstName',
      oldValue: 'John',
      newValue: 'Jane'
    }
  ]
}

Configuration

Environment Variables

# .env
AUDIT_TABLE_PREFIX=audit_history  # Default: audit_history
AUDIT_TRACK_IP=true                # Track IP addresses
AUDIT_TRACK_USER_AGENT=true        # Track user agents

Advanced Configuration

import { AuditHistoryModule } from 'cnd-audit-history';

@Module({
  imports: [
    AuditHistoryModule.forRoot({
      tablePrefix: 'custom_audit',
      trackIp: true,
      trackUserAgent: true,
      useAsyncLocalStorage: true
    })
  ]
})
export class AppModule {}

API Reference

Decorators

@Auditable(options?)

Marks an entity class as auditable.

@Auditable({ name: 'CustomName', disabled: false })
@Entity()
export class MyEntity {}

@SkipAudit()

Skips auditing for a specific field.

@SkipAudit()
@Column()
password: string;

@UserTrace()

Automatically tracks user context in controllers.

@UserTrace()
@Controller()
export class MyController {}

Services

AuditHistoryService

Main service for querying audit logs.

// Find by entity
findByEntity(entityType: string, entityId: string | number): Promise<AuditHistoryLog[]>

// Find recent
findRecent(limit: number): Promise<AuditHistoryLog[]>

// Find by user
findByUser(userId: number): Promise<AuditHistoryLog[]>

// Find by date range
findByDateRange(start: Date, end: Date): Promise<AuditHistoryLog[]>

Examples

See the examples directory for complete working examples.

License

MIT

Support

• Documentation
• GitHub Issues
• Discord Community