@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:

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:

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:

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

Base interface for all automation tasks.

IFlow

Interface for flow definitions and execution.

TaskContext

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.