@geekmidas/testkit 9.0.2 → 10.0.0-alpha.1

package/src/ObjectionFactory.ts

@@ -1,412 +0,0 @@
-import type { Knex } from 'knex';
-import type { Model } from 'objection';
-import { type ExtractSeedAttrs, Factory, type FactorySeed } from './Factory';
-import { type FakerFactory, faker } from './faker';
-
-/**
- * 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: ObjectionFactory.createBuilder(User, ({ attrs, faker }) => ({
- *     id: faker.string.uuid(),
- *     name: faker.person.fullName(),
- *     email: faker.internet.email(),
- *     ...attrs
- *   })),
- *   post: ObjectionFactory.createBuilder(Post, ({ attrs }) => ({
- *     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 (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 override createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed {
-		return Factory.createSeed(seedFn);
-	}
-
-	/**
-	 * Creates a typed builder function for Objection.js models.
-	 * This is a utility method that helps create builders with proper type inference.
-	 *
-	 * @template TModel - The Objection.js Model class type
-	 * @template Attrs - The attributes type for the builder (defaults to Partial of model)
-	 * @template Factory - The factory instance type
-	 * @template Result - The result type (defaults to the model instance)
-	 *
-	 * @param ModelClass - The Objection.js Model class
-	 * @param defaults - Optional function to provide default values (receives destructured context)
-	 * @param autoInsert - Whether to automatically insert the record (default: true)
-	 * @returns A builder function that creates and optionally inserts records
-	 *
-	 * @example
-	 * ```typescript
-	 * // Create a simple builder with defaults - destructure only what you need
-	 * const userBuilder = ObjectionFactory.createBuilder(User,
-	 *   ({ attrs, faker }) => ({
-	 *     id: faker.string.uuid(),
-	 *     name: faker.person.fullName(),
-	 *     email: faker.internet.email(),
-	 *     createdAt: new Date(),
-	 *     ...attrs
-	 *   })
-	 * );
-	 *
-	 * // Only need faker? Just destructure that
-	 * const leaveTypeBuilder = ObjectionFactory.createBuilder(LeaveType,
-	 *   ({ faker }) => ({
-	 *     name: faker.helpers.arrayElement(['Annual', 'Sick', 'Maternity']),
-	 *     code: faker.string.alpha({ length: 3, casing: 'upper' }),
-	 *   })
-	 * );
-	 *
-	 * // Create a builder that doesn't auto-insert (useful for nested inserts)
-	 * const addressBuilder = ObjectionFactory.createBuilder(Address,
-	 *   ({ attrs }) => ({
-	 *     street: '123 Main St',
-	 *     city: 'Anytown',
-	 *     ...attrs
-	 *   }),
-	 *   false // Don't auto-insert
-	 * );
-	 *
-	 * // Use with relations
-	 * const postBuilder = ObjectionFactory.createBuilder(Post,
-	 *   async ({ attrs, factory, faker }) => ({
-	 *     title: faker.lorem.sentence(),
-	 *     content: faker.lorem.paragraphs(),
-	 *     authorId: attrs.authorId || (await factory.insert('user')).id,
-	 *     ...attrs
-	 *   })
-	 * );
-	 * ```
-	 */
-	static createBuilder<
-		TModel extends typeof Model,
-		Attrs extends Partial<InstanceType<TModel>> = Partial<InstanceType<TModel>>,
-		Factory = any,
-		Result = InstanceType<TModel>,
-	>(
-		ModelClass: TModel,
-		defaults?: (context: {
-			attrs: Attrs;
-			factory: Factory;
-			db: Knex;
-			faker: FakerFactory;
-		}) =>
-			| Partial<InstanceType<TModel>>
-			| Promise<Partial<InstanceType<TModel>>>,
-		autoInsert?: boolean,
-	): (
-		attrs: Attrs,
-		factory: Factory,
-		db: Knex,
-		faker: FakerFactory,
-	) => Promise<Result> {
-		return async (
-			attrs: Attrs,
-			factory: Factory,
-			db: Knex,
-			fakerInstance: FakerFactory,
-		) => {
-			// Start with attributes
-			let data: Partial<InstanceType<TModel>> = { ...attrs };
-
-			// Apply defaults
-			if (defaults) {
-				const defaultValues = await defaults({
-					attrs,
-					factory,
-					db,
-					faker: fakerInstance,
-				});
-				data = { ...defaultValues, ...data };
-			}
-
-			// Create model instance
-			const model = ModelClass.fromJson(data) as InstanceType<TModel>;
-
-			// Handle insertion based on autoInsert flag
-			if (autoInsert !== false) {
-				// Auto insert is enabled by default
-				// Extract only defined values for insertion
-				const insertData = Object.entries(model).reduce((acc, [key, value]) => {
-					if (value !== undefined && key !== 'id') {
-						acc[key] = value;
-					}
-					return acc;
-				}, {} as any);
-
-				// Use static query method to insert data directly
-				const result = await ModelClass.query(db).insert(insertData);
-				return result as Result;
-			} else {
-				// Return model for factory to handle insertion
-				return model as Result;
-			}
-		};
-	}
-
-	/**
-	 * 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,
-		private db: Knex,
-	) {
-		super();
-	}
-
-	/**
-	 * Inserts a single record into the database using the specified builder.
-	 * Uses Objection.js's insertGraph method to handle nested relations.
-	 *
-	 * @template K - The builder name (must be a key of Builders)
-	 * @param builderName - 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'
-	 *   }
-	 * });
-	 * ```
-	 */
-	async insert<K extends keyof Builders>(
-		builderName: K,
-		attrs?: Parameters<Builders[K]>[0],
-	): Promise<Awaited<ReturnType<Builders[K]>>> {
-		if (!(builderName in this.builders)) {
-			throw new Error(
-				`Factory "${
-					builderName as string
-				}" 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 the builder returns a model instance, insert it
-		if (result && typeof result.$query === 'function') {
-			// Extract data from model, excluding undefined values and id
-			const insertData = Object.entries(result).reduce((acc, [key, value]) => {
-				if (value !== undefined && key !== 'id') {
-					acc[key] = value;
-				}
-				return acc;
-			}, {} as any);
-
-			// Use the model's constructor to get the query builder
-			return await result.constructor.query(this.db).insert(insertData);
-		}
-
-		// Otherwise, assume the builder handled insertion itself
-		return result;
-	}
-	/**
-	 * 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'
-	 * }));
-	 * ```
-	 */
-	// Method overloads for better type inference
-	async insertMany<K extends keyof Builders>(
-		count: number,
-		builderName: K,
-		attrs?: Parameters<Builders[K]>[0],
-	): Promise<Awaited<ReturnType<Builders[K]>>[]>;
-	async insertMany<K extends keyof Builders>(
-		count: number,
-		builderName: K,
-		attrs: (idx: number, faker: FakerFactory) => Parameters<Builders[K]>[0],
-	): Promise<Awaited<ReturnType<Builders[K]>>[]>;
-	async insertMany<K extends keyof Builders>(
-		count: number,
-		builderName: K,
-		attrs?: any,
-	): Promise<Awaited<ReturnType<Builders[K]>>[]> {
-		if (!(builderName in this.builders)) {
-			throw new Error(
-				`Builder "${
-					builderName as string
-				}" is not registered in this factory. Make sure it is correct and registered in src/test/setup.ts`,
-			);
-		}
-
-		const records: any[] = [];
-		for (let i = 0; i < count; i++) {
-			const newAttrs =
-				typeof attrs === 'function' ? await (attrs as any)(i, faker) : attrs;
-
-			records.push(
-				this.builders[builderName](newAttrs, this, this.db, faker).then(
-					(record: any) => {
-						// If the builder returns a model instance, insert it
-						if (record && typeof record.$query === 'function') {
-							// Extract data from model, excluding undefined values and id
-							const insertData = Object.entries(record).reduce(
-								(acc, [key, value]) => {
-									if (value !== undefined && key !== 'id') {
-										acc[key] = value;
-									}
-									return acc;
-								},
-								{} as any,
-							);
-
-							// Use the model's constructor to get the query builder
-							return record.constructor.query(this.db).insert(insertData);
-						}
-						// Otherwise, assume the builder handled insertion itself
-						return record;
-					},
-				),
-			);
-		}
-
-		return Promise.all(records);
-	}
-	/**
-	 * 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.
-	 *
-	 * @template K - The seed name (must be a key of Seeds)
-	 * @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<K extends keyof Seeds>(
-		seedName: K,
-		attrs?: ExtractSeedAttrs<Seeds[K]>,
-	): ReturnType<Seeds[K]> {
-		if (!(seedName in this.seeds)) {
-			throw new Error(
-				`Seed "${
-					seedName as string
-				}" is not registered in this factory. Make sure it is correct and registered in src/test/setup.ts`,
-			);
-		}
-
-		return this.seeds[seedName]({
-			attrs: attrs || {},
-			factory: this,
-			db: this.db,
-		});
-	}
-}

package/src/PostgresKyselyMigrator.ts

@@ -1,104 +0,0 @@
-import type { Kysely } from 'kysely';
-// `Migrator` and the `MigrationProvider` type moved from the root barrel ('kysely')
-// to the 'kysely/migration' subpath in kysely 0.29+.
-import { type MigrationProvider, Migrator } from 'kysely/migration';
-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();
- *
- * // With afterCreate hook to create per-app users
- * import { runInitScript } from '@geekmidas/testkit/postgres';
- *
- * const migrator = new PostgresKyselyMigrator({
- *   uri: 'postgresql://localhost:5432/test_db',
- *   db,
- *   provider,
- *   afterCreate: async (uri) => {
- *     await runInitScript('docker/postgres/init.sh', uri, env);
- *   },
- * });
- * ```
- */
-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
-	 * @param options.afterCreate - Optional hook called after database creation but before migrations
-	 */
-	constructor(
-		private options: {
-			uri: string;
-			db: Kysely<any>;
-			provider: MigrationProvider;
-			afterCreate?: (uri: string) => Promise<void>;
-		},
-	) {
-		super(options.uri, options.afterCreate);
-	}
-
-	/**
-	 * 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,
-			provider: this.options.provider,
-		});
-		const migrations = await migrator.migrateToLatest();
-
-		if (migrations.error) {
-			logger.error(migrations.error, `Failed to apply migrations`);
-			throw migrations.error;
-		}
-
-		await this.options.db.destroy();
-
-		logger.log(`Applied ${migrations.results?.length} migrations successfully`);
-	}
-}

package/src/PostgresMigrator.ts

@@ -1,193 +0,0 @@
-import pg from 'pg';
-
-const { Client } = 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);
-
-	const db = new Client({
-		user: url.username,
-		password: url.password,
-		host: url.hostname,
-		port: parseInt(url.port, 10),
-		database: 'postgres',
-	});
-
-	let database = url.pathname.slice(1);
-	if (database.includes('?')) {
-		database = database.substring(0, database.indexOf('?'));
-	}
-	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();
- *
- * // With afterCreate hook (e.g. run init script to create per-app users)
- * import { runInitScript } from '@geekmidas/testkit/postgres';
- *
- * const migrator = new MyMigrator(
- *   'postgresql://localhost:5432/test_db',
- *   async (uri) => {
- *     await runInitScript('docker/postgres/init.sh', uri, env);
- *   },
- * );
- * 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
-	 * @param afterCreate - Optional hook called after database creation but before migrations
-	 */
-	constructor(
-		private uri: string,
-		private afterCreate?: (uri: string) => Promise<void>,
-	) {}
-
-	/**
-	 * 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 }> {
-		const { database, db } = await setupClient(uri);
-		try {
-			await db.connect();
-			const result = await db.query(
-				`SELECT * FROM pg_catalog.pg_database WHERE datname = '${database}'`,
-			);
-
-			if (result.rowCount === 0) {
-				try {
-					await db.query(`CREATE DATABASE "${database}"`);
-				} catch (error: any) {
-					// 42P04 = duplicate_database — another process created it between our check and create
-					if (error?.code === '42P04') {
-						return { alreadyExisted: true };
-					}
-					throw error;
-				}
-			}
-
-			return {
-				alreadyExisted: result.rowCount ? result.rowCount > 0 : false,
-			};
-		} finally {
-			await db.end();
-		}
-	}
-
-	/**
-	 * 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 {
-			await db.connect();
-			await db.query(`DROP DATABASE "${database}"`);
-		} finally {
-			await db.end();
-		}
-	}
-
-	/**
-	 * 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 {
-			await PostgresMigrator.create(this.uri);
-			if (this.afterCreate) {
-				await this.afterCreate(this.uri);
-			}
-			await this.migrate();
-			logger.log(`Migrating database: ${database}`);
-			// Example: await db.query('CREATE TABLE example (id SERIAL PRIMARY KEY)');
-		} finally {
-			await db.end();
-		}
-
-		return async () => {
-			await PostgresMigrator.drop(this.uri);
-		};
-	}
-}