@geekmidas/testkit 0.0.5 → 0.0.7

package/src/PostgresMigrator.ts

@@ -1,5 +1,19 @@
 import { Client } from 'pg';
 
+/**
+ * Creates a PostgreSQL client connected to the 'postgres' database.
+ * Extracts connection details from the provided URI.
+ *
+ * @param uri - PostgreSQL connection URI
+ * @returns Object containing the target database name and client instance
+ *
+ * @example
+ * ```typescript
+ * const { database, db } = await setupClient('postgresql://user:pass@localhost:5432/mydb');
+ * // database = 'mydb'
+ * // db = Client instance connected to 'postgres' database
+ * ```
+ */
 async function setupClient(uri: string) {
   const url = new URL(uri);
 
@@ -18,13 +32,59 @@ async function setupClient(uri: string) {
   return { database, db };
 }
 
+/**
+ * Default logger instance for migration operations.
+ */
 const logger = console;
 
+/**
+ * Abstract base class for PostgreSQL database migration utilities.
+ * Provides database creation, migration, and cleanup functionality for testing.
+ * Subclasses must implement the migrate() method to define migration logic.
+ *
+ * @example
+ * ```typescript
+ * class MyMigrator extends PostgresMigrator {
+ *   async migrate(): Promise<void> {
+ *     // Run your migrations here
+ *     await this.runMigrations();
+ *   }
+ * }
+ *
+ * // Use in tests
+ * const migrator = new MyMigrator('postgresql://localhost:5432/test_db');
+ * const cleanup = await migrator.start();
+ *
+ * // Run tests...
+ *
+ * // Clean up
+ * await cleanup();
+ * ```
+ */
 export abstract class PostgresMigrator {
+  /**
+   * Creates a new PostgresMigrator instance.
+   *
+   * @param uri - PostgreSQL connection URI
+   */
   constructor(private uri: string) {}
 
+  /**
+   * Abstract method to be implemented by subclasses.
+   * Should contain the migration logic for setting up database schema.
+   *
+   * @returns Promise that resolves when migrations are complete
+   */
   abstract migrate(): Promise<void>;
 
+  /**
+   * Creates a PostgreSQL database if it doesn't already exist.
+   * Connects to the 'postgres' database to check and create the target database.
+   *
+   * @param uri - PostgreSQL connection URI
+   * @returns Object indicating whether the database already existed
+   * @private
+   */
   private static async create(
     uri: string,
   ): Promise<{ alreadyExisted: boolean }> {
@@ -47,6 +107,14 @@ export abstract class PostgresMigrator {
     }
   }
 
+  /**
+   * Drops a PostgreSQL database.
+   * Used for cleanup after tests are complete.
+   *
+   * @param uri - PostgreSQL connection URI
+   * @throws Error if database cannot be dropped
+   * @private
+   */
   private static async drop(uri: string): Promise<void> {
     const { database, db } = await setupClient(uri);
     try {
@@ -57,6 +125,28 @@ export abstract class PostgresMigrator {
     }
   }
 
+  /**
+   * Starts the migration process by creating the database and running migrations.
+   * Returns a cleanup function that will drop the database when called.
+   *
+   * @returns Async cleanup function that drops the created database
+   *
+   * @example
+   * ```typescript
+   * const migrator = new MyMigrator('postgresql://localhost:5432/test_db');
+   *
+   * // Start migrations and get cleanup function
+   * const cleanup = await migrator.start();
+   *
+   * try {
+   *   // Run your tests here
+   *   await runTests();
+   * } finally {
+   *   // Always clean up
+   *   await cleanup();
+   * }
+   * ```
+   */
   async start() {
     const { database, db } = await setupClient(this.uri);
     try {

package/src/VitestKyselyTransactionIsolator.ts

@@ -4,12 +4,58 @@ import {
   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>
 > {
+  /**
+   * 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,

package/src/VitestObjectionTransactionIsolator.ts

@@ -0,0 +1,73 @@
+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
+> {
+  /**
+   * 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(
+    conn: Knex,
+    level: IsolationLevel,
+    fn: (trx: Knex.Transaction) => Promise<void>,
+  ): Promise<void> {
+    const isolationLevel = level.toUpperCase() as Lowercase<IsolationLevel>;
+    await conn.transaction(
+      async (trx) => {
+        await fn(trx);
+      },
+      {
+        isolationLevel,
+      },
+    );
+  }
+}

package/src/VitestTransactionIsolator.ts

@@ -1,32 +1,129 @@
-import { test as base } from 'vitest';
+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
+ */
 export interface DatabaseFixtures<Transaction> {
+  /**
+   * The database transaction available to the test.
+   * All database operations should use this transaction to ensure proper rollback.
+   */
   trx: Transaction;
 }
 
+/**
+ * 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 Connection - 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<
   Connection,
   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: Connection,
     isolationLevel: IsolationLevel,
     fn: (trx: Transaction) => Promise<void>,
   ): 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 conn - The database connection to use
+   * @param setup - Optional setup function to run within the transaction before each test
+   * @param level - The transaction isolation level (defaults to REPEATABLE_READ)
+   * @returns A wrapped test API with transaction support
+   *
+   * @example
+   * ```typescript
+   * const isolatedTest = isolator.wrapVitestWithTransaction(db, async (trx) => {
+   *   // Optional setup: create common test data
+   *   await trx.insert('settings', { key: 'test', value: 'true' });
+   * });
+   *
+   * isolatedTest('test with transaction', async ({ trx }) => {
+   *   const user = await trx.insert('users', { name: 'Test' });
+   *   expect(user).toBeDefined();
+   * });
+   * ```
+   */
   wrapVitestWithTransaction(
     conn: Connection,
     setup?: (trx: Transaction) => Promise<void>,
     level: IsolationLevel = IsolationLevel.REPEATABLE_READ,
   ) {
-    return base.extend<DatabaseFixtures<Transaction>>({
+    return this.api.extend<DatabaseFixtures<Transaction>>({
       // This fixture automatically provides a transaction to each test
       trx: async ({}, use) => {
         // Create a custom error class for rollback

package/src/__tests__/KyselyFactory.spec.ts

@@ -1,13 +1,14 @@
-import type { ControlledTransaction, Kysely } from 'kysely';
 import pg from 'pg';
-import { describe, expect } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { TEST_DATABASE_CONFIG } from '../../test/globalSetup';
 import { type TestDatabase, createTestTables } from '../../test/helpers';
 import { KyselyFactory } from '../KyselyFactory';
-import { createKyselyDb, wrapVitestKyselyTransaction } from '../helpers';
+import { createKyselyDb } from '../helpers';
+import { wrapVitestKyselyTransaction } from '../kysely';
 
 const db = createKyselyDb<TestDatabase>(TEST_DATABASE_CONFIG);
 const itWithTransaction = wrapVitestKyselyTransaction<TestDatabase>(
+  it,
   db,
   createTestTables,
 );
@@ -17,9 +18,6 @@ pg.types.setTypeParser(int8TypeId, (val) => {
   return parseInt(val, 10);
 });
 describe('KyselyFactory', () => {
-  let db: Kysely<TestDatabase>;
-  let trx: ControlledTransaction<TestDatabase, []>;
-
   describe('KyselyFactory.insert', () => {
     itWithTransaction(
       'should insert a record with defaults',

package/src/__tests__/integration.spec.ts

@@ -1,11 +1,16 @@
-import { beforeAll, describe, expect } from 'vitest';
+import { it as base, beforeAll, describe, expect } from 'vitest';
 import { TEST_DATABASE_CONFIG } from '../../test/globalSetup';
 import { type TestDatabase, createTestTables } from '../../test/helpers';
 import { KyselyFactory } from '../KyselyFactory';
-import { createKyselyDb, wrapVitestKyselyTransaction } from '../helpers';
+import { createKyselyDb } from '../helpers';
+import { wrapVitestKyselyTransaction } from '../kysely';
 
 const db = createKyselyDb<TestDatabase>(TEST_DATABASE_CONFIG);
-const it = wrapVitestKyselyTransaction<TestDatabase>(db, createTestTables);
+const it = wrapVitestKyselyTransaction<TestDatabase>(
+  base,
+  db,
+  createTestTables,
+);
 describe('Testkit Integration Tests', () => {
   beforeAll(async () => {});
   describe('Complex Factory Scenarios', () => {

package/src/faker.ts

@@ -3,15 +3,39 @@ import { faker as baseFaker } from '@faker-js/faker';
 // NOTE: This is a simple way to extend `faker` with additional methods
 
 /**
- * Atomic counter implementation for thread-safe sequence generation
+ * Atomic counter implementation for thread-safe sequence generation.
+ * Provides a clean abstraction for generating sequential numbers in tests.
+ * While JavaScript is single-threaded, this class makes the intent explicit.
+ *
+ * @example
+ * ```typescript
+ * const counter = new AtomicCounter(100);
+ * console.log(counter.increment()); // 101
+ * console.log(counter.increment()); // 102
+ * console.log(counter.get()); // 102
+ * counter.reset(200);
+ * console.log(counter.increment()); // 201
+ * ```
  */
 class AtomicCounter {
+  /**
+   * The current counter value.
+   * @private
+   */
   private value: number;
 
+  /**
+   * Creates a new atomic counter.
+   * @param initialValue - The starting value (default: 0)
+   */
   constructor(initialValue = 0) {
     this.value = initialValue;
   }
 
+  /**
+   * Increments the counter and returns the new value.
+   * @returns The incremented value
+   */
   increment(): number {
     // In Node.js, JavaScript is single-threaded within the event loop,
     // so this operation is already atomic. However, this class provides
@@ -19,17 +43,42 @@ class AtomicCounter {
     return ++this.value;
   }
 
+  /**
+   * Gets the current counter value without incrementing.
+   * @returns The current value
+   */
   get(): number {
     return this.value;
   }
 
+  /**
+   * Resets the counter to a specific value.
+   * @param value - The new value (default: 0)
+   */
   reset(value = 0): void {
     this.value = value;
   }
 }
 
 /**
- * Sets the `insertedAt` and `updatedAt` to a random date in the past.
+ * Generates random timestamp fields for database records.
+ * Creates a createdAt date in the past and an updatedAt date between creation and now.
+ * Milliseconds are set to 0 for cleaner database storage.
+ *
+ * @returns Object with createdAt and updatedAt Date fields
+ *
+ * @example
+ * ```typescript
+ * const { createdAt, updatedAt } = timestamps();
+ * console.log(createdAt); // 2023-05-15T10:30:00.000Z
+ * console.log(updatedAt); // 2023-11-20T14:45:00.000Z
+ *
+ * // Use in factory
+ * const user = {
+ *   name: 'John Doe',
+ *   ...timestamps()
+ * };
+ * ```
  */
 export function timestamps(): Timestamps {
   const createdAt = faker.date.past();
@@ -45,7 +94,18 @@ export function timestamps(): Timestamps {
 }
 
 /**
- * Returns a reverse domain name identifier.
+ * Generates a reverse domain name identifier.
+ * Useful for creating unique identifiers that follow domain naming conventions.
+ *
+ * @param suffix - Optional suffix to append to the identifier
+ * @returns A reverse domain name string (e.g., "com.example.feature123")
+ *
+ * @example
+ * ```typescript
+ * console.log(identifier()); // "com.example.widget1"
+ * console.log(identifier('user')); // "org.acme.user"
+ * console.log(identifier('api')); // "net.demo.api"
+ * ```
  */
 export function identifier(suffix?: string): string {
   return [
@@ -55,9 +115,33 @@ export function identifier(suffix?: string): string {
   ].join('.');
 }
 
-// Atomic sequences for thread-safe counter generation
+/**
+ * Storage for named sequence counters.
+ * Each sequence maintains its own independent counter.
+ * @private
+ */
 const sequences = new Map<string, AtomicCounter>();
 
+/**
+ * Generates sequential numbers for a named sequence.
+ * Useful for creating unique IDs or numbered test data.
+ * Each named sequence maintains its own counter.
+ *
+ * @param name - The sequence name (default: 'default')
+ * @returns The next number in the sequence
+ *
+ * @example
+ * ```typescript
+ * console.log(sequence()); // 1
+ * console.log(sequence()); // 2
+ * console.log(sequence('user')); // 1
+ * console.log(sequence('user')); // 2
+ * console.log(sequence()); // 3
+ *
+ * // Use in factories
+ * const email = `user${sequence('email')}@example.com`;
+ * ```
+ */
 export function sequence(name = 'default'): number {
   if (!sequences.has(name)) {
     sequences.set(name, new AtomicCounter());
@@ -68,7 +152,22 @@ export function sequence(name = 'default'): number {
 }
 
 /**
- * Resets a sequence counter to a specific value (default: 0)
+ * Resets a named sequence counter to a specific value.
+ * Useful for resetting sequences between test suites.
+ *
+ * @param name - The sequence name to reset (default: 'default')
+ * @param value - The new starting value (default: 0)
+ *
+ * @example
+ * ```typescript
+ * sequence('user'); // 1
+ * sequence('user'); // 2
+ * resetSequence('user');
+ * sequence('user'); // 1
+ *
+ * resetSequence('order', 1000);
+ * sequence('order'); // 1001
+ * ```
  */
 export function resetSequence(name = 'default', value = 0): void {
   if (sequences.has(name)) {
@@ -80,19 +179,61 @@ export function resetSequence(name = 'default', value = 0): void {
 }
 
 /**
- * Resets all sequence counters
+ * Resets all sequence counters.
+ * Useful for cleaning up between test suites to ensure predictable sequences.
+ *
+ * @example
+ * ```typescript
+ * // In test setup
+ * beforeEach(() => {
+ *   resetAllSequences();
+ * });
+ *
+ * it('starts sequences from 1', () => {
+ *   expect(sequence()).toBe(1);
+ *   expect(sequence('user')).toBe(1);
+ * });
+ * ```
  */
 export function resetAllSequences(): void {
   sequences.clear();
 }
 
 /**
- * Returns a random price number.
+ * Generates a random price as a number.
+ * Converts faker's string price to a numeric value.
+ *
+ * @returns A random price number
+ *
+ * @example
+ * ```typescript
+ * const productPrice = price(); // 29.99
+ * const total = price() * quantity; // Numeric calculation
+ * ```
  */
 function price(): number {
   return +faker.commerce.price();
 }
 
+/**
+ * Enhanced faker instance with additional utility methods for testing.
+ * Extends @faker-js/faker with custom methods for common test data generation patterns.
+ *
+ * @example
+ * ```typescript
+ * import { faker } from '@geekmidas/testkit';
+ *
+ * // Use standard faker methods
+ * const name = faker.person.fullName();
+ * const email = faker.internet.email();
+ *
+ * // Use custom extensions
+ * const { createdAt, updatedAt } = faker.timestamps();
+ * const id = faker.identifier('user');
+ * const orderNumber = faker.sequence('order');
+ * const productPrice = faker.price();
+ * ```
+ */
 export const faker = Object.freeze(
   Object.assign({}, baseFaker, {
     timestamps,
@@ -104,9 +245,19 @@ export const faker = Object.freeze(
   }),
 );
 
+/**
+ * Type definition for timestamp fields.
+ * Used by the timestamps() function to generate date fields.
+ */
 export type Timestamps = {
+  /** The creation date */
   createdAt: Date;
+  /** The last update date */
   updatedAt: Date;
 };
 
+/**
+ * Type definition for the enhanced faker factory.
+ * Includes all standard faker methods plus custom extensions.
+ */
 export type FakerFactory = typeof faker;