@geekmidas/testkit 9.0.2 → 10.0.0-alpha.0

package/src/faker.ts

@@ -1,349 +0,0 @@
-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.
- * 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
-		// a cleaner abstraction and makes the intent explicit.
-		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;
-	}
-}
-
-/**
- * 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();
-	const updatedAt = faker.date.between({
-		from: createdAt,
-		to: new Date(),
-	});
-
-	createdAt.setMilliseconds(0);
-	updatedAt.setMilliseconds(0);
-
-	return { createdAt, updatedAt };
-}
-
-/**
- * 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 [
-		faker.internet.domainSuffix(),
-		faker.internet.domainWord(),
-		suffix ? suffix : faker.internet.domainWord() + sequence('identifier'),
-	].join('.');
-}
-
-/**
- * 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());
-	}
-
-	const counter = sequences.get(name) as AtomicCounter;
-	return counter.increment();
-}
-
-/**
- * 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)) {
-		const counter = sequences.get(name) as AtomicCounter;
-		counter.reset(value);
-	} else {
-		sequences.set(name, new AtomicCounter(value));
-	}
-}
-
-/**
- * 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();
-}
-
-/**
- * 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();
-}
-
-type Coordinate = {
-	lat: number;
-	lng: number;
-};
-
-export function coordinateInRadius(
-	center: Coordinate,
-	radius: number,
-): Coordinate {
-	// Earth's radius in meters
-	const earth = 6378137;
-	// Convert radius from meters to degrees
-	const d = radius / earth;
-
-	// Random bearing and distance
-	const theta = 2 * Math.PI * Math.random();
-	const r = d * Math.sqrt(Math.random());
-
-	const lat1 = (center.lat * Math.PI) / 180;
-	const lng1 = (center.lng * Math.PI) / 180;
-
-	const lat2 = Math.asin(
-		Math.sin(lat1) * Math.cos(r) +
-			Math.cos(lat1) * Math.sin(r) * Math.cos(theta),
-	);
-	const lng2 =
-		lng1 +
-		Math.atan2(
-			Math.sin(theta) * Math.sin(r) * Math.cos(lat1),
-			Math.cos(r) - Math.sin(lat1) * Math.sin(lat2),
-		);
-
-	return {
-		lat: (lat2 * 180) / Math.PI,
-		lng: (lng2 * 180) / Math.PI,
-	};
-}
-
-function coordinateOutsideRadius(
-	center: Coordinate,
-	minRadiusMeters: number,
-	maxRadiusMeters: number,
-): Coordinate {
-	// Earth's radius in meters
-	const earth = 6378137;
-
-	// Convert radii from meters to radians
-	const minD = minRadiusMeters / earth;
-	const maxD = maxRadiusMeters / earth;
-
-	// Random bearing
-	const theta = 2 * Math.PI * Math.random();
-
-	// Random distance in annular ring (uniform distribution by area)
-	// For uniform distribution in annulus: r = sqrt(r_min² + (r_max² - r_min²) * random)
-	const r = Math.sqrt(
-		minD * minD + (maxD * maxD - minD * minD) * Math.random(),
-	);
-
-	const lat1 = (center.lat * Math.PI) / 180;
-	const lng1 = (center.lng * Math.PI) / 180;
-
-	const lat2 = Math.asin(
-		Math.sin(lat1) * Math.cos(r) +
-			Math.cos(lat1) * Math.sin(r) * Math.cos(theta),
-	);
-	const lng2 =
-		lng1 +
-		Math.atan2(
-			Math.sin(theta) * Math.sin(r) * Math.cos(lat1),
-			Math.cos(r) - Math.sin(lat1) * Math.sin(lat2),
-		);
-
-	// Normalize longitude to [-180, 180]
-	const normalizedLng = (((lng2 * 180) / Math.PI + 540) % 360) - 180;
-
-	return {
-		lat: (lat2 * 180) / Math.PI,
-		lng: normalizedLng,
-	};
-}
-
-/**
- * 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,
-		identifier,
-		sequence,
-		resetSequence,
-		resetAllSequences,
-		price,
-		coordinates: {
-			within: coordinateInRadius,
-			outside: coordinateOutsideRadius,
-		},
-	}),
-);
-
-/**
- * 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,45 +0,0 @@
-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({
-			pool: new pg.Pool(config),
-		}),
-		plugins: [new CamelCasePlugin()],
-	});
-}

package/src/initScript.ts

@@ -1,122 +0,0 @@
-import { readFileSync } from 'node:fs';
-import pg from 'pg';
-
-const { Client } = pg;
-
-/**
- * Parse a shell init script (like docker/postgres/init.sh) and extract
- * SQL blocks from heredoc sections (<<-EOSQL ... EOSQL).
- *
- * @param content - The shell script content
- * @param env - Environment variables to substitute ($VAR_NAME references)
- * @returns Array of SQL strings ready to execute
- * @internal Exported for testing
- */
-export function parseInitScript(
-	content: string,
-	env: Record<string, string>,
-): string[] {
-	const blocks: string[] = [];
-	const lines = content.split('\n');
-	let inHeredoc = false;
-	let currentBlock: string[] = [];
-
-	for (const line of lines) {
-		if (inHeredoc) {
-			// Check for heredoc terminator (EOSQL at start of line, with optional leading whitespace)
-			if (/^\s*EOSQL\s*$/.test(line)) {
-				const sql = substituteEnvVars(currentBlock.join('\n'), env);
-				blocks.push(sql);
-				currentBlock = [];
-				inHeredoc = false;
-			} else {
-				currentBlock.push(line);
-			}
-		} else if (
-			line.includes('<<-EOSQL') ||
-			line.includes('<< EOSQL') ||
-			line.includes('<<EOSQL')
-		) {
-			inHeredoc = true;
-			currentBlock = [];
-		}
-	}
-
-	return blocks;
-}
-
-/**
- * Replace shell variable references ($VAR_NAME and ${VAR_NAME})
- * with values from the provided env object.
- */
-function substituteEnvVars(sql: string, env: Record<string, string>): string {
-	// Replace ${VAR_NAME} syntax
-	let result = sql.replace(/\$\{(\w+)\}/g, (_, name) => env[name] ?? '');
-	// Replace $VAR_NAME syntax (word boundary after)
-	result = result.replace(/\$(\w+)/g, (_, name) => env[name] ?? '');
-	// Unescape bash-escaped dollar signs (\$ → $) AFTER variable substitution
-	// This handles PL/pgSQL dollar-quoting like DO \$\$ ... END \$\$;
-	result = result.replace(/\\\$/g, '$');
-	return result;
-}
-
-/**
- * Read a postgres init script, parse out the SQL blocks,
- * substitute environment variables, and execute against a database.
- *
- * This is intended to run `docker/postgres/init.sh` against a test database
- * so that per-app users and schemas are created (matching what Docker does
- * on first volume initialization).
- *
- * Uses `CREATE ... IF NOT EXISTS` and `DO $$ ... END $$` wrappers where
- * needed so the script is idempotent.
- *
- * @param scriptPath - Path to the init.sh file
- * @param databaseUrl - PostgreSQL connection URL (should point to the test database)
- *
- * @example
- * ```typescript
- * // In your globalSetup.ts
- * import { runInitScript } from '@geekmidas/testkit/postgres';
- * import { Credentials } from '@geekmidas/envkit/credentials';
- *
- * const cleanup = await migrator.start();
- *
- * // Create per-app users in the test database
- * await runInitScript('docker/postgres/init.sh', Credentials.DATABASE_URL, {
- *   ...process.env,
- *   ...Credentials,
- * });
- * ```
- */
-export async function runInitScript(
-	scriptPath: string,
-	databaseUrl: string,
-	env?: Record<string, string>,
-): Promise<void> {
-	const content = readFileSync(scriptPath, 'utf-8');
-	const resolvedEnv = env ?? ({ ...process.env } as Record<string, string>);
-	const blocks = parseInitScript(content, resolvedEnv);
-
-	if (blocks.length === 0) {
-		return;
-	}
-
-	const url = new URL(databaseUrl);
-	const client = new Client({
-		user: url.username,
-		password: decodeURIComponent(url.password),
-		host: url.hostname,
-		port: parseInt(url.port, 10),
-		database: url.pathname.slice(1),
-	});
-
-	try {
-		await client.connect();
-		for (const sql of blocks) {
-			await client.query(sql);
-		}
-	} finally {
-		await client.end();
-	}
-}

package/src/kysely.ts

@@ -1,166 +0,0 @@
-import type { Kysely, Transaction } from 'kysely';
-import type { TestAPI } from 'vitest';
-import { VitestKyselyTransactionIsolator } from './VitestKyselyTransactionIsolator';
-import {
-	extendWithFixtures as baseExtendWithFixtures,
-	type DatabaseConnection,
-	type FixtureCreators,
-	type IsolationLevel,
-} from './VitestTransactionIsolator';
-
-/**
- * Kysely-specific exports for test utilities.
- * Provides factories, migrators, and transaction isolators for Kysely ORM.
- */
-
-export type { ExtractSeedAttrs, FactorySeed } from './Factory';
-export { KyselyFactory } from './KyselyFactory';
-export { PostgresKyselyMigrator } from './PostgresKyselyMigrator';
-export { VitestKyselyTransactionIsolator } from './VitestKyselyTransactionIsolator';
-export type {
-	DatabaseFixtures,
-	ExtendedDatabaseFixtures,
-	FixtureCreators,
-	TestWithExtendedFixtures,
-	TransactionWrapperOptions,
-} from './VitestTransactionIsolator';
-export { IsolationLevel } from './VitestTransactionIsolator';
-
-/**
- * Kysely-specific options for transaction wrapping.
- */
-export interface KyselyTransactionOptions<
-	Database,
-	Extended extends Record<string, unknown> = {},
-> {
-	/** Function that creates or returns a Kysely database instance */
-	connection: DatabaseConnection<Kysely<Database>>;
-	/** Optional setup function to run within the transaction before each test */
-	setup?: (trx: Transaction<Database>) => Promise<void>;
-	/** Transaction isolation level (defaults to REPEATABLE_READ) */
-	isolationLevel?: IsolationLevel;
-	/** Additional fixtures that depend on the transaction */
-	fixtures?: FixtureCreators<Transaction<Database>, Extended>;
-}
-
-// Re-export faker and FakerFactory for type portability in declaration files
-export { type FakerFactory, faker } from './faker';
-
-/**
- * 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
- * @template Extended - Additional fixtures to provide
- * @param api - The Vitest test API (usually `test` from vitest)
- * @param options - Configuration options for transaction wrapping
- * @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, {
- *   connection: 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();
- * });
- *
- * // With fixtures for factories
- * const it = wrapVitestKyselyTransaction<DB, { factory: Factory }>(test, {
- *   connection: db,
- *   fixtures: {
- *     factory: (trx) => new Factory(trx),
- *   },
- * });
- *
- * it('should create user with factory', async ({ trx, factory }) => {
- *   const user = await factory.insert('user', { name: 'Test' });
- *   expect(user.id).toBeDefined();
- * });
- * ```
- */
-export function wrapVitestKyselyTransaction<
-	Database,
-	Extended extends Record<string, unknown> = {},
->(api: TestAPI, options: KyselyTransactionOptions<Database, Extended>) {
-	const wrapper = new VitestKyselyTransactionIsolator<Database>(api);
-
-	return wrapper.wrapVitestWithTransaction(options);
-}
-
-/**
- * Extends a Kysely transaction-wrapped test with additional fixtures.
- * Each fixture receives the transaction and can create dependencies like factories or repositories.
- *
- * @template Database - The database schema type
- * @template Extended - The type of additional fixtures to provide
- * @param wrappedTest - The base wrapped test from wrapVitestKyselyTransaction
- * @param fixtures - Object mapping fixture names to creator functions
- * @returns An extended test API with both trx and the additional fixtures
- *
- * @example
- * ```typescript
- * import { test } from 'vitest';
- * import { wrapVitestKyselyTransaction, extendWithFixtures, KyselyFactory } from '@geekmidas/testkit/kysely';
- *
- * // Define your builders
- * const builders = {
- *   user: KyselyFactory.createBuilder<DB, 'users'>('users', ({ faker }) => ({
- *     name: faker.person.fullName(),
- *     email: faker.internet.email(),
- *   })),
- * };
- *
- * // Create base wrapped test
- * const baseTest = wrapVitestKyselyTransaction<DB>(test, {
- *   connection: db,
- *   setup: createTestTables,
- * });
- *
- * // Extend with fixtures - each fixture receives the transaction
- * const it = extendWithFixtures<DB, { factory: KyselyFactory<DB, typeof builders, {}> }>(
- *   baseTest,
- *   {
- *     factory: (trx) => new KyselyFactory(builders, {}, trx),
- *   }
- * );
- *
- * // Use in tests - both trx and factory are available
- * it('should create user with factory', async ({ trx, factory }) => {
- *   const user = await factory.insert('user', { name: 'Test User' });
- *   expect(user.id).toBeDefined();
- *
- *   // Verify in database
- *   const found = await trx
- *     .selectFrom('users')
- *     .where('id', '=', user.id)
- *     .selectAll()
- *     .executeTakeFirst();
- *   expect(found?.name).toBe('Test User');
- * });
- * ```
- */
-export function extendWithFixtures<
-	Database,
-	Extended extends Record<string, unknown>,
-	T extends ReturnType<TestAPI['extend']> = ReturnType<TestAPI['extend']>,
->(wrappedTest: T, fixtures: FixtureCreators<Transaction<Database>, Extended>) {
-	return baseExtendWithFixtures<Transaction<Database>, Extended, T>(
-		wrappedTest,
-		fixtures,
-	);
-}

package/src/logger.ts

@@ -1,18 +0,0 @@
-import type { Logger } from '@geekmidas/logger';
-import { vi } from 'vitest';
-
-/**
- * Creates a mock Logger for testing
- */
-export function createMockLogger(): Logger {
-	const logger: Logger = {
-		debug: vi.fn(),
-		info: vi.fn(),
-		warn: vi.fn(),
-		error: vi.fn(),
-		fatal: vi.fn(),
-		trace: vi.fn(),
-		child: vi.fn(() => logger),
-	};
-	return logger;
-}