ts2workflows 0.6.0 → 0.8.0

package/README.md

@@ -16,6 +16,12 @@ Converting Typescript code in a file samples/sample1.ts into GCP Workflows YAML
 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.
+
+```sh
+npx ts2workflows --project samples/tsconfig.json --outdir workflowsfiles samples/*.ts
+```
+
 When developing ts2workflows, you can run the transpiler directly from the source directory:
 
 ```sh
@@ -29,10 +35,10 @@ One benefit of writing the workflow programs in Typescript is that the sources c
 This example command shows how to type check source files in the [samples](samples) directory using the standard Typescript compiler `tsc`. The command prints typing errors or finishes silently, if there are no errors.
 
 ```sh
-npx tsc --project tsconfig.workflows.json
+npx tsc --project samples/tsconfig.json
 ```
 
-The file [tsconfig.workflows.json](tsconfig.workflows.json) contains a sample configuration for type checking workflow sources.
+The file [samples/tsconfig.json](samples/tsconfig.json) contains a sample configuration for type checking workflow sources.
 
 Type annotations for [Workflows standard library functions and expression helpers](https://cloud.google.com/workflows/docs/reference/stdlib/overview) and for some [connectors](https://cloud.google.com/workflows/docs/reference/googleapis) are provided in [types/workflowslib.d.ts](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:
 

package/dist/cli.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { program } from 'commander';
 import { transpile } from './transpiler/index.js';
 import { WorkflowSyntaxError } from './errors.js';
@@ -7,11 +9,16 @@ import { TSError } from '@typescript-eslint/typescript-estree';
 function parseArgs() {
     program
         .name('ts2workflow')
-        .version('0.1.0')
+        .version(versionFromPackageJson())
         .description('Transpile a Typescript program into GCP Workflows YAML syntax.')
-        .argument('[FILES]', 'Path to source file(s) to compile. If not given, reads from stdin.');
-    program.parse();
+        .option('--project <path>', 'Path to TSConfig for the Typescript sources files.')
+        .option('--outdir <path>', 'Specify an output directory for where transpilation result are written.')
+        .option('--generated-file-comment', 'Include a comment stating that the result is a generated file', true)
+        .option('--no-generated-file-comment', "Don't include a comment about file being generated")
+        .argument('[FILES...]', 'Path to source file(s) to compile. If not given, reads from stdin.')
+        .parse();
     return {
+        ...program.opts(),
         sourceFiles: program.args,
     };
 }
@@ -25,32 +32,27 @@ function cliMain() {
         files = args.sourceFiles;
     }
     files.forEach((inputFile) => {
-        const inp = inputFile === '-' ? process.stdin.fd : inputFile;
-        let sourceCode = '';
         try {
-            sourceCode = fs.readFileSync(inp, 'utf8');
-            console.log(transpile(sourceCode));
-        }
-        catch (err) {
-            if (isIoError(err, 'ENOENT')) {
-                console.error(`Error: "${inp}" not found`);
-                process.exit(1);
-            }
-            else if (isIoError(err, 'EISDIR')) {
-                console.error(`Error: "${inp}" is a directory`);
+            const transpiled = generateTranspiledText(inputFile, args.generatedFileComment, args.project);
+            if (transpiled === undefined) {
                 process.exit(1);
             }
-            else if (isIoError(err, 'EAGAIN') && inp === process.stdin.fd) {
-                // Reading from stdin if there's no input causes error. This is a bug in node
-                console.error('Error: Failed to read from stdin');
-                process.exit(1);
-            }
-            else if (err instanceof WorkflowSyntaxError) {
-                prettyPrintSyntaxError(err, inputFile, sourceCode);
-                process.exit(1);
-            }
-            else if (err instanceof TSError) {
-                prettyPrintSyntaxError(err, inputFile, sourceCode);
+            writeOutput(transpiled, inputFile, args.outdir);
+        }
+        catch (err) {
+            if (isIoError(err)) {
+                let message;
+                if ('code' in err && err.code === 'EAGAIN' && inputFile === '-') {
+                    // Reading from stdin if there's no input causes error. This is a bug in node
+                    message = 'Error: Failed to read from stdin';
+                }
+                else if ('code' in err && err.code === 'EISDIR') {
+                    message = `Error: "${inputFile}" is a directory`;
+                }
+                else {
+                    message = err.message;
+                }
+                console.error(message);
                 process.exit(1);
             }
             else {
@@ -59,8 +61,56 @@ function cliMain() {
         }
     });
 }
-function isIoError(err, errorCode) {
-    return err instanceof Error && 'code' in err && err.code == errorCode;
+function generateTranspiledText(inputFile, addGeneratedFileComment, project) {
+    const inputIsStdIn = inputFile === '-';
+    const inp = inputIsStdIn ? process.stdin.fd : inputFile;
+    const sourceCode = fs.readFileSync(inp, 'utf8');
+    try {
+        const needsHeader = addGeneratedFileComment && !inputIsStdIn;
+        const header = needsHeader ? generatedFileComment(inputFile) : '';
+        const transpiled = transpile(sourceCode, inputFile, project);
+        return `${header}${transpiled}`;
+    }
+    catch (err) {
+        if (err instanceof WorkflowSyntaxError) {
+            prettyPrintSyntaxError(err, inputFile, sourceCode);
+            return undefined;
+        }
+        else if (err instanceof TSError) {
+            prettyPrintSyntaxError(err, inputFile, sourceCode);
+            return undefined;
+        }
+        else {
+            throw err;
+        }
+    }
+}
+function writeOutput(transpiled, inputFile, outdir) {
+    if (outdir !== undefined) {
+        if (!fs.existsSync(outdir)) {
+            fs.mkdirSync(outdir, { recursive: true });
+        }
+        const outputFile = createOutputFilename(inputFile, outdir);
+        fs.writeFileSync(outputFile, transpiled);
+    }
+    else {
+        process.stdout.write(transpiled);
+    }
+}
+function createOutputFilename(inputFile, outdir) {
+    const parsedInput = path.parse(inputFile);
+    return path.format({
+        dir: outdir,
+        name: parsedInput.name,
+        ext: '.yaml',
+    });
+}
+function generatedFileComment(inputFile) {
+    return (`# This file has been generated by "ts2workflows ${inputFile}"\n` +
+        '# Do not edit!\n\n');
+}
+function isIoError(err) {
+    return err instanceof Error && 'code' in err;
 }
 function prettyPrintSyntaxError(exception, inputFile, sourceCode) {
     console.error(errorDisplay(inputFile, sourceCode, exception.location));
@@ -108,6 +158,13 @@ function highlightedSourceCodeLine(sourceCode, lineNumber, start, end) {
     const markerLine = `${' '.repeat(start)}${'^'.repeat(markerLength)}`;
     return `${sourceLine}\n${markerLine}`;
 }
+function versionFromPackageJson() {
+    const currentFile = fileURLToPath(import.meta.url);
+    const currentDir = path.dirname(currentFile);
+    const packagePath = path.join(currentDir, '..', 'package.json');
+    const pjson = JSON.parse(fs.readFileSync(packagePath, 'utf-8'));
+    return pjson.version ?? '???';
+}
 if (import.meta.url.endsWith(process.argv[1]) ||
     process.argv[1].endsWith('/ts2workflows')) {
     cliMain();

package/dist/transpiler/expressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expressions.d.ts","sourceRoot":"","sources":["../../src/transpiler/expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAkB,MAAM,sCAAsC,CAAA;AAC/E,OAAO,EAGL,UAAU,EAGV,SAAS,EAMV,MAAM,uBAAuB,CAAA;AAI9B,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,GAAG,UAAU,CAO3E;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,CAAC,gBAAgB,GAC9B,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC,CAgCxC;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,QAAQ,CAAC,gBAAgB,GAC9B,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAG5B;AAsMD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,CAAC,gBAAgB,GAC9B,UAAU,CAcZ;AA0JD,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG3D;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAGvE;AA8CD,wBAAgB,aAAa,CAC3B,CAAC,SACG,QAAQ,CAAC,UAAU,GACnB,QAAQ,CAAC,QAAQ,GACjB,QAAQ,CAAC,aAAa,GACtB,IAAI,EACR,KAAK,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,CAgBlD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAElE"}
+{"version":3,"file":"expressions.d.ts","sourceRoot":"","sources":["../../src/transpiler/expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAkB,MAAM,sCAAsC,CAAA;AAC/E,OAAO,EAGL,UAAU,EAGV,SAAS,EAMV,MAAM,uBAAuB,CAAA;AAI9B,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,GAAG,UAAU,CAO3E;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,CAAC,gBAAgB,GAC9B,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC,CAgCxC;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,QAAQ,CAAC,gBAAgB,GAC9B,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAG5B;AAmOD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,CAAC,gBAAgB,GAC9B,UAAU,CAcZ;AA0JD,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG3D;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAGvE;AAoDD,wBAAgB,aAAa,CAC3B,CAAC,SACG,QAAQ,CAAC,UAAU,GACnB,QAAQ,CAAC,QAAQ,GACjB,QAAQ,CAAC,aAAa,GACtB,IAAI,EACR,KAAK,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,CAgBlD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAElE"}

package/dist/transpiler/expressions.js

@@ -87,6 +87,8 @@ function convertExpressionOrPrimitive(instance) {
             return convertExpressionOrPrimitive(instance.expression);
         case AST_NODE_TYPES.AwaitExpression:
             return convertExpressionOrPrimitive(instance.argument);
+        case AST_NODE_TYPES.TSInstantiationExpression:
+            return convertExpressionOrPrimitive(instance.expression);
         default:
             throw new WorkflowSyntaxError(`Not implemented expression type: ${instance.type}`, instance.loc);
     }
@@ -149,6 +151,7 @@ function convertUnaryExpression(instance) {
         throw new WorkflowSyntaxError('only prefix unary operators are supported', instance.loc);
     }
     let op;
+    let istypeof = false;
     switch (instance.operator) {
         case '+':
             op = '+';
@@ -164,6 +167,10 @@ function convertUnaryExpression(instance) {
             // This is wrong: the return value should be ignored.
             op = undefined;
             break;
+        case 'typeof':
+            op = undefined;
+            istypeof = true;
+            break;
         case undefined:
             op = undefined;
             break;
@@ -171,7 +178,27 @@ function convertUnaryExpression(instance) {
             throw new WorkflowSyntaxError(`Unsupported unary operator: ${instance.operator}`, instance.loc);
     }
     const ex = convertExpression(instance.argument);
-    return op ? new UnaryExpression(op, ex) : ex;
+    if (istypeof) {
+        return convertTypeOfExpression(ex);
+    }
+    else if (op) {
+        return new UnaryExpression(op, ex);
+    }
+    else {
+        return ex;
+    }
+}
+function convertTypeOfExpression(value) {
+    // Note for future rectoring: evalute value only once (in case it has side effects)
+    return new FunctionInvocationExpression('text.replace_all_regex', [
+        new FunctionInvocationExpression('text.replace_all_regex', [
+            new FunctionInvocationExpression('get_type', [value]),
+            new PrimitiveExpression('^(bytes|list|map|null)$'),
+            new PrimitiveExpression('object'),
+        ]),
+        new PrimitiveExpression('^(double|integer)$'),
+        new PrimitiveExpression('number'),
+    ]);
 }
 export function convertMemberExpression(node) {
     if (node.property.type === AST_NODE_TYPES.PrivateIdentifier) {
@@ -307,7 +334,12 @@ function convertTemplateLiteralToExpression(node) {
     const stringTerms = node.quasis
         .map((x) => x.value.cooked)
         .map((x) => new PrimitiveExpression(x));
-    const templateTerms = node.expressions.map(convertExpression);
+    const templateTerms = node.expressions
+        .map(convertExpression)
+        .map((ex) => new FunctionInvocationExpression('default', [
+        ex,
+        new PrimitiveExpression('null'),
+    ]));
     // interleave string parts and the expression parts starting with strings
     const interleavedTerms = stringTerms
         .slice(0, stringTerms.length - 1)
@@ -324,13 +356,8 @@ function convertTemplateLiteralToExpression(node) {
     if (interleavedTerms.length === 0) {
         return new PrimitiveExpression('');
     }
-    else if (interleavedTerms.length === 1) {
-        return interleavedTerms[0];
-    }
     else {
-        return interleavedTerms.reduce((previous, current) => {
-            return new BinaryExpression(previous, '+', current);
-        });
+        return interleavedTerms.reduce((previous, current) => new BinaryExpression(previous, '+', current));
     }
 }
 export function throwIfSpread(nodes) {

package/dist/transpiler/index.d.ts

@@ -1,2 +1,2 @@
-export declare function transpile(code: string): string;
+export declare function transpile(code: string, inputFile?: string, tsconfigPath?: string): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/transpiler/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transpiler/index.ts"],"names":[],"mappings":"AAYA,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW9C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transpiler/index.ts"],"names":[],"mappings":"AAaA,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAkBR"}

package/dist/transpiler/index.js

@@ -1,16 +1,22 @@
-import { parse, AST_NODE_TYPES, } from '@typescript-eslint/typescript-estree';
+import { AST_NODE_TYPES, parseAndGenerateServices, } from '@typescript-eslint/typescript-estree';
 import * as YAML from 'yaml';
 import { SubworkflowAST } from '../ast/steps.js';
 import { WorkflowSyntaxError } from '../errors.js';
 import { generateStepNames } from '../ast/stepnames.js';
 import { parseStatement } from './statements.js';
-export function transpile(code) {
+export function transpile(code, inputFile, tsconfigPath) {
     const parserOptions = {
         jsDocParsingMode: 'none',
         loc: true,
         range: false,
     };
-    const ast = parse(code, parserOptions);
+    if (tsconfigPath && inputFile && inputFile != '-') {
+        parserOptions.filePath = inputFile;
+        parserOptions.projectService = {
+            defaultProject: tsconfigPath,
+        };
+    }
+    const { ast } = parseAndGenerateServices(code, parserOptions);
     const workflowAst = { subworkflows: ast.body.flatMap(parseTopLevelStatement) };
     const workflow = generateStepNames(workflowAst);
     return YAML.stringify(workflow.render(), { lineWidth: 100 });
@@ -49,24 +55,14 @@ function parseSubworkflows(node) {
     const workflowParams = nodeParams.map((param) => {
         switch (param.type) {
             case AST_NODE_TYPES.Identifier:
-                return { name: param.name };
-            case AST_NODE_TYPES.AssignmentPattern:
-                if (param.left.type !== AST_NODE_TYPES.Identifier) {
-                    throw new WorkflowSyntaxError('The default value must be an identifier', param.left.loc);
-                }
-                if (param.right.type !== AST_NODE_TYPES.Literal) {
-                    throw new WorkflowSyntaxError('The default value must be a literal', param.right.loc);
+                if (param.optional) {
+                    return { name: param.name, default: null };
                 }
-                if (!(typeof param.right.value === 'string' ||
-                    typeof param.right.value === 'number' ||
-                    typeof param.right.value === 'boolean' ||
-                    param.right.value === null)) {
-                    throw new WorkflowSyntaxError('The default value must be a string, number, boolean or null', param.left.loc);
+                else {
+                    return { name: param.name };
                 }
-                return {
-                    name: param.left.name,
-                    default: param.right.value,
-                };
+            case AST_NODE_TYPES.AssignmentPattern:
+                return parseSubworkflowDefaultArgument(param);
             default:
                 throw new WorkflowSyntaxError('Function parameter must be an identifier or an assignment', param.loc);
         }
@@ -74,3 +70,31 @@ function parseSubworkflows(node) {
     const steps = parseStatement(node.body, {});
     return new SubworkflowAST(node.id.name, steps, workflowParams);
 }
+function parseSubworkflowDefaultArgument(param) {
+    if (param.left.type !== AST_NODE_TYPES.Identifier) {
+        throw new WorkflowSyntaxError('The default value must be an identifier', param.left.loc);
+    }
+    if (param.left.optional) {
+        throw new WorkflowSyntaxError("Parameter can't have default value and initializer", param.left.loc);
+    }
+    const name = param.left.name;
+    let defaultValue;
+    if (param.right.type === AST_NODE_TYPES.Identifier &&
+        param.right.name === 'undefined') {
+        defaultValue = null;
+    }
+    else if (param.right.type === AST_NODE_TYPES.Literal &&
+        (typeof param.right.value === 'string' ||
+            typeof param.right.value === 'number' ||
+            typeof param.right.value === 'boolean' ||
+            param.right.value === null)) {
+        defaultValue = param.right.value;
+    }
+    else {
+        throw new WorkflowSyntaxError('The default value must be a literal number, string, boolean, null, or undefined', param.right.loc);
+    }
+    return {
+        name,
+        default: defaultValue,
+    };
+}

package/dist/transpiler/statements.js

@@ -199,18 +199,21 @@ function createCallStep(node, argumentsNode, resultVariable) {
         throw new WorkflowSyntaxError('The first argument must be a Function', node.loc);
     }
     let functionName;
-    if (argumentsNode[0].type === AST_NODE_TYPES.Identifier) {
-        functionName = argumentsNode[0].name;
-    }
-    else if (argumentsNode[0].type === AST_NODE_TYPES.MemberExpression) {
-        const memberExp = convertMemberExpression(argumentsNode[0]);
+    const argNode = argumentsNode[0].type === AST_NODE_TYPES.TSInstantiationExpression
+        ? argumentsNode[0].expression
+        : argumentsNode[0];
+    if (argNode.type === AST_NODE_TYPES.Identifier) {
+        functionName = argNode.name;
+    }
+    else if (argNode.type === AST_NODE_TYPES.MemberExpression) {
+        const memberExp = convertMemberExpression(argNode);
         if (!isFullyQualifiedName(memberExp)) {
-            throw new WorkflowSyntaxError('Function name must be a fully-qualified name', argumentsNode[0].loc);
+            throw new WorkflowSyntaxError('Function name must be a fully-qualified name', argNode.loc);
         }
         functionName = memberExp.toString();
     }
     else {
-        throw new WorkflowSyntaxError('Expected an identifier or a member expression', argumentsNode[0].loc);
+        throw new WorkflowSyntaxError('Expected an identifier or a member expression', argNode.loc);
     }
     let args = {};
     if (argumentsNode.length >= 2) {

package/language_reference.md

@@ -34,11 +34,13 @@ Map keys can be identifiers or strings: `{temperature: -12}` or `{"temperature":
 
 ### Bytes type
 
-It is not possible to construct a bytes object expect by calling a function that returns bytes (e.g. base64.decode). It is not possible to do anything else with a bytes object than to assign it to a variable and to pass it one of the functions that take bytes type as input variable (e.g. base64.encode).
+A `bytes` object can only be constructed by calling a function that returns bytes (e.g. `base64.decode`). The only things that can be done with a `bytes` object is to assign it to variable and to pass the `bytes` object to one of the functions that take `bytes` type as input variable (e.g. `base64.encode`).
 
 ### null type
 
-In addition to the literal `null`, the Typescript `undefined` value is also treated as `null` in Workflows YAML.
+In addition to the literal `null`, the Typescript `undefined` value is also translated to `null` in Workflows YAML.
+
+Note that on Typescript-level typechecking `null` and `undefined` are considered distinct types.
 
 ### Implicit type conversions
 
@@ -79,6 +81,7 @@ sys.get_env('GOOGLE_CLOUD_PROJECT_ID')
 | ??           | nullish coalescing                           |
 | ?.           | optional chaining                            |
 | ? :          | conditional operator                         |
+| typeof       | return the type of the operand as a string   |
 
 The [precendence order of operators](https://cloud.google.com/workflows/docs/reference/syntax/datatypes#order-operations) is the same as in GCP Workflows.
 
@@ -98,7 +101,7 @@ is converted to an [if() expression](https://cloud.google.com/workflows/docs/ref
 ${if(x > 0, "positive", "not positive")}
 ```
 
-⚠️ Note that Workflows always evaluates both expression branches unlike Typescript which evaluates only the branch that gets executed.
+⚠️ Workflows always evaluates both expression branches unlike Typescript which evaluates only the branch that gets executed.
 
 ### Nullish coalescing operator
 
@@ -114,7 +117,7 @@ is converted to a [default() expression](https://cloud.google.com/workflows/docs
 ${default(x, "default value")}
 ```
 
-⚠️ Note that Workflows always evaluates the right-hand side expression unlike Typescript which evaluates the right-hand side only if the left-hand side is `null` or `undefined`.
+⚠️ Workflows always evaluates the right-hand side expression unlike Typescript which evaluates the right-hand side only if the left-hand side is `null` or `undefined`.
 
 ### Optional chaining
 
@@ -130,11 +133,28 @@ is converted to a [map.get() expression](https://cloud.google.com/workflows/docs
 ${map.get(data, ["user", "name"])}
 ```
 
+### typeof operator
+
+Returns the type of the operand as a string. The return values are the same ones that Javascript typeof operation returns. The following table shows the possible values for different operand types.
+
+| Operand | Result    |
+| ------- | --------- |
+| boolean | "boolean" |
+| bytes   | "object"  |
+| double  | "number"  |
+| integer | "number"  |
+| list    | "object"  |
+| map     | "object"  |
+| string  | "string"  |
+| null    | "object"  |
+
+The typeof operator is useful as a type guard in Typescript (e.g. `typeof x === "string"`). For other use cases, consider the [get_type function](https://cloud.google.com/workflows/docs/reference/stdlib/expression-helpers#type_functions) from the Workflows standard library. It makes finer distinctions between types. It, for example, returns distinct values for lists and maps.
+
 ## Template literals
 
 Template literals are strings that support string interpolation. For example, `Hello ${name}`.
 
-⚠️ Interpolated values can (only) be numbers, strings or booleans. Other types will throw a TypeError at runtime.
+⚠️ Interpolated values can (only) be numbers, strings, booleans or nulls. Other types will throw a TypeError at runtime.
 
 ## Subworkflow definitions
 
@@ -155,7 +175,7 @@ function anotherWorkflow(): number {
 }
 ```
 
-Workflows can have parameters:
+Subworkflows can have parameters:
 
 ```typescript
 function multiply(firstFactor: number, secondFactor: number): number {
@@ -163,10 +183,18 @@ function multiply(firstFactor: number, secondFactor: number): number {
 }
 ```
 
-Parameters can be optional and have a default value that is used if a value is not provided in a subworkflow call:
+Optional parameters can be specified with a question mark. If a value is not provided on the call site, the value is set to `null` during the subworkflow execution. The following subworkflow can be called as `greet()` or `greet("Tiabeanie")`.
+
+```typescript
+function greet(name?: string): string {
+  return 'Hello, ${name ?? "world"}'
+}
+```
+
+Parameters can have default values. The default value is used if a value is not provided in a subworkflow call. The following subworkflow can be called with one parameter (`log(3)`) or with two parameters (`log(3, 2)`).
 
 ```typescript
-function log(x, base = 10) {
+function log(x: number, base: number = 10) {
   return 'Should compute the logarithm of x'
 }
 ```
@@ -201,7 +229,7 @@ is converted to an [assign step](https://cloud.google.com/workflows/docs/referen
 
 This syntax can be used to call [standard library functions](https://cloud.google.com/workflows/docs/reference/stdlib/overview), subworkflows or connectors. Note that Javascript runtime functions (such as `fetch()`, `console.error()` or `new XMLHttpRequest()`) are not available on Workflows.
 
-GCP Workflows language has two ways of calling functions and subworkflows: as expression in an [assign step](https://cloud.google.com/workflows/docs/reference/syntax/variables#assign-step) or as [call step](https://cloud.google.com/workflows/docs/reference/syntax/calls). They can mostly be used interchangeably. However, [blocking calls](https://cloud.google.com/workflows/docs/reference/syntax/expressions#blocking-calls) must be made as call steps. The transpiler tries to automatically output a call step when necessary.
+GCP Workflows language has two ways of calling functions and subworkflows: as expression in an [assign step](https://cloud.google.com/workflows/docs/reference/syntax/variables#assign-step) or as [call step](https://cloud.google.com/workflows/docs/reference/syntax/calls). They can mostly be used interchangeably. However, [blocking calls](https://cloud.google.com/workflows/docs/reference/syntax/expressions#blocking-calls) must be made as call steps. The ts2workflows transpiler tries to automatically output a call step when necessary.
 
 It is also possible to force a function to be called as call step. This might be useful, if the transpiler fails to output call step when it should, or if you want to use named parameters. For example, the following Typescript program
 
@@ -738,7 +766,7 @@ is converted to a step with the label `setName`:
 
 ## Type annotations for standard library functions
 
-Type annotations for GCP Workflows standard library functions and expression helpers are provided by importing "ts2workflows/types/workflowslib".
+Type annotations for [GCP Workflows standard library functions and expression helpers](https://cloud.google.com/workflows/docs/reference/stdlib/overview) are provided by importing "ts2workflows/types/workflowslib".
 
 ```typescript
 import { sys } from 'ts2workflows/types/workflowslib'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts2workflows",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Transpile Typescript code to GCP Workflows programs",
   "homepage": "https://github.com/aajanki/ts2workflows",
   "repository": {
@@ -20,7 +20,7 @@
     "lint": "eslint src test scripts",
     "format": "prettier . --write",
     "test": "mocha",
-    "prepare": "husky"
+    "prepare": "husky && npm run build"
   },
   "lint-staged": {
     "src/**/*.ts": [
@@ -66,7 +66,7 @@
     "eslint": "^9.10.0",
     "husky": "^9.1.6",
     "lint-staged": "^15.2.10",
-    "mocha": "^10.4.0",
+    "mocha": "^11.1.0",
     "prettier": "^3.2.5",
     "rimraf": "^5.0.10",
     "tsx": "^4.10.2",
@@ -74,7 +74,7 @@
   },
   "dependencies": {
     "@typescript-eslint/typescript-estree": "^8.0.0",
-    "commander": "^12.1.0",
+    "commander": "^13.1.0",
     "typescript": "^5.0.0",
     "yaml": "^2.4.2"
   }

package/types/workflowslib.d.ts

@@ -1,11 +1,13 @@
+export {}
+
 // Type annotations for GCP Workflows expression helpers, standard library
 // functions and (some) connectors
 
 // An opaque bytes type.
 // This should really be defined in the transpiler, not here.
-declare const tag: unique symbol
+declare const __bytes_tag: unique symbol
 export interface bytes {
-  readonly [tag]: 'bytes'
+  readonly [__bytes_tag]: 'bytes'
 }
 
 // GCP Workflows expression helpers
@@ -37,17 +39,36 @@ export declare namespace base64 {
 }
 
 export declare namespace events {
-  function await_callback(
+  function await_callback<ResponseType = unknown>(
     callback: {
       url: string
     },
     timeout?: number,
-  ): object
+  ): {
+    http_request: {
+      body: ResponseType | null
+      headers: Record<string, string>
+      method: string
+      query: Record<string, string>
+      url: string
+    }
+    received_time: string
+    type: string
+  }
   function create_callback_endpoint(http_callback_method: string): {
     url: string
   }
 }
 
+export declare namespace hash {
+  export function compute_checksum(data: bytes, algorithm: string): bytes
+  export function compute_hmac(
+    key: bytes,
+    data: bytes,
+    algorithm: string,
+  ): bytes
+}
+
 export declare namespace http {
   export function default_retry(errormap: Record<string, any>): void
   export function default_retry_non_idempotent(
@@ -59,7 +80,7 @@ export declare namespace http {
   export function default_retry_predicate_non_idempotent(
     errormap: Record<string, any>,
   ): boolean
-  function _delete(
+  function _delete<ResponseType = unknown>(
     url: string,
     timeout?: number,
     body?: unknown,
@@ -72,11 +93,11 @@ export declare namespace http {
     private_service_name?: string,
     ca_certificate?: string,
   ): {
-    body: unknown
+    body: ResponseType
     code: number
     headers: Record<string, string>
   }
-  export function get(
+  export function get<ResponseType = unknown>(
     url: string,
     timeout?: number,
     headers?: Record<string, string>,
@@ -88,11 +109,11 @@ export declare namespace http {
     private_service_name?: string,
     ca_certificate?: string,
   ): {
-    body: unknown
+    body: ResponseType
     code: number
     headers: Record<string, string>
   }
-  export function patch(
+  export function patch<ResponseType = unknown>(
     url: string,
     timeout?: number,
     body?: unknown,
@@ -105,11 +126,11 @@ export declare namespace http {
     private_service_name?: string,
     ca_certificate?: string,
   ): {
-    body: unknown
+    body: ResponseType
     code: number
     headers: Record<string, string>
   }
-  export function post(
+  export function post<ResponseType = unknown>(
     url: string,
     timeout?: number,
     body?: unknown,
@@ -122,11 +143,11 @@ export declare namespace http {
     private_service_name?: string,
     ca_certificate?: string,
   ): {
-    body: unknown
+    body: ResponseType
     code: number
     headers: Record<string, string>
   }
-  export function put(
+  export function put<ResponseType = unknown>(
     url: string,
     timeout?: number,
     body?: unknown,
@@ -139,11 +160,11 @@ export declare namespace http {
     private_service_name?: string,
     ca_certificate?: string,
   ): {
-    body: unknown
+    body: ResponseType
     code: number
     headers: Record<string, string>
   }
-  export function request(
+  export function request<ResponseType = unknown>(
     method: string,
     url: string,
     timeout?: number,
@@ -157,7 +178,7 @@ export declare namespace http {
     private_service_name?: string,
     ca_certificate?: string,
   ): {
-    body: unknown
+    body: ResponseType
     code: number
     headers: Record<string, string>
   }
@@ -173,7 +194,8 @@ export declare namespace json {
       | boolean
       | unknown[]
       | Record<string, unknown>
-      | null,
+      | null
+      | undefined,
     indent?:
       | boolean
       | {
@@ -188,7 +210,8 @@ export declare namespace json {
       | boolean
       | unknown[]
       | Record<string, unknown>
-      | null,
+      | null
+      | undefined,
     indent?:
       | boolean
       | {
@@ -237,7 +260,8 @@ export declare namespace retry {
 }
 
 export declare namespace sys {
-  function get_env(name: string, default_value?: string): string | undefined
+  function get_env(name: string): string | null
+  function get_env(name: string, default_value: string): string
   function log(
     data?: number | boolean | string | unknown[] | object,
     severity?: string,
@@ -716,7 +740,7 @@ export declare function retry_policy(
     | ((errormap: Record<string, any>) => void)
     | {
         predicate?: (errormap: Record<string, any>) => boolean
-        max_retries: number | string | null
+        max_retries?: number | string | null
         backoff: {
           initial_delay?: number | string | null
           max_delay?: number | string | null