@geekmidas/testkit 0.0.6 → 0.0.7

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;

package/src/helpers.ts

@@ -1,6 +1,40 @@
 import { CamelCasePlugin, Kysely, PostgresDialect } from 'kysely';
 import pg from 'pg';
 
+/**
+ * Creates a Kysely database instance with PostgreSQL dialect and camelCase plugin.
+ * This is a convenience function for quickly setting up a Kysely connection for testing.
+ *
+ * @template Database - The database schema type
+ * @param config - PostgreSQL connection configuration (pg.Pool config)
+ * @returns A configured Kysely instance
+ *
+ * @example
+ * ```typescript
+ * interface Database {
+ *   users: UsersTable;
+ *   posts: PostsTable;
+ * }
+ *
+ * // Create from connection string
+ * const db = createKyselyDb<Database>({
+ *   connectionString: 'postgresql://user:pass@localhost:5432/testdb'
+ * });
+ *
+ * // Create with detailed config
+ * const db = createKyselyDb<Database>({
+ *   host: 'localhost',
+ *   port: 5432,
+ *   database: 'testdb',
+ *   user: 'testuser',
+ *   password: 'testpass',
+ *   max: 10 // connection pool size
+ * });
+ *
+ * // Use in tests
+ * const users = await db.selectFrom('users').selectAll().execute();
+ * ```
+ */
 export function createKyselyDb<Database>(config: any): Kysely<Database> {
   return new Kysely({
     dialect: new PostgresDialect({

package/src/kysely.ts

@@ -3,9 +3,72 @@ import type { TestAPI } from 'vitest';
 import { VitestKyselyTransactionIsolator } from './VitestKyselyTransactionIsolator';
 import { IsolationLevel } from './VitestTransactionIsolator';
 
+/**
+ * Kysely-specific exports for test utilities.
+ * Provides factories, migrators, and transaction isolators for Kysely ORM.
+ */
+
 export { KyselyFactory } from './KyselyFactory';
 export { PostgresKyselyMigrator } from './PostgresKyselyMigrator';
+export { VitestKyselyTransactionIsolator } from './VitestKyselyTransactionIsolator';
+export { IsolationLevel } from './VitestTransactionIsolator';
 
+/**
+ * Creates a wrapped Vitest test API with automatic transaction rollback for Kysely.
+ * Each test runs in an isolated database transaction that is rolled back after completion.
+ * This ensures tests don't affect each other's data and run faster than truncating tables.
+ *
+ * @template Database - The database schema type
+ * @param api - The Vitest test API (usually `test` from vitest)
+ * @param db - The Kysely database instance
+ * @param setup - Optional setup function to run before each test in the transaction
+ * @param level - Transaction isolation level (defaults to REPEATABLE_READ)
+ * @returns A wrapped test API that provides transaction isolation
+ *
+ * @example
+ * ```typescript
+ * import { test } from 'vitest';
+ * import { wrapVitestKyselyTransaction } from '@geekmidas/testkit/kysely';
+ * import { db } from './database';
+ *
+ * // Create isolated test with automatic rollback
+ * const isolatedTest = wrapVitestKyselyTransaction(test, db);
+ *
+ * // Use in tests - each test gets its own transaction
+ * isolatedTest('should create user', async ({ trx }) => {
+ *   const user = await trx
+ *     .insertInto('users')
+ *     .values({ name: 'Test User', email: 'test@example.com' })
+ *     .returningAll()
+ *     .executeTakeFirst();
+ *
+ *   expect(user).toBeDefined();
+ *   // User is automatically rolled back after test
+ * });
+ *
+ * // With setup function for common test data
+ * const testWithSetup = wrapVitestKyselyTransaction(
+ *   test,
+ *   db,
+ *   async (trx) => {
+ *     // Create common test data
+ *     await trx.insertInto('settings')
+ *       .values({ key: 'test_mode', value: 'true' })
+ *       .execute();
+ *   }
+ * );
+ *
+ * testWithSetup('should have test settings', async ({ trx }) => {
+ *   const setting = await trx
+ *     .selectFrom('settings')
+ *     .where('key', '=', 'test_mode')
+ *     .selectAll()
+ *     .executeTakeFirst();
+ *
+ *   expect(setting?.value).toBe('true');
+ * });
+ * ```
+ */
 export function wrapVitestKyselyTransaction<Database>(
   api: TestAPI,
   db: Kysely<Database>,

package/src/objection.ts

@@ -1 +1,96 @@
+import type { Knex } from 'knex';
+import type { TestAPI } from 'vitest';
+import { VitestObjectionTransactionIsolator } from './VitestObjectionTransactionIsolator';
+import { IsolationLevel } from './VitestTransactionIsolator';
+
+/**
+ * Objection.js-specific exports for test utilities.
+ * Provides factory implementation for creating test data with Objection.js ORM
+ * and transaction isolation for test suites.
+ */
+
 export { ObjectionFactory } from './ObjectionFactory';
+export { VitestObjectionTransactionIsolator } from './VitestObjectionTransactionIsolator';
+export { IsolationLevel } from './VitestTransactionIsolator';
+
+/**
+ * Creates a wrapped Vitest test API with automatic transaction rollback for Objection.js.
+ * Each test runs in an isolated database transaction that is rolled back after completion.
+ * This ensures tests don't affect each other's data and run faster than truncating tables.
+ *
+ * @param api - The Vitest test API (usually `test` from vitest)
+ * @param knex - The Knex database connection instance
+ * @param setup - Optional setup function to run before each test in the transaction
+ * @param level - Transaction isolation level (defaults to REPEATABLE_READ)
+ * @returns A wrapped test API that provides transaction isolation
+ *
+ * @example
+ * ```typescript
+ * import { test } from 'vitest';
+ * import { wrapVitestObjectionTransaction } from '@geekmidas/testkit/objection';
+ * import { knex } from './database';
+ * import { User, Post } from './models';
+ *
+ * // Create isolated test with automatic rollback
+ * const isolatedTest = wrapVitestObjectionTransaction(test, knex);
+ *
+ * // Use in tests - each test gets its own transaction
+ * isolatedTest('should create user', async ({ trx }) => {
+ *   const user = await User.query(trx)
+ *     .insert({ name: 'Test User', email: 'test@example.com' });
+ *
+ *   expect(user).toBeDefined();
+ *   // User is automatically rolled back after test
+ * });
+ *
+ * // With setup function for common test data
+ * const testWithSetup = wrapVitestObjectionTransaction(
+ *   test,
+ *   knex,
+ *   async (trx) => {
+ *     // Create common test data
+ *     await knex('settings')
+ *       .transacting(trx)
+ *       .insert({ key: 'test_mode', value: 'true' });
+ *   }
+ * );
+ *
+ * testWithSetup('should have test settings', async ({ trx }) => {
+ *   const setting = await knex('settings')
+ *     .transacting(trx)
+ *     .where('key', 'test_mode')
+ *     .first();
+ *
+ *   expect(setting?.value).toBe('true');
+ * });
+ *
+ * // Example with factory and transaction
+ * const isolatedTest = wrapVitestObjectionTransaction(test, knex);
+ * const factory = new ObjectionFactory(builders, seeds, knex);
+ *
+ * isolatedTest('creates related data', async ({ trx }) => {
+ *   // Factory can use the transaction
+ *   const user = await User.query(trx).insert({ name: 'Author' });
+ *   const posts = await Post.query(trx).insert([
+ *     { title: 'Post 1', userId: user.id },
+ *     { title: 'Post 2', userId: user.id }
+ *   ]);
+ *
+ *   const userWithPosts = await User.query(trx)
+ *     .findById(user.id)
+ *     .withGraphFetched('posts');
+ *
+ *   expect(userWithPosts.posts).toHaveLength(2);
+ * });
+ * ```
+ */
+export function wrapVitestObjectionTransaction(
+  api: TestAPI,
+  knex: Knex,
+  setup?: (trx: Knex.Transaction) => Promise<void>,
+  level: IsolationLevel = IsolationLevel.REPEATABLE_READ,
+) {
+  const wrapper = new VitestObjectionTransactionIsolator(api);
+
+  return wrapper.wrapVitestWithTransaction(knex, setup, level);
+}

package/dist/Factory-DREHoms3.cjs

@@ -1,15 +0,0 @@
-
-//#region src/Factory.ts
-var Factory = class {
-	static createSeed(seedFn) {
-		return seedFn;
-	}
-};
-
-//#endregion
-Object.defineProperty(exports, 'Factory', {
-  enumerable: true,
-  get: function () {
-    return Factory;
-  }
-});

package/dist/Factory-DlzMkMzb.mjs

@@ -1,9 +0,0 @@
-//#region src/Factory.ts
-var Factory = class {
-	static createSeed(seedFn) {
-		return seedFn;
-	}
-};
-
-//#endregion
-export { Factory };

package/dist/KyselyFactory-BX7Kv2uP.cjs

@@ -1,65 +0,0 @@
-const require_Factory = require('./Factory-DREHoms3.cjs');
-const require_faker = require('./faker-caz-8zt8.cjs');
-
-//#region src/KyselyFactory.ts
-var KyselyFactory = class extends require_Factory.Factory {
-	static createSeed(seedFn) {
-		return require_Factory.Factory.createSeed(seedFn);
-	}
-	constructor(builders, seeds, db) {
-		super();
-		this.builders = builders;
-		this.seeds = seeds;
-		this.db = db;
-	}
-	static createBuilder(table, item, autoInsert) {
-		return async (attrs, factory, db, faker$1) => {
-			let data = { ...attrs };
-			if (item) {
-				const defaults = await item(attrs, factory, db, faker$1);
-				data = {
-					...defaults,
-					...data
-				};
-			}
-			if (autoInsert !== false) {
-				const result = await db.insertInto(table).values(data).returningAll().executeTakeFirst();
-				if (!result) throw new Error(`Failed to insert into ${table}`);
-				return result;
-			} else return {
-				table,
-				data
-			};
-		};
-	}
-	async insert(builderName, attrs) {
-		if (!(builderName in this.builders)) throw new Error(`Factory "${builderName}" does not exist. Make sure it is correct and registered in src/test/setup.ts`);
-		const result = await this.builders[builderName](attrs || {}, this, this.db, require_faker.faker);
-		if (result && typeof result === "object" && "table" in result && "data" in result) {
-			const inserted = await this.db.insertInto(result.table).values(result.data).returningAll().executeTakeFirst();
-			return inserted;
-		}
-		return result;
-	}
-	async insertMany(count, builderName, attrs) {
-		if (!(builderName in this.builders)) throw new Error(`Builder "${builderName}" is not registered in this factory. Make sure it is correct and registered in src/test/setup.ts`);
-		const promises = [];
-		for (let i = 0; i < count; i++) {
-			const newAttrs = typeof attrs === "function" ? attrs(i, require_faker.faker) : attrs;
-			promises.push(this.insert(builderName, newAttrs));
-		}
-		return Promise.all(promises);
-	}
-	seed(seedName, attrs) {
-		if (!(seedName in this.seeds)) throw new Error(`Seed "${seedName}" is not registered in this factory. Make sure it is correct and registered in src/test/setup.ts`);
-		return this.seeds[seedName](attrs || {}, this, this.db);
-	}
-};
-
-//#endregion
-Object.defineProperty(exports, 'KyselyFactory', {
-  enumerable: true,
-  get: function () {
-    return KyselyFactory;
-  }
-});

package/dist/KyselyFactory-pOMOFQWE.mjs

@@ -1,60 +0,0 @@
-import { Factory } from "./Factory-DlzMkMzb.mjs";
-import { faker } from "./faker-BwaXA_RF.mjs";
-
-//#region src/KyselyFactory.ts
-var KyselyFactory = class extends Factory {
-	static createSeed(seedFn) {
-		return Factory.createSeed(seedFn);
-	}
-	constructor(builders, seeds, db) {
-		super();
-		this.builders = builders;
-		this.seeds = seeds;
-		this.db = db;
-	}
-	static createBuilder(table, item, autoInsert) {
-		return async (attrs, factory, db, faker$1) => {
-			let data = { ...attrs };
-			if (item) {
-				const defaults = await item(attrs, factory, db, faker$1);
-				data = {
-					...defaults,
-					...data
-				};
-			}
-			if (autoInsert !== false) {
-				const result = await db.insertInto(table).values(data).returningAll().executeTakeFirst();
-				if (!result) throw new Error(`Failed to insert into ${table}`);
-				return result;
-			} else return {
-				table,
-				data
-			};
-		};
-	}
-	async insert(builderName, attrs) {
-		if (!(builderName in this.builders)) throw new Error(`Factory "${builderName}" does not exist. Make sure it is correct and registered in src/test/setup.ts`);
-		const result = await this.builders[builderName](attrs || {}, this, this.db, faker);
-		if (result && typeof result === "object" && "table" in result && "data" in result) {
-			const inserted = await this.db.insertInto(result.table).values(result.data).returningAll().executeTakeFirst();
-			return inserted;
-		}
-		return result;
-	}
-	async insertMany(count, builderName, attrs) {
-		if (!(builderName in this.builders)) throw new Error(`Builder "${builderName}" is not registered in this factory. Make sure it is correct and registered in src/test/setup.ts`);
-		const promises = [];
-		for (let i = 0; i < count; i++) {
-			const newAttrs = typeof attrs === "function" ? attrs(i, faker) : attrs;
-			promises.push(this.insert(builderName, newAttrs));
-		}
-		return Promise.all(promises);
-	}
-	seed(seedName, attrs) {
-		if (!(seedName in this.seeds)) throw new Error(`Seed "${seedName}" is not registered in this factory. Make sure it is correct and registered in src/test/setup.ts`);
-		return this.seeds[seedName](attrs || {}, this, this.db);
-	}
-};
-
-//#endregion
-export { KyselyFactory };

package/dist/ObjectionFactory-BlkzSEqo.cjs

@@ -1,41 +0,0 @@
-const require_Factory = require('./Factory-DREHoms3.cjs');
-
-//#region src/ObjectionFactory.ts
-var ObjectionFactory = class extends require_Factory.Factory {
-	static createSeed(seedFn) {
-		return require_Factory.Factory.createSeed(seedFn);
-	}
-	constructor(builders, seeds, db) {
-		super();
-		this.builders = builders;
-		this.seeds = seeds;
-		this.db = db;
-	}
-	insert(factory, attrs = {}) {
-		if (!(factory in this.builders)) throw new Error(`Factory "${factory}" does not exist. Make sure it is correct and registered in src/test/setup.ts`);
-		return this.builders[factory](attrs, {}, this.db).then((record) => {
-			return record.$query(this.db).insertGraph(record).execute();
-		});
-	}
-	insertMany(count, builderName, attrs = {}) {
-		if (!(builderName in this.builders)) throw new Error(`Builder "${builderName}" is not registered in this factory. Make sure it is correct and registered in src/test/setup.ts`);
-		const records = [];
-		for (let i = 0; i < count; i++) {
-			const newAttrs = typeof attrs === "function" ? attrs(i) : attrs;
-			records.push(this.builders[builderName](newAttrs, {}, this.db).then((record) => record.$query(this.db).insertGraph(record).execute()));
-		}
-		return Promise.all(records);
-	}
-	seed(seedName, attrs = {}) {
-		if (!(seedName in this.seeds)) throw new Error(`Seed "${seedName}" is not registered in this factory. Make sure it is correct and registered in src/test/setup.ts`);
-		return this.seeds[seedName](attrs, this, this.db);
-	}
-};
-
-//#endregion
-Object.defineProperty(exports, 'ObjectionFactory', {
-  enumerable: true,
-  get: function () {
-    return ObjectionFactory;
-  }
-});

package/dist/ObjectionFactory-ChuX8sZN.mjs

@@ -1,36 +0,0 @@
-import { Factory } from "./Factory-DlzMkMzb.mjs";
-
-//#region src/ObjectionFactory.ts
-var ObjectionFactory = class extends Factory {
-	static createSeed(seedFn) {
-		return Factory.createSeed(seedFn);
-	}
-	constructor(builders, seeds, db) {
-		super();
-		this.builders = builders;
-		this.seeds = seeds;
-		this.db = db;
-	}
-	insert(factory, attrs = {}) {
-		if (!(factory in this.builders)) throw new Error(`Factory "${factory}" does not exist. Make sure it is correct and registered in src/test/setup.ts`);
-		return this.builders[factory](attrs, {}, this.db).then((record) => {
-			return record.$query(this.db).insertGraph(record).execute();
-		});
-	}
-	insertMany(count, builderName, attrs = {}) {
-		if (!(builderName in this.builders)) throw new Error(`Builder "${builderName}" is not registered in this factory. Make sure it is correct and registered in src/test/setup.ts`);
-		const records = [];
-		for (let i = 0; i < count; i++) {
-			const newAttrs = typeof attrs === "function" ? attrs(i) : attrs;
-			records.push(this.builders[builderName](newAttrs, {}, this.db).then((record) => record.$query(this.db).insertGraph(record).execute()));
-		}
-		return Promise.all(records);
-	}
-	seed(seedName, attrs = {}) {
-		if (!(seedName in this.seeds)) throw new Error(`Seed "${seedName}" is not registered in this factory. Make sure it is correct and registered in src/test/setup.ts`);
-		return this.seeds[seedName](attrs, this, this.db);
-	}
-};
-
-//#endregion
-export { ObjectionFactory };