@geekmidas/audit 0.0.8 → 0.1.0

package/src/__tests__/KyselyAuditStorage.integration.spec.ts

@@ -20,9 +20,13 @@ import { DefaultAuditor } from '../DefaultAuditor';
 import { type AuditLogTable, KyselyAuditStorage } from '../kysely';
 import type { AuditableAction } from '../types';
 
+// Use unique table names to avoid conflicts with parallel tests
+const AUDIT_TABLE = 'audit_int_logs' as const;
+const USERS_TABLE = 'audit_int_users' as const;
+
 interface TestDatabase {
-  auditLogs: AuditLogTable;
-  users: {
+  [AUDIT_TABLE]: AuditLogTable;
+  [USERS_TABLE]: {
     id: Generated<number>;
     name: string;
     email: string;
@@ -52,7 +56,7 @@ describe('KyselyAuditStorage Integration Tests', () => {
 
     // Create audit_logs table
     await db.schema
-      .createTable('auditLogs')
+      .createTable(AUDIT_TABLE)
       .ifNotExists()
       .addColumn('id', 'varchar(32)', (col) => col.primaryKey())
       .addColumn('type', 'varchar', (col) => col.notNull())
@@ -73,7 +77,7 @@ describe('KyselyAuditStorage Integration Tests', () => {
 
     // Create users table for testing audit integration
     await db.schema
-      .createTable('users')
+      .createTable(USERS_TABLE)
       .ifNotExists()
       .addColumn('id', 'serial', (col) => col.primaryKey())
       .addColumn('name', 'varchar', (col) => col.notNull())
@@ -82,20 +86,20 @@ describe('KyselyAuditStorage Integration Tests', () => {
 
     storage = new KyselyAuditStorage({
       db,
-      tableName: 'auditLogs',
+      tableName: AUDIT_TABLE,
     });
   });
 
   afterEach(async () => {
     // Clean up data after each test
-    await db.deleteFrom('auditLogs').execute();
-    await db.deleteFrom('users').execute();
+    await db.deleteFrom(AUDIT_TABLE).execute();
+    await db.deleteFrom(USERS_TABLE).execute();
   });
 
   afterAll(async () => {
     // Drop tables and close connection
-    await db.schema.dropTable('auditLogs').ifExists().execute();
-    await db.schema.dropTable('users').ifExists().execute();
+    await db.schema.dropTable(AUDIT_TABLE).ifExists().execute();
+    await db.schema.dropTable(USERS_TABLE).ifExists().execute();
     await db.destroy();
   });
 
@@ -112,7 +116,7 @@ describe('KyselyAuditStorage Integration Tests', () => {
       await auditor.flush();
 
       // Verify record was written
-      const records = await db.selectFrom('auditLogs').selectAll().execute();
+      const records = await db.selectFrom(AUDIT_TABLE).selectAll().execute();
 
       expect(records).toHaveLength(1);
       expect(records[0].type).toBe('user.created');
@@ -140,7 +144,7 @@ describe('KyselyAuditStorage Integration Tests', () => {
       await auditor.flush();
 
       const records = await db
-        .selectFrom('auditLogs')
+        .selectFrom(AUDIT_TABLE)
         .selectAll()
         .orderBy('timestamp', 'asc')
         .execute();
@@ -162,7 +166,7 @@ describe('KyselyAuditStorage Integration Tests', () => {
       await db.transaction().execute(async (trx) => {
         // Insert user
         const user = await trx
-          .insertInto('users')
+          .insertInto(USERS_TABLE)
           .values({ name: 'Test User', email: 'test@example.com' })
           .returningAll()
           .executeTakeFirstOrThrow();
@@ -179,8 +183,8 @@ describe('KyselyAuditStorage Integration Tests', () => {
       });
 
       // Verify both user and audit record exist
-      const users = await db.selectFrom('users').selectAll().execute();
-      const audits = await db.selectFrom('auditLogs').selectAll().execute();
+      const users = await db.selectFrom(USERS_TABLE).selectAll().execute();
+      const audits = await db.selectFrom(AUDIT_TABLE).selectAll().execute();
 
       expect(users).toHaveLength(1);
       expect(audits).toHaveLength(1);
@@ -198,7 +202,7 @@ describe('KyselyAuditStorage Integration Tests', () => {
       const transactionPromise = db.transaction().execute(async (trx) => {
         // Insert user
         const user = await trx
-          .insertInto('users')
+          .insertInto(USERS_TABLE)
           .values({ name: 'Rollback User', email: 'rollback@example.com' })
           .returningAll()
           .executeTakeFirstOrThrow();
@@ -218,8 +222,8 @@ describe('KyselyAuditStorage Integration Tests', () => {
       );
 
       // Verify both user and audit record were rolled back
-      const users = await db.selectFrom('users').selectAll().execute();
-      const audits = await db.selectFrom('auditLogs').selectAll().execute();
+      const users = await db.selectFrom(USERS_TABLE).selectAll().execute();
+      const audits = await db.selectFrom(AUDIT_TABLE).selectAll().execute();
 
       expect(users).toHaveLength(0);
       expect(audits).toHaveLength(0);
@@ -374,7 +378,7 @@ describe('KyselyAuditStorage Integration Tests', () => {
       });
 
       const user = await db
-        .insertInto('users')
+        .insertInto(USERS_TABLE)
         .values({ name: 'John Doe', email: 'john@example.com' })
         .returningAll()
         .executeTakeFirstOrThrow();
@@ -399,7 +403,7 @@ describe('KyselyAuditStorage Integration Tests', () => {
       });
 
       await db
-        .updateTable('users')
+        .updateTable(USERS_TABLE)
         .set({ name: 'John Smith' })
         .where('id', '=', user.id)
         .execute();
@@ -424,7 +428,7 @@ describe('KyselyAuditStorage Integration Tests', () => {
         metadata: { endpoint: '/users/1', method: 'DELETE' },
       });
 
-      await db.deleteFrom('users').where('id', '=', user.id).execute();
+      await db.deleteFrom(USERS_TABLE).where('id', '=', user.id).execute();
 
       deleteAuditor.audit(
         'user.deleted',

package/src/cache.ts

@@ -0,0 +1,263 @@
+import type { Cache } from '@geekmidas/cache';
+import type { AuditQueryOptions, AuditStorage } from './storage';
+import type { AuditRecord, AuditableAction } from './types';
+
+/**
+ * Configuration for CacheAuditStorage.
+ */
+export interface CacheAuditStorageConfig {
+  /** Cache instance to use for storage */
+  cache: Cache;
+  /**
+   * Key prefix for audit records.
+   * Records are stored as `${prefix}:${id}`.
+   * @default 'audit'
+   */
+  prefix?: string;
+  /**
+   * TTL (time-to-live) in seconds for audit records.
+   * If not set, records use the cache's default TTL.
+   */
+  ttl?: number;
+}
+
+/**
+ * Cache-based audit storage implementation.
+ * Uses any @geekmidas/cache implementation for storage.
+ *
+ * Best suited for:
+ * - Development and testing
+ * - Temporary audit logs that don't need persistence
+ * - Applications with existing cache infrastructure
+ * - Distributed systems needing shared audit state (with Redis/Upstash)
+ *
+ * Note: Query performance may degrade with large numbers of records
+ * since filtering happens in memory after fetching all records.
+ *
+ * @template TAuditAction - Optional type parameter for type-safe audit actions.
+ *
+ * @example
+ * ```typescript
+ * import { CacheAuditStorage } from '@geekmidas/audit/cache';
+ * import { InMemoryCache } from '@geekmidas/cache/memory';
+ * import { UpstashCache } from '@geekmidas/cache/upstash';
+ *
+ * // With in-memory cache (development/testing)
+ * const storage = new CacheAuditStorage({
+ *   cache: new InMemoryCache(),
+ *   ttl: 86400, // 24 hours
+ * });
+ *
+ * // With Upstash Redis (production)
+ * const storage = new CacheAuditStorage({
+ *   cache: new UpstashCache({
+ *     url: process.env.UPSTASH_REDIS_URL,
+ *     token: process.env.UPSTASH_REDIS_TOKEN,
+ *   }),
+ *   ttl: 604800, // 7 days
+ * });
+ * ```
+ */
+export class CacheAuditStorage<
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+> implements AuditStorage<TAuditAction>
+{
+  private readonly cache: Cache;
+  private readonly prefix: string;
+  private readonly ttl?: number;
+  private readonly indexKey: string;
+
+  constructor(config: CacheAuditStorageConfig) {
+    this.cache = config.cache;
+    this.prefix = config.prefix ?? 'audit';
+    this.ttl = config.ttl;
+    this.indexKey = `${this.prefix}:__index__`;
+  }
+
+  /**
+   * Write audit records to cache.
+   */
+  async write(records: AuditRecord[]): Promise<void> {
+    if (records.length === 0) {
+      return;
+    }
+
+    // Get existing index
+    const existingIds = (await this.cache.get<string[]>(this.indexKey)) ?? [];
+    const newIds: string[] = [];
+
+    // Write each record
+    for (const record of records) {
+      const key = this.getRecordKey(record.id);
+      // Serialize Date to ISO string for cache storage
+      const serialized = this.serializeRecord(record);
+      await this.cache.set(key, serialized, this.ttl);
+      newIds.push(record.id);
+    }
+
+    // Update index with new IDs
+    const updatedIds = [...existingIds, ...newIds];
+    await this.cache.set(this.indexKey, updatedIds, this.ttl);
+  }
+
+  /**
+   * Query audit records from cache.
+   */
+  async query(options: AuditQueryOptions): Promise<AuditRecord[]> {
+    const allRecords = await this.getAllRecords();
+    let results = this.applyFilters(allRecords, options);
+
+    // Ordering
+    const orderBy = options.orderBy ?? 'timestamp';
+    const orderDirection = options.orderDirection ?? 'desc';
+    results.sort((a, b) => {
+      const aValue = orderBy === 'timestamp' ? a.timestamp.getTime() : a.type;
+      const bValue = orderBy === 'timestamp' ? b.timestamp.getTime() : b.type;
+      if (aValue < bValue) return orderDirection === 'asc' ? -1 : 1;
+      if (aValue > bValue) return orderDirection === 'asc' ? 1 : -1;
+      return 0;
+    });
+
+    // Pagination
+    if (options.offset !== undefined) {
+      results = results.slice(options.offset);
+    }
+    if (options.limit !== undefined) {
+      results = results.slice(0, options.limit);
+    }
+
+    return results;
+  }
+
+  /**
+   * Count audit records matching filters.
+   */
+  async count(
+    options: Omit<AuditQueryOptions, 'limit' | 'offset'>,
+  ): Promise<number> {
+    const allRecords = await this.getAllRecords();
+    return this.applyFilters(allRecords, options).length;
+  }
+
+  /**
+   * Get all stored records (for testing/debugging).
+   */
+  async getRecords(): Promise<AuditRecord[]> {
+    return this.getAllRecords();
+  }
+
+  /**
+   * Clear all stored records.
+   */
+  async clear(): Promise<void> {
+    const ids = (await this.cache.get<string[]>(this.indexKey)) ?? [];
+
+    // Delete all records
+    for (const id of ids) {
+      await this.cache.delete(this.getRecordKey(id));
+    }
+
+    // Delete index
+    await this.cache.delete(this.indexKey);
+  }
+
+  private getRecordKey(id: string): string {
+    return `${this.prefix}:${id}`;
+  }
+
+  private async getAllRecords(): Promise<AuditRecord[]> {
+    const ids = (await this.cache.get<string[]>(this.indexKey)) ?? [];
+    const records: AuditRecord[] = [];
+    const validIds: string[] = [];
+
+    for (const id of ids) {
+      const key = this.getRecordKey(id);
+      const serialized = await this.cache.get<SerializedAuditRecord>(key);
+      if (serialized) {
+        records.push(this.deserializeRecord(serialized));
+        validIds.push(id);
+      }
+    }
+
+    // Clean up index if some records expired
+    if (validIds.length !== ids.length) {
+      await this.cache.set(this.indexKey, validIds, this.ttl);
+    }
+
+    return records;
+  }
+
+  private serializeRecord(record: AuditRecord): SerializedAuditRecord {
+    return {
+      ...record,
+      timestamp: record.timestamp.toISOString(),
+    };
+  }
+
+  private deserializeRecord(serialized: SerializedAuditRecord): AuditRecord {
+    return {
+      ...serialized,
+      timestamp: new Date(serialized.timestamp),
+    };
+  }
+
+  private applyFilters(
+    records: AuditRecord[],
+    options: AuditQueryOptions,
+  ): AuditRecord[] {
+    return records.filter((record) => {
+      // Type filter
+      if (options.type !== undefined) {
+        if (Array.isArray(options.type)) {
+          if (!options.type.includes(record.type)) return false;
+        } else {
+          if (record.type !== options.type) return false;
+        }
+      }
+
+      // Entity ID filter
+      if (options.entityId !== undefined) {
+        const entityId =
+          typeof options.entityId === 'string'
+            ? options.entityId
+            : JSON.stringify(options.entityId);
+        const recordEntityId =
+          typeof record.entityId === 'string'
+            ? record.entityId
+            : JSON.stringify(record.entityId);
+        if (recordEntityId !== entityId) return false;
+      }
+
+      // Table filter
+      if (options.table !== undefined) {
+        if (record.table !== options.table) return false;
+      }
+
+      // Actor ID filter
+      if (options.actorId !== undefined) {
+        if (record.actor?.id !== options.actorId) return false;
+      }
+
+      // Date range filters
+      if (options.from !== undefined) {
+        if (record.timestamp < options.from) return false;
+      }
+      if (options.to !== undefined) {
+        if (record.timestamp > options.to) return false;
+      }
+
+      return true;
+    });
+  }
+}
+
+/**
+ * Serialized version of AuditRecord for cache storage.
+ * Dates are stored as ISO strings.
+ */
+type SerializedAuditRecord = Omit<AuditRecord, 'timestamp'> & {
+  timestamp: string;
+};

package/src/kysely.ts

@@ -286,6 +286,39 @@ export class KyselyAuditStorage<DB> implements AuditStorage {
     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) {

package/src/memory.ts

@@ -0,0 +1,50 @@
+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

@@ -125,4 +125,51 @@ export interface AuditStorage<
    * ```
    */
   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>;
 }