@geekmidas/testkit 0.0.6 → 0.0.8

package/src/ObjectionFactory.ts

@@ -1,14 +1,65 @@
 import type { Knex } from 'knex';
 import { Factory, type FactorySeed } from './Factory.ts';
 
+/**
+ * Factory implementation for Objection.js ORM, providing test data creation utilities.
+ * Extends the base Factory class with Objection.js-specific database operations.
+ *
+ * @template Builders - Record of builder functions for creating entities
+ * @template Seeds - Record of seed functions for complex test scenarios
+ *
+ * @example
+ * ```typescript
+ * // Define your models with Objection.js
+ * class User extends Model {
+ *   static tableName = 'users';
+ * }
+ *
+ * // Create builders
+ * const builders = {
+ *   user: (attrs) => User.fromJson({
+ *     id: faker.string.uuid(),
+ *     name: faker.person.fullName(),
+ *     email: faker.internet.email(),
+ *     ...attrs
+ *   }),
+ *   post: (attrs) => Post.fromJson({
+ *     title: 'Test Post',
+ *     content: 'Test content',
+ *     ...attrs
+ *   })
+ * };
+ *
+ * // Create factory instance
+ * const factory = new ObjectionFactory(builders, seeds, knex);
+ *
+ * // Use in tests
+ * const user = await factory.insert('user', { name: 'John Doe' });
+ * ```
+ */
 export class ObjectionFactory<
   Builders extends Record<string, any>,
   Seeds extends Record<string, any>,
 > extends Factory<Builders, Seeds> {
+  /**
+   * Creates a typed seed function with proper type inference.
+   * Inherits from the base Factory class implementation.
+   *
+   * @template Seed - The seed function type
+   * @param seedFn - The seed function to wrap
+   * @returns The same seed function with proper typing
+   */
   static createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed {
     return Factory.createSeed(seedFn);
   }
 
+  /**
+   * Creates a new ObjectionFactory instance.
+   *
+   * @param builders - Record of builder functions for creating individual entities
+   * @param seeds - Record of seed functions for creating complex test scenarios
+   * @param db - Knex database connection instance
+   */
   constructor(
     private builders: Builders,
     private seeds: Seeds,
@@ -17,7 +68,37 @@ export class ObjectionFactory<
     super();
   }
 
-  insert(factory, attrs = {}) {
+  /**
+   * Inserts a single record into the database using the specified builder.
+   * Uses Objection.js's insertGraph method to handle nested relations.
+   *
+   * @param factory - The name of the builder to use
+   * @param attrs - Optional attributes to override builder defaults
+   * @returns A promise resolving to the inserted record with all relations
+   * @throws Error if the specified builder doesn't exist
+   *
+   * @example
+   * ```typescript
+   * // Insert with defaults
+   * const user = await factory.insert('user');
+   *
+   * // Insert with overrides
+   * const adminUser = await factory.insert('user', {
+   *   email: 'admin@example.com',
+   *   role: 'admin'
+   * });
+   *
+   * // Insert with nested relations
+   * const userWithProfile = await factory.insert('user', {
+   *   name: 'John Doe',
+   *   profile: {
+   *     bio: 'Software Developer',
+   *     avatar: 'avatar.jpg'
+   *   }
+   * });
+   * ```
+   */
+  insert(factory: keyof Builders, attrs: any = {}) {
     if (!(factory in this.builders)) {
       throw new Error(
         `Factory "${
@@ -30,7 +111,36 @@ export class ObjectionFactory<
       return record.$query(this.db).insertGraph(record).execute();
     }) as any;
   }
-  insertMany(count, builderName, attrs = {}) {
+  /**
+   * Inserts multiple records into the database using the specified builder.
+   * Supports both static attributes and dynamic attribute generation via a function.
+   *
+   * @param count - The number of records to insert
+   * @param builderName - The name of the builder to use
+   * @param attrs - Static attributes or a function that generates attributes for each record
+   * @returns A promise resolving to an array of inserted records
+   * @throws Error if the specified builder doesn't exist
+   *
+   * @example
+   * ```typescript
+   * // Insert multiple with same attributes
+   * const users = await factory.insertMany(5, 'user', { role: 'member' });
+   *
+   * // Insert multiple with dynamic attributes
+   * const posts = await factory.insertMany(10, 'post', (idx) => ({
+   *   title: `Post ${idx + 1}`,
+   *   content: `Content for post ${idx + 1}`,
+   *   publishedAt: new Date()
+   * }));
+   *
+   * // Create users with sequential emails
+   * const admins = await factory.insertMany(3, 'user', (idx) => ({
+   *   email: `admin${idx + 1}@example.com`,
+   *   role: 'admin'
+   * }));
+   * ```
+   */
+  insertMany(count: number, builderName: keyof Builders, attrs: any = {}) {
     if (!(builderName in this.builders)) {
       throw new Error(
         `Builder "${
@@ -52,7 +162,39 @@ export class ObjectionFactory<
 
     return Promise.all(records);
   }
-  seed(seedName, attrs = {}) {
+  /**
+   * Executes a seed function to create complex test scenarios with multiple related records.
+   * Seeds are useful for setting up complete test environments with realistic data relationships.
+   *
+   * @param seedName - The name of the seed to execute
+   * @param attrs - Optional configuration attributes for the seed
+   * @returns The result of the seed function (typically the primary record created)
+   * @throws Error if the specified seed doesn't exist
+   *
+   * @example
+   * ```typescript
+   * // Execute a simple seed
+   * const user = await factory.seed('userWithProfile');
+   *
+   * // Execute a seed with configuration
+   * const author = await factory.seed('authorWithBooks', {
+   *   bookCount: 5,
+   *   includeReviews: true
+   * });
+   *
+   * // Use seed result in tests with Objection.js relations
+   * const company = await factory.seed('companyWithDepartments', {
+   *   departmentCount: 3,
+   *   employeesPerDepartment: 10
+   * });
+   *
+   * // Access eager loaded relations
+   * const companyWithRelations = await Company.query()
+   *   .findById(company.id)
+   *   .withGraphFetched('[departments.employees]');
+   * ```
+   */
+  seed(seedName: keyof Seeds, attrs: any = {}) {
     if (!(seedName in this.seeds)) {
       throw new Error(
         `Seed "${

package/src/PostgresKyselyMigrator.ts

@@ -1,9 +1,56 @@
 import { type Kysely, type MigrationProvider, Migrator } from 'kysely';
 import { PostgresMigrator } from './PostgresMigrator';
 
+/**
+ * Default logger instance for migration operations.
+ */
 const logger = console;
 
+/**
+ * PostgreSQL migrator implementation for Kysely ORM.
+ * Extends PostgresMigrator to provide Kysely-specific migration functionality.
+ * Automatically creates test databases and applies migrations for testing environments.
+ *
+ * @example
+ * ```typescript
+ * import { FileMigrationProvider } from 'kysely';
+ * import { PostgresKyselyMigrator } from '@geekmidas/testkit';
+ *
+ * // Create migration provider
+ * const provider = new FileMigrationProvider({
+ *   fs: require('fs'),
+ *   path: require('path'),
+ *   migrationFolder: path.join(__dirname, 'migrations')
+ * });
+ *
+ * // Create Kysely instance
+ * const db = new Kysely<Database>({
+ *   dialect: new PostgresDialect({
+ *     pool: new Pool({ connectionString: uri })
+ *   })
+ * });
+ *
+ * // Create and use migrator
+ * const migrator = new PostgresKyselyMigrator({
+ *   uri: 'postgresql://localhost:5432/test_db',
+ *   db,
+ *   provider
+ * });
+ *
+ * const cleanup = await migrator.start();
+ * // Run tests...
+ * await cleanup();
+ * ```
+ */
 export class PostgresKyselyMigrator extends PostgresMigrator {
+  /**
+   * Creates a new PostgresKyselyMigrator instance.
+   *
+   * @param options - Configuration options
+   * @param options.uri - PostgreSQL connection URI
+   * @param options.db - Kysely database instance
+   * @param options.provider - Migration provider for locating migration files
+   */
   constructor(
     private options: {
       uri: string;
@@ -14,6 +61,13 @@ export class PostgresKyselyMigrator extends PostgresMigrator {
     super(options.uri);
   }
 
+  /**
+   * Executes Kysely 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> {
     const migrator = new Migrator({
       db: this.options.db,

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,74 @@
+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.toLowerCase() as Lowercase<IsolationLevel>;
+
+    await conn.transaction(
+      async (trx) => {
+        await fn(trx);
+      },
+      {
+        isolationLevel,
+      },
+    );
+  }
+}

package/src/VitestTransactionIsolator.ts

@@ -1,28 +1,123 @@
 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>,