npm package: @nimba/automation
Description: Task and flow automation engine for Nimba
Latest version: 1.0.93

# @nimba/automation

A comprehensive task and flow automation engine for NestJS applications within the Nimba monorepo, providing declarative workflow orchestration and execution.

## Features

- Type-safe task definitions with full TypeScript support
- Declarative flow orchestration via YAML/JSON configuration
- Unified automation registry with intelligent conflict resolution
- Execution context and state management
- Plugin architecture for extensibility
- Deep NestJS integration with dependency injection

## Architecture

The automation engine is built around three core concepts:

### Tasks
Individual units of work that can be executed independently. Tasks are TypeScript classes that implement the `ITask` interface and can be composed into larger workflows.

### Flows
Orchestrated sequences of tasks with support for conditional execution, parallel processing, and dependency management. Flows are defined declaratively and support complex control structures.

### Registry
A unified registry system that manages both tasks and flows, providing intelligent name resolution, conflict detection, and dependency tracking.

## Usage

This library is part of the Nimba monorepo and is designed to be used within the monorepo structure. To use it in your NestJS application within the monorepo:

1. Import and configure the module in your app:

```typescript
import { AutomationModule } from '@nimba/automation';

@Module({
  imports: [
    AutomationModule.forRoot({
      taskDiscovery: {
        patterns: ['src/**/*.task.ts'],
        autoRegister: true,
      },
      flowDiscovery: {
        patterns: ['flows/**/*.{yml,yaml,json}'],
        autoLoad: true,
      },
      execution: {
        defaultTimeout: 300000, // 5 minutes
        maxConcurrency: 10,
      },
    }),
  ],
})
export class AppModule {}
```

2. Define tasks using the task decorator:

```typescript
import { Task, ITask, TaskContext, TaskResult } from '@nimba/automation';

@Task({
  name: 'process-data',
  description: 'Process incoming data with validation and transformation',
  options: {
    schema: ProcessDataOptionsSchema,
    required: ['input', 'format'],
  },
})
export class ProcessDataTask implements ITask<ProcessDataOptions> {
  async execute(context: TaskContext<ProcessDataOptions>): Promise<TaskResult> {
    const { input, format, transform } = context.options;
    
    // Task implementation
    const result = await this.processData(input, format, transform);
    
    return {
      success: true,
      data: result,
      metadata: {
        processedAt: new Date(),
        recordCount: result.length,
      },
    };
  }
  
  private async processData(input: any, format: string, transform?: string): Promise<any> {
    // Implementation details
  }
}
```

3. Define flows using YAML configuration:

```yaml
name: data-pipeline
description: Complete data processing pipeline with error handling
version: 1.0.0

context:
  workspace: /tmp/pipeline
  timeout: 600000

steps:
  - name: validate-input
    task: validate-data
    options:
      schema: input-schema.json
      strict: true
    on_failure: cleanup

  - name: process-data
    task: process-data
    depends_on: [validate-input]
    options:
      input: "{{ steps.validate-input.result.data }}"
      format: json
      transform: normalize
    parallel: true

  - name: store-results
    task: store-data
    depends_on: [process-data]
    options:
      destination: "{{ context.workspace }}/results"
      data: "{{ steps.process-data.result.data }}"

  - name: cleanup
    task: cleanup-workspace
    condition: always
    options:
      path: "{{ context.workspace }}"
```

## API Reference

### Core Interfaces

#### ITask<TOptions>
Base interface for all automation tasks.

#### IFlow
Interface for flow definitions and execution.

#### TaskContext<TOptions>
Execution context provided to tasks during execution.

#### TaskResult
Standard result format returned by task execution.

### Services

#### AutomationRegistry
Central registry for managing tasks and flows.

#### TaskExecutor
Service responsible for task execution and lifecycle management.

#### FlowExecutor  
Service responsible for flow orchestration and execution.

### Decorators

#### @Task(metadata)
Decorator for marking classes as automation tasks.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

This project is licensed under the MIT License.