ts2workflows

0.15.0 verified Fri May 01 auth: no javascript

ts2workflows is a transpiler that converts TypeScript code into GCP Workflows YAML programs, enabling type-safe workflow development. Current version is 0.15.0. It supports a subset of TypeScript features, includes type annotations for Workflows standard library and connectors, and provides CLI for batch compilation. Key differentiators: enables type-checking of workflow sources with tsc, integrates with TypeScript ecosystem, and produces self-contained YAML with subworkflows via --link. Requires Node >=20 and TypeScript >=5.5.4 <6.0.

Common errors

error Error: Cannot find module 'ts2workflows/types/workflowslib' ↓

cause Missing import path or package not installed

fix

npm install ts2workflows and use correct import path: 'ts2workflows/types/workflowslib'

error TypeError: transpile is not a function ↓

cause Using CommonJS require incorrectly

fix

Use ESM import: import { transpile } from 'ts2workflows'

error Unsupported syntax: ... ↓

cause Using unsupported TypeScript feature (e.g., generators, decorators)

fix

Rewrite using supported syntax per language_reference.md

Warnings

breaking Requires Node >=20, TypeScript >=5.5.4 <6.0.0 ↓

fix Upgrade Node and TypeScript to compatible versions

gotcha Only a subset of TypeScript features are supported; see language reference for details. Unsupported features may cause transpilation errors or silent omission. ↓

fix Review language_reference.md before writing workflows

gotcha Without --link flag, only subworkflows from the input file are emitted; main workflow code is not included in output. ↓

fix Use --link flag to generate self-contained YAML with all subworkflows

gotcha --link requires --project argument ↓

fix Always provide --project when using --link

Install

npm install ts2workflows

yarn add ts2workflows

pnpm add ts2workflows

Imports

transpile

wrong

const transpile = require('ts2workflows'); transpile()

correct

import { transpile } from 'ts2workflows'

ESM-only import; transpile() is the main API function

http

wrong

import { http } from 'ts2workflows'

correct

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

Type annotations for Workflows standard library are exported from a subpath

retry_policy

wrong

import retry_policy from 'ts2workflows'

correct

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

Named export from the types subpath

Quickstart

Shows a basic workflow function with HTTP call and transpilation command.

// sample.ts - a simple workflow
import { http, retry_policy } from 'ts2workflows/types/workflowslib';

async function myWorkflow(input: { name: string }) {
  const result = await http.get(`https://api.example.com/greet?name=${input.name}`);
  return result.body;
}

// Transpile using CLI:
// npx ts2workflows sample.ts