Typescript to GCP Workflows transpiler

ts2workflows converts Typescript code to a GCP Workflows program.

Only a subset of Typescript features are supported. The language reference describes the supported Typescript features.

See the samples directory for code examples.

Installation

npm install ts2workflows

Usage

Converting Typescript code in a file samples/sample1.ts into GCP Workflows YAML syntax on stdout:

npx ts2workflows samples/sample1.ts

Compile multiple files and write result to an output directory workflowsfiles. This will write one output file corresponding to each input file in a directory given by the --outdir argument. The output files are named similarly to the input files but using .yaml as the file extension. The output directory will be created if it doesn't exist. Supplying the TSConfig with the --project argument makes compiling multiple files faster.

npx ts2workflows --project samples/tsconfig.json --outdir workflowsfiles samples/*.ts

The --link argument generates YAML output that includes all necessary subworkflows (i.e. imported Typescript functions) in a single file. It will generate one output file for each input file.

npx ts2workflows --link --project samples/tsconfig.json --outdir workflowsfiles samples/sample*.ts

When developing ts2workflows, you can run the transpiler directly from the source directory:

npx tsx src/cli.ts samples/sample1.ts

Command arguments

• --project: Path to TSConfig for the Typescript sources files
• --link: Emit a self-contained YAML. That is, the output includes code from the main input file and all subworkflows imported from the main file. Without this, emits only subworkflows in the input file. Requires --project.
• --[no-]generated-file-comment: Start the output with a comment mentioning that the file has been generated by ts2workflows.

Type checking workflow sources

One benefit of writing the workflow programs in Typescript is that the sources can be type checked.

This example command shows how to type check source files in the samples directory using the standard Typescript compiler tsc. The command prints typing errors or finishes silently, if there are no errors.

npx tsc --project samples/tsconfig.json

The file samples/tsconfig.json contains a sample configuration for type checking workflow sources.

Type annotations for Workflows standard library functions and expression helpers and for some connectors are provided in types/workflowslib.d.ts. They are also included in the published npm module. To import type annotations in a project that has ts2workflows module as a dependency, use the following import command:

import { http, retry_policy } from 'ts2workflows/types/workflowslib'

Type checking step is completely separate from the transpiling. The ts2workflows command ignores type annotations.

Development

Build

npm install
npm run build

Run unit tests

npm run test

Run tests and print the test coverage:

npm run test:coverage

Architecture

A transpilation using ts2workflows consists of five phases:

• parsing Typescript source code
• converting to intermediate representation (IR)
• transforming and optimizing the IR
• assigning names for the Workflows steps
• outputting in the program in Workflows YAML format

The main function implementing these phases is transpile() in src/transpiler/index.ts.

The transpiler parses a Typescript source file using @typescript-eslint/typescript-estree module by the typescript-eslint project. The result of the parsing is an ESTree-compatible abstract syntax tree (AST) of the source code. typescript-eslint playgroud is an useful tool for exploring the Typescript parsing.

Next, ts2workflows converts the AST to a custom intermediate representation (IR). The IR format brings the representation of the program closer the GCP Workflows language than Typescript code. The types for IR are defined in the src/ast directory. Particularly, see src/ast/statements.ts for statement types and src/ast/expressions.ts for expression types.

The transpiler applies a few transformations to the IR to make it a valid and optimized Workflows program. These transformations, for example, merge consecutive assignments into a single assign step and ensure that blocking function are invoked by call steps (as required by Workflows). The transformations are implemented in src/transpiler/transformations.ts.

To spare the programmer from labeling each and every Workflows step manually, ts2workflows automatically assigns names to the steps. The automatically choosen step names consist of the step type and a sequential number. The implementation is in src/ast/stepnames.ts.

Finally, the transpiler converts the result into a YAML document.

License

The MIT License