@geekmidas/testkit 3.1.1 → 10.0.0-alpha.0

package/src/PostgresObjectionMigrator.ts

@@ -1,138 +0,0 @@
-import type { Knex } from 'knex';
-import { PostgresMigrator } from './PostgresMigrator';
-
-/**
- * Default logger instance for migration operations.
- */
-const logger = console;
-
-/**
- * PostgreSQL migrator implementation for Objection.js ORM with Knex.
- * Extends PostgresMigrator to provide Knex-specific migration functionality.
- * Automatically creates test databases and applies migrations for testing environments.
- *
- * @example
- * ```typescript
- * import knex from 'knex';
- * import { PostgresObjectionMigrator } from '@geekmidas/testkit';
- *
- * // Create Knex instance
- * const db = knex({
- *   client: 'pg',
- *   connection: uri,
- *   migrations: {
- *     directory: path.join(__dirname, 'migrations'),
- *     extension: 'ts'
- *   }
- * });
- *
- * // Create and use migrator
- * const migrator = new PostgresObjectionMigrator({
- *   uri: 'postgresql://localhost:5432/test_db',
- *   knex: db
- * });
- *
- * const cleanup = await migrator.start();
- * // Run tests...
- * await cleanup();
- * ```
- */
-export class PostgresObjectionMigrator extends PostgresMigrator {
-	/**
-	 * Creates a new PostgresObjectionMigrator instance.
-	 *
-	 * @param options - Configuration options
-	 * @param options.uri - PostgreSQL connection URI
-	 * @param options.knex - Knex database instance configured with migrations
-	 */
-	constructor(
-		private options: {
-			uri: string;
-			knex: Knex;
-		},
-	) {
-		super(options.uri);
-	}
-
-	/**
-	 * Executes Knex migrations to the latest version.
-	 * Implements the abstract migrate() method from PostgresMigrator.
-	 *
-	 * @throws Error if migrations fail to apply
-	 * @returns Promise that resolves when all migrations are applied
-	 */
-	async migrate(): Promise<void> {
-		try {
-			// Run migrations to latest
-			const [batchNo, migrations] = await this.options.knex.migrate.latest();
-
-			if (migrations.length > 0) {
-				logger.log(
-					`Applied batch ${batchNo} with ${migrations.length} migrations:`,
-				);
-				migrations.forEach((migration: string) => {
-					logger.log(`  - ${migration}`);
-				});
-			} else {
-				logger.log('No pending migrations to apply');
-			}
-		} catch (error) {
-			logger.error('Failed to apply migrations:', error);
-			throw error;
-		} finally {
-			// Always destroy the connection pool
-			await this.options.knex.destroy();
-		}
-	}
-
-	/**
-	 * Rolls back the last batch of migrations.
-	 * Useful for testing migration rollback scenarios.
-	 *
-	 * @returns Promise that resolves when rollback is complete
-	 */
-	async rollback(): Promise<void> {
-		try {
-			const [batchNo, migrations] = await this.options.knex.migrate.rollback();
-
-			if (migrations.length > 0) {
-				logger.log(
-					`Rolled back batch ${batchNo} with ${migrations.length} migrations:`,
-				);
-				migrations.forEach((migration: string) => {
-					logger.log(`  - ${migration}`);
-				});
-			} else {
-				logger.log('No migrations to rollback');
-			}
-		} catch (error) {
-			logger.error('Failed to rollback migrations:', error);
-			throw error;
-		} finally {
-			await this.options.knex.destroy();
-		}
-	}
-
-	/**
-	 * Gets the current migration status.
-	 * Returns information about completed and pending migrations.
-	 *
-	 * @returns Promise with migration status information
-	 */
-	async status(): Promise<{
-		completed: string[];
-		pending: string[];
-	}> {
-		try {
-			const completed = await this.options.knex.migrate.list();
-			const [, pending] = await this.options.knex.migrate.currentVersion();
-
-			return {
-				completed: Array.isArray(completed[0]) ? completed[0] : [],
-				pending: Array.isArray(pending) ? pending : [],
-			};
-		} finally {
-			await this.options.knex.destroy();
-		}
-	}
-}

package/src/VitestKyselyTransactionIsolator.ts

@@ -1,72 +0,0 @@
-import type { Kysely, Transaction } from 'kysely';
-import {
-	type IsolationLevel,
-	VitestPostgresTransactionIsolator,
-} from './VitestTransactionIsolator';
-
-/**
- * Kysely-specific implementation of the Vitest transaction isolator.
- * Provides automatic transaction rollback for test isolation using Kysely's transaction API.
- * Each test runs within a database transaction that is rolled back after completion,
- * ensuring a clean state between tests without the overhead of recreating data.
- *
- * @template Database - The database schema type
- *
- * @example
- * ```typescript
- * import { VitestKyselyTransactionIsolator } from '@geekmidas/testkit';
- * import { db } from './database';
- *
- * // Create isolator instance
- * const isolator = new VitestKyselyTransactionIsolator<Database>();
- *
- * // In your test setup
- * beforeEach(async () => {
- *   await isolator.start(db);
- * });
- *
- * afterEach(async () => {
- *   await isolator.rollback();
- * });
- *
- * // Tests run in isolated transactions
- * it('should create user', async () => {
- *   const user = await db.insertInto('users')
- *     .values({ name: 'Test User' })
- *     .returningAll()
- *     .executeTakeFirst();
- *
- *   expect(user).toBeDefined();
- *   // This data will be rolled back after the test
- * });
- * ```
- */
-export class VitestKyselyTransactionIsolator<
-	Database,
-> extends VitestPostgresTransactionIsolator<
-	Kysely<Database>,
-	Transaction<Database>
-> {
-	async destroy(_conn: Kysely<Database>): Promise<void> {
-		// return conn.destroy();
-	}
-	/**
-	 * Creates a Kysely transaction with the specified isolation level.
-	 * Implements the abstract transact method from VitestPostgresTransactionIsolator.
-	 *
-	 * @param conn - The Kysely 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
-	 */
-	async transact(
-		conn: Kysely<Database>,
-		level: IsolationLevel,
-		fn: (trx: Transaction<Database>) => Promise<void>,
-	): Promise<void> {
-		const isolationLevel =
-			level.toLocaleLowerCase() as Lowercase<IsolationLevel>;
-		await conn.transaction().setIsolationLevel(isolationLevel).execute(fn);
-	}
-	// Implement any Kysely-specific transaction logic here
-}

package/src/VitestObjectionTransactionIsolator.ts

@@ -1,75 +0,0 @@
-import type { Knex } from 'knex';
-import {
-	type IsolationLevel,
-	VitestPostgresTransactionIsolator,
-} from './VitestTransactionIsolator';
-
-/**
- * Objection.js-specific implementation of the Vitest transaction isolator.
- * Provides automatic transaction rollback for test isolation using Objection.js and Knex transaction API.
- * Each test runs within a database transaction that is rolled back after completion,
- * ensuring a clean state between tests without the overhead of recreating data.
- *
- * @example
- * ```typescript
- * import { VitestObjectionTransactionIsolator } from '@geekmidas/testkit';
- * import { knex } from './database';
- * import { User } from './models';
- * import { test } from 'vitest';
- *
- * // Create isolator instance
- * const isolator = new VitestObjectionTransactionIsolator(test);
- *
- * // Use with wrapped test API
- * const isolatedTest = isolator.wrapVitestWithTransaction(knex);
- *
- * isolatedTest('should create user', async ({ trx }) => {
- *   const user = await User.query(trx)
- *     .insert({ name: 'Test User' });
- *
- *   expect(user).toBeDefined();
- *   // This data will be rolled back after the test
- * });
- * ```
- */
-export class VitestObjectionTransactionIsolator extends VitestPostgresTransactionIsolator<
-	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>;
-
-		await connection.transaction(
-			async (trx) => {
-				await fn(trx);
-			},
-			{
-				isolationLevel,
-			},
-		);
-	}
-}

package/src/VitestTransactionIsolator.ts

@@ -1,348 +0,0 @@
-import type { TestAPI } from 'vitest';
-
-/**
- * Type definition for test fixtures that provide transaction access.
- * Used with Vitest's test.extend() API to inject transactions into tests.
- *
- * @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;
-}
-
-/**
- * Combined fixtures type that merges the base transaction fixture with extended context.
- */
-export type ExtendedDatabaseFixtures<
-	Transaction,
-	Extended = object,
-> = DatabaseFixtures<Transaction> & Extended;
-
-/**
- * Function type for extending test context with additional properties.
- * Receives the transaction and returns additional context to be merged with { trx }.
- *
- * @template Transaction - The transaction type
- * @template Extended - The type of additional context to provide
- *
- * @example
- * ```typescript
- * const extendContext: ExtendContextFn<Transaction<DB>, { factory: KyselyFactory }> =
- *   (trx) => ({ factory: new KyselyFactory(builders, seeds, trx) });
- * ```
- */
-export type ExtendContextFn<Transaction, Extended> = (
-	trx: Transaction,
-) => Extended | Promise<Extended>;
-
-/**
- * PostgreSQL transaction isolation levels.
- * Controls the visibility of concurrent transactions.
- *
- * @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',
-}
-
-/**
- * Abstract base class for implementing database transaction isolation in Vitest tests.
- * Provides automatic transaction rollback after each test to maintain test isolation.
- * Subclasses must implement the transact() method for their specific database driver.
- *
- * @template TConn - The database connection type
- * @template Transaction - The transaction type
- *
- * @example
- * ```typescript
- * // Implement for your database driver
- * class MyDatabaseIsolator extends VitestPostgresTransactionIsolator<MyDB, MyTx> {
- *   async transact(conn: MyDB, level: IsolationLevel, fn: (tx: MyTx) => Promise<void>) {
- *     await conn.transaction(level, fn);
- *   }
- * }
- *
- * // Use in tests
- * const isolator = new MyDatabaseIsolator(test);
- * const isolatedTest = isolator.wrapVitestWithTransaction(db);
- *
- * isolatedTest('should create user', async ({ trx }) => {
- *   await trx.insert('users', { name: 'Test' });
- *   // Data is automatically rolled back after test
- * });
- * ```
- */
-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 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;
-
-		// 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;
-
-		// 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 api = this.api as TestAPI & {
-			extend: <T>(fixtures: any) => TestAPI<T>;
-		};
-
-		return api.extend<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;
-						}
-
-						// 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,
-		});
-	}
-}
-
-export type DatabaseConnectionFn<Conn> = () => Conn | Promise<Conn>;
-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> = {},
-> {
-	/** 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>;
-}
-
-/**
- * Type for fixture creator functions that depend on the transaction.
- * Each function receives the transaction and returns the fixture value.
- */
-export type FixtureCreators<
-	Transaction,
-	Extended extends Record<string, unknown>,
-> = {
-	[K in keyof Extended]: (
-		trx: Transaction,
-	) => Extended[K] | Promise<Extended[K]>;
-};
-
-/**
- * The test API returned by extendWithFixtures.
- * Provides access to both the transaction (trx) and all extended fixtures.
- *
- * @template Transaction - The transaction type
- * @template Extended - The type of additional fixtures provided
- * @template BaseTest - The base wrapped test type
- */
-export type TestWithExtendedFixtures<
-	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;
-};
-
-/**
- * Extends a wrapped test API with additional fixtures that depend on the transaction.
- * This allows composing test context with factories, repositories, or other helpers.
- *
- * @template Transaction - The transaction type
- * @template Extended - The type of additional context to provide
- * @param wrappedTest - The base wrapped test from wrapVitestWithTransaction
- * @param fixtures - Object mapping fixture names to creator functions
- * @returns An extended test API with both trx and the additional fixtures
- *
- * @example
- * ```typescript
- * import { wrapVitestKyselyTransaction, extendWithFixtures } from '@geekmidas/testkit/kysely';
- *
- * // Create base wrapped test
- * const baseTest = wrapVitestKyselyTransaction(test, {
- *   connection: db,
- *   setup: createTestTables,
- * });
- *
- * // Extend with fixtures
- * const it = extendWithFixtures(baseTest, {
- *   factory: (trx) => new KyselyFactory(builders, seeds, trx),
- *   userRepo: (trx) => new UserRepository(trx),
- * });
- *
- * // Use in tests - trx and all fixtures are available
- * it('should create user with factory', async ({ trx, factory, userRepo }) => {
- *   const user = await factory.insert('user', { name: 'Test' });
- *   expect(user).toBeDefined();
- * });
- * ```
- */
-export function extendWithFixtures<
-	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>,
-): TestWithExtendedFixtures<Transaction, Extended, T> {
-	// 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);
-		};
-	}
-
-	return (wrappedTest as any).extend(fixtureDefinitions);
-}