ez-flow – Typescript library for a workflow engine

This library was heavily inspired to j-easy/easy-flows in the Java world.

Definitions

A Workflow is a collection of Work Units must be run tu achieve a given purpose.

Each Work unit implements a behaviour and interacts with outer environment and the other units by the means of a Context exchanged between them. You can place each unit in a flow applying some logic to control it.

That is you can place unit in a sequential flow, in a conditional one, in a parallel one and so on.

At the end of this "chain" we obtain the final result.

In this library are actually available the following flow constructs:

• Sequential Flow
• Conditional Flow
• Iterative Flow
• Parallel Flow

How to apply a flow?

Suppose you have defined a work unit called PrintMessageWork that implements Work. It takes a message and its call method prints it:

import {
  Work,
  WorkContext,
  WorkReport,
  DefaultWorkReport,
  WorkStatus,
} from '@rs-box/ez-flow';

export class PrintMessageWork implements Work {
  private message: string;

  constructor(message: string) {
    this.message = message;
  }

  getName() {
    return 'print message';
  }

  async call(workContext: WorkContext): Promise<WorkReport> {
    console.log(this.message);
    return new DefaultWorkReport(WorkStatus.COMPLETED, workContext);
  }
}

Use case

To test the library, a use case scenario was built in which, given a list of Italian cities, I wish to perform certain operations on each city and produce results.

To achieve this, it was important to first define the available inputs and what the workflow wanted to obtain, in this case the cumulative data on the regions to which the cities belong.

Installation

npm install @rs-box/ez-flow

Workflows definition

Specifically, three workflows were built:

• Main workflow
• Loop over cities workflow
• Operations workflow

Main

This is the main workflow, a Sequential Flow that performs two operations:

• Validate the context given as input (ValidateContext unit).
• Calling the Loop over cities workflow.

Loop over cities

This is a Repeat Flow, it will run until the IsNotLastCity predicate returns a negative value

Operations city

This is a Parallel Flow that executes the list of units passed as input, in the specific case of this test it will perform the following actions:

• Print the city name
• Update the cumulative region data.

Complete

This is the complete workflow resulting from the combination of those shown above.

Result

Finally, the workflow described above is translated as follows:

const workflow = SequentialFlow.Builder.newFlow()
  .withName('Main workflow')
  .addWork(new ValidateContextWork())
  .addWork(
    RepeatFlow.Builder.newFlow()
      .withName('Loop over cities')
      .withWork(
        ParallelFlow.Builder.newFlow()
          .withName('Operations city')
          .withWorks([new PrintCityWork(), new RegionCity()])
          .build(),
      )
      .until(new IsNotLastCityPredicate())
      .build(),
  )
  .build();

Source code

You can find the full source code for this scenario here:

rstanziale / ez-flow-test

Application for testing ez-flow

ez-flow-test

This application test aims to demonstrate @rs-box/ez-flow functions.

Use case

To test the library, a use case scenario was built in which, given a list of Italian cities, I wish to perform certain operations on each city and produce results.

To achieve this, it was important to first define the available inputs and what the workflow wanted to obtain, in this case the cumulative data on the regions to which the cities belong.

Workflows definition

Specifically, three workflows were built:

• Main workflow
• Loop over cities workflow
• Operations workflow

Main

This is the main workflow, a Sequential Flow that performs two operations:

• Validate the context given as input (ValidateContext unit).
• Calling the Loop over cities workflow.

Loop over cities

This is a Repeat Flow, it will run until the IsNotLastCity predicate returns a negative value

Operations city

This is a Parallel Flow that executes the list of units…

View on GitHub