@geekmidas/testkit 0.3.1 → 0.6.0

package/src/VitestObjectionTransactionIsolator.ts

@@ -1,7 +1,7 @@
 import type { Knex } from 'knex';
 import {
-  type IsolationLevel,
-  VitestPostgresTransactionIsolator,
+	type IsolationLevel,
+	VitestPostgresTransactionIsolator,
 } from './VitestTransactionIsolator';
 
 /**
@@ -33,43 +33,43 @@ import {
  * ```
  */
 export class VitestObjectionTransactionIsolator extends VitestPostgresTransactionIsolator<
-  Knex,
-  Knex.Transaction
+	Knex,
+	Knex.Transaction
 > {
-  async destroy(conn: Knex<any, any[]>): Promise<void> {}
-  /**
-   * Creates a Knex transaction with the specified isolation level.
-   * Implements the abstract transact method from VitestPostgresTransactionIsolator.
-   * This transaction can be used with Objection.js models via Model.query(trx).
-   *
-   * @param conn - The Knex database connection
-   * @param level - The transaction isolation level
-   * @param fn - The function to execute within the transaction
-   * @returns Promise that resolves when the transaction completes
-   *
-   * @example
-   * ```typescript
-   * await isolator.transact(knex, IsolationLevel.REPEATABLE_READ, async (trx) => {
-   *   // Use transaction with Objection models
-   *   await User.query(trx).insert({ name: 'Test' });
-   *   await Post.query(trx).where('userId', user.id).delete();
-   * });
-   * ```
-   */
-  async transact(
-    connection: Knex,
-    level: IsolationLevel,
-    fn: (trx: Knex.Transaction) => Promise<void>,
-  ): Promise<void> {
-    const isolationLevel = level.toLowerCase() as Lowercase<IsolationLevel>;
+	async destroy(_conn: Knex<any, any[]>): Promise<void> {}
+	/**
+	 * Creates a Knex transaction with the specified isolation level.
+	 * Implements the abstract transact method from VitestPostgresTransactionIsolator.
+	 * This transaction can be used with Objection.js models via Model.query(trx).
+	 *
+	 * @param conn - The Knex database connection
+	 * @param level - The transaction isolation level
+	 * @param fn - The function to execute within the transaction
+	 * @returns Promise that resolves when the transaction completes
+	 *
+	 * @example
+	 * ```typescript
+	 * await isolator.transact(knex, IsolationLevel.REPEATABLE_READ, async (trx) => {
+	 *   // Use transaction with Objection models
+	 *   await User.query(trx).insert({ name: 'Test' });
+	 *   await Post.query(trx).where('userId', user.id).delete();
+	 * });
+	 * ```
+	 */
+	async transact(
+		connection: Knex,
+		level: IsolationLevel,
+		fn: (trx: Knex.Transaction) => Promise<void>,
+	): Promise<void> {
+		const isolationLevel = level.toLowerCase() as Lowercase<IsolationLevel>;
 
-    await connection.transaction(
-      async (trx) => {
-        await fn(trx);
-      },
-      {
-        isolationLevel,
-      },
-    );
-  }
+		await connection.transaction(
+			async (trx) => {
+				await fn(trx);
+			},
+			{
+				isolationLevel,
+			},
+		);
+	}
 }

package/src/VitestTransactionIsolator.ts

@@ -7,20 +7,20 @@ import type { TestAPI } from 'vitest';
  * @template Transaction - The transaction type specific to the database driver
  * @template Extended - Additional context properties provided by the extend function
  */
-export interface DatabaseFixtures<Transaction, Extended = object> {
-  /**
-   * The database transaction available to the test.
-   * All database operations should use this transaction to ensure proper rollback.
-   */
-  trx: Transaction;
+export interface DatabaseFixtures<Transaction, _Extended = object> {
+	/**
+	 * The database transaction available to the test.
+	 * All database operations should use this transaction to ensure proper rollback.
+	 */
+	trx: Transaction;
 }
 
 /**
  * Combined fixtures type that merges the base transaction fixture with extended context.
  */
 export type ExtendedDatabaseFixtures<
-  Transaction,
-  Extended = object,
+	Transaction,
+	Extended = object,
 > = DatabaseFixtures<Transaction> & Extended;
 
 /**
@@ -37,7 +37,7 @@ export type ExtendedDatabaseFixtures<
  * ```
  */
 export type ExtendContextFn<Transaction, Extended> = (
-  trx: Transaction,
+	trx: Transaction,
 ) => Extended | Promise<Extended>;
 
 /**
@@ -47,26 +47,26 @@ export type ExtendContextFn<Transaction, Extended> = (
  * @see https://www.postgresql.org/docs/current/transaction-iso.html
  */
 export enum IsolationLevel {
-  /**
-   * Lowest isolation level. Allows dirty reads.
-   * Not recommended for testing.
-   */
-  READ_UNCOMMITTED = 'READ UNCOMMITTED',
-  /**
-   * Default PostgreSQL isolation level.
-   * Prevents dirty reads but allows non-repeatable reads.
-   */
-  READ_COMMITTED = 'READ COMMITTED',
-  /**
-   * Prevents dirty reads and non-repeatable reads.
-   * Recommended for most test scenarios.
-   */
-  REPEATABLE_READ = 'REPEATABLE READ',
-  /**
-   * Highest isolation level. Prevents all phenomena.
-   * May cause performance overhead in tests.
-   */
-  SERIALIZABLE = 'SERIALIZABLE',
+	/**
+	 * Lowest isolation level. Allows dirty reads.
+	 * Not recommended for testing.
+	 */
+	READ_UNCOMMITTED = 'READ UNCOMMITTED',
+	/**
+	 * Default PostgreSQL isolation level.
+	 * Prevents dirty reads but allows non-repeatable reads.
+	 */
+	READ_COMMITTED = 'READ COMMITTED',
+	/**
+	 * Prevents dirty reads and non-repeatable reads.
+	 * Recommended for most test scenarios.
+	 */
+	REPEATABLE_READ = 'REPEATABLE READ',
+	/**
+	 * Highest isolation level. Prevents all phenomena.
+	 * May cause performance overhead in tests.
+	 */
+	SERIALIZABLE = 'SERIALIZABLE',
 }
 
 /**
@@ -97,129 +97,130 @@ export enum IsolationLevel {
  * ```
  */
 export abstract class VitestPostgresTransactionIsolator<TConn, Transaction> {
-  /**
-   * Abstract method to create a transaction with the specified isolation level.
-   * Must be implemented by subclasses for specific database drivers.
-   *
-   * @param conn - The database connection
-   * @param isolationLevel - The transaction isolation level
-   * @param fn - The function to execute within the transaction
-   * @returns Promise that resolves when the transaction completes
-   */
-  abstract transact(
-    conn: TConn,
-    isolationLevel: IsolationLevel,
-    fn: (trx: Transaction) => Promise<void>,
-  ): Promise<void>;
+	/**
+	 * Abstract method to create a transaction with the specified isolation level.
+	 * Must be implemented by subclasses for specific database drivers.
+	 *
+	 * @param conn - The database connection
+	 * @param isolationLevel - The transaction isolation level
+	 * @param fn - The function to execute within the transaction
+	 * @returns Promise that resolves when the transaction completes
+	 */
+	abstract transact(
+		conn: TConn,
+		isolationLevel: IsolationLevel,
+		fn: (trx: Transaction) => Promise<void>,
+	): Promise<void>;
 
-  abstract destroy(conn: TConn): Promise<void>;
-  /**
-   * Creates a new VitestPostgresTransactionIsolator instance.
-   *
-   * @param api - The Vitest test API (usually the `test` export from vitest)
-   */
-  constructor(private readonly api: TestAPI) {}
+	abstract destroy(conn: TConn): Promise<void>;
+	/**
+	 * Creates a new VitestPostgresTransactionIsolator instance.
+	 *
+	 * @param api - The Vitest test API (usually the `test` export from vitest)
+	 */
+	constructor(private readonly api: TestAPI) {}
 
-  /**
-   * Creates a wrapped version of Vitest's test API that provides transaction isolation.
-   * Each test will run within a database transaction that is automatically rolled back.
-   *
-   * @param options - Configuration options for transaction wrapping
-   * @returns A wrapped test API with transaction support
-   *
-   * @example
-   * ```typescript
-   * const isolatedTest = isolator.wrapVitestWithTransaction({
-   *   connection: db,
-   *   setup: async (trx) => {
-   *     await trx.insert('settings', { key: 'test', value: 'true' });
-   *   },
-   *   fixtures: {
-   *     factory: (trx) => new Factory(trx),
-   *   },
-   * });
-   *
-   * isolatedTest('test with transaction', async ({ trx, factory }) => {
-   *   const user = await factory.insert('user', { name: 'Test' });
-   *   expect(user).toBeDefined();
-   * });
-   * ```
-   */
-  wrapVitestWithTransaction<Extended extends Record<string, unknown> = {}>(
-    options: TransactionWrapperOptions<TConn, Transaction, Extended>,
-  ) {
-    const {
-      connection,
-      setup,
-      isolationLevel = IsolationLevel.REPEATABLE_READ,
-      fixtures,
-    } = options;
+	/**
+	 * Creates a wrapped version of Vitest's test API that provides transaction isolation.
+	 * Each test will run within a database transaction that is automatically rolled back.
+	 *
+	 * @param options - Configuration options for transaction wrapping
+	 * @returns A wrapped test API with transaction support
+	 *
+	 * @example
+	 * ```typescript
+	 * const isolatedTest = isolator.wrapVitestWithTransaction({
+	 *   connection: db,
+	 *   setup: async (trx) => {
+	 *     await trx.insert('settings', { key: 'test', value: 'true' });
+	 *   },
+	 *   fixtures: {
+	 *     factory: (trx) => new Factory(trx),
+	 *   },
+	 * });
+	 *
+	 * isolatedTest('test with transaction', async ({ trx, factory }) => {
+	 *   const user = await factory.insert('user', { name: 'Test' });
+	 *   expect(user).toBeDefined();
+	 * });
+	 * ```
+	 */
+	wrapVitestWithTransaction<Extended extends Record<string, unknown> = {}>(
+		options: TransactionWrapperOptions<TConn, Transaction, Extended>,
+	) {
+		const {
+			connection,
+			setup,
+			isolationLevel = IsolationLevel.REPEATABLE_READ,
+			fixtures,
+		} = options;
 
-    // Build fixture definitions for additional fixtures that depend on trx
-    const additionalFixtures: Record<string, unknown> = {};
-    if (fixtures) {
-      for (const [key, creator] of Object.entries(fixtures)) {
-        additionalFixtures[key] = async (
-          { trx }: { trx: Transaction },
-          use: (value: unknown) => Promise<void>,
-        ) => {
-          const value = await (creator as (trx: Transaction) => unknown)(trx);
-          await use(value);
-        };
-      }
-    }
+		// Build fixture definitions for additional fixtures that depend on trx
+		const additionalFixtures: Record<string, unknown> = {};
+		if (fixtures) {
+			for (const [key, creator] of Object.entries(fixtures)) {
+				additionalFixtures[key] = async (
+					{ trx }: { trx: Transaction },
+					use: (value: unknown) => Promise<void>,
+				) => {
+					const value = await (creator as (trx: Transaction) => unknown)(trx);
+					await use(value);
+				};
+			}
+		}
 
-    type CombinedFixtures = DatabaseFixtures<Transaction> & Extended;
+		type CombinedFixtures = DatabaseFixtures<Transaction> & Extended;
 
-    // Cast to bypass Vitest's strict fixture typing which can't infer
-    // dynamically built fixture objects
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const extendFn = this.api.extend as <T>(fixtures: any) => TestAPI<T>;
+		// Cast to bypass Vitest's strict fixture typing which can't infer
+		// dynamically built fixture objects
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const extendFn = this.api.extend as <T>(fixtures: any) => TestAPI<T>;
 
-    return extendFn<CombinedFixtures>({
-      // This fixture automatically provides a transaction to each test
-      trx: async ({}, use: (value: Transaction) => Promise<void>) => {
-        // Create a custom error class for rollback
-        class TestRollback extends Error {
-          constructor() {
-            super('Test rollback');
-            this.name = 'TestRollback';
-          }
-        }
+		return extendFn<CombinedFixtures>({
+			// This fixture automatically provides a transaction to each test
+			// biome-ignore lint/correctness/noEmptyPattern: this has to be like this to satisfy Biome
+			trx: async ({}: {}, use: (value: Transaction) => Promise<void>) => {
+				// Create a custom error class for rollback
+				class TestRollback extends Error {
+					constructor() {
+						super('Test rollback');
+						this.name = 'TestRollback';
+					}
+				}
 
-        let testError: Error | undefined;
-        const conn = await connection();
-        try {
-          await this.transact(conn, isolationLevel, async (transaction) => {
-            try {
-              // Provide the transaction to the test
-              await setup?.(transaction);
-              await use(transaction);
-            } catch (error) {
-              // Capture any test errors
-              testError = error as Error;
-            }
+				let testError: Error | undefined;
+				const conn = await connection();
+				try {
+					await this.transact(conn, isolationLevel, async (transaction) => {
+						try {
+							// Provide the transaction to the test
+							await setup?.(transaction);
+							await use(transaction);
+						} catch (error) {
+							// Capture any test errors
+							testError = error as Error;
+						}
 
-            // Always throw to trigger rollback
-            throw new TestRollback();
-          });
-        } catch (error) {
-          // Only rethrow if it's not our rollback error
-          if (!(error instanceof TestRollback)) {
-            throw error;
-          }
+						// Always throw to trigger rollback
+						throw new TestRollback();
+					});
+				} catch (error) {
+					// Only rethrow if it's not our rollback error
+					if (!(error instanceof TestRollback)) {
+						throw error;
+					}
 
-          // If the test had an error, throw it now
-          if (testError) {
-            throw testError;
-          }
-        } finally {
-          await this.destroy(conn);
-        }
-      },
-      ...additionalFixtures,
-    });
-  }
+					// If the test had an error, throw it now
+					if (testError) {
+						throw testError;
+					}
+				} finally {
+					await this.destroy(conn);
+				}
+			},
+			...additionalFixtures,
+		});
+	}
 }
 
 export type DatabaseConnectionFn<Conn> = () => Conn | Promise<Conn>;
@@ -229,18 +230,18 @@ export type DatabaseConnection<Conn> = DatabaseConnectionFn<Conn>;
  * Options for wrapping Vitest tests with database transaction isolation.
  */
 export interface TransactionWrapperOptions<
-  TConn,
-  Transaction,
-  Extended extends Record<string, unknown> = {},
+	TConn,
+	Transaction,
+	Extended extends Record<string, unknown> = {},
 > {
-  /** Function that creates or returns a database connection */
-  connection: DatabaseConnection<TConn>;
-  /** Optional setup function to run within the transaction before each test */
-  setup?: (trx: Transaction) => Promise<void>;
-  /** Transaction isolation level (defaults to REPEATABLE_READ) */
-  isolationLevel?: IsolationLevel;
-  /** Additional fixtures that depend on the transaction */
-  fixtures?: FixtureCreators<Transaction, Extended>;
+	/** Function that creates or returns a database connection */
+	connection: DatabaseConnection<TConn>;
+	/** Optional setup function to run within the transaction before each test */
+	setup?: (trx: Transaction) => Promise<void>;
+	/** Transaction isolation level (defaults to REPEATABLE_READ) */
+	isolationLevel?: IsolationLevel;
+	/** Additional fixtures that depend on the transaction */
+	fixtures?: FixtureCreators<Transaction, Extended>;
 }
 
 /**
@@ -248,12 +249,12 @@ export interface TransactionWrapperOptions<
  * Each function receives the transaction and returns the fixture value.
  */
 export type FixtureCreators<
-  Transaction,
-  Extended extends Record<string, unknown>,
+	Transaction,
+	Extended extends Record<string, unknown>,
 > = {
-  [K in keyof Extended]: (
-    trx: Transaction,
-  ) => Extended[K] | Promise<Extended[K]>;
+	[K in keyof Extended]: (
+		trx: Transaction,
+	) => Extended[K] | Promise<Extended[K]>;
 };
 
 /**
@@ -265,25 +266,25 @@ export type FixtureCreators<
  * @template BaseTest - The base wrapped test type
  */
 export type TestWithExtendedFixtures<
-  Transaction,
-  Extended extends Record<string, unknown>,
-  BaseTest extends ReturnType<TestAPI['extend']> = ReturnType<
-    TestAPI['extend']
-  >,
+	Transaction,
+	Extended extends Record<string, unknown>,
+	BaseTest extends ReturnType<TestAPI['extend']> = ReturnType<
+		TestAPI['extend']
+	>,
 > = BaseTest & {
-  <C extends object>(
-    name: string,
-    fn: (
-      context: DatabaseFixtures<Transaction> & Extended & C,
-    ) => Promise<void>,
-  ): void;
-  <C extends object>(
-    name: string,
-    options: object,
-    fn: (
-      context: DatabaseFixtures<Transaction> & Extended & C,
-    ) => Promise<void>,
-  ): void;
+	<C extends object>(
+		name: string,
+		fn: (
+			context: DatabaseFixtures<Transaction> & Extended & C,
+		) => Promise<void>,
+	): void;
+	<C extends object>(
+		name: string,
+		options: object,
+		fn: (
+			context: DatabaseFixtures<Transaction> & Extended & C,
+		) => Promise<void>,
+	): void;
 };
 
 /**
@@ -320,26 +321,26 @@ export type TestWithExtendedFixtures<
  * ```
  */
 export function extendWithFixtures<
-  Transaction,
-  Extended extends Record<string, unknown>,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  T extends ReturnType<TestAPI['extend']> = any,
+	Transaction,
+	Extended extends Record<string, unknown>,
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	T extends ReturnType<TestAPI['extend']> = any,
 >(
-  wrappedTest: T,
-  fixtures: FixtureCreators<Transaction, Extended>,
+	wrappedTest: T,
+	fixtures: FixtureCreators<Transaction, Extended>,
 ): TestWithExtendedFixtures<Transaction, Extended, T> {
-  // Build fixture definitions for Vitest's extend API
-  const fixtureDefinitions: Record<string, any> = {};
+	// Build fixture definitions for Vitest's extend API
+	const fixtureDefinitions: Record<string, any> = {};
 
-  for (const [key, creator] of Object.entries(fixtures)) {
-    fixtureDefinitions[key] = async (
-      { trx }: { trx: Transaction },
-      use: (value: unknown) => Promise<void>,
-    ) => {
-      const value = await (creator as (trx: Transaction) => unknown)(trx);
-      await use(value);
-    };
-  }
+	for (const [key, creator] of Object.entries(fixtures)) {
+		fixtureDefinitions[key] = async (
+			{ trx }: { trx: Transaction },
+			use: (value: unknown) => Promise<void>,
+		) => {
+			const value = await (creator as (trx: Transaction) => unknown)(trx);
+			await use(value);
+		};
+	}
 
-  return (wrappedTest as any).extend(fixtureDefinitions);
+	return (wrappedTest as any).extend(fixtureDefinitions);
 }