Home

Introduction

The Step Functions library is a powerful and flexible tool for creating multiple-step functions. It provides users with the ability to create both synchronous and asynchronous step functions with ease. The library offers flexibility in defining custom steps and transitions, allowing for the creation of complex workflows with capabilities such as parallel branching, conditional branching, and branch merging with aggregation.

Getting Started

Installation

Gradle

To install the Step Functions library using Gradle, add the following dependency to your project’s build file:

dependencies {
  implementation("com.koralix.stepfn:step-functions:1.1.1")
}

Make sure to also add the GitHub packages repository to your build file:

repositories {
  maven {
    url = uri("https://maven.pkg.github.com/koralix-studios/step-functions")
    credentials {
      username = project.findProperty("gpr.user") as String?
      password = project.findProperty("gpr.key") as String?
    }
  }
}

Don’t forget to add the following properties to your gradle.properties file:

gpr.user=your_github_username
gpr.key=your_github_token

Maven

To install the Step Functions library using Maven, add the following dependency to your project’s pom.xml file:

<dependency>
  <groupId>com.koralix.stepfn</groupId>
  <artifactId>step-functions</artifactId>
  <version>1.1.1</version>
</dependency>

Make sure to also add the GitHub packages repository to your pom.xml file:

<repositories>
  <repository>
    <id>github</id>
    <url>https://maven.pkg.github.com/koralix-studios/step-functions</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

Don’t forget to add your GitHub username and token to your settings.xml file:

<servers>
  <server>
    <id>github</id>
    <username>your_github_username</username>
    <password>your_github_token</password>
  </server>
</servers>

Basic Usage

Here’s a basic usage example that demonstrates how to create a synchronous step function using the Step Functions library:

SyncStepFunction<String, Boolean> syncStepFunction = StepFunctionBuilder.step(String::length)
        .transition(
                step -> true,
                StepFunctionBuilder.step(input -> input > 5)
        ).sync();

syncStepFunction.apply("Hello World"); // returns true
syncStepFunction.apply("Hello"); // returns false

In this example, we create a SyncStepFunction that takes a String as input and returns a Boolean as output. The function first applies the String::length step to compute the length of the input string. It then transitions to a second step that checks if the length of the input string is greater than 5. The first call to apply returns true because the length of “Hello World” is greater than 5, while the second call returns false because the length of “Hello” is not greater than 5.

Advanced Usage

Here’s an advanced usage example that demonstrates how to create an asynchronous step function with parallel branching and branch merging using aggregation:

StepFunctionBuilder<Integer, Integer> lastStep = StepFunctionBuilder.step(
        aggregation -> aggregation.size() == 2,
        (input, aggregation) -> aggregation.values().stream().mapToInt(Integer::intValue).sum()
);

AsyncStepFunction<String, Integer> asyncStepFunction = StepFunctionBuilder.step(String::length)
        .transition(
                step -> true,
                StepFunctionBuilder.<Integer, Integer>step(
                        input -> input + 1
                ).transition(
                        step -> true,
                        lastStep
                )
        ).transition(
                step -> true,
                StepFunctionBuilder.<Integer, Integer>step(
                        input -> input + 1
                ).transition(
                        step -> true,
                        lastStep
                )
        ).async(() -> Executors.newFixedThreadPool(8));

asyncStepFunction.apply("Hello World").join(); // returns 24
asyncStepFunction.apply("Hello").join();     // returns 12

In this example, we create an AsyncStepFunction that takes a String as input and returns an Integer as output. The function first applies the String::length step to compute the length of the input string. It then transitions to two parallel branches that both apply a step that adds 1 to the length of the input string. These two branches then merge into a final step that aggregates the results from both branches by summing them. The first call to apply returns 24 because “Hello World” has a length of 11 and both branches add 1 to this length before summing the results (11 + 1 + 11 + 1 = 24), while the second call returns 12 because “Hello” has a length of 5 (5 + 1 + 5 + 1 = 12).

API Reference

Detailed documentation of the library’s API can be found in its Javadocs.

Contributing

We welcome contributions to the Step Functions library! If you're interested in contributing, please take a look at our contributing guidelines for more information.

Changelog

1.1.1

• Added the ability to use aggregation when creating Step Functions using the new builder approach.

1.1.0

• Added mapping transitions and a StepFunctionBuilder to make the process of creating Step Functions even easier.
• Cleaned up some code, added more documentation, and included more metadata in the library's pom.xml file.
• Implemented short-termination when an exception occurs, cancelling all running steps on async functions when it finishes.

1.0.1

• Fixed a bug with the aggregation clear process in AsyncStepFunctions, which now occurs after execution to ensure data availability and prevent issues when executing in parallel.

1.0.0

• Initial release of the Step Functions library.
• Added the ability to create both synchronous and asynchronous step functions with ease.
• Provided flexibility in defining custom steps and transitions, allowing for the creation of complex workflows with capabilities such as parallel branching, conditional branching, and branch merging with aggregation.
• Supported multiple termination steps, allowing a StepFunction to return a result from multiple steps rather than just a single final step.
• Allowed for dynamic addition of transitions and steps to a StepFunction at runtime.