@geekmidas/testkit 0.1.1 → 0.3.0

package/src/Factory.ts

@@ -39,7 +39,7 @@ export abstract class Factory<
    *
    * @example
    * ```typescript
-   * const userWithPostsSeed = Factory.createSeed(async (attrs, factory, db) => {
+   * const userWithPostsSeed = Factory.createSeed(async ({ attrs, factory, db }) => {
    *   const user = await factory.insert('user', attrs);
    *   return user;
    * });
@@ -86,7 +86,7 @@ export abstract class Factory<
    */
   abstract seed<K extends keyof Seeds>(
     seedName: K,
-    attrs?: Parameters<Seeds[K]>[0],
+    attrs?: ExtractSeedAttrs<Seeds[K]>,
   ): ReturnType<Seeds[K]>;
 }
 
@@ -133,15 +133,16 @@ export type MixedFactoryBuilder<
  * @template Result - The type of object returned by the seed
  * @template DB - The database connection type (Kysely, Knex, etc.)
  *
- * @param attrs - Configuration attributes for the seed
- * @param factory - The factory instance for creating records
- * @param db - The database connection
+ * @param context - Object containing attrs, factory, and db
+ * @param context.attrs - Configuration attributes for the seed
+ * @param context.factory - The factory instance for creating records
+ * @param context.db - The database connection
  * @returns A promise resolving to the seed result
  *
  * @example
  * ```typescript
  * const userWithPostsSeed: FactorySeed<{ postCount?: number }, Factory, User, DB> =
- *   async (attrs, factory, db) => {
+ *   async ({ attrs, factory, db }) => {
  *     const user = await factory.insert('user', attrs);
  *     const postCount = attrs.postCount || 3;
  *
@@ -153,8 +154,21 @@ export type MixedFactoryBuilder<
  *   };
  * ```
  */
-export type FactorySeed<Attrs = any, Factory = any, Result = any, DB = any> = (
-  attrs: Attrs,
-  factory: Factory,
-  db: DB,
-) => Promise<Result>;
+export type FactorySeed<
+  Attrs = any,
+  Factory = any,
+  Result = any,
+  DB = any,
+> = (context: { attrs: Attrs; factory: Factory; db: DB }) => Promise<Result>;
+
+/**
+ * Helper type to extract the Attrs type from a FactorySeed function.
+ * Used internally by Factory implementations to correctly type the seed method parameters.
+ */
+export type ExtractSeedAttrs<T> = T extends (context: {
+  attrs: infer A;
+  factory: any;
+  db: any;
+}) => any
+  ? A
+  : never;

package/src/KyselyFactory.ts

@@ -4,7 +4,7 @@ import type {
   Kysely,
   Selectable,
 } from 'kysely';
-import { Factory, type FactorySeed } from './Factory.ts';
+import { type ExtractSeedAttrs, Factory, type FactorySeed } from './Factory.ts';
 import { type FakerFactory, faker } from './faker.ts';
 
 /**
@@ -55,8 +55,21 @@ export class KyselyFactory<
    * Inherits from the base Factory class implementation.
    *
    * @template Seed - The seed function type
-   * @param seedFn - The seed function to wrap
+   * @param seedFn - The seed function to wrap (receives { attrs, factory, db } object)
    * @returns The same seed function with proper typing
+   *
+   * @example
+   * ```typescript
+   * const seeds = {
+   *   userWithPosts: KyselyFactory.createSeed(
+   *     async ({ attrs, factory }) => {
+   *       const user = await factory.insert('user', attrs);
+   *       await factory.insertMany(3, 'post', { userId: user.id });
+   *       return user;
+   *     },
+   *   ),
+   * };
+   * ```
    */
   static createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed {
     return Factory.createSeed(seedFn);
@@ -359,7 +372,7 @@ export class KyselyFactory<
    */
   seed<K extends keyof Seeds>(
     seedName: K,
-    attrs?: Parameters<Seeds[K]>[0],
+    attrs?: ExtractSeedAttrs<Seeds[K]>,
   ): ReturnType<Seeds[K]> {
     if (!(seedName in this.seeds)) {
       throw new Error(
@@ -369,6 +382,10 @@ export class KyselyFactory<
       );
     }
 
-    return this.seeds[seedName](attrs || {}, this, this.db);
+    return this.seeds[seedName]({
+      attrs: attrs || {},
+      factory: this,
+      db: this.db,
+    });
   }
 }

package/src/ObjectionFactory.ts

@@ -1,6 +1,6 @@
 import type { Knex } from 'knex';
 import type { Model } from 'objection';
-import { Factory, type FactorySeed } from './Factory.ts';
+import { type ExtractSeedAttrs, Factory, type FactorySeed } from './Factory.ts';
 import { type FakerFactory, faker } from './faker.ts';
 
 /**
@@ -48,8 +48,21 @@ export class ObjectionFactory<
    * Inherits from the base Factory class implementation.
    *
    * @template Seed - The seed function type
-   * @param seedFn - The seed function to wrap
+   * @param seedFn - The seed function to wrap (receives { attrs, factory, db } object)
    * @returns The same seed function with proper typing
+   *
+   * @example
+   * ```typescript
+   * const seeds = {
+   *   userWithPosts: ObjectionFactory.createSeed(
+   *     async ({ attrs, factory }) => {
+   *       const user = await factory.insert('user', attrs);
+   *       await factory.insertMany(3, 'post', { userId: user.id });
+   *       return user;
+   *     },
+   *   ),
+   * };
+   * ```
    */
   static createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed {
     return Factory.createSeed(seedFn);
@@ -381,7 +394,7 @@ export class ObjectionFactory<
    */
   seed<K extends keyof Seeds>(
     seedName: K,
-    attrs?: Parameters<Seeds[K]>[0],
+    attrs?: ExtractSeedAttrs<Seeds[K]>,
   ): ReturnType<Seeds[K]> {
     if (!(seedName in this.seeds)) {
       throw new Error(
@@ -391,6 +404,10 @@ export class ObjectionFactory<
       );
     }
 
-    return this.seeds[seedName](attrs || {}, this, this.db);
+    return this.seeds[seedName]({
+      attrs: attrs || {},
+      factory: this,
+      db: this.db,
+    });
   }
 }

package/src/VitestTransactionIsolator.ts

@@ -124,30 +124,59 @@ export abstract class VitestPostgresTransactionIsolator<TConn, Transaction> {
    * 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)
+   * @param options - Configuration options for transaction wrapping
    * @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' });
+   * 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 }) => {
-   *   const user = await trx.insert('users', { name: 'Test' });
+   * isolatedTest('test with transaction', async ({ trx, factory }) => {
+   *   const user = await factory.insert('user', { name: 'Test' });
    *   expect(user).toBeDefined();
    * });
    * ```
    */
-  wrapVitestWithTransaction(
-    createConnection: DatabaseConnection<TConn>,
-    setup?: (trx: Transaction) => Promise<void>,
-    level: IsolationLevel = IsolationLevel.REPEATABLE_READ,
+  wrapVitestWithTransaction<Extended extends Record<string, unknown> = {}>(
+    options: TransactionWrapperOptions<TConn, Transaction, Extended>,
   ) {
-    return this.api.extend<DatabaseFixtures<Transaction>>({
+    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 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
@@ -159,9 +188,9 @@ export abstract class VitestPostgresTransactionIsolator<TConn, Transaction> {
         }
 
         let testError: Error | undefined;
-        const conn = await createConnection();
+        const conn = await connection();
         try {
-          await this.transact(conn, level, async (transaction) => {
+          await this.transact(conn, isolationLevel, async (transaction) => {
             try {
               // Provide the transaction to the test
               await setup?.(transaction);
@@ -188,6 +217,7 @@ export abstract class VitestPostgresTransactionIsolator<TConn, Transaction> {
           await this.destroy(conn);
         }
       },
+      ...additionalFixtures,
     });
   }
 }
@@ -195,6 +225,24 @@ export abstract class VitestPostgresTransactionIsolator<TConn, Transaction> {
 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.
@@ -253,7 +301,10 @@ export type TestWithExtendedFixtures<
  * import { wrapVitestKyselyTransaction, extendWithFixtures } from '@geekmidas/testkit/kysely';
  *
  * // Create base wrapped test
- * const baseTest = wrapVitestKyselyTransaction(test, db, createTestTables);
+ * const baseTest = wrapVitestKyselyTransaction(test, {
+ *   connection: db,
+ *   setup: createTestTables,
+ * });
  *
  * // Extend with fixtures
  * const it = extendWithFixtures(baseTest, {

package/src/__tests__/Factory.spec.ts

@@ -46,7 +46,11 @@ describe('Factory', () => {
 
   describe('createSeed static method', () => {
     it('should return the seed function unchanged', () => {
-      const seedFn = async (attrs: any, factory: any, db: any) => {
+      const seedFn = async ({
+        attrs,
+        factory,
+        db,
+      }: { attrs: any; factory: any; db: any }) => {
         return { id: 1, name: 'test' };
       };
 
@@ -57,12 +61,14 @@ describe('Factory', () => {
     });
 
     it('should work with different seed function signatures', () => {
-      const simpleSeed = () => Promise.resolve({ simple: true });
-      const complexSeed = async (
-        attrs: { name: string },
-        factory: any,
-        db: any,
-      ) => {
+      const simpleSeed = async () => ({ simple: true });
+      const complexSeed = async ({
+        attrs,
+      }: {
+        attrs: { name: string };
+        factory: any;
+        db: any;
+      }) => {
         return { name: attrs.name, created: true };
       };
 
@@ -124,8 +130,8 @@ describe('Factory', () => {
     });
 
     it('should properly type FactorySeed', () => {
-      // Test that FactorySeed requires async return
-      const seed: FactorySeed = async (attrs, factory, db) => ({
+      // Test that FactorySeed requires async return with object parameter
+      const seed: FactorySeed = async ({ attrs, factory, db }) => ({
         seeded: true,
       });
 
@@ -155,7 +161,7 @@ describe('Factory types', () => {
       TestFactory,
       { created: number },
       any
-    > = async (attrs, factory, db) => {
+    > = async ({ attrs }) => {
       return { created: attrs.count };
     };
 

package/src/__tests__/KyselyFactory.spec.ts

@@ -7,11 +7,10 @@ import { createKyselyDb } from '../helpers';
 import { wrapVitestKyselyTransaction } from '../kysely';
 
 const db = () => createKyselyDb<TestDatabase>(TEST_DATABASE_CONFIG);
-const itWithTransaction = wrapVitestKyselyTransaction<TestDatabase>(
-  it,
-  db,
-  createTestTables,
-);
+const itWithTransaction = wrapVitestKyselyTransaction<TestDatabase>(it, {
+  connection: db,
+  setup: createTestTables,
+});
 
 const int8TypeId = 20;
 pg.types.setTypeParser(int8TypeId, (val) => {
@@ -280,7 +279,10 @@ describe('KyselyFactory', () => {
 
       const seeds = {
         createAdminUser: KyselyFactory.createSeed(
-          async (attrs: { name?: string }, factory: any, db: any) => {
+          async ({
+            attrs,
+            factory,
+          }: { attrs: { name?: string }; factory: any; db: any }) => {
             return await factory.insert('user', {
               name: attrs.name || 'Admin User',
               email: 'admin@example.com',
@@ -320,11 +322,14 @@ describe('KyselyFactory', () => {
 
         const seeds = {
           createCustomUser: KyselyFactory.createSeed(
-            async (
-              attrs: { name: string; email: string },
-              factory: any,
-              db: any,
-            ) => {
+            async ({
+              attrs,
+              factory,
+            }: {
+              attrs: { name: string; email: string };
+              factory: any;
+              db: any;
+            }) => {
               return await factory.insert('user', attrs);
             },
           ),

package/src/__tests__/ObjectionFactory.spec.ts

@@ -37,11 +37,10 @@ class Comment extends Model {
   user_id!: string;
 }
 
-const it = wrapVitestObjectionTransaction(
-  test,
-  createKnexDb,
-  createTestTablesKnex,
-);
+const it = wrapVitestObjectionTransaction(test, {
+  connection: createKnexDb,
+  setup: createTestTablesKnex,
+});
 describe('ObjectionFactory', () => {
   it('should create an ObjectionFactory instance', ({ trx }) => {
     const builders = {};
@@ -217,20 +216,22 @@ describe('ObjectionFactory', () => {
 
     const builders = { user: userBuilder };
 
-    const createAdminSeed = async (attrs: any, factory: any, db: Knex) => {
-      return await factory.insert('user', {
-        name: attrs.name || 'Admin User',
-      });
-    };
-
     const seeds = {
-      createAdmin: createAdminSeed,
+      createAdmin: ObjectionFactory.createSeed(
+        async ({
+          attrs,
+          factory,
+        }: { attrs: { name?: string }; factory: any; db: Knex }) => {
+          return await factory.insert('user', {
+            name: attrs.name || 'Admin User',
+          });
+        },
+      ),
     };
 
     const factory = new ObjectionFactory(builders, seeds, trx);
 
-    const attrs = { name: 'Super Admin' };
-    const result = await factory.seed('createAdmin', attrs);
+    const result = await factory.seed('createAdmin', { name: 'Super Admin' });
 
     expect(result).toBeInstanceOf(User);
     expect(result.name).toBe('Super Admin');
@@ -248,15 +249,15 @@ describe('ObjectionFactory', () => {
 
     const builders = { user: userBuilder };
 
-    const createAdminSeed = async (attrs: any, factory: any, db: Knex) => {
-      return await factory.insert('user', {
-        name: 'Default Admin',
-        role: 'admin',
-      });
-    };
-
     const seeds = {
-      createAdmin: createAdminSeed,
+      createAdmin: ObjectionFactory.createSeed(
+        async ({ factory }: { attrs: any; factory: any; db: Knex }) => {
+          return await factory.insert('user', {
+            name: 'Default Admin',
+            role: 'admin',
+          });
+        },
+      ),
     };
 
     const factory = new ObjectionFactory(builders, seeds, trx);
@@ -284,25 +285,28 @@ describe('ObjectionFactory', () => {
 
     const builders = { user: userBuilder };
 
-    const complexSeed = async (
-      attrs: any,
-      passedFactory: any,
-      passedDb: Knex,
-    ) => {
-      // Verify that factory and db are passed correctly
-      expect(passedFactory).toBe(factory);
-      expect(passedDb).toBe(trx);
-
-      return await passedFactory.insert('user', {
-        name: `Complex ${attrs.data}`,
-      });
-    };
+    let factoryRef: any;
 
     const seeds = {
-      complexSeed,
+      complexSeed: ObjectionFactory.createSeed(
+        async ({
+          attrs,
+          factory: passedFactory,
+          db: passedDb,
+        }: { attrs: { data: string }; factory: any; db: Knex }) => {
+          // Verify that factory and db are passed correctly
+          expect(passedFactory).toBe(factoryRef);
+          expect(passedDb).toBe(trx);
+
+          return await passedFactory.insert('user', {
+            name: `Complex ${attrs.data}`,
+          });
+        },
+      ),
     };
 
     const factory = new ObjectionFactory(builders, seeds, trx);
+    factoryRef = factory;
 
     const result = await factory.seed('complexSeed', { data: 'test' });
 
@@ -311,7 +315,7 @@ describe('ObjectionFactory', () => {
   });
 
   it('should return the seed function unchanged', () => {
-    const seedFn = async (attrs: any, factory: any, db: any) => {
+    const seedFn = async ({ attrs }: { attrs: any; factory: any; db: any }) => {
       return { id: 1, name: 'test' };
     };
 
@@ -482,12 +486,12 @@ describe('ObjectionFactory', () => {
   });
 
   it('should handle seed function errors gracefully', async ({ trx }) => {
-    const failingSeed = async (attrs: any, factory: any, db: Knex) => {
-      throw new Error('Seed failed');
-    };
-
     const seeds = {
-      failingSeed,
+      failingSeed: ObjectionFactory.createSeed(
+        async ({}: { attrs: any; factory: any; db: Knex }) => {
+          throw new Error('Seed failed');
+        },
+      ),
     };
 
     const factory = new ObjectionFactory({}, seeds, trx);
@@ -509,18 +513,22 @@ describe('ObjectionFactory', () => {
       });
     };
 
-    const adminSeed = async (
-      attrs: { isSuper?: boolean },
-      factory: any,
-      db: Knex,
-    ) => {
-      return factory.insert('user', {
-        name: 'Admin',
-      });
-    };
-
     const builders = { user: userBuilder };
-    const seeds = { admin: adminSeed };
+    const seeds = {
+      admin: ObjectionFactory.createSeed(
+        async ({
+          factory,
+        }: {
+          attrs: { isSuper?: boolean };
+          factory: any;
+          db: Knex;
+        }) => {
+          return factory.insert('user', {
+            name: 'Admin',
+          });
+        },
+      ),
+    };
 
     // This should compile without type errors
     const factory = new ObjectionFactory(builders, seeds, trx);

package/src/__tests__/VitestObjectionTransactionIsolator.spec.ts

@@ -108,9 +108,12 @@ class Comment extends Model {
 // Create database connection
 
 // Create wrapped test with transaction isolation
-const it = wrapVitestObjectionTransaction(base, createKnexDb, async (trx) => {
-  // Create tables in the transaction
-  await createTestTablesKnex(trx);
+const it = wrapVitestObjectionTransaction(base, {
+  connection: createKnexDb,
+  setup: async (trx) => {
+    // Create tables in the transaction
+    await createTestTablesKnex(trx);
+  },
 });
 
 describe('VitestObjectionTransactionIsolator', () => {

package/src/__tests__/integration.spec.ts

@@ -6,11 +6,10 @@ import { createKyselyDb } from '../helpers';
 import { extendWithFixtures, wrapVitestKyselyTransaction } from '../kysely';
 
 const db = () => createKyselyDb<TestDatabase>(TEST_DATABASE_CONFIG);
-const it = wrapVitestKyselyTransaction<TestDatabase>(
-  base,
-  db,
-  createTestTables,
-);
+const it = wrapVitestKyselyTransaction<TestDatabase>(base, {
+  connection: db,
+  setup: createTestTables,
+});
 describe('Testkit Integration Tests', () => {
   beforeAll(async () => {});
   describe('Complex Factory Scenarios', () => {
@@ -193,10 +192,14 @@ describe('Testkit Integration Tests', () => {
       // Create complex seeds
       const seeds = {
         blogWithAdminAndPosts: KyselyFactory.createSeed(
-          async (
-            attrs: { postCount?: number },
-            factory: KyselyFactory<TestDatabase, typeof builders, {}>,
-          ) => {
+          async ({
+            attrs,
+            factory,
+          }: {
+            attrs: { postCount?: number };
+            factory: KyselyFactory<TestDatabase, typeof builders, {}>;
+            db: any;
+          }) => {
             // Create admin user
             const admin = await factory.insert('user', {
               name: 'Blog Admin',
@@ -230,10 +233,14 @@ describe('Testkit Integration Tests', () => {
         ),
 
         usersWithPosts: KyselyFactory.createSeed(
-          async (
-            attrs: { userCount?: number; postsPerUser?: number },
-            factory: KyselyFactory<TestDatabase, typeof builders, {}>,
-          ) => {
+          async ({
+            attrs,
+            factory,
+          }: {
+            attrs: { userCount?: number; postsPerUser?: number };
+            factory: KyselyFactory<TestDatabase, typeof builders, {}>;
+            db: any;
+          }) => {
             const userCount = attrs.userCount || 2;
             const postsPerUser = attrs.postsPerUser || 2;
 
@@ -481,11 +488,10 @@ describe('extendWithFixtures', () => {
   };
 
   // Create base test with transaction
-  const baseTest = wrapVitestKyselyTransaction<TestDatabase>(
-    base,
-    db,
-    createTestTables,
-  );
+  const baseTest = wrapVitestKyselyTransaction<TestDatabase>(base, {
+    connection: db,
+    setup: createTestTables,
+  });
 
   // Extend with factory fixture
   const itWithFactory = extendWithFixtures<