@seedts/types/README.md

Core TypeScript types and interfaces for SeedTS

# @seedts/types

> Core TypeScript types and interfaces for SeedTS

This package contains all the core TypeScript type definitions and interfaces used throughout the SeedTS ecosystem. It has zero runtime dependencies and serves as the foundation for type safety across all SeedTS packages.

## Installation

```bash
pnpm add @seedts/types
```

> **Note:** This package is automatically included when you install the main `seedts` package. You typically only need to install it directly if you're building custom adapters or extensions.

## Overview

The `@seedts/types` package provides TypeScript types for:

- **Seed Definitions** - Types for defining seeds and their configuration
- **Adapters** - Interface for database adapters
- **Execution Context** - Context available during seed execution
- **Errors** - Custom error types for better error handling
- **Configuration** - Configuration options for executors and seeds

## Key Types

### SeedAdapter

The core interface that all database adapters must implement:

```typescript
import type { SeedAdapter } from '@seedts/types';

type SeedAdapter<T = any> = {
  name: string;
  insert(tableName: string, data: T[]): Promise<T[]>;
  update(tableName: string, data: T[]): Promise<T[]>;
  delete(tableName: string, ids: any[]): Promise<void>;
  beginTransaction(): Promise<void>;
  commit(): Promise<void>;
  rollback(): Promise<void>;
  query(tableName: string, conditions?: any): Promise<T[]>;
  close?(): Promise<void>;
};
```

### SeedDefinition

Type for seed configuration:

```typescript
import type { SeedDefinition } from '@seedts/types';

type SeedDefinition<T = any> = {
  name: string;
  adapter: SeedAdapter<T>;
  data?: T[];
  factory?: (context: ExecutionContext) => Promise<T[]> | T[];
  dependsOn?: string | string[];
  onConflict?: 'skip' | 'update' | 'error';
  hooks?: SeedHooks<T>;
};
```

### ExecutionContext

Context available during seed execution:

```typescript
import type { ExecutionContext } from '@seedts/types';

type ExecutionContext = {
  index: number;
  count: number;
  seedName: string;
  getSeed(name: string): Promise<any[]>;
  getInsertedData(seedName: string): any[];
  metadata: Record<string, any>;
};
```

### SeedHooks

Lifecycle hooks for seeds:

```typescript
import type { SeedHooks } from '@seedts/types';

type SeedHooks<T = any> = {
  beforeInsert?: (data: T[]) => Promise<T[]> | T[];
  afterInsert?: (data: T[], inserted: T[]) => Promise<void> | void;
  onSuccess?: (data: T[], metadata: ExecutionMetadata) => Promise<void> | void;
  onError?: (error: Error) => Promise<void> | void;
};
```

### Error Types

Custom error types for better error handling:

```typescript
import type {
  SeedError,
  SeedValidationError,
  SeedExecutionError,
  SeedDependencyError,
} from '@seedts/types';
```

## Usage

### Creating Type-Safe Seeds

```typescript
import type { SeedDefinition, SeedAdapter } from '@seedts/types';

type User = {
  id?: number;
  email: string;
  name: string;
  role: string;
};

const userSeed: SeedDefinition<User> = {
  name: 'users',
  adapter: myAdapter,
  factory: async (ctx) => {
    return Array.from({ length: 100 }, (_, i) => ({
      email: `user${i}@example.com`,
      name: `User ${i}`,
      role: 'user',
    }));
  },
};
```

### Implementing Custom Adapters

```typescript
import type { SeedAdapter } from '@seedts/types';

export class MyCustomAdapter implements SeedAdapter {
  name = 'my-custom-adapter';

  async insert<T>(tableName: string, data: T[]): Promise<T[]> {
    // Implementation
    return data;
  }

  async update<T>(tableName: string, data: T[]): Promise<T[]> {
    // Implementation
    return data;
  }

  async delete(tableName: string, ids: any[]): Promise<void> {
    // Implementation
  }

  async beginTransaction(): Promise<void> {
    // Implementation
  }

  async commit(): Promise<void> {
    // Implementation
  }

  async rollback(): Promise<void> {
    // Implementation
  }

  async query<T>(tableName: string, conditions?: any): Promise<T[]> {
    // Implementation
    return [];
  }
}
```

### Using Execution Context

```typescript
import type { ExecutionContext } from '@seedts/types';

const factory = async (ctx: ExecutionContext) => {
  // Access execution context
  console.log(`Generating record ${ctx.index + 1} of ${ctx.count}`);

  // Get data from other seeds
  const users = await ctx.getSeed('users');

  // Return generated data
  return {
    userId: users[ctx.index % users.length].id,
    content: `Post ${ctx.index}`,
  };
};
```

## Type Exports

### Main Types

```typescript
export type {
  // Adapter types
  SeedAdapter,
  AdapterConfig,

  // Seed definition types
  SeedDefinition,
  SeedConfig,
  SeedHooks,

  // Execution types
  ExecutionContext,
  ExecutionMetadata,
  ExecutionResult,
  ExecutorConfig,

  // Data types
  ConflictStrategy,
  SeedData,

  // Error types
  SeedError,
  SeedValidationError,
  SeedExecutionError,
  SeedDependencyError,
  SeedAdapterError,
};
```

## API Documentation

For detailed API documentation, visit:
- [Full Documentation](https://seedts.dev/docs/api/types)
- [Adapter Guide](https://seedts.dev/docs/guides/adapters)
- [Type Safety Guide](https://seedts.dev/docs/advanced/typescript)

## Related Packages

- **[@seedts/core](https://www.npmjs.com/package/@seedts/core)** - Core execution engine
- **[@seedts/adapters](https://www.npmjs.com/package/@seedts/adapters)** - Base adapter classes
- **[seedts](https://www.npmjs.com/package/seedts)** - Main convenience package

## Contributing

Contributions are welcome! Please see our [Contributing Guide](https://github.com/DarioBR91/seedts/blob/main/CONTRIBUTING.md).

## License

MIT © [SeedTS Contributors](../../LICENSE)