@geekmidas/testkit 0.4.0 → 1.0.0

package/src/KyselyFactory.ts

@@ -1,11 +1,11 @@
 import type {
-  ControlledTransaction,
-  Insertable,
-  Kysely,
-  Selectable,
+	ControlledTransaction,
+	Insertable,
+	Kysely,
+	Selectable,
 } from 'kysely';
-import { type ExtractSeedAttrs, Factory, type FactorySeed } from './Factory.ts';
-import { type FakerFactory, faker } from './faker.ts';
+import { type ExtractSeedAttrs, Factory, type FactorySeed } from './Factory';
+import { type FakerFactory, faker } from './faker';
 
 /**
  * Factory implementation for Kysely ORM, providing test data creation utilities.
@@ -46,346 +46,346 @@ import { type FakerFactory, faker } from './faker.ts';
  * ```
  */
 export class KyselyFactory<
-  DB,
-  Builders extends Record<string, any>,
-  Seeds extends Record<string, any>,
+	DB,
+	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: 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);
-  }
+	/**
+	 * 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: KyselyFactory.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 new KyselyFactory instance.
-   *
-   * @param builders - Record of builder functions for creating individual entities
-   * @param seeds - Record of seed functions for creating complex test scenarios
-   * @param db - Kysely database instance or controlled transaction
-   */
-  constructor(
-    private builders: Builders,
-    private seeds: Seeds,
-    private db: Kysely<DB> | ControlledTransaction<DB, []>,
-  ) {
-    super();
-  }
+	/**
+	 * Creates a new KyselyFactory instance.
+	 *
+	 * @param builders - Record of builder functions for creating individual entities
+	 * @param seeds - Record of seed functions for creating complex test scenarios
+	 * @param db - Kysely database instance or controlled transaction
+	 */
+	constructor(
+		private builders: Builders,
+		private seeds: Seeds,
+		private db: Kysely<DB> | ControlledTransaction<DB, []>,
+	) {
+		super();
+	}
 
-  /**
-   * Creates a typed builder function for a specific database table.
-   * This is a utility method that helps create builders with proper type inference for Kysely.
-   *
-   * @template DB - The database schema type
-   * @template TableName - The name of the table (must be a key of DB)
-   * @template Attrs - The attributes type for the builder (defaults to Partial<Insertable>)
-   * @template Factory - The factory instance type
-   * @template Result - The result type (defaults to Selectable of the table)
-   *
-   * @param table - The name of the database table
-   * @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 = KyselyFactory.createBuilder<DB, 'users'>('users',
-   *   ({ 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 = KyselyFactory.createBuilder<DB, 'leaveTypes'>('leaveTypes',
-   *   ({ 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 = KyselyFactory.createBuilder<DB, 'addresses'>('addresses',
-   *   ({ attrs }) => ({
-   *     street: '123 Main St',
-   *     city: 'Anytown',
-   *     ...attrs
-   *   }),
-   *   false // Don't auto-insert
-   * );
-   * ```
-   */
-  static createBuilder<
-    DB,
-    TableName extends keyof DB & string,
-    Attrs extends Partial<Insertable<DB[TableName]>> = Partial<
-      Insertable<DB[TableName]>
-    >,
-    Factory = any,
-    Result = Selectable<DB[TableName]>,
-  >(
-    table: TableName,
-    defaults?: (context: {
-      attrs: Attrs;
-      factory: Factory;
-      db: Kysely<DB>;
-      faker: FakerFactory;
-    }) =>
-      | Partial<Insertable<DB[TableName]>>
-      | Promise<Partial<Insertable<DB[TableName]>>>,
-    autoInsert?: boolean,
-  ): (
-    attrs: Attrs,
-    factory: Factory,
-    db: Kysely<DB>,
-    faker: FakerFactory,
-  ) => Promise<Result> {
-    return async (
-      attrs: Attrs,
-      factory: Factory,
-      db: Kysely<DB>,
-      fakerInstance: FakerFactory,
-    ) => {
-      // Start with attributes
-      let data: Partial<Insertable<DB[TableName]>> = { ...attrs };
+	/**
+	 * Creates a typed builder function for a specific database table.
+	 * This is a utility method that helps create builders with proper type inference for Kysely.
+	 *
+	 * @template DB - The database schema type
+	 * @template TableName - The name of the table (must be a key of DB)
+	 * @template Attrs - The attributes type for the builder (defaults to Partial<Insertable>)
+	 * @template Factory - The factory instance type
+	 * @template Result - The result type (defaults to Selectable of the table)
+	 *
+	 * @param table - The name of the database table
+	 * @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 = KyselyFactory.createBuilder<DB, 'users'>('users',
+	 *   ({ 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 = KyselyFactory.createBuilder<DB, 'leaveTypes'>('leaveTypes',
+	 *   ({ 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 = KyselyFactory.createBuilder<DB, 'addresses'>('addresses',
+	 *   ({ attrs }) => ({
+	 *     street: '123 Main St',
+	 *     city: 'Anytown',
+	 *     ...attrs
+	 *   }),
+	 *   false // Don't auto-insert
+	 * );
+	 * ```
+	 */
+	static createBuilder<
+		DB,
+		TableName extends keyof DB & string,
+		Attrs extends Partial<Insertable<DB[TableName]>> = Partial<
+			Insertable<DB[TableName]>
+		>,
+		Factory = any,
+		Result = Selectable<DB[TableName]>,
+	>(
+		table: TableName,
+		defaults?: (context: {
+			attrs: Attrs;
+			factory: Factory;
+			db: Kysely<DB>;
+			faker: FakerFactory;
+		}) =>
+			| Partial<Insertable<DB[TableName]>>
+			| Promise<Partial<Insertable<DB[TableName]>>>,
+		autoInsert?: boolean,
+	): (
+		attrs: Attrs,
+		factory: Factory,
+		db: Kysely<DB>,
+		faker: FakerFactory,
+	) => Promise<Result> {
+		return async (
+			attrs: Attrs,
+			factory: Factory,
+			db: Kysely<DB>,
+			fakerInstance: FakerFactory,
+		) => {
+			// Start with attributes
+			let data: Partial<Insertable<DB[TableName]>> = { ...attrs };
 
-      // Apply defaults
-      if (defaults) {
-        const defaultValues = await defaults({
-          attrs,
-          factory,
-          db,
-          faker: fakerInstance,
-        });
-        data = { ...defaultValues, ...data };
-      }
+			// Apply defaults
+			if (defaults) {
+				const defaultValues = await defaults({
+					attrs,
+					factory,
+					db,
+					faker: fakerInstance,
+				});
+				data = { ...defaultValues, ...data };
+			}
 
-      // Handle insertion based on autoInsert flag
-      if (autoInsert !== false) {
-        // Auto insert is enabled by default
-        const result = await db
-          .insertInto(table)
-          .values(data as Insertable<DB[TableName]>)
-          .returningAll()
-          .executeTakeFirst();
+			// Handle insertion based on autoInsert flag
+			if (autoInsert !== false) {
+				// Auto insert is enabled by default
+				const result = await db
+					.insertInto(table)
+					.values(data as Insertable<DB[TableName]>)
+					.returningAll()
+					.executeTakeFirst();
 
-        if (!result) {
-          throw new Error(`Failed to insert into ${table}`);
-        }
+				if (!result) {
+					throw new Error(`Failed to insert into ${table}`);
+				}
 
-        return result as Result;
-      } else {
-        // Return object for factory to handle insertion
-        return { table, data } as any;
-      }
-    };
-  }
+				return result as Result;
+			} else {
+				// Return object for factory to handle insertion
+				return { table, data } as any;
+			}
+		};
+	}
 
-  /**
-   * Inserts a single record into the database using the specified builder.
-   * The builder function is responsible for generating the record data with defaults
-   * and the factory handles the actual database insertion.
-   *
-   * @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
-   * @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'
-   * });
-   *
-   * // Use the inserted record
-   * const post = await factory.insert('post', {
-   *   userId: user.id,
-   *   title: 'My First Post'
-   * });
-   * ```
-   */
-  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`,
-      );
-    }
+	/**
+	 * Inserts a single record into the database using the specified builder.
+	 * The builder function is responsible for generating the record data with defaults
+	 * and the factory handles the actual database insertion.
+	 *
+	 * @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
+	 * @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'
+	 * });
+	 *
+	 * // Use the inserted record
+	 * const post = await factory.insert('post', {
+	 *   userId: user.id,
+	 *   title: 'My First Post'
+	 * });
+	 * ```
+	 */
+	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,
-    );
+		const result = await this.builders[builderName](
+			attrs || {},
+			this,
+			this.db,
+			faker,
+		);
 
-    // For Kysely, we expect the builder to return an object with table and data properties
-    // or to handle the insertion itself and return the inserted record
-    if (
-      result &&
-      typeof result === 'object' &&
-      'table' in result &&
-      'data' in result
-    ) {
-      // If the builder returns {table: string, data: object}, we insert it
-      const inserted = await this.db
-        .insertInto(result.table)
-        .values(result.data)
-        .returningAll()
-        .executeTakeFirst();
+		// For Kysely, we expect the builder to return an object with table and data properties
+		// or to handle the insertion itself and return the inserted record
+		if (
+			result &&
+			typeof result === 'object' &&
+			'table' in result &&
+			'data' in result
+		) {
+			// If the builder returns {table: string, data: object}, we insert it
+			const inserted = await this.db
+				.insertInto(result.table)
+				.values(result.data)
+				.returningAll()
+				.executeTakeFirst();
 
-      return inserted as any;
-    }
+			return inserted as any;
+		}
 
-    // Otherwise, assume the builder handled the insertion itself
-    return result;
-  }
+		// Otherwise, assume the builder handled the 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.
-   *
-   * @template K - The builder name (must be a key of Builders)
-   * @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, faker) => ({
-   *   title: `Post ${idx + 1}`,
-   *   content: faker.lorem.paragraph(),
-   *   publishedAt: faker.date.past()
-   * }));
-   *
-   * // 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<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`,
-      );
-    }
+	/**
+	 * Inserts multiple records into the database using the specified builder.
+	 * Supports both static attributes and dynamic attribute generation via a function.
+	 *
+	 * @template K - The builder name (must be a key of Builders)
+	 * @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, faker) => ({
+	 *   title: `Post ${idx + 1}`,
+	 *   content: faker.lorem.paragraph(),
+	 *   publishedAt: faker.date.past()
+	 * }));
+	 *
+	 * // 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<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 promises: Promise<any>[] = [];
+		const promises: Promise<any>[] = [];
 
-    for (let i = 0; i < count; i++) {
-      const newAttrs =
-        typeof attrs === 'function' ? await attrs(i, faker) : attrs;
-      promises.push(this.insert(builderName, newAttrs));
-    }
+		for (let i = 0; i < count; i++) {
+			const newAttrs =
+				typeof attrs === 'function' ? await attrs(i, faker) : attrs;
+			promises.push(this.insert(builderName, newAttrs));
+		}
 
-    return Promise.all(promises);
-  }
+		return Promise.all(promises);
+	}
 
-  /**
-   * 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
-   * const company = await factory.seed('companyWithDepartments', {
-   *   departmentCount: 3,
-   *   employeesPerDepartment: 10
-   * });
-   * expect(company.departments).toHaveLength(3);
-   * ```
-   */
-  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`,
-      );
-    }
+	/**
+	 * 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
+	 * const company = await factory.seed('companyWithDepartments', {
+	 *   departmentCount: 3,
+	 *   employeesPerDepartment: 10
+	 * });
+	 * expect(company.departments).toHaveLength(3);
+	 * ```
+	 */
+	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,
-    });
-  }
+		return this.seeds[seedName]({
+			attrs: attrs || {},
+			factory: this,
+			db: this.db,
+		});
+	}
 }