@geekmidas/testkit 0.0.16 → 0.1.0

package/README.md

@@ -6,20 +6,21 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.8.2-blue)](https://www.typescriptlang.org)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-## 🚀 Overview
+## 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
+- **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
+- **Enhanced Faker**: Extended faker with timestamps, sequences, and coordinates
+- **AWS Mocks**: Mock Lambda contexts and API Gateway events
+- **Better Auth**: In-memory adapter for authentication testing
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install --save-dev @geekmidas/testkit
@@ -29,9 +30,22 @@ pnpm add -D @geekmidas/testkit
 yarn add -D @geekmidas/testkit
 ```
 
-## 🛠️ Quick Start
+## Subpath Exports
 
-### With Kysely
+```typescript
+import { KyselyFactory } from '@geekmidas/testkit/kysely';
+import { ObjectionFactory } from '@geekmidas/testkit/objection';
+import { faker } from '@geekmidas/testkit/faker';
+import { waitFor } from '@geekmidas/testkit/timer';
+import { itWithDir } from '@geekmidas/testkit/os';
+import { createMockContext, createMockV1Event, createMockV2Event } from '@geekmidas/testkit/aws';
+import { createMockLogger } from '@geekmidas/testkit/logger';
+import { memoryAdapter } from '@geekmidas/testkit/better-auth';
+```
+
+## Quick Start
+
+### Database Factories with Kysely
 
 ```typescript
 import { KyselyFactory } from '@geekmidas/testkit/kysely';
@@ -40,41 +54,43 @@ import { Kysely } from 'kysely';
 // Define your database schema
 interface Database {
   users: {
-    id: number;
+    id: string;
     name: string;
     email: string;
     createdAt: Date;
   };
   posts: {
-    id: number;
+    id: string;
     title: string;
     content: string;
-    userId: number;
-    publishedAt: Date | null;
+    userId: string;
   };
 }
 
 // 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,
-  }),
-});
+const builders = {
+  user: KyselyFactory.createBuilder<Database, 'users'>(
+    'users',
+    (attrs, factory, db, faker) => ({
+      id: faker.string.uuid(),
+      name: faker.person.fullName(),
+      email: faker.internet.email(),
+      createdAt: new Date(),
+      ...attrs,
+    })
+  ),
+  post: KyselyFactory.createBuilder<Database, 'posts'>(
+    'posts',
+    (attrs, factory, db, faker) => ({
+      id: faker.string.uuid(),
+      title: 'Test Post',
+      content: faker.lorem.paragraph(),
+      ...attrs,
+    })
+  ),
+};
 
 // Initialize factory
-const builders = { user: userBuilder, post: postBuilder };
 const factory = new KyselyFactory(builders, {}, db);
 
 // Use in tests
@@ -101,124 +117,200 @@ describe('User Service', () => {
 import { ObjectionFactory } from '@geekmidas/testkit/objection';
 import { Model } from 'objection';
 
-// Define your models
 class User extends Model {
   static tableName = 'users';
-  id!: number;
+  id!: string;
   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`,
-  }),
+const builders = {
+  user: ObjectionFactory.createBuilder(
+    User,
+    (attrs, factory, db, faker) => ({
+      id: faker.string.uuid(),
+      name: faker.person.fullName(),
+      email: faker.internet.email(),
+      ...attrs,
+    })
+  ),
 };
 
-// Use in tests
-const factory = new ObjectionFactory({ user: userBuilder }, {});
+const factory = new ObjectionFactory(builders, {}, knex);
 const user = await factory.insert('user', { name: 'Jane Doe' });
 ```
 
-## 🏗️ Core Concepts
+## Enhanced Faker
+
+The testkit provides an enhanced faker instance with additional utilities for common test data patterns.
+
+```typescript
+import { faker } from '@geekmidas/testkit/faker';
+
+// Standard faker methods
+const name = faker.person.fullName();
+const email = faker.internet.email();
+
+// Generate timestamps for database records
+const { createdAt, updatedAt } = faker.timestamps();
+// createdAt: Date in the past
+// updatedAt: Date between createdAt and now
+
+// Sequential numbers (useful for unique IDs)
+faker.sequence();           // 1
+faker.sequence();           // 2
+faker.sequence('user');     // 1 (separate sequence)
+faker.sequence('user');     // 2
+
+// Reset sequences between tests
+faker.resetSequence('user');
+faker.resetAllSequences();
+
+// Generate prices as numbers
+const price = faker.price(); // 29.99
+
+// Generate reverse domain identifiers
+faker.identifier();         // "com.example.widget1"
+faker.identifier('user');   // "org.acme.user"
+
+// Generate coordinates within/outside a radius
+const center = { lat: 40.7128, lng: -74.0060 };
+faker.coordinates.within(center, 1000);   // Within 1km
+faker.coordinates.outside(center, 1000, 5000); // Between 1km and 5km
+```
+
+## Timer Utilities
+
+Simple async wait utility for tests.
 
-### Builders
+```typescript
+import { waitFor } from '@geekmidas/testkit/timer';
+
+it('should process after delay', async () => {
+  startBackgroundProcess();
+  await waitFor(100); // Wait 100ms
+  expect(processComplete).toBe(true);
+});
+```
 
-Builders define how to create test data for each table. They specify:
+## OS Utilities
 
-- **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
+Vitest fixture for temporary directory creation with automatic cleanup.
 
 ```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 });
-  },
+import { itWithDir } from '@geekmidas/testkit/os';
+
+// Creates a temp directory before test, removes it after
+itWithDir('should write files to temp dir', async ({ dir }) => {
+  const filePath = path.join(dir, 'test.txt');
+  await fs.writeFile(filePath, 'hello');
+
+  const content = await fs.readFile(filePath, 'utf-8');
+  expect(content).toBe('hello');
+  // Directory is automatically cleaned up after test
 });
 ```
 
-### Seeds
+## AWS Testing Utilities
 
-Seeds are functions that create complex test scenarios with multiple related entities:
+Mock AWS Lambda contexts and API Gateway events for testing Lambda handlers.
 
 ```typescript
-const blogSeed = async (factory: Factory) => {
-  const author = await factory.insert('user', {
-    name: 'Blog Author',
-    role: 'author',
+import {
+  createMockContext,
+  createMockV1Event,
+  createMockV2Event
+} from '@geekmidas/testkit/aws';
+
+describe('Lambda Handler', () => {
+  it('should handle API Gateway v1 event', async () => {
+    const event = createMockV1Event({
+      httpMethod: 'POST',
+      path: '/users',
+      body: JSON.stringify({ name: 'John' }),
+    });
+    const context = createMockContext();
+
+    const result = await handler(event, context);
+    expect(result.statusCode).toBe(201);
   });
 
-  const categories = await factory.insertMany(3, 'category');
+  it('should handle API Gateway v2 event', async () => {
+    const event = createMockV2Event({
+      routeKey: 'POST /users',
+      rawPath: '/users',
+      body: JSON.stringify({ name: 'John' }),
+    });
+    const context = createMockContext();
 
-  const posts = await factory.insertMany(5, 'post', (index) => ({
-    title: `Post ${index + 1}`,
-    authorId: author.id,
-    categoryId: categories[index % categories.length].id,
-  }));
+    const result = await handler(event, context);
+    expect(result.statusCode).toBe(201);
+  });
+});
+```
 
-  return { author, categories, posts };
-};
+## Logger Testing Utilities
 
-// Use in tests
-const data = await factory.seed('blog');
+Create mock loggers for testing code that uses `@geekmidas/logger`.
+
+```typescript
+import { createMockLogger } from '@geekmidas/testkit/logger';
+
+describe('Service', () => {
+  it('should log errors', async () => {
+    const logger = createMockLogger();
+    const service = new MyService(logger);
+
+    await service.doSomethingRisky();
+
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.objectContaining({ error: expect.any(Error) }),
+      'Operation failed'
+    );
+  });
+});
 ```
 
-### Transaction Support
+## Better Auth Testing
 
-TestKit supports transaction-based test isolation:
+In-memory adapter for testing Better Auth without a real database.
 
 ```typescript
-describe('User Service', () => {
-  let trx: Transaction<Database>;
-  let factory: KyselyFactory;
+import { memoryAdapter } from '@geekmidas/testkit/better-auth';
+import { betterAuth } from 'better-auth';
+
+describe('Authentication', () => {
+  const adapter = memoryAdapter({
+    debugLogs: false,
+    initialData: {
+      user: [{ id: '1', email: 'test@example.com', name: 'Test User' }],
+    },
+  });
 
-  beforeEach(async () => {
-    trx = await db.transaction();
-    factory = new KyselyFactory(builders, seeds, trx);
+  const auth = betterAuth({
+    database: adapter,
+    // ... other config
   });
 
-  afterEach(async () => {
-    await trx.rollback();
+  afterEach(() => {
+    adapter.clear(); // Reset data between tests
   });
 
-  it('should perform operations in isolation', async () => {
-    const user = await factory.insert('user');
-    // Test operations...
-    // All changes will be rolled back after the test
+  it('should create user', async () => {
+    await auth.api.signUp({
+      email: 'new@example.com',
+      password: 'password123',
+    });
+
+    const data = adapter.getAllData();
+    expect(data.user).toHaveLength(2);
   });
 });
 ```
 
-## 📚 Advanced Usage
+## Database Migration
 
-### Database Migration
-
-TestKit includes utilities for managing test database migrations:
+TestKit includes utilities for managing test database migrations.
 
 ```typescript
 import { PostgresKyselyMigrator } from '@geekmidas/testkit/kysely';
@@ -237,147 +329,158 @@ const migrator = new PostgresKyselyMigrator({
 // 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
+## Transaction Isolation
 
-You can extend the base Factory class for custom implementations:
+TestKit supports transaction-based test isolation:
 
 ```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],
-    }));
-  }
-}
-```
+describe('User Service', () => {
+  let trx: Transaction<Database>;
+  let factory: KyselyFactory;
 
-### Dynamic Attributes
+  beforeEach(async () => {
+    trx = await db.transaction();
+    factory = new KyselyFactory(builders, seeds, trx);
+  });
 
-Create dynamic attributes for each record in batch operations:
+  afterEach(async () => {
+    await trx.rollback();
+  });
 
-```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
-}));
+  it('should perform operations in isolation', async () => {
+    const user = await factory.insert('user');
+    // All changes will be rolled back after the test
+  });
+});
 ```
 
-### Conditional Auto-insertion
+## Seeds
 
-Control whether builders automatically insert data:
+Seeds are functions that create complex test scenarios:
 
 ```typescript
-const draftBuilder = KyselyFactory.createBuilder<Database, 'posts'>({
-  table: 'posts',
-  defaults: async () => ({
-    title: 'Draft Post',
-    status: 'draft',
-  }),
-  autoInsert: false, // Don't insert automatically
-});
+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 };
+};
 
-// Manually handle the data
-const draftData = await draftBuilder.build();
-// Perform validation or modifications...
-const post = await db.insertInto('posts').values(draftData).execute();
+// Use in tests
+const data = await factory.seed('blog');
 ```
 
-## 🔧 API Reference
+## API Reference
 
 ### KyselyFactory
 
 ```typescript
-class KyselyFactory<TBuilders, TSeeds> extends Factory {
+class KyselyFactory<DB, Builders, Seeds> {
   constructor(
-    builders: TBuilders,
-    seeds: TSeeds,
-    db: Kysely<any> | Transaction<any>
+    builders: Builders,
+    seeds: Seeds,
+    db: Kysely<DB> | ControlledTransaction<DB>
   );
 
-  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>(
+  static createBuilder<DB, TableName extends keyof DB & string>(
+    table: TableName,
+    item?: (
+      attrs: Partial<Insertable<DB[TableName]>>,
+      factory: KyselyFactory,
+      db: Kysely<DB>,
+      faker: FakerFactory
+    ) => Partial<Insertable<DB[TableName]>> | Promise<...>,
+    autoInsert?: boolean
+  ): BuilderFunction;
+
+  insert<K extends keyof Builders>(
+    builderName: K,
+    attrs?: Partial<BuilderAttrs>
+  ): Promise<BuilderResult>;
+
+  insertMany<K extends keyof Builders>(
     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]>>;
+    builderName: K,
+    attrs?: Partial<BuilderAttrs> | ((idx: number, faker: FakerFactory) => Partial<BuilderAttrs>)
+  ): Promise<BuilderResult[]>;
+
+  seed<K extends keyof Seeds>(
+    seedName: K,
+    attrs?: SeedAttrs
+  ): Promise<SeedResult>;
 }
 ```
 
-### ObjectionFactory
+### Enhanced Faker
 
 ```typescript
-class ObjectionFactory<TBuilders, TSeeds> extends Factory {
-  constructor(
-    builders: TBuilders,
-    seeds: TSeeds,
-    knex?: Knex
-  );
-
-  // Same methods as KyselyFactory
+interface EnhancedFaker extends Faker {
+  timestamps(): { createdAt: Date; updatedAt: Date };
+  sequence(name?: string): number;
+  resetSequence(name?: string, value?: number): void;
+  resetAllSequences(): void;
+  identifier(suffix?: string): string;
+  price(): number;
+  coordinates: {
+    within(center: Coordinate, radiusMeters: number): Coordinate;
+    outside(center: Coordinate, minRadius: number, maxRadius: number): Coordinate;
+  };
 }
 ```
 
-### Builder Configuration
+### AWS Mocks
 
 ```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;
-}
+function createMockContext(): Context;
+function createMockV1Event(overrides?: Partial<APIGatewayProxyEvent>): APIGatewayProxyEvent;
+function createMockV2Event(overrides?: Partial<APIGatewayProxyEventV2>): APIGatewayProxyEventV2;
+```
+
+### Memory Adapter (Better Auth)
+
+```typescript
+function memoryAdapter(config?: {
+  debugLogs?: boolean;
+  usePlural?: boolean;
+  initialData?: Record<string, any[]>;
+}): DatabaseAdapter & {
+  clear(): void;
+  getAllData(): Record<string, any[]>;
+  getStore(): Map<string, any>;
+};
 ```
 
-## 🧪 Testing Best Practices
+## 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
+6. **Reset Sequences**: Call `faker.resetAllSequences()` in `beforeEach` for predictable IDs
 
-## 🤝 Contributing
+## Contributing
 
 We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
 
-## 📄 License
+## License
 
-This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.