@geekmidas/audit 9.0.2 → 10.0.0-alpha.1

package/src/kysely.ts

@@ -1,424 +0,0 @@
-import type {
-	ControlledTransaction,
-	IsolationLevel,
-	Kysely,
-	Transaction,
-} from 'kysely';
-import { nanoid } from 'nanoid';
-import type {
-	AuditQueryOptions,
-	AuditStorage,
-	TransactionAwareAuditor,
-} from './storage';
-import type { AuditRecord } from './types';
-
-export type { TransactionAwareAuditor };
-
-export interface TransactionSettings {
-	isolationLevel?: IsolationLevel;
-}
-
-export type DatabaseConnection<T> =
-	| ControlledTransaction<T>
-	| Kysely<T>
-	| Transaction<T>;
-
-/**
- * Execute a callback within a database transaction with automatic audit handling.
- *
- * This wrapper ensures that:
- * 1. The transaction is automatically registered with the auditor
- * 2. Manual audits (via `auditor.audit()`) are flushed BEFORE the transaction commits
- * 3. If audit flush fails, the entire transaction rolls back
- * 4. If the callback fails, audits are NOT written (atomic consistency)
- *
- * **Note:** Declarative audits (defined via `.audit([...])` on the endpoint builder)
- * are processed AFTER the handler returns, so they run outside this transaction.
- * If you need all audits to be atomic with your database operations, use manual
- * audits via `auditor.audit()` inside this wrapper.
- *
- * @param db - Database connection (Kysely, Transaction, or ControlledTransaction)
- * @param auditor - Auditor instance that will receive the transaction
- * @param cb - Callback to execute within the transaction
- * @param settings - Optional transaction settings (isolation level)
- * @returns The result of the callback
- *
- * @example
- * ```typescript
- * import { withAuditableTransaction } from '@geekmidas/audit/kysely';
- *
- * const result = await withAuditableTransaction(
- *   services.database,
- *   auditor,
- *   async (trx) => {
- *     const user = await trx
- *       .insertInto('users')
- *       .values(data)
- *       .returningAll()
- *       .executeTakeFirstOrThrow();
- *
- *     // Manual audits are atomic with the transaction
- *     auditor.audit('user.created', { userId: user.id, email: user.email });
- *
- *     return user;
- *   },
- * );
- * // Audits are automatically flushed inside the transaction before commit
- * ```
- */
-export async function withAuditableTransaction<DB, T>(
-	db: DatabaseConnection<DB>,
-	auditor: TransactionAwareAuditor<Transaction<DB>>,
-	cb: (trx: Transaction<DB>) => Promise<T>,
-	settings?: TransactionSettings,
-): Promise<T> {
-	const execute = async (trx: Transaction<DB>): Promise<T> => {
-		// Register transaction with auditor
-		auditor.setTransaction(trx);
-
-		// Execute the callback
-		const result = await cb(trx);
-
-		// Flush audits BEFORE transaction commits
-		// If this fails, the transaction will roll back
-		await auditor.flush(trx);
-
-		return result;
-	};
-
-	// If already in a transaction, just run with it
-	if (db.isTransaction) {
-		return execute(db as Transaction<DB>);
-	}
-
-	const builder = db.transaction();
-
-	if (settings?.isolationLevel) {
-		return builder.setIsolationLevel(settings.isolationLevel).execute(execute);
-	}
-
-	return builder.execute(execute);
-}
-
-/**
- * Database table interface for audit records.
- * Use this to define your audit_logs table in your Kysely database schema.
- *
- * Column names use snake_case to match standard PostgreSQL conventions.
- *
- * @example
- * ```typescript
- * interface Database {
- *   audit_logs: AuditLogTable;
- *   // ... other tables
- * }
- * ```
- */
-export interface AuditLogTable {
-	id: string;
-	type: string;
-	operation: string;
-	table: string | null;
-	entityId: string | null;
-	oldValues: unknown | null;
-	newValues: unknown | null;
-	payload: unknown | null;
-	timestamp: Date;
-	actorId: string | null;
-	actorType: string | null;
-	actorData: unknown | null;
-	metadata: unknown | null;
-}
-
-/**
- * Insertable version of AuditLogTable where id is optional.
- * Use this when your database auto-generates IDs or when using autoId option.
- *
- * @example
- * ```typescript
- * interface Database {
- *   audit_logs: AuditLogTable;
- * }
- *
- * // For insertions where id is auto-generated
- * type NewAuditLog = InsertableAuditLogTable;
- * ```
- */
-export type InsertableAuditLogTable = Omit<AuditLogTable, 'id'> & {
-	id?: string;
-};
-
-/**
- * Configuration for KyselyAuditStorage.
- */
-export interface KyselyAuditStorageConfig<DB> {
-	/** Kysely database instance */
-	db: Kysely<DB>;
-	/** Table name for audit logs (must be a key in DB that extends AuditLogTable) */
-	tableName: keyof DB & string;
-	/**
-	 * Service name of the database service.
-	 * When set, endpoint adaptors will automatically use the audit transaction as `db`
-	 * in the handler context if the endpoint's database service has the same name.
-	 */
-	databaseServiceName?: string;
-	/**
-	 * Let the database auto-generate IDs (e.g., via DEFAULT gen_random_uuid()).
-	 * When true, the ID field is omitted from inserts if not provided.
-	 * When false (default), IDs are generated using nanoid if not provided.
-	 * @default false
-	 */
-	autoId?: boolean;
-}
-
-/**
- * Kysely-based audit storage implementation.
- * Stores audit records in a database table using Kysely.
- *
- * @template DB - Your Kysely database schema
- *
- * @example
- * ```typescript
- * interface Database {
- *   audit_logs: AuditLogTable;
- * }
- *
- * const storage = new KyselyAuditStorage({
- *   db: kyselyDb,
- *   tableName: 'audit_logs',
- * });
- *
- * const auditor = new DefaultAuditor({
- *   actor: { id: 'user-123', type: 'user' },
- *   storage,
- * });
- * ```
- */
-export class KyselyAuditStorage<DB> implements AuditStorage {
-	private readonly db: Kysely<DB>;
-	private readonly tableName: keyof DB & string;
-	private readonly autoId: boolean;
-	readonly databaseServiceName?: string;
-
-	constructor(config: KyselyAuditStorageConfig<DB>) {
-		this.db = config.db;
-		this.tableName = config.tableName;
-		this.databaseServiceName = config.databaseServiceName;
-		this.autoId = config.autoId ?? false;
-	}
-
-	async write(records: AuditRecord[], trx?: unknown): Promise<void> {
-		if (records.length === 0) {
-			return;
-		}
-
-		const db = (trx as Transaction<DB>) ?? this.db;
-		const rows = records.map((record) => this.toRow(record));
-
-		await (db as any).insertInto(this.tableName).values(rows).execute();
-	}
-
-	async query(options: AuditQueryOptions): Promise<AuditRecord[]> {
-		let query = (this.db as any).selectFrom(this.tableName).selectAll();
-
-		query = this.applyFilters(query, options);
-
-		// Ordering
-		const orderBy = options.orderBy ?? 'timestamp';
-		const orderDirection = options.orderDirection ?? 'desc';
-		query = query.orderBy(
-			orderBy === 'timestamp' ? 'timestamp' : 'type',
-			orderDirection,
-		);
-
-		// Pagination
-		if (options.limit !== undefined) {
-			query = query.limit(options.limit);
-		}
-		if (options.offset !== undefined) {
-			query = query.offset(options.offset);
-		}
-
-		const rows = await query.execute();
-		return rows.map((row: AuditLogTable) => this.fromRow(row));
-	}
-
-	async count(
-		options: Omit<AuditQueryOptions, 'limit' | 'offset'>,
-	): Promise<number> {
-		let query = (this.db as any)
-			.selectFrom(this.tableName)
-			.select((eb: any) => eb.fn.count('id').as('count'));
-
-		query = this.applyFilters(query, options);
-
-		const result = await query.executeTakeFirst();
-		return Number(result?.count ?? 0);
-	}
-
-	/**
-	 * Get the Kysely database instance for transactional operations.
-	 * Used by endpoint adaptors to automatically wrap handlers in transactions.
-	 */
-	getDatabase(): Kysely<DB> {
-		return this.db;
-	}
-
-	/**
-	 * Execute a callback within a Kysely transaction with automatic audit handling.
-	 * The auditor is registered with the transaction and audits are flushed
-	 * before the transaction commits.
-	 *
-	 * If the provided db connection is already a transaction, it will be reused
-	 * instead of creating a nested transaction.
-	 */
-	async withTransaction<T>(
-		auditor: TransactionAwareAuditor<Transaction<DB>>,
-		callback: () => Promise<T>,
-		db?: DatabaseConnection<DB>,
-	): Promise<T> {
-		const connection = db ?? this.db;
-
-		// If already in a transaction, reuse it
-		if (connection.isTransaction) {
-			const trx = connection as Transaction<DB>;
-			auditor.setTransaction(trx);
-			const result = await callback();
-			await auditor.flush(trx);
-			return result;
-		}
-
-		// Create new transaction
-		return connection.transaction().execute(async (trx) => {
-			auditor.setTransaction(trx);
-			const result = await callback();
-			await auditor.flush(trx);
-			return result;
-		});
-	}
-
-	private applyFilters(query: any, options: AuditQueryOptions): any {
-		// Type filter
-		if (options.type !== undefined) {
-			if (Array.isArray(options.type)) {
-				query = query.where('type', 'in', options.type);
-			} else {
-				query = query.where('type', '=', options.type);
-			}
-		}
-
-		// Entity ID filter
-		if (options.entityId !== undefined) {
-			const entityId =
-				typeof options.entityId === 'string'
-					? options.entityId
-					: JSON.stringify(options.entityId);
-			query = query.where('entityId', '=', entityId);
-		}
-
-		// Table filter
-		if (options.table !== undefined) {
-			query = query.where('table', '=', options.table);
-		}
-
-		// Actor ID filter
-		if (options.actorId !== undefined) {
-			query = query.where('actorId', '=', options.actorId);
-		}
-
-		// Date range filters
-		if (options.from !== undefined) {
-			query = query.where('timestamp', '>=', options.from);
-		}
-		if (options.to !== undefined) {
-			query = query.where('timestamp', '<=', options.to);
-		}
-
-		return query;
-	}
-
-	private toRow(record: AuditRecord): AuditLogTable {
-		// If autoId is true, let database generate ID (ignore record.id)
-		// If autoId is false (default), use record.id or generate with nanoid
-		const id = this.autoId ? undefined : record.id || nanoid();
-
-		return {
-			...(id && { id }),
-			type: record.type,
-			operation: record.operation,
-			table: record.table ?? null,
-			entityId:
-				record.entityId === undefined
-					? null
-					: typeof record.entityId === 'string'
-						? record.entityId
-						: JSON.stringify(record.entityId),
-			oldValues: record.oldValues ?? null,
-			newValues: record.newValues ?? null,
-			payload: record.payload ?? null,
-			timestamp: record.timestamp,
-			actorId: record.actor?.id ?? null,
-			actorType: record.actor?.type ?? null,
-			actorData:
-				record.actor !== undefined ? this.getActorData(record.actor) : null,
-			metadata: record.metadata ?? null,
-		} as AuditLogTable;
-	}
-
-	private fromRow(row: AuditLogTable): AuditRecord {
-		const actor =
-			row.actorId !== null || row.actorType !== null
-				? {
-						id: row.actorId ?? undefined,
-						type: row.actorType ?? undefined,
-						...(row.actorData ? this.parseJson(row.actorData) : {}),
-					}
-				: undefined;
-
-		return {
-			id: row.id,
-			type: row.type,
-			operation: row.operation as AuditRecord['operation'],
-			table: row.table ?? undefined,
-			entityId: row.entityId ? this.parseEntityId(row.entityId) : undefined,
-			oldValues: row.oldValues ? this.parseJson(row.oldValues) : undefined,
-			newValues: row.newValues ? this.parseJson(row.newValues) : undefined,
-			payload: row.payload ? this.parseJson(row.payload) : undefined,
-			timestamp: row.timestamp,
-			actor,
-			metadata: row.metadata ? this.parseJson(row.metadata) : undefined,
-		};
-	}
-
-	/**
-	 * Parse a JSON value that may already be parsed (e.g., from jsonb columns).
-	 */
-	private parseJson(value: unknown): Record<string, unknown> {
-		if (typeof value === 'object' && value !== null) {
-			return value as Record<string, unknown>;
-		}
-		if (typeof value === 'string') {
-			return JSON.parse(value);
-		}
-		return {};
-	}
-
-	private getActorData(
-		actor: NonNullable<AuditRecord['actor']>,
-	): Record<string, unknown> {
-		const { id, type, ...rest } = actor;
-		return rest;
-	}
-
-	private parseEntityId(entityId: string): string | Record<string, unknown> {
-		try {
-			const parsed = JSON.parse(entityId);
-			if (typeof parsed === 'object' && parsed !== null) {
-				return parsed;
-			}
-			return entityId;
-		} catch {
-			return entityId;
-		}
-	}
-}

package/src/memory.ts

@@ -1,50 +0,0 @@
-import { InMemoryCache } from '@geekmidas/cache/memory';
-import { CacheAuditStorage } from './cache';
-import type { AuditableAction } from './types';
-
-/**
- * In-memory audit storage implementation.
- * Convenience wrapper around CacheAuditStorage with InMemoryCache.
- *
- * Useful for testing, development, and applications that don't need persistent audit logs.
- *
- * @template TAuditAction - Optional type parameter for type-safe audit actions.
- *
- * @example
- * ```typescript
- * import { InMemoryAuditStorage } from '@geekmidas/audit/memory';
- * import { DefaultAuditor } from '@geekmidas/audit';
- *
- * const storage = new InMemoryAuditStorage();
- * const auditor = new DefaultAuditor({
- *   actor: { id: 'user-123', type: 'user' },
- *   storage,
- * });
- *
- * auditor.audit('user.created', { userId: '789', email: 'test@example.com' });
- * await auditor.flush();
- *
- * // Query stored records
- * const records = await storage.query({ type: 'user.created' });
- *
- * // Get all records (for testing)
- * const all = await storage.getRecords();
- *
- * // Clear for next test
- * await storage.clear();
- * ```
- */
-export class InMemoryAuditStorage<
-	TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
-		string,
-		unknown
-	>,
-> extends CacheAuditStorage<TAuditAction> {
-	constructor() {
-		super({
-			cache: new InMemoryCache(),
-			// Use a long TTL since in-memory cache expires items
-			ttl: 86400 * 365, // 1 year
-		});
-	}
-}

package/src/storage.ts

@@ -1,203 +0,0 @@
-import type { AuditableAction, AuditRecord } from './types';
-
-/**
- * Minimal interface for transaction-aware audit flushing.
- * Use this when you need to flush audits within a database transaction.
- *
- * @template TTransaction - Transaction type (e.g., Kysely `Transaction`, Knex `Transaction`)
- *
- * @example
- * ```typescript
- * import { withAuditableTransaction } from '@geekmidas/audit/kysely';
- * import type { TransactionAwareAuditor } from '@geekmidas/audit/kysely';
- *
- * const result = await withAuditableTransaction(
- *   db,
- *   auditor as TransactionAwareAuditor<Transaction<DB>>,
- *   async (trx) => {
- *     // Your transactional operations
- *     return result;
- *   },
- * );
- * ```
- */
-export interface TransactionAwareAuditor<TTransaction = unknown> {
-	/** Register the transaction with the auditor for use during flush */
-	setTransaction(trx: TTransaction): void;
-	/** Flush all pending audits, optionally within a transaction */
-	flush(trx?: TTransaction): Promise<void>;
-}
-
-/**
- * Options for querying audit records.
- */
-export interface AuditQueryOptions {
-	/** Filter by audit type */
-	type?: string | string[];
-	/** Filter by entity ID */
-	entityId?: string | Record<string, unknown>;
-	/** Filter by table name */
-	table?: string;
-	/** Filter by actor ID */
-	actorId?: string;
-	/** Filter by date range (start) */
-	from?: Date;
-	/** Filter by date range (end) */
-	to?: Date;
-	/** Limit number of results */
-	limit?: number;
-	/** Offset for pagination */
-	offset?: number;
-	/** Sort order */
-	orderBy?: 'timestamp' | 'type';
-	/** Sort direction */
-	orderDirection?: 'asc' | 'desc';
-}
-
-/**
- * Interface for audit storage backends.
- * Implement this to store audits in your preferred location.
- *
- * @example
- * ```typescript
- * // Same database storage (recommended for transactions)
- * const auditStorage: AuditStorage = {
- *   async write(records, trx) {
- *     const db = trx ?? getDatabase();
- *     await db.insertInto('audit_logs').values(records).execute();
- *   },
- * };
- *
- * // External audit service
- * const externalAuditStorage: AuditStorage = {
- *   async write(records) {
- *     await fetch('https://audit.example.com/api/audits', {
- *       method: 'POST',
- *       body: JSON.stringify({ records }),
- *     });
- *   },
- * };
- * ```
- *
- * @template TAuditAction - Optional type parameter for type-safe audit actions.
- *   When provided, this type is preserved in the Service definition and can be
- *   extracted by EndpointBuilder to provide type inference for `.audit([...])`.
- */
-export interface AuditStorage<
-	TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
-		string,
-		unknown
-	>,
-> {
-	/** @internal Type marker for extracting audit action type */
-	readonly __auditActionType?: TAuditAction;
-	/**
-	 * Write audit records to storage.
-	 * Called by Auditor.flush() to persist collected audits.
-	 *
-	 * @param records - The audit records to write
-	 * @param trx - Optional transaction context (for same-DB storage)
-	 */
-	write(records: AuditRecord[], trx?: unknown): Promise<void>;
-
-	/**
-	 * Optional: Query audit records for retrieval.
-	 * Implement this for audit log viewing/searching.
-	 *
-	 * @param options - Query filters and pagination
-	 * @returns Matching audit records
-	 */
-	query?(options: AuditQueryOptions): Promise<AuditRecord[]>;
-
-	/**
-	 * Optional: Count audit records matching filters.
-	 * Useful for pagination.
-	 *
-	 * @param options - Query filters (limit/offset ignored)
-	 * @returns Count of matching records
-	 */
-	count?(options: Omit<AuditQueryOptions, 'limit' | 'offset'>): Promise<number>;
-
-	/**
-	 * Optional: Get the database connection for transactional audit writes.
-	 * When implemented, the endpoint adaptor can automatically wrap handlers
-	 * in a transaction, ensuring audits are atomic with other database operations.
-	 *
-	 * @returns Database connection (e.g., Kysely instance)
-	 *
-	 * @example
-	 * ```typescript
-	 * class KyselyAuditStorage implements AuditStorage {
-	 *   constructor(private db: Kysely<DB>) {}
-	 *
-	 *   getDatabase() {
-	 *     return this.db;
-	 *   }
-	 * }
-	 * ```
-	 */
-	getDatabase?(): unknown;
-
-	/**
-	 * Optional: The service name of the database service used by this storage.
-	 * When set, endpoint adaptors will automatically use the audit transaction as `db`
-	 * in the handler context if the endpoint's database service has the same name.
-	 *
-	 * @example
-	 * ```typescript
-	 * const storage = new KyselyAuditStorage({
-	 *   db,
-	 *   tableName: 'audit_logs',
-	 *   databaseServiceName: 'database', // Matches databaseService.serviceName
-	 * });
-	 * ```
-	 */
-	databaseServiceName?: string;
-
-	/**
-	 * Optional: Execute a callback within a database transaction.
-	 * The auditor is registered with the transaction and audits are flushed
-	 * before the transaction commits.
-	 *
-	 * This is database-agnostic - each storage implementation provides its own
-	 * transaction handling based on the underlying database.
-	 *
-	 * If a database connection is provided, it should be used instead of the
-	 * storage's internal connection. If the connection is already a transaction,
-	 * it should be reused instead of creating a nested transaction.
-	 *
-	 * @param auditor - The auditor to register with the transaction
-	 * @param callback - The callback to execute within the transaction
-	 * @param db - Optional database connection (may already be a transaction)
-	 * @returns The result of the callback
-	 *
-	 * @example
-	 * ```typescript
-	 * // KyselyAuditStorage implementation
-	 * async withTransaction<T>(auditor, callback, db) {
-	 *   const connection = db ?? this.db;
-	 *   if (connection.isTransaction) {
-	 *     // Reuse existing transaction
-	 *     auditor.setTransaction(connection);
-	 *     const result = await callback();
-	 *     await auditor.flush(connection);
-	 *     return result;
-	 *   }
-	 *   return connection.transaction().execute(async (trx) => {
-	 *     auditor.setTransaction(trx);
-	 *     const result = await callback();
-	 *     await auditor.flush(trx);
-	 *     return result;
-	 *   });
-	 * }
-	 * ```
-	 */
-	withTransaction?<T>(
-		auditor: {
-			setTransaction(trx: unknown): void;
-			flush(trx?: unknown): Promise<void>;
-		},
-		callback: () => Promise<T>,
-		db?: unknown,
-	): Promise<T>;
-}