npm package: @seedts/core
Description: Core execution engine for SeedTS
Author: SeedTS Contributors
Latest version: 0.1.1

# @seedts/core

> Core execution engine for SeedTS

The core package provides the execution engine, seed registry, dependency resolution, and transaction management for SeedTS. It's the heart of the SeedTS ecosystem.

## Installation

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

> **Note:** This package is automatically included when you install the main `seedts` package.

## Features

- **Executor** - Executes seeds in the correct order with dependency resolution
- **Seed Registry** - Manages and organizes seeds
- **Dependency Graph** - Automatic topological sorting of seed dependencies
- **Transaction Manager** - Wraps seed execution in database transactions
- **Parallel Execution** - Run independent seeds concurrently
- **Rollback Support** - Automatic rollback on failure

## Quick Start

### Creating a Seed

```typescript
import { seed } from '@seedts/core';
import type { User } from './types';

const userSeed = seed<User>('users')
  .adapter(myAdapter)
  .data([
    { email: 'admin@example.com', name: 'Admin', role: 'admin' },
    { email: 'user@example.com', name: 'User', role: 'user' },
  ])
  .build();
```

### Using Factory Functions

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

### Executing Seeds

```typescript
import { Executor } from '@seedts/core';

const executor = new Executor([userSeed, postSeed, commentSeed]);

const results = await executor.execute({
  parallel: false,      // Run seeds sequentially
  transaction: true,    // Wrap in transaction
  verbose: true,        // Log progress
});

console.log(results);
// [
//   { name: 'users', inserted: 100, duration: 45, ... },
//   { name: 'posts', inserted: 500, duration: 120, ... },
//   { name: 'comments', inserted: 2000, duration: 350, ... }
// ]
```

## Core API

### `seed<T>(name: string)`

Creates a new seed builder with a fluent API:

```typescript
import { seed } from '@seedts/core';

const mySeed = seed<MyType>('table-name')
  .adapter(adapter)
  .data([...])           // Static data
  .factory(factoryFn)    // Dynamic data generation
  .dependsOn(['other'])  // Dependencies
  .onConflict('skip')    // Conflict strategy
  .hooks({...})          // Lifecycle hooks
  .build();
```

### `Executor`

Manages and executes multiple seeds:

```typescript
import { Executor } from '@seedts/core';

const executor = new Executor(seeds, {
  parallel: true,          // Enable parallel execution
  maxParallel: 5,          // Max concurrent seeds
  transaction: true,       // Use transactions
  verbose: false,          // Logging
  continueOnError: false,  // Stop on first error
});

// Execute all seeds
const results = await executor.execute();

// Execute specific seeds
const results = await executor.execute({
  only: ['users', 'posts'],
});

// Dry run (validate without executing)
const validation = await executor.validate();
```

### `SeedRegistry`

Manages seed registration and lookup:

```typescript
import { SeedRegistry } from '@seedts/core';

const registry = new SeedRegistry();

// Register seeds
registry.register(userSeed);
registry.register(postSeed);

// Get seed by name
const seed = registry.get('users');

// Get all seeds
const allSeeds = registry.getAll();

// Check if seed exists
const exists = registry.has('users');
```

### `DependencyGraph`

Resolves seed dependencies and performs topological sorting:

```typescript
import { DependencyGraph } from '@seedts/core';

const graph = new DependencyGraph(seeds);

// Get execution order
const order = graph.getExecutionOrder();
// ['users', 'posts', 'comments']

// Detect circular dependencies
const cycles = graph.detectCycles();

// Get independent seeds that can run in parallel
const batches = graph.getParallelBatches();
// [
//   ['users', 'categories'],  // Batch 1: no dependencies
//   ['posts', 'tags'],         // Batch 2: depend on batch 1
//   ['comments']               // Batch 3: depends on posts
// ]
```

## Seed Configuration

### Dependencies

```typescript
const postSeed = seed<Post>('posts')
  .dependsOn('users')  // Single dependency
  .adapter(adapter)
  .factory(async (ctx) => {
    const users = await ctx.getSeed('users');
    return posts.map(p => ({ ...p, userId: users[0].id }));
  })
  .build();

const commentSeed = seed<Comment>('comments')
  .dependsOn(['users', 'posts'])  // Multiple dependencies
  .adapter(adapter)
  .factory(async () => comments)
  .build();
```

### Conflict Strategies

```typescript
const seed = seed<User>('users')
  .adapter(adapter)
  .data(users)
  .onConflict('skip')    // Skip existing records
  // .onConflict('update') // Update existing records
  // .onConflict('error')  // Throw error on conflict
  .build();
```

### Lifecycle Hooks

```typescript
const seed = seed<User>('users')
  .adapter(adapter)
  .hooks({
    beforeInsert: async (data) => {
      console.log(`Inserting ${data.length} users`);
      return data.map(u => ({ ...u, createdAt: new Date() }));
    },
    afterInsert: async (data, inserted) => {
      console.log(`Inserted ${inserted.length} users`);
    },
    onSuccess: async (data, metadata) => {
      console.log(`Success! Duration: ${metadata.duration}ms`);
    },
    onError: async (error) => {
      console.error('Seeding failed:', error);
    },
  })
  .build();
```

## Execution Context

The execution context provides useful information and utilities:

```typescript
const factory = async (ctx) => {
  // Current index and total count
  console.log(`${ctx.index + 1} of ${ctx.count}`);

  // Seed name
  console.log(ctx.seedName);

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

  // Get inserted data from specific seed
  const insertedUsers = ctx.getInsertedData('users');

  // Custom metadata
  ctx.metadata.customData = 'value';

  return generatedData;
};
```

## Transaction Management

```typescript
import { TransactionManager } from '@seedts/core';

const txManager = new TransactionManager(adapter);

await txManager.run(async () => {
  // All operations here are in a transaction
  await adapter.insert('users', users);
  await adapter.insert('posts', posts);
  // Automatically commits if no error
  // Automatically rolls back on error
});
```

## Error Handling

```typescript
import {
  SeedExecutionError,
  SeedDependencyError,
  SeedValidationError,
} from '@seedts/core';

try {
  await executor.execute();
} catch (error) {
  if (error instanceof SeedDependencyError) {
    console.error('Dependency error:', error.message);
    console.error('Missing:', error.missing);
    console.error('Circular:', error.circular);
  } else if (error instanceof SeedExecutionError) {
    console.error('Execution failed:', error.seedName);
    console.error('Original error:', error.cause);
  } else if (error instanceof SeedValidationError) {
    console.error('Validation failed:', error.errors);
  }
}
```

## Advanced Usage

### Custom Seed Implementation

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

class CustomSeed extends BaseSeed {
  async execute(context) {
    // Custom execution logic
    const data = await this.generateData(context);
    const inserted = await this.adapter.insert(this.name, data);
    return { inserted, metadata: {} };
  }
}
```

### Extending the Executor

```typescript
import { Executor } from '@seedts/core';

class CustomExecutor extends Executor {
  async beforeExecution() {
    // Custom pre-execution logic
    console.log('Starting seed execution...');
  }

  async afterExecution(results) {
    // Custom post-execution logic
    console.log(`Completed ${results.length} seeds`);
  }
}
```

## API Reference

For detailed API documentation, visit:
- [Full Documentation](https://seedts.dev/docs/api/core)
- [Execution Guide](https://seedts.dev/docs/guides/execution)
- [Dependency Management](https://seedts.dev/docs/core-concepts/dependencies)

## Related Packages

- **[@seedts/types](https://www.npmjs.com/package/@seedts/types)** - Core type definitions
- **[@seedts/adapters](https://www.npmjs.com/package/@seedts/adapters)** - Base adapter classes
- **[@seedts/cli](https://www.npmjs.com/package/@seedts/cli)** - Command-line interface
- **[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)