@geekmidas/audit 0.0.8 → 0.2.0

package/src/Auditor.ts

@@ -1,11 +1,11 @@
 import type {
-  AuditActor,
-  AuditMetadata,
-  AuditOptions,
-  AuditRecord,
-  AuditableAction,
-  ExtractAuditPayload,
-  ExtractAuditType,
+	AuditActor,
+	AuditableAction,
+	AuditMetadata,
+	AuditOptions,
+	AuditRecord,
+	ExtractAuditPayload,
+	ExtractAuditType,
 } from './types';
 
 /**
@@ -31,127 +31,127 @@ import type {
  * ```
  */
 export interface Auditor<
-  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
-    string,
-    unknown
-  >,
-  TTransaction = unknown,
+	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;
+	/**
+	 * 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 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;
+	/**
+	 * 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[];
+	/**
+	 * 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>;
+	/**
+	 * 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;
+	/**
+	 * 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;
+	/**
+	 * 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;
+	/**
+	 * 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;
+	/**
+	 * Get the currently set transaction context.
+	 * Returns undefined if no transaction has been set.
+	 */
+	getTransaction(): TTransaction | undefined;
 }

package/src/DefaultAuditor.ts

@@ -2,27 +2,27 @@ import { nanoid } from 'nanoid';
 import type { Auditor } from './Auditor';
 import type { AuditStorage } from './storage';
 import type {
-  AuditActor,
-  AuditMetadata,
-  AuditOptions,
-  AuditRecord,
-  AuditableAction,
-  ExtractAuditPayload,
-  ExtractAuditType,
+	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;
+	/** 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;
 }
 
 /**
@@ -47,95 +47,95 @@ export interface DefaultAuditorConfig {
  * ```
  */
 export class DefaultAuditor<
-  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
-    string,
-    unknown
-  >,
-  TTransaction = unknown,
+	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;
+	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());
-  }
+	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,
-    };
+	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);
-  }
+		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,
-    };
+	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);
-  }
+		this.records.push(fullRecord);
+	}
 
-  getRecords(): AuditRecord[] {
-    return [...this.records];
-  }
+	getRecords(): AuditRecord[] {
+		return [...this.records];
+	}
 
-  async flush(trx?: TTransaction): Promise<void> {
-    if (this.records.length === 0) {
-      return;
-    }
+	async flush(trx?: TTransaction): Promise<void> {
+		if (this.records.length === 0) {
+			return;
+		}
 
-    const recordsToFlush = [...this.records];
-    this.records = [];
+		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);
-  }
+		// 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;
-  }
+	setTransaction(trx: TTransaction): void {
+		this.transaction = trx;
+	}
 
-  getTransaction(): TTransaction | undefined {
-    return this.transaction;
-  }
+	getTransaction(): TTransaction | undefined {
+		return this.transaction;
+	}
 
-  clear(): void {
-    this.records = [];
-  }
+	clear(): void {
+		this.records = [];
+	}
 
-  addMetadata(metadata: AuditMetadata): void {
-    this.metadata = this.metadata
-      ? { ...this.metadata, ...metadata }
-      : metadata;
-  }
+	addMetadata(metadata: AuditMetadata): void {
+		this.metadata = this.metadata
+			? { ...this.metadata, ...metadata }
+			: metadata;
+	}
 }