readme.md

ts2asl: A TypeScript to Amazon States Language (ASL) transpiler

⚠️ All internal and external interfaces are considered unstable and subject to change without notice. ⚠️

ts2asl allows developers to define AWS Step Functions using the TypeScript programming language. It allows developers to benefit from a familiar syntax, type safety, and mature ecosystem of tools for linting, editing, and automated testing.

Example

The following code example can be executed and tested locally. The output is ASL, which can be deployed to your AWS account to create a Standard or Express Step Function.

You can also explore the TypeScript code and the corresponding ASL it generates in the interactive playground.

import * as asl from "@ts2asl/asl-lib"

//main will be converted to ASL and deployed as a state machine
export const main = asl.deploy.asStateMachine(async (input: IInput) => {
  if (typeof input.name !== "string") {
    input.name = "World";
  }
  const rnd = await random();
  return {
    greeting: `Hello ${input.name}`,
    luckyNumber: rnd
  }
});

//random will be deployed as a lambda function
export const random = asl.deploy.asLambda(async (input: { min?: number; max?: number } = {}) => {
  const min = input.min ?? 0;
  const max = input.max ?? 100;
  return Math.round(Math.random() * (max - min) + min);
});

interface IInput {
  name: string;
}

TypeScript language support

ts2asl converts native TypeScript code to ASL. The following TypeScript langauge features are supported:

• variable assignments
• throwing errors
• input validation
• enclosed variables
• enum literals
• in keyword
• if statements
• for ... of statements
• do while statements
• switch statements
• try/catch/finally statements
• boolean evaluation logic
• promise.all
• array.map
• array.filter
• console.log
• evaluation of literal expressions
• string templates

ASL TypeScript library runtime support

ts2asl is integrated with the @ts2asl/asl-lib module. This module can be used to integrate ASL features such as states and JsonPath with native TypeScript.

• ASL States (Pass, Wait, Choice, Parallel, Map, etc.)
• tasks with sync invocations, waitForTaskToken
• typesafe SDK Integrations
• intrinsic functions
• type conversions
• jsonPath expressions
• deploytime configuration & integration with CDK

asl-lib implements the same behavior as AWS Step Functions, so you can execute your TypeScript code locally (using ts-node) or write unit tests (using ts-jest) without having to deploy anything to AWS.

Differences between TypeScript and ASL

There are some differences between TypeScript and ASL that a compiler won't be able to solve (fully):

• object references in TypeScript are passed by reference; object references in ASL references are passed by value.

Deployment using the AWS Cloud Development Kit (CDK)

ts2asl features a CDK Construct that allows developers to integrate the TypeScript -> ASL conversion process into existing CI/CD pipelines. An example stack can be found in this repository.

import * as ts2asl from '@ts2asl/cdk-typescript-statemachine';

new ts2asl.TypescriptStateMachine(this, "TypescriptStateMachine", {
  programName: "hello-world",
  defaultFunctionProps: {},
  defaultStepFunctionProps: {
    stateMachineType: "EXPRESS",
    roleArn: executionRole.roleArn
  },
  sourceFile: "./src/program.ts",
});

Useful patterns & examples

• example project containing a simple program, CDK for deployment and Jest for testing
• Waiting for completion of SDK state: organizations.createAccount.