@geekmidas/audit 9.0.2 → 10.0.0-alpha.0

package/src/Auditor.ts

@@ -1,157 +0,0 @@
-import type {
-	AuditActor,
-	AuditableAction,
-	AuditMetadata,
-	AuditOptions,
-	AuditRecord,
-	ExtractAuditPayload,
-	ExtractAuditType,
-} from './types';
-
-/**
- * Interface for audit collection and flushing.
- * Generic over audit action types for full type safety.
- *
- * @template TAuditAction - Union of all allowed audit action types
- * @template TTransaction - Transaction type (e.g., Kysely Transaction)
- *
- * @example
- * ```typescript
- * type AppAuditAction =
- *   | AuditableAction<'user.created', { userId: string; email: string }>
- *   | AuditableAction<'user.updated', { userId: string; changes: string[] }>;
- *
- * // In endpoint handler
- * const auditor: Auditor<AppAuditAction> = ...;
- *
- * // Type-safe audit calls
- * auditor.audit('user.created', { userId: '123', email: 'test@example.com' }); // ✅
- * auditor.audit('user.created', { orderId: '123' }); // ❌ Type error
- * auditor.audit('unknown.type', {}); // ❌ Type error
- * ```
- */
-export interface Auditor<
-	TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
-		string,
-		unknown
-	>,
-	TTransaction = unknown,
-> {
-	/**
-	 * The actor for all audits in this context.
-	 * Set at construction time, immutable throughout the request.
-	 */
-	readonly actor: AuditActor;
-
-	/**
-	 * Record a type-safe audit entry.
-	 * The payload type is inferred from the audit type.
-	 *
-	 * @param type - The audit type (must be a valid type from TAuditAction)
-	 * @param payload - The audit payload (shape enforced by type)
-	 * @param options - Optional audit metadata
-	 *
-	 * @example
-	 * ```typescript
-	 * auditor.audit('user.created', {
-	 *   userId: '123',
-	 *   email: 'test@example.com',
-	 * });
-	 *
-	 * auditor.audit('order.placed', {
-	 *   orderId: 'order-456',
-	 *   total: 99.99,
-	 * }, {
-	 *   entityId: 'order-456',
-	 *   table: 'orders',
-	 * });
-	 * ```
-	 */
-	audit<TType extends ExtractAuditType<TAuditAction>>(
-		type: TType,
-		payload: ExtractAuditPayload<TAuditAction, TType>,
-		options?: AuditOptions,
-	): void;
-
-	/**
-	 * Record a raw audit record.
-	 * Use this when you need full control over the audit structure,
-	 * bypassing type safety.
-	 *
-	 * @param record - The audit record (id, timestamp, actor added automatically)
-	 */
-	record(record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>): void;
-
-	/**
-	 * Get all collected audit records.
-	 * Useful for inspection or custom processing.
-	 */
-	getRecords(): AuditRecord[];
-
-	/**
-	 * Flush all collected audits to storage.
-	 * Called automatically by the endpoint adaptor inside the transaction.
-	 *
-	 * @param trx - Optional transaction context for atomic writes
-	 */
-	flush(trx?: TTransaction): Promise<void>;
-
-	/**
-	 * Clear all collected audit records without flushing.
-	 * Use with caution - collected audits will be lost.
-	 */
-	clear(): void;
-
-	/**
-	 * Add metadata to all future audit records.
-	 * Merges with existing metadata (new values override existing).
-	 * Typically called by adaptors to add request context.
-	 *
-	 * @param metadata - Metadata to add (requestId, endpoint, method, ip, etc.)
-	 *
-	 * @example
-	 * ```typescript
-	 * // In endpoint adaptor
-	 * auditor.addMetadata({
-	 *   requestId: 'req-123',
-	 *   endpoint: '/users',
-	 *   method: 'POST',
-	 *   ip: '192.168.1.1',
-	 * });
-	 * ```
-	 */
-	addMetadata(metadata: AuditMetadata): void;
-
-	/**
-	 * Set the transaction context for audit flushing.
-	 * When set, flush() will use this transaction instead of requiring
-	 * it to be passed explicitly. This enables declarative audits to
-	 * participate in the same transaction as the handler's database operations.
-	 *
-	 * @param trx - The transaction context (e.g., Kysely Transaction)
-	 *
-	 * @example
-	 * ```typescript
-	 * // In handler with explicit transaction management
-	 * const result = await withTransaction(services.database.raw, async (trx) => {
-	 *   // Register transaction with auditor so declarative audits use it
-	 *   auditor.setTransaction(trx);
-	 *
-	 *   const user = await trx.insertInto('users').values(data).returningAll().executeTakeFirstOrThrow();
-	 *
-	 *   // Manual audits will also use this transaction when flush() is called
-	 *   auditor.audit('user.created', { userId: user.id });
-	 *
-	 *   return user;
-	 * });
-	 * // After handler, adaptor calls auditor.flush() which uses the stored transaction
-	 * ```
-	 */
-	setTransaction(trx: TTransaction): void;
-
-	/**
-	 * Get the currently set transaction context.
-	 * Returns undefined if no transaction has been set.
-	 */
-	getTransaction(): TTransaction | undefined;
-}

package/src/DefaultAuditor.ts

@@ -1,141 +0,0 @@
-import { nanoid } from 'nanoid';
-import type { Auditor } from './Auditor';
-import type { AuditStorage } from './storage';
-import type {
-	AuditActor,
-	AuditableAction,
-	AuditMetadata,
-	AuditOptions,
-	AuditRecord,
-	ExtractAuditPayload,
-	ExtractAuditType,
-} from './types';
-
-/**
- * Configuration for DefaultAuditor.
- */
-export interface DefaultAuditorConfig {
-	/** The actor performing audits (set at construction, immutable) */
-	actor: AuditActor;
-	/** Storage backend for persisting audits */
-	storage: AuditStorage;
-	/** Optional metadata to attach to all audits */
-	metadata?: AuditMetadata;
-	/** Optional custom ID generator (defaults to nanoid) */
-	generateId?: () => string;
-}
-
-/**
- * Default implementation of the Auditor interface.
- * Collects audit records in memory and flushes to storage.
- *
- * @template TAuditAction - Union of all allowed audit action types
- * @template TTransaction - Transaction type (e.g., Kysely Transaction)
- *
- * @example
- * ```typescript
- * const auditor = new DefaultAuditor<AppAuditAction>({
- *   actor: { id: 'user-123', type: 'user' },
- *   storage: auditStorage,
- *   metadata: { requestId: 'req-456', endpoint: '/users' },
- * });
- *
- * auditor.audit('user.created', { userId: '789', email: 'test@example.com' });
- *
- * // Flush inside transaction
- * await auditor.flush(trx);
- * ```
- */
-export class DefaultAuditor<
-	TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
-		string,
-		unknown
-	>,
-	TTransaction = unknown,
-> implements Auditor<TAuditAction, TTransaction>
-{
-	readonly actor: AuditActor;
-	private readonly storage: AuditStorage;
-	private metadata?: AuditMetadata;
-	private readonly generateId: () => string;
-	private records: AuditRecord[] = [];
-	private transaction?: TTransaction;
-
-	constructor(config: DefaultAuditorConfig) {
-		this.actor = config.actor;
-		this.storage = config.storage;
-		this.metadata = config.metadata;
-		this.generateId = config.generateId ?? (() => nanoid());
-	}
-
-	audit<TType extends ExtractAuditType<TAuditAction>>(
-		type: TType,
-		payload: ExtractAuditPayload<TAuditAction, TType>,
-		options?: AuditOptions,
-	): void {
-		const record: AuditRecord = {
-			id: this.generateId(),
-			type,
-			operation: options?.operation ?? 'CUSTOM',
-			table: options?.table,
-			entityId: options?.entityId,
-			oldValues: options?.oldValues,
-			newValues: options?.newValues,
-			payload,
-			timestamp: new Date(),
-			actor: this.actor,
-			metadata: this.metadata,
-		};
-
-		this.records.push(record);
-	}
-
-	record(record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>): void {
-		const fullRecord: AuditRecord = {
-			...record,
-			id: this.generateId(),
-			timestamp: new Date(),
-			actor: this.actor,
-			metadata: this.metadata
-				? { ...this.metadata, ...record.metadata }
-				: record.metadata,
-		};
-
-		this.records.push(fullRecord);
-	}
-
-	getRecords(): AuditRecord[] {
-		return [...this.records];
-	}
-
-	async flush(trx?: TTransaction): Promise<void> {
-		if (this.records.length === 0) {
-			return;
-		}
-
-		const recordsToFlush = [...this.records];
-		this.records = [];
-
-		// Use explicitly passed transaction, or fall back to stored transaction
-		const transactionToUse = trx ?? this.transaction;
-		await this.storage.write(recordsToFlush, transactionToUse);
-	}
-
-	setTransaction(trx: TTransaction): void {
-		this.transaction = trx;
-	}
-
-	getTransaction(): TTransaction | undefined {
-		return this.transaction;
-	}
-
-	clear(): void {
-		this.records = [];
-	}
-
-	addMetadata(metadata: AuditMetadata): void {
-		this.metadata = this.metadata
-			? { ...this.metadata, ...metadata }
-			: metadata;
-	}
-}

package/src/__tests__/CacheAuditStorage.spec.ts

@@ -1,382 +0,0 @@
-import { InMemoryCache } from '@geekmidas/cache/memory';
-import { beforeEach, describe, expect, it } from 'vitest';
-import { CacheAuditStorage } from '../cache';
-import type { AuditRecord } from '../types';
-
-describe('CacheAuditStorage', () => {
-	let cache: InMemoryCache;
-	let storage: CacheAuditStorage;
-
-	beforeEach(() => {
-		cache = new InMemoryCache();
-		storage = new CacheAuditStorage({ cache });
-	});
-
-	describe('write', () => {
-		it('should write records to cache', async () => {
-			const records: AuditRecord[] = [
-				{
-					id: 'audit-1',
-					type: 'user.created',
-					operation: 'INSERT',
-					table: 'users',
-					entityId: 'user-123',
-					payload: { email: 'test@example.com' },
-					timestamp: new Date('2024-01-01T00:00:00Z'),
-					actor: { id: 'admin-1', type: 'admin' },
-					metadata: { requestId: 'req-123' },
-				},
-			];
-
-			await storage.write(records);
-
-			const stored = await storage.getRecords();
-			expect(stored).toHaveLength(1);
-			expect(stored[0]).toMatchObject({
-				id: 'audit-1',
-				type: 'user.created',
-				entityId: 'user-123',
-			});
-		});
-
-		it('should append multiple records', async () => {
-			const record1: AuditRecord = {
-				id: 'audit-1',
-				type: 'user.created',
-				operation: 'INSERT',
-				timestamp: new Date('2024-01-01T00:00:00Z'),
-			};
-			const record2: AuditRecord = {
-				id: 'audit-2',
-				type: 'user.updated',
-				operation: 'UPDATE',
-				timestamp: new Date('2024-01-02T00:00:00Z'),
-			};
-
-			await storage.write([record1]);
-			await storage.write([record2]);
-
-			const stored = await storage.getRecords();
-			expect(stored).toHaveLength(2);
-		});
-
-		it('should do nothing for empty records', async () => {
-			await storage.write([]);
-
-			const records = await storage.getRecords();
-			expect(records).toHaveLength(0);
-		});
-
-		it('should serialize and deserialize dates correctly', async () => {
-			const timestamp = new Date('2024-06-15T12:30:45.123Z');
-			await storage.write([
-				{
-					id: 'audit-1',
-					type: 'test',
-					operation: 'CUSTOM',
-					timestamp,
-				},
-			]);
-
-			const records = await storage.getRecords();
-			expect(records[0].timestamp).toBeInstanceOf(Date);
-			expect(records[0].timestamp.toISOString()).toBe(timestamp.toISOString());
-		});
-	});
-
-	describe('query', () => {
-		beforeEach(async () => {
-			await storage.write([
-				{
-					id: 'audit-1',
-					type: 'user.created',
-					operation: 'INSERT',
-					table: 'users',
-					entityId: 'user-123',
-					payload: { email: 'test@example.com' },
-					timestamp: new Date('2024-01-01T00:00:00Z'),
-					actor: { id: 'admin-1', type: 'admin' },
-				},
-				{
-					id: 'audit-2',
-					type: 'user.updated',
-					operation: 'UPDATE',
-					table: 'users',
-					entityId: 'user-123',
-					timestamp: new Date('2024-01-02T00:00:00Z'),
-					actor: { id: 'admin-1', type: 'admin' },
-				},
-				{
-					id: 'audit-3',
-					type: 'order.placed',
-					operation: 'INSERT',
-					table: 'orders',
-					entityId: 'order-456',
-					timestamp: new Date('2024-01-03T00:00:00Z'),
-					actor: { id: 'user-1', type: 'user' },
-				},
-			]);
-		});
-
-		it('should return all records when no filters', async () => {
-			const results = await storage.query({});
-			expect(results).toHaveLength(3);
-		});
-
-		it('should filter by type (string)', async () => {
-			const results = await storage.query({ type: 'user.created' });
-			expect(results).toHaveLength(1);
-			expect(results[0].id).toBe('audit-1');
-		});
-
-		it('should filter by type (array)', async () => {
-			const results = await storage.query({
-				type: ['user.created', 'user.updated'],
-			});
-			expect(results).toHaveLength(2);
-		});
-
-		it('should filter by entityId (string)', async () => {
-			const results = await storage.query({ entityId: 'user-123' });
-			expect(results).toHaveLength(2);
-		});
-
-		it('should filter by entityId (object)', async () => {
-			await storage.write([
-				{
-					id: 'audit-4',
-					type: 'relation.created',
-					operation: 'INSERT',
-					entityId: { userId: 'u1', roleId: 'r1' },
-					timestamp: new Date('2024-01-04T00:00:00Z'),
-				},
-			]);
-
-			const results = await storage.query({
-				entityId: { userId: 'u1', roleId: 'r1' },
-			});
-			expect(results).toHaveLength(1);
-			expect(results[0].id).toBe('audit-4');
-		});
-
-		it('should filter by table', async () => {
-			const results = await storage.query({ table: 'users' });
-			expect(results).toHaveLength(2);
-		});
-
-		it('should filter by actorId', async () => {
-			const results = await storage.query({ actorId: 'user-1' });
-			expect(results).toHaveLength(1);
-			expect(results[0].id).toBe('audit-3');
-		});
-
-		it('should filter by date range (from)', async () => {
-			const results = await storage.query({
-				from: new Date('2024-01-02T00:00:00Z'),
-			});
-			expect(results).toHaveLength(2);
-		});
-
-		it('should filter by date range (to)', async () => {
-			const results = await storage.query({
-				to: new Date('2024-01-02T00:00:00Z'),
-			});
-			expect(results).toHaveLength(2);
-		});
-
-		it('should filter by date range (from and to)', async () => {
-			const results = await storage.query({
-				from: new Date('2024-01-02T00:00:00Z'),
-				to: new Date('2024-01-02T00:00:00Z'),
-			});
-			expect(results).toHaveLength(1);
-			expect(results[0].id).toBe('audit-2');
-		});
-
-		it('should apply pagination (limit)', async () => {
-			const results = await storage.query({ limit: 2 });
-			expect(results).toHaveLength(2);
-		});
-
-		it('should apply pagination (offset)', async () => {
-			const results = await storage.query({ offset: 1 });
-			expect(results).toHaveLength(2);
-		});
-
-		it('should apply pagination (limit and offset)', async () => {
-			const results = await storage.query({ limit: 1, offset: 1 });
-			expect(results).toHaveLength(1);
-		});
-
-		it('should order by timestamp desc by default', async () => {
-			const results = await storage.query({});
-			expect(results[0].id).toBe('audit-3'); // Most recent first
-			expect(results[2].id).toBe('audit-1'); // Oldest last
-		});
-
-		it('should order by timestamp asc', async () => {
-			const results = await storage.query({
-				orderBy: 'timestamp',
-				orderDirection: 'asc',
-			});
-			expect(results[0].id).toBe('audit-1'); // Oldest first
-			expect(results[2].id).toBe('audit-3'); // Most recent last
-		});
-
-		it('should order by type', async () => {
-			const results = await storage.query({
-				orderBy: 'type',
-				orderDirection: 'asc',
-			});
-			expect(results[0].type).toBe('order.placed');
-			expect(results[2].type).toBe('user.updated');
-		});
-
-		it('should combine multiple filters', async () => {
-			const results = await storage.query({
-				table: 'users',
-				actorId: 'admin-1',
-			});
-			expect(results).toHaveLength(2);
-		});
-	});
-
-	describe('count', () => {
-		beforeEach(async () => {
-			await storage.write([
-				{
-					id: 'audit-1',
-					type: 'user.created',
-					operation: 'INSERT',
-					timestamp: new Date(),
-					actor: { id: 'admin-1', type: 'admin' },
-				},
-				{
-					id: 'audit-2',
-					type: 'user.updated',
-					operation: 'UPDATE',
-					timestamp: new Date(),
-					actor: { id: 'admin-1', type: 'admin' },
-				},
-				{
-					id: 'audit-3',
-					type: 'order.placed',
-					operation: 'INSERT',
-					timestamp: new Date(),
-					actor: { id: 'user-1', type: 'user' },
-				},
-			]);
-		});
-
-		it('should count all records', async () => {
-			const count = await storage.count({});
-			expect(count).toBe(3);
-		});
-
-		it('should count with type filter', async () => {
-			const count = await storage.count({ type: 'user.created' });
-			expect(count).toBe(1);
-		});
-
-		it('should count with actor filter', async () => {
-			const count = await storage.count({ actorId: 'admin-1' });
-			expect(count).toBe(2);
-		});
-	});
-
-	describe('clear', () => {
-		it('should clear all records', async () => {
-			await storage.write([
-				{
-					id: 'audit-1',
-					type: 'test',
-					operation: 'CUSTOM',
-					timestamp: new Date(),
-				},
-				{
-					id: 'audit-2',
-					type: 'test',
-					operation: 'CUSTOM',
-					timestamp: new Date(),
-				},
-			]);
-
-			let records = await storage.getRecords();
-			expect(records).toHaveLength(2);
-
-			await storage.clear();
-
-			records = await storage.getRecords();
-			expect(records).toHaveLength(0);
-		});
-	});
-
-	describe('configuration', () => {
-		it('should use custom prefix', async () => {
-			const customStorage = new CacheAuditStorage({
-				cache,
-				prefix: 'my-audit',
-			});
-
-			await customStorage.write([
-				{
-					id: 'audit-1',
-					type: 'test',
-					operation: 'CUSTOM',
-					timestamp: new Date(),
-				},
-			]);
-
-			// Check that it uses the custom prefix
-			const indexValue = await cache.get<string[]>('my-audit:__index__');
-			expect(indexValue).toContain('audit-1');
-
-			const recordValue = await cache.get('my-audit:audit-1');
-			expect(recordValue).toBeDefined();
-		});
-
-		it('should use custom TTL', async () => {
-			const ttl = 3600; // 1 hour
-			const customStorage = new CacheAuditStorage({
-				cache,
-				ttl,
-			});
-
-			await customStorage.write([
-				{
-					id: 'audit-1',
-					type: 'test',
-					operation: 'CUSTOM',
-					timestamp: new Date(),
-				},
-			]);
-
-			// Record should be retrievable
-			const records = await customStorage.getRecords();
-			expect(records).toHaveLength(1);
-		});
-	});
-
-	describe('type safety', () => {
-		it('should support generic audit action types', async () => {
-			type AppAuditAction =
-				| { type: 'user.created'; payload: { userId: string } }
-				| { type: 'order.placed'; payload: { orderId: string } };
-
-			const typedStorage = new CacheAuditStorage<AppAuditAction>({ cache });
-
-			await typedStorage.write([
-				{
-					id: 'audit-1',
-					type: 'user.created',
-					operation: 'CUSTOM',
-					timestamp: new Date(),
-					payload: { userId: '123' },
-				},
-			]);
-
-			const records = await typedStorage.getRecords();
-			expect(records).toHaveLength(1);
-		});
-	});
-});