@geekmidas/testkit 0.0.1

package/README.md

@@ -0,0 +1,383 @@
+# @geekmidas/testkit
+
+> Type-safe testing utilities and database factories for modern TypeScript applications
+
+[![Node Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## 🚀 Overview
+
+**@geekmidas/testkit** provides a comprehensive set of testing utilities designed to simplify database testing in TypeScript applications. It offers factory patterns for creating test data, supports multiple database libraries, and ensures type safety throughout your tests.
+
+### Key Features
+
+- 🏭 **Factory Pattern**: Create test data with minimal boilerplate
+- 🔒 **Type Safety**: Full TypeScript support with automatic schema inference
+- 🗄️ **Multi-Database Support**: Works with Kysely and Objection.js
+- 🔄 **Transaction Isolation**: Built-in support for test isolation
+- 🚀 **Performance**: Efficient batch operations and data seeding
+- 🧩 **Flexible**: Extensible architecture for custom implementations
+
+## 📦 Installation
+
+```bash
+npm install --save-dev @geekmidas/testkit
+# or
+pnpm add -D @geekmidas/testkit
+# or
+yarn add -D @geekmidas/testkit
+```
+
+## 🛠️ Quick Start
+
+### With Kysely
+
+```typescript
+import { KyselyFactory } from '@geekmidas/testkit/kysely';
+import { Kysely } from 'kysely';
+
+// Define your database schema
+interface Database {
+  users: {
+    id: number;
+    name: string;
+    email: string;
+    createdAt: Date;
+  };
+  posts: {
+    id: number;
+    title: string;
+    content: string;
+    userId: number;
+    publishedAt: Date | null;
+  };
+}
+
+// Create builders for your tables
+const userBuilder = KyselyFactory.createBuilder<Database, 'users'>({
+  table: 'users',
+  defaults: async () => ({
+    name: 'John Doe',
+    email: `user${Date.now()}@example.com`,
+    createdAt: new Date(),
+  }),
+});
+
+const postBuilder = KyselyFactory.createBuilder<Database, 'posts'>({
+  table: 'posts',
+  defaults: async () => ({
+    title: 'Test Post',
+    content: 'Lorem ipsum dolor sit amet',
+    publishedAt: null,
+  }),
+});
+
+// Initialize factory
+const builders = { user: userBuilder, post: postBuilder };
+const factory = new KyselyFactory(builders, {}, db);
+
+// Use in tests
+describe('User Service', () => {
+  it('should create a user with posts', async () => {
+    const user = await factory.insert('user', {
+      name: 'Jane Smith',
+      email: 'jane@example.com',
+    });
+
+    const posts = await factory.insertMany(3, 'post', {
+      userId: user.id,
+    });
+
+    expect(posts).toHaveLength(3);
+    expect(posts[0].userId).toBe(user.id);
+  });
+});
+```
+
+### With Objection.js
+
+```typescript
+import { ObjectionFactory } from '@geekmidas/testkit/objection';
+import { Model } from 'objection';
+
+// Define your models
+class User extends Model {
+  static tableName = 'users';
+  id!: number;
+  name!: string;
+  email!: string;
+}
+
+class Post extends Model {
+  static tableName = 'posts';
+  id!: number;
+  title!: string;
+  userId!: number;
+}
+
+// Create builders
+const userBuilder = {
+  table: 'users',
+  model: User,
+  defaults: async () => ({
+    name: 'John Doe',
+    email: `user${Date.now()}@example.com`,
+  }),
+};
+
+// Use in tests
+const factory = new ObjectionFactory({ user: userBuilder }, {});
+const user = await factory.insert('user', { name: 'Jane Doe' });
+```
+
+## 🏗️ Core Concepts
+
+### Builders
+
+Builders define how to create test data for each table. They specify:
+
+- **Table name**: The database table to insert into
+- **Default values**: Function returning default attributes
+- **Transformations**: Optional data transformations before insertion
+- **Relations**: Optional related data to create after insertion
+
+```typescript
+const userBuilder = KyselyFactory.createBuilder<Database, 'users'>({
+  table: 'users',
+  defaults: async () => ({
+    id: generateId(),
+    name: faker.person.fullName(),
+    email: faker.internet.email(),
+    createdAt: new Date(),
+  }),
+  transform: async (data) => ({
+    ...data,
+    email: data.email.toLowerCase(),
+  }),
+  relations: async (user, factory) => {
+    // Create related data after user insertion
+    await factory.insert('profile', { userId: user.id });
+  },
+});
+```
+
+### Seeds
+
+Seeds are functions that create complex test scenarios with multiple related entities:
+
+```typescript
+const blogSeed = async (factory: Factory) => {
+  const author = await factory.insert('user', {
+    name: 'Blog Author',
+    role: 'author',
+  });
+
+  const categories = await factory.insertMany(3, 'category');
+
+  const posts = await factory.insertMany(5, 'post', (index) => ({
+    title: `Post ${index + 1}`,
+    authorId: author.id,
+    categoryId: categories[index % categories.length].id,
+  }));
+
+  return { author, categories, posts };
+};
+
+// Use in tests
+const data = await factory.seed('blog');
+```
+
+### Transaction Support
+
+TestKit supports transaction-based test isolation:
+
+```typescript
+describe('User Service', () => {
+  let trx: Transaction<Database>;
+  let factory: KyselyFactory;
+
+  beforeEach(async () => {
+    trx = await db.transaction();
+    factory = new KyselyFactory(builders, seeds, trx);
+  });
+
+  afterEach(async () => {
+    await trx.rollback();
+  });
+
+  it('should perform operations in isolation', async () => {
+    const user = await factory.insert('user');
+    // Test operations...
+    // All changes will be rolled back after the test
+  });
+});
+```
+
+## 📚 Advanced Usage
+
+### Database Migration
+
+TestKit includes utilities for managing test database migrations:
+
+```typescript
+import { PostgresKyselyMigrator } from '@geekmidas/testkit/migrator/postgres-kysely';
+
+const migrator = new PostgresKyselyMigrator({
+  database: 'test_db',
+  connection: {
+    host: 'localhost',
+    port: 5432,
+    user: 'postgres',
+    password: 'password',
+  },
+  migrationFolder: './migrations',
+});
+
+// In test setup
+beforeAll(async () => {
+  const cleanup = await migrator.start();
+  // Database is created and migrations are run
+  
+  // Store cleanup function for later
+  globalThis.cleanupDb = cleanup;
+});
+
+afterAll(async () => {
+  await globalThis.cleanupDb?.();
+  // Database is dropped
+});
+```
+
+### Custom Factories
+
+You can extend the base Factory class for custom implementations:
+
+```typescript
+import { Factory } from '@geekmidas/testkit/factory';
+
+class MongoFactory extends Factory {
+  async performInsert(table: string, data: any) {
+    const collection = this.db.collection(table);
+    const result = await collection.insertOne(data);
+    return { ...data, _id: result.insertedId };
+  }
+
+  async performInsertMany(table: string, data: any[]) {
+    const collection = this.db.collection(table);
+    const result = await collection.insertMany(data);
+    return data.map((item, index) => ({
+      ...item,
+      _id: result.insertedIds[index],
+    }));
+  }
+}
+```
+
+### Dynamic Attributes
+
+Create dynamic attributes for each record in batch operations:
+
+```typescript
+const users = await factory.insertMany(10, 'user', (index) => ({
+  name: `User ${index + 1}`,
+  email: `user${index + 1}@example.com`,
+  isAdmin: index === 0, // First user is admin
+}));
+```
+
+### Conditional Auto-insertion
+
+Control whether builders automatically insert data:
+
+```typescript
+const draftBuilder = KyselyFactory.createBuilder<Database, 'posts'>({
+  table: 'posts',
+  defaults: async () => ({
+    title: 'Draft Post',
+    status: 'draft',
+  }),
+  autoInsert: false, // Don't insert automatically
+});
+
+// Manually handle the data
+const draftData = await draftBuilder.build();
+// Perform validation or modifications...
+const post = await db.insertInto('posts').values(draftData).execute();
+```
+
+## 🔧 API Reference
+
+### KyselyFactory
+
+```typescript
+class KyselyFactory<TBuilders, TSeeds> extends Factory {
+  constructor(
+    builders: TBuilders,
+    seeds: TSeeds,
+    db: Kysely<any> | Transaction<any>
+  );
+
+  static createBuilder<TDatabase, TTable>(
+    config: BuilderConfig<TDatabase, TTable>
+  ): Builder;
+
+  insert<K extends keyof TBuilders>(
+    name: K,
+    overrides?: Partial<BuilderOutput>
+  ): Promise<BuilderOutput>;
+
+  insertMany<K extends keyof TBuilders>(
+    count: number,
+    name: K,
+    overrides?: Partial<BuilderOutput> | ((index: number) => Partial<BuilderOutput>)
+  ): Promise<BuilderOutput[]>;
+
+  seed<K extends keyof TSeeds>(
+    name: K,
+    ...args: Parameters<TSeeds[K]>
+  ): Promise<ReturnType<TSeeds[K]>>;
+}
+```
+
+### ObjectionFactory
+
+```typescript
+class ObjectionFactory<TBuilders, TSeeds> extends Factory {
+  constructor(
+    builders: TBuilders,
+    seeds: TSeeds,
+    knex?: Knex
+  );
+
+  // Same methods as KyselyFactory
+}
+```
+
+### Builder Configuration
+
+```typescript
+interface BuilderConfig<TDatabase, TTable> {
+  table: TTable;
+  defaults: () => Promise<Insertable<TDatabase[TTable]>>;
+  transform?: (data: any) => Promise<any>;
+  relations?: (inserted: any, factory: Factory) => Promise<void>;
+  autoInsert?: boolean;
+}
+```
+
+## 🧪 Testing Best Practices
+
+1. **Use Transactions**: Always wrap tests in transactions for isolation
+2. **Create Minimal Data**: Only create the data necessary for each test
+3. **Use Seeds for Complex Scenarios**: Encapsulate complex setups in seeds
+4. **Leverage Type Safety**: Let TypeScript catch schema mismatches
+5. **Clean Up Resources**: Always clean up database connections and transactions
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@geekmidas/testkit",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    "./objection": "./src/ObjectionFactory.ts",
+    "./kysely": "./src/KyselyFactory.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/pg": "~8.15.4"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "peerDependencies": {
+    "kysely": "~0.28.2",
+    "pg": "~8.16.3",
+    "knex": "~3.1.0",
+    "objection": "~3.1.5",
+    "db-errors": "~0.2.3",
+    "@geekmidas/envkit": "0.0.1"
+  }
+}

package/src/Factory.ts

@@ -0,0 +1,58 @@
+export abstract class Factory<
+  Builders extends Record<string, any>,
+  Seeds extends Record<string, any>,
+> {
+  static createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed {
+    return seedFn;
+  }
+  /**
+   * Inserts an object into the database using a builder function.
+   *
+   * @param builderName - The name of the builder to use
+   * @param attrs - The attributes to insert
+   */
+  abstract insert<K extends keyof Builders>(
+    builderName: K,
+    attrs?: Parameters<Builders[K]>[0],
+  ): Promise<Awaited<ReturnType<Builders[K]>>>;
+
+  /**
+   * Inserts multiple objects into the database
+   *
+   * @param count -  Number of objects to insert
+   * @param builderName - The name of the builder to use
+   * @param attrs - The attributes to insert
+   */
+  abstract insertMany<K extends keyof Builders>(
+    count: number,
+    builderName: K,
+    attrs?:
+      | Parameters<Builders[K]>[0]
+      | ((idx: number) => Parameters<Builders[K]>[0]),
+  ): Promise<Awaited<ReturnType<Builders[K]>>[]>;
+
+  /**
+   * Seeds the database using a seed function.
+   *
+   * @param seedName - The name of the seed to use
+   * @returns The result of the seed function
+   * @param attrs - The attributes to pass to the seed function
+   */
+  abstract seed<K extends keyof Seeds>(
+    seedName: K,
+    attrs?: Parameters<Seeds[K]>[0],
+  ): ReturnType<Seeds[K]>;
+}
+
+export type MixedFactoryBuilder<
+  Attrs = any,
+  Factory = any,
+  Result = any,
+  DB = any,
+> = (attrs: Attrs, factory: Factory, db: DB) => Result | Promise<Result>;
+
+export type FactorySeed<Attrs = any, Factory = any, Result = any, DB = any> = (
+  attrs: Attrs,
+  factory: Factory,
+  db: DB,
+) => Promise<Result>;

package/src/KyselyFactory.ts

@@ -0,0 +1,183 @@
+import type {
+  ControlledTransaction,
+  Insertable,
+  Kysely,
+  Selectable,
+} from 'kysely';
+import { Factory, type FactorySeed } from './Factory.ts';
+
+export class KyselyFactory<
+  DB,
+  Builders extends Record<string, any>,
+  Seeds extends Record<string, any>,
+> extends Factory<Builders, Seeds> {
+  static createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed {
+    return Factory.createSeed(seedFn);
+  }
+
+  constructor(
+    private builders: Builders,
+    private seeds: Seeds,
+    private db: Kysely<DB> | ControlledTransaction<DB, []>,
+  ) {
+    super();
+  }
+
+  static createBuilder<
+    DB,
+    TableName extends keyof DB & string,
+    Attrs extends Partial<Insertable<DB[TableName]>> = Partial<
+      Insertable<DB[TableName]>
+    >,
+    Factory = any,
+    Result = Selectable<DB[TableName]>,
+  >(config: {
+    table: TableName;
+    defaults?: (
+      attrs: Attrs,
+      factory: Factory,
+      db: Kysely<DB>,
+    ) =>
+      | Partial<Insertable<DB[TableName]>>
+      | Promise<Partial<Insertable<DB[TableName]>>>;
+    transform?: (
+      data: Partial<Insertable<DB[TableName]>>,
+      factory: Factory,
+      db: Kysely<DB>,
+    ) =>
+      | Partial<Insertable<DB[TableName]>>
+      | Promise<Partial<Insertable<DB[TableName]>>>;
+    relations?: (
+      record: Result,
+      attrs: Attrs,
+      factory: Factory,
+      db: Kysely<DB>,
+    ) => Promise<void>;
+    autoInsert?: boolean;
+  }): (attrs: Attrs, factory: Factory, db: Kysely<DB>) => Promise<Result> {
+    return async (attrs: Attrs, factory: Factory, db: Kysely<DB>) => {
+      // Start with attributes
+      let data: Partial<Insertable<DB[TableName]>> = { ...attrs };
+
+      // Apply defaults
+      if (config.defaults) {
+        const defaults = await config.defaults(attrs, factory, db);
+        data = { ...defaults, ...data };
+      }
+
+      // Apply transformations
+      if (config.transform) {
+        data = await config.transform(data, factory, db);
+      }
+
+      // Handle insertion based on autoInsert flag
+      if (config.autoInsert !== false) {
+        // Auto insert is enabled by default
+        const result = await db
+          .insertInto(config.table)
+          .values(data as Insertable<DB[TableName]>)
+          .returningAll()
+          .executeTakeFirst();
+
+        if (!result) {
+          throw new Error(`Failed to insert into ${config.table}`);
+        }
+
+        // Handle relations if defined
+        if (config.relations) {
+          await config.relations(result as Result, attrs, factory, db);
+        }
+
+        return result as Result;
+      } else {
+        // Return object for factory to handle insertion
+        return { table: config.table, data } as any;
+      }
+    };
+  }
+
+  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);
+
+    // 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;
+    }
+
+    // Otherwise, assume the builder handled the insertion itself
+    return result;
+  }
+
+  // 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) => 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>[] = [];
+
+    for (let i = 0; i < count; i++) {
+      const newAttrs = typeof attrs === 'function' ? attrs(i) : attrs;
+      promises.push(this.insert(builderName, newAttrs));
+    }
+
+    return Promise.all(promises);
+  }
+
+  seed<K extends keyof Seeds>(
+    seedName: K,
+    attrs?: Parameters<Seeds[K]>[0],
+  ): 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 || {}, this, this.db);
+  }
+}

package/src/ObjectionFactory.ts

@@ -0,0 +1,66 @@
+import type { Knex } from 'knex';
+import { Factory, type FactorySeed } from './Factory.ts';
+
+export class ObjectionFactory<
+  Builders extends Record<string, any>,
+  Seeds extends Record<string, any>,
+> extends Factory<Builders, Seeds> {
+  static createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed {
+    return Factory.createSeed(seedFn);
+  }
+
+  constructor(
+    private builders: Builders,
+    private seeds: Seeds,
+    private db: Knex,
+  ) {
+    super();
+  }
+
+  insert(factory, attrs = {}) {
+    if (!(factory in this.builders)) {
+      throw new Error(
+        `Factory "${
+          factory as string
+        }" does not exist. Make sure it is correct and registered in src/test/setup.ts`,
+      );
+    }
+
+    return this.builders[factory](attrs, {}, this.db).then((record: any) => {
+      return record.$query(this.db).insertGraph(record).execute();
+    }) as any;
+  }
+  insertMany(count, builderName, attrs = {}) {
+    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' ? (attrs as any)(i) : attrs;
+
+      records.push(
+        this.builders[builderName](newAttrs, {}, this.db).then((record: any) =>
+          record.$query(this.db).insertGraph(record).execute(),
+        ),
+      );
+    }
+
+    return Promise.all(records);
+  }
+  seed(seedName, attrs = {}) {
+    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, this, this.db);
+  }
+}

package/src/PostgresKyselyMigrator.ts

@@ -0,0 +1,33 @@
+import { type Kysely, type MigrationProvider, Migrator } from 'kysely';
+import { PostgresMigrator } from './PostgresMigrator';
+
+const logger = console;
+
+export class PostgresKyselyMigrator extends PostgresMigrator {
+  constructor(
+    private options: {
+      uri: string;
+      db: Kysely<any>;
+      provider: MigrationProvider;
+    },
+  ) {
+    super(options.uri);
+  }
+
+  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

@@ -0,0 +1,76 @@
+import { Client } from 'pg';
+
+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),
+    database: 'postgres',
+  });
+
+  let database = url.pathname.slice(1);
+  if (database.includes('?')) {
+    database = database.substring(0, database.indexOf('?'));
+  }
+  return { database, db };
+}
+
+const logger = console;
+
+export abstract class PostgresMigrator {
+  constructor(private uri: string) {}
+
+  abstract migrate(): Promise<void>;
+
+  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) {
+        await db.query(`CREATE DATABASE "${database}"`);
+      }
+
+      return {
+        alreadyExisted: result.rowCount ? result.rowCount > 0 : false,
+      };
+    } finally {
+      await db.end();
+    }
+  }
+
+  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();
+    }
+  }
+
+  async start() {
+    const { database, db } = await setupClient(this.uri);
+    try {
+      await PostgresMigrator.create(this.uri);
+      // Implement migration logic here
+      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);
+    };
+  }
+}

package/src/__tests__/KyselyFactory.spec.ts

@@ -0,0 +1,83 @@
+import {
+  CamelCasePlugin,
+  type ControlledTransaction,
+  Kysely,
+  PostgresDialect,
+} from 'kysely';
+import pg from 'pg';
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+} from 'vitest';
+import { TEST_DATABASE_CONFIG } from '../../test/globalSetup';
+import { KyselyFactory } from '../KyselyFactory';
+
+describe('KyselyFactory', () => {
+  interface Database {
+    users: {
+      id: number;
+      name: string;
+      email: string;
+      createdAt: Date;
+    };
+    posts: {
+      id: number;
+      title: string;
+      content: string;
+      userId: number;
+      createdAt: Date;
+    };
+  }
+
+  let db: Kysely<Database>;
+  let trx: ControlledTransaction<Database, []>;
+  beforeAll(async () => {
+    db = new Kysely({
+      dialect: new PostgresDialect({
+        pool: new pg.Pool(TEST_DATABASE_CONFIG),
+      }),
+      plugins: [new CamelCasePlugin()],
+    });
+  });
+
+  beforeEach(async () => {
+    trx = await db.startTransaction().execute();
+  });
+  afterEach(async () => {
+    await trx.rollback().execute();
+  });
+
+  afterAll(async () => {
+    await db.destroy();
+  });
+  it('KyselyFactory.insert', async () => {
+    const userBuilder = KyselyFactory.createBuilder<Database, 'users'>({
+      table: 'users',
+      defaults: async (attrs) => ({
+        name: 'John Doe',
+      }),
+    });
+
+    const builders = {
+      user: userBuilder,
+    };
+
+    const factory = new KyselyFactory<Database, typeof builders, {}>(
+      builders,
+      {},
+      trx,
+    );
+
+    const user = await factory.insert('user', {
+      email: `user${Date.now()}@example.com`,
+      createdAt: new Date(),
+    });
+
+    expect(user).toBeDefined();
+  });
+});

package/src/example.ts

@@ -0,0 +1,45 @@
+import { KyselyFactory } from './KyselyFactory';
+
+interface Database {
+  users: {
+    id: number;
+    name: string;
+    email: string;
+    createdAt: Date;
+  };
+  posts: {
+    id: number;
+    title: string;
+    content: string;
+    userId: number;
+    createdAt: Date;
+  };
+}
+
+const userBuilder = KyselyFactory.createBuilder<Database, 'users'>({
+  table: 'users',
+  defaults: async (attrs) => ({
+    name: 'John Doe',
+    email: `user${Date.now()}@example.com`,
+    createdAt: new Date(),
+  }),
+});
+
+const builders = {
+  user: userBuilder,
+};
+
+export type Builders = typeof builders;
+export type Seeds = Record<string, any>;
+
+const factory = new KyselyFactory<Database, Builders, Seeds>(
+  builders,
+  {},
+  {} as any,
+);
+
+factory.insert('user', {
+  name: 'Jane Doe',
+  email: `user${Date.now()}@example.com`,
+  createdAt: new Date(),
+});

package/test/globalSetup.ts

@@ -0,0 +1,53 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import pg from 'pg';
+
+import {
+  CamelCasePlugin,
+  FileMigrationProvider,
+  Kysely,
+  PostgresDialect,
+} from 'kysely';
+
+import { PostgresKyselyMigrator } from '../src/PostgresKyselyMigrator';
+
+const TEST_DATABASE_NAME = 'geekmidas_test';
+
+const logger = console;
+
+export const TEST_DATABASE_CONFIG = {
+  host: 'localhost',
+  port: 5432,
+  user: 'geekmidas',
+  password: 'geekmidas',
+  database: TEST_DATABASE_NAME,
+};
+
+// password: get('Database.password').string(),
+//       user: get('Database.username').string(),
+//       database: get('Database.database').string(),
+//       host: get('Database.host').string(),
+//       port: get('Database.port').number().default(5432),
+
+export default async function globalSetup() {
+  const uri = `postgres://${TEST_DATABASE_CONFIG.user}:${TEST_DATABASE_CONFIG.password}@${TEST_DATABASE_CONFIG.host}:${TEST_DATABASE_CONFIG.port}/${TEST_DATABASE_CONFIG.database}`;
+
+  const migrationFolder = path.resolve(__dirname, './migrations');
+
+  const migrationProcessor = new PostgresKyselyMigrator({
+    uri,
+    db: new Kysely({
+      dialect: new PostgresDialect({
+        pool: new pg.Pool(TEST_DATABASE_CONFIG),
+      }),
+      plugins: [new CamelCasePlugin()],
+    }),
+    provider: new FileMigrationProvider({
+      fs,
+      path,
+      migrationFolder,
+    }),
+  });
+
+  return migrationProcessor.start();
+}

package/test/migrations/1749664623372_user.ts

@@ -0,0 +1,22 @@
+import { type Kysely, sql } from 'kysely';
+
+// `any` is required here since migrations should be frozen in time. alternatively, keep a "snapshot" db interface.
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('users')
+    .addColumn('id', 'bigserial', (col) => col.primaryKey())
+    .addColumn('email', 'varchar', (col) => col.notNull().unique())
+    .addColumn('name', 'varchar', (col) => col.notNull())
+    .addColumn('created_at', 'timestamp', (col) =>
+      col.defaultTo(sql`now()`).notNull(),
+    )
+    .addColumn('updated_at', 'timestamp', (col) =>
+      col.defaultTo(sql`now()`).notNull(),
+    )
+    .execute();
+}
+
+// `any` is required here since migrations should be frozen in time. alternatively, keep a "snapshot" db interface.
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('users').execute();
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    globalSetup: ['test/globalSetup.ts'],
+    pool: 'forks',
+  },
+});