@geekmidas/audit 0.0.8 → 0.2.0

package/src/storage.ts

@@ -1,29 +1,29 @@
-import type { AuditRecord, AuditableAction } from './types';
+import type { AuditableAction, AuditRecord } from './types';
 
 /**
  * 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';
+	/** 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';
 }
 
 /**
@@ -56,73 +56,120 @@ export interface AuditQueryOptions {
  *   extracted by EndpointBuilder to provide type inference for `.audit([...])`.
  */
 export interface AuditStorage<
-  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
-    string,
-    unknown
-  >,
+	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>;
+	/** @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: 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: 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: 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: 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>;
 }

package/src/types.ts

@@ -17,22 +17,22 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
  * ```
  */
 export type AuditableAction<TType extends string, TPayload = unknown> = {
-  type: TType;
-  payload: TPayload;
+	type: TType;
+	payload: TPayload;
 };
 
 /**
  * Extract the type string from an AuditableAction union.
  */
 export type ExtractAuditType<T extends AuditableAction<string, unknown>> =
-  T extends AuditableAction<infer TType, unknown> ? TType : never;
+	T extends AuditableAction<infer TType, unknown> ? TType : never;
 
 /**
  * Extract the payload for a specific audit type from an AuditableAction union.
  */
 export type ExtractAuditPayload<
-  T extends AuditableAction<string, unknown>,
-  TType extends ExtractAuditType<T>,
+	T extends AuditableAction<string, unknown>,
+	TType extends ExtractAuditType<T>,
 > = T extends AuditableAction<TType, infer TPayload> ? TPayload : never;
 
 /**
@@ -44,74 +44,74 @@ export type AuditOperation = 'INSERT' | 'UPDATE' | 'DELETE' | 'CUSTOM';
  * Represents the actor who performed an audited action.
  */
 export interface AuditActor {
-  /** Unique identifier for the actor (user ID, service ID, etc.) */
-  id?: string;
-  /** Type of actor ('user', 'system', 'service', etc.) */
-  type?: string;
-  /** Additional actor properties */
-  [key: string]: unknown;
+	/** Unique identifier for the actor (user ID, service ID, etc.) */
+	id?: string;
+	/** Type of actor ('user', 'system', 'service', etc.) */
+	type?: string;
+	/** Additional actor properties */
+	[key: string]: unknown;
 }
 
 /**
  * Metadata associated with an audit record.
  */
 export interface AuditMetadata {
-  /** Request correlation ID */
-  requestId?: string;
-  /** Which endpoint was called */
-  endpoint?: string;
-  /** HTTP method */
-  method?: string;
-  /** Client IP address */
-  ip?: string;
-  /** Client user agent */
-  userAgent?: string;
-  /** Additional metadata */
-  [key: string]: unknown;
+	/** Request correlation ID */
+	requestId?: string;
+	/** Which endpoint was called */
+	endpoint?: string;
+	/** HTTP method */
+	method?: string;
+	/** Client IP address */
+	ip?: string;
+	/** Client user agent */
+	userAgent?: string;
+	/** Additional metadata */
+	[key: string]: unknown;
 }
 
 /**
  * A complete audit record representing a tracked action.
  */
 export interface AuditRecord<TPayload = unknown> {
-  /** Unique identifier for this audit record */
-  id: string;
-  /** Audit type (e.g., 'user.created', 'order.placed') */
-  type: string;
-  /** Operation type for database audits */
-  operation: AuditOperation;
-  /** Database table name (for database operations) */
-  table?: string;
-  /** Entity primary key(s) */
-  entityId?: string | Record<string, unknown>;
-  /** Previous state (for UPDATE/DELETE) */
-  oldValues?: Record<string, unknown>;
-  /** New state (for INSERT/UPDATE) */
-  newValues?: Record<string, unknown>;
-  /** Custom payload (for CUSTOM operations) */
-  payload?: TPayload;
-  /** When the audit was recorded */
-  timestamp: Date;
-  /** Who performed the action */
-  actor?: AuditActor;
-  /** Request context */
-  metadata?: AuditMetadata;
+	/** Unique identifier for this audit record */
+	id: string;
+	/** Audit type (e.g., 'user.created', 'order.placed') */
+	type: string;
+	/** Operation type for database audits */
+	operation: AuditOperation;
+	/** Database table name (for database operations) */
+	table?: string;
+	/** Entity primary key(s) */
+	entityId?: string | Record<string, unknown>;
+	/** Previous state (for UPDATE/DELETE) */
+	oldValues?: Record<string, unknown>;
+	/** New state (for INSERT/UPDATE) */
+	newValues?: Record<string, unknown>;
+	/** Custom payload (for CUSTOM operations) */
+	payload?: TPayload;
+	/** When the audit was recorded */
+	timestamp: Date;
+	/** Who performed the action */
+	actor?: AuditActor;
+	/** Request context */
+	metadata?: AuditMetadata;
 }
 
 /**
  * Options for manual audit calls.
  */
 export interface AuditOptions {
-  /** Entity primary key(s) for easier querying */
-  entityId?: string | Record<string, unknown>;
-  /** Database table name */
-  table?: string;
-  /** Operation type (defaults to 'CUSTOM') */
-  operation?: AuditOperation;
-  /** Previous state */
-  oldValues?: Record<string, unknown>;
-  /** New state */
-  newValues?: Record<string, unknown>;
+	/** Entity primary key(s) for easier querying */
+	entityId?: string | Record<string, unknown>;
+	/** Database table name */
+	table?: string;
+	/** Operation type (defaults to 'CUSTOM') */
+	operation?: AuditOperation;
+	/** Previous state */
+	oldValues?: Record<string, unknown>;
+	/** New state */
+	newValues?: Record<string, unknown>;
 }
 
 /**
@@ -119,23 +119,23 @@ export interface AuditOptions {
  * Similar to MappedEvent in @geekmidas/events.
  */
 export interface MappedAudit<
-  TAuditAction extends AuditableAction<string, unknown>,
-  TOutput extends StandardSchemaV1 | undefined = undefined,
+	TAuditAction extends AuditableAction<string, unknown>,
+	TOutput extends StandardSchemaV1 | undefined = undefined,
 > {
-  /** The audit type - must be a valid type from the AuditableAction union */
-  type: ExtractAuditType<TAuditAction>;
-  /** Function to extract payload from the response */
-  payload: (
-    response: InferStandardSchema<TOutput>,
-  ) => ExtractAuditPayload<TAuditAction, ExtractAuditType<TAuditAction>>;
-  /** Optional condition - only audit if this returns true */
-  when?: (response: InferStandardSchema<TOutput>) => boolean;
-  /** Optional entity ID extractor for easier querying */
-  entityId?: (
-    response: InferStandardSchema<TOutput>,
-  ) => string | Record<string, unknown>;
-  /** Optional table name for database association */
-  table?: string;
+	/** The audit type - must be a valid type from the AuditableAction union */
+	type: ExtractAuditType<TAuditAction>;
+	/** Function to extract payload from the response */
+	payload: (
+		response: InferStandardSchema<TOutput>,
+	) => ExtractAuditPayload<TAuditAction, ExtractAuditType<TAuditAction>>;
+	/** Optional condition - only audit if this returns true */
+	when?: (response: InferStandardSchema<TOutput>) => boolean;
+	/** Optional entity ID extractor for easier querying */
+	entityId?: (
+		response: InferStandardSchema<TOutput>,
+	) => string | Record<string, unknown>;
+	/** Optional table name for database association */
+	table?: string;
 }
 
 /**
@@ -146,9 +146,8 @@ export type ExtractAuditorAction<T> = T extends Auditor<infer A> ? A : never;
 /**
  * Extract the AuditableAction type from an AuditStorage.
  */
-export type ExtractStorageAuditAction<T> = T extends AuditStorage<infer A>
-  ? A
-  : AuditableAction<string, unknown>;
+export type ExtractStorageAuditAction<T> =
+	T extends AuditStorage<infer A> ? A : AuditableAction<string, unknown>;
 
 // Forward declaration for Auditor type extraction
 import type { Auditor } from './Auditor';

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true
+  },
+  "include": ["src/**/*"]
+}