ts2workflows 0.4.0 → 0.6.0

package/dist/transpiler/transformations.js

@@ -1,7 +1,7 @@
-import { AssignStepAST, CallStepAST, ForStepAST, RaiseStepAST, ReturnStepAST, SwitchStepAST, TryStepAST, } from '../ast/steps.js';
+import { AssignStepAST, CallStepAST, ForStepAST, RaiseStepAST, ReturnStepAST, SwitchStepAST, } from '../ast/steps.js';
 import { InternalTranspilingError } from '../errors.js';
-import { isRecord } from '../utils.js';
-import { BinaryExpression, FunctionInvocationExpression, MemberExpression, PrimitiveExpression, UnaryExpression, VariableReferenceExpression, expressionToLiteralValueOrLiteralExpression, isExpression, isFullyQualifiedName, isLiteral, } from '../ast/expressions.js';
+import { isRecord, mapRecordValues } from '../utils.js';
+import { BinaryExpression, FunctionInvocationExpression, MemberExpression, PrimitiveExpression, UnaryExpression, VariableReferenceExpression, isExpression, isLiteral, } from '../ast/expressions.js';
 import { blockingFunctions } from './generated/functionMetadata.js';
 const Unmodified = Symbol();
 /**
@@ -11,7 +11,7 @@ const Unmodified = Symbol();
  * called on each nesting level separately.
  */
 export function transformAST(steps) {
-    return blockingCallsAsCallSteps(runtimeFunctionImplementation(flattenPlainNextConditions(combineRetryBlocksToTry(mergeAssignSteps(mapLiteralsAsAssignSteps(steps))))));
+    return blockingCallsAsCallSteps(runtimeFunctionImplementation(flattenPlainNextConditions(mergeAssignSteps(mapLiteralsAsAssignSteps(steps)))));
 }
 /**
  * Merge consecutive assign steps into one assign step
@@ -25,7 +25,7 @@ function mergeAssignSteps(steps) {
             prev?.tag === 'assign' &&
             prev.assignments.length < 50 &&
             !prev.next) {
-            const merged = new AssignStepAST(prev.assignments.concat(current.assignments), current.next);
+            const merged = new AssignStepAST(prev.assignments.concat(current.assignments), current.next, prev.label ?? current.label);
             acc.pop();
             acc.push(merged);
         }
@@ -35,95 +35,6 @@ function mergeAssignSteps(steps) {
         return acc;
     }, []);
 }
-/**
- * Transform a retry_policy call step to a retry block in a preceeding try step
- */
-function combineRetryBlocksToTry(steps) {
-    return steps.reduce((acc, current) => {
-        const prev = acc.length > 0 ? acc[acc.length - 1] : null;
-        if (current.tag === 'call' && current.call === 'retry_policy') {
-            if (prev?.tag === 'try') {
-                if (prev.retryPolicy) {
-                    throw new InternalTranspilingError('Retry policy already assigned!');
-                }
-                let retryPolicy = undefined;
-                const retryParameters = current.args;
-                if (retryParameters) {
-                    const retryPolicyEx = retryParameters.policy;
-                    if (retryPolicyEx && isFullyQualifiedName(retryPolicyEx)) {
-                        retryPolicy = retryPolicyEx.toString();
-                    }
-                    if (!retryPolicy) {
-                        let predicate = '';
-                        const predicateEx = retryParameters.predicate;
-                        if (predicateEx) {
-                            if (isFullyQualifiedName(predicateEx)) {
-                                predicate = predicateEx.toString();
-                            }
-                            else {
-                                throw new InternalTranspilingError('"predicate" must be a function name');
-                            }
-                        }
-                        const maxRetries = parseRetryPolicyNumber(retryParameters, 'max_retries');
-                        let initialDelay = 1;
-                        let maxDelay = 1;
-                        let multiplier = 1;
-                        const backoffEx = retryParameters.backoff;
-                        if (backoffEx &&
-                            isLiteral(backoffEx) &&
-                            backoffEx.expressionType === 'primitive') {
-                            const backoffLit = backoffEx.value;
-                            if (isRecord(backoffLit)) {
-                                initialDelay = parseRetryPolicyNumber(backoffLit, 'initial_delay');
-                                maxDelay = parseRetryPolicyNumber(backoffLit, 'max_delay');
-                                multiplier = parseRetryPolicyNumber(backoffLit, 'multiplier');
-                            }
-                        }
-                        retryPolicy = {
-                            predicate,
-                            maxRetries,
-                            backoff: {
-                                initialDelay,
-                                maxDelay,
-                                multiplier,
-                            },
-                        };
-                    }
-                }
-                const tryWithRetry = new TryStepAST(prev.trySteps, prev.exceptSteps, retryPolicy, prev.errorMap);
-                acc.pop();
-                acc.push(tryWithRetry);
-            }
-            // If prev is not a try step, "retry_policy" is ignored. Should print a warning.
-        }
-        else {
-            acc.push(current);
-        }
-        return acc;
-    }, []);
-}
-function parseRetryPolicyNumber(record, keyName) {
-    let primitiveValue;
-    const primitiveOrExpression = record[keyName];
-    if (primitiveOrExpression && isExpression(primitiveOrExpression)) {
-        if (isLiteral(primitiveOrExpression)) {
-            primitiveValue = expressionToLiteralValueOrLiteralExpression(primitiveOrExpression);
-        }
-        else {
-            throw new InternalTranspilingError(`Support for non-literal "${keyName}" values not yet implemented`);
-        }
-    }
-    else if (primitiveOrExpression) {
-        primitiveValue = primitiveOrExpression;
-    }
-    else {
-        throw new InternalTranspilingError(`"${keyName}" expected`);
-    }
-    if (typeof primitiveValue !== 'number') {
-        throw new InternalTranspilingError(`"${keyName}" must be a number`);
-    }
-    return primitiveValue;
-}
 /**
  * Merge a next step to the previous step.
  *
@@ -301,11 +212,11 @@ function transformExpressionsAssign(step, transform) {
 function transformExpressionsCall(step, transform) {
     if (step.args) {
         const newSteps = [];
-        const newArgs = Object.fromEntries(Object.entries(step.args).map(([name, ex]) => {
+        const newArgs = mapRecordValues(step.args, (ex) => {
             const [steps2, ex2] = transform(ex);
             newSteps.push(...steps2);
-            return [name, ex2];
-        }));
+            return ex2;
+        });
         newSteps.push(new CallStepAST(step.call, newArgs, step.result, step.label));
         return newSteps;
     }
@@ -357,8 +268,8 @@ function transformExpressionsSwitch(step, transform) {
     newSteps.push(new SwitchStepAST(newBranches, step.label));
     return newSteps;
 }
-function transformExpression(ex, transformer) {
-    const transformed = transformer(ex);
+function transformExpression(ex, transform) {
+    const transformed = transform(ex);
     if (transformed !== Unmodified) {
         // Use the transformed version of this term
         return transformed;
@@ -367,28 +278,76 @@ function transformExpression(ex, transformer) {
         // Otherwise, recurse into the nested expression
         switch (ex.expressionType) {
             case 'primitive':
-            case 'variableReference':
-                return ex;
+                if (isLiteral(ex)) {
+                    return ex;
+                }
+                else {
+                    const newPrimitive = transformPrimitive(ex.value, transform);
+                    return newPrimitive === ex.value
+                        ? ex
+                        : new PrimitiveExpression(newPrimitive);
+                }
             case 'binary':
-                return transformBinaryExpression(ex, transformer);
+                return transformBinaryExpression(ex, transform);
             case 'functionInvocation':
-                return transformFunctionInvocationExpression(ex, transformer);
+                return transformFunctionInvocationExpression(ex, transform);
             case 'member':
-                return new MemberExpression(transformExpression(ex.object, transformer), transformExpression(ex.property, transformer), ex.computed);
+                return transformMemberExpression(ex, transform);
             case 'unary':
-                return new UnaryExpression(ex.operator, transformExpression(ex.value, transformer));
+                return transformUnaryExpression(ex, transform);
+            case 'variableReference':
+                return ex;
         }
     }
 }
-function transformBinaryExpression(ex, transformer) {
+function transformPrimitive(val, transform) {
+    if (Array.isArray(val)) {
+        return val.map((x) => isExpression(x)
+            ? transformExpression(x, transform)
+            : transformPrimitive(x, transform));
+    }
+    else if (isRecord(val)) {
+        return mapRecordValues(val, (x) => isExpression(x)
+            ? transformExpression(x, transform)
+            : transformPrimitive(x, transform));
+    }
+    else {
+        return val;
+    }
+}
+function transformBinaryExpression(ex, transform) {
     // Transform left first to keep the correct order of execution of sub-expressions
-    const newLeft = transformExpression(ex.left, transformer);
-    const newRight = transformExpression(ex.right, transformer);
-    return new BinaryExpression(newLeft, ex.binaryOperator, newRight);
+    const newLeft = transformExpression(ex.left, transform);
+    const newRight = transformExpression(ex.right, transform);
+    if (newLeft === ex.left && newRight === ex.right) {
+        return ex;
+    }
+    else {
+        return new BinaryExpression(newLeft, ex.binaryOperator, newRight);
+    }
 }
-function transformFunctionInvocationExpression(ex, transformer) {
-    const newArguments = ex.arguments.map((x) => transformExpression(x, transformer));
-    return new FunctionInvocationExpression(ex.functionName, newArguments);
+function transformFunctionInvocationExpression(ex, transform) {
+    const newArguments = ex.arguments.map((x) => transformExpression(x, transform));
+    if (newArguments.every((x, i) => x === ex.arguments[i])) {
+        return ex;
+    }
+    else {
+        return new FunctionInvocationExpression(ex.functionName, newArguments);
+    }
+}
+function transformMemberExpression(ex, transform) {
+    const newObject = transformExpression(ex.object, transform);
+    const newProperty = transformExpression(ex.property, transform);
+    if (newObject === ex.object && newProperty === ex.property) {
+        return ex;
+    }
+    else {
+        return new MemberExpression(newObject, newProperty, ex.computed);
+    }
+}
+function transformUnaryExpression(ex, transform) {
+    const newValue = transformExpression(ex.value, transform);
+    return newValue === ex.value ? ex : new UnaryExpression(ex.operator, newValue);
 }
 /**
  * Search for map literals in expressions and replace them with assign step + variable.
@@ -410,89 +369,143 @@ function transformFunctionInvocationExpression(ex, transformer) {
  *     return: ${__temp0.value}
  */
 function mapLiteralsAsAssignSteps(steps) {
-    function transformer(ex) {
-        const generateTemporaryVariableName = createTempVariableGenerator();
-        const { transformedExpression, assignSteps } = replaceMapLiterals(ex, generateTemporaryVariableName);
-        return [assignSteps, transformedExpression];
-    }
-    return steps.reduce((acc, current) => {
-        let needsTransformation = true;
-        // These steps are allowed to contain map literals if the map is the
-        // main expression
-        if (current.tag === 'assign') {
-            // This does the transformation a bit too eagerly: If any of the
-            // assignments need the map literal extraction, it is done on all of
-            // the variables.
-            needsTransformation = !current.assignments.every(([, value]) => {
-                return value.expressionType === 'primitive';
-            });
-        }
-        else if (current.tag === 'raise' || current.tag === 'return') {
-            needsTransformation =
-                current.value !== undefined &&
-                    includesExtractableMapLiteral(current.value, true);
-        }
-        else if (current.tag === 'call') {
-            if (current.args) {
-                needsTransformation = Object.values(current.args).some((ex) => includesExtractableMapLiteral(ex, true));
-            }
-        }
-        if (needsTransformation) {
-            const transformedSteps = transformStepExpressions(current, transformer);
-            acc.push(...transformedSteps);
-        }
-        else {
-            acc.push(current);
-        }
-        return acc;
-    }, []);
+    return steps.flatMap((step) => transformStepExpressions(step, transformNestedMaps));
+}
+function transformNestedMaps(ex) {
+    const generateTemporaryVariableName = createTempVariableGenerator();
+    const { transformedExpression, tempVariables } = extractNestedMaps(ex, generateTemporaryVariableName, 0);
+    const assignments = tempVariables.length > 0 ? [new AssignStepAST(tempVariables)] : [];
+    return [assignments, transformedExpression];
 }
-// Return true if the string representation of ex would include {}
-function includesExtractableMapLiteral(ex, parentAllowsMaps) {
+function extractNestedMaps(ex, generateName, nestingLevel) {
     switch (ex.expressionType) {
         case 'primitive':
-            if (isRecord(ex.value)) {
-                return (!parentAllowsMaps ||
-                    Object.values(ex.value).some((x) => isExpression(x) &&
-                        includesExtractableMapLiteral(x, parentAllowsMaps)));
-            }
-            else if (Array.isArray(ex.value)) {
-                return ex.value.some((x) => isExpression(x) &&
-                    includesExtractableMapLiteral(x, parentAllowsMaps));
-            }
-            else {
-                return false;
-            }
+            return extractNestedMapPrimitive(ex.value, generateName, nestingLevel);
         case 'binary':
-            return (includesExtractableMapLiteral(ex.left, parentAllowsMaps) ||
-                includesExtractableMapLiteral(ex.right, parentAllowsMaps));
+            return extractNestedMapBinary(ex, generateName, nestingLevel);
         case 'variableReference':
-            return false;
-        case 'unary':
-            return includesExtractableMapLiteral(ex.value, parentAllowsMaps);
+            return { transformedExpression: ex, tempVariables: [] };
         case 'functionInvocation':
-            return ex.arguments.some((x) => includesExtractableMapLiteral(x, false));
+            return extractNestedMapFunctionInvocation(ex, generateName, nestingLevel);
         case 'member':
-            return (includesExtractableMapLiteral(ex.object, false) ||
-                includesExtractableMapLiteral(ex.property, false));
+            return extractNestedMapMember(ex, generateName, nestingLevel);
+        case 'unary':
+            return extractNestedMapUnary(ex, generateName, nestingLevel);
+    }
+}
+function extractNestedMapPrimitive(primitiveEx, generateName, nestingLevel) {
+    const { transformed, tempVariables } = extractNestedMapPrimitiveRecursive(primitiveEx, generateName, nestingLevel);
+    const ex = isExpression(transformed)
+        ? transformed
+        : new PrimitiveExpression(transformed);
+    return {
+        transformedExpression: ex,
+        tempVariables,
+    };
+}
+function extractNestedMapPrimitiveRecursive(primitiveEx, generateName, nestingLevel) {
+    if (typeof primitiveEx === 'string' ||
+        typeof primitiveEx === 'number' ||
+        typeof primitiveEx === 'boolean' ||
+        primitiveEx === null) {
+        return {
+            transformed: primitiveEx,
+            tempVariables: [],
+        };
+    }
+    else if (Array.isArray(primitiveEx)) {
+        return extractMapsInList(primitiveEx, generateName, nestingLevel);
+    }
+    else {
+        return extractMapsInMap(primitiveEx, generateName, nestingLevel);
     }
 }
-function replaceMapLiterals(expression, generateName) {
-    function replace(ex) {
-        if (ex.expressionType === 'primitive' && isRecord(ex.value)) {
-            const tempVariable = generateName();
-            assignSteps.push(new AssignStepAST([[tempVariable, new PrimitiveExpression(ex.value)]]));
-            // replace the map literal with a reference to the temporary variable
-            return new VariableReferenceExpression(tempVariable);
+function extractMapsInList(primitiveEx, generateName, nestingLevel) {
+    const { tempVariables, elements } = primitiveEx.reduce((acc, val) => {
+        if (isExpression(val)) {
+            const { transformedExpression, tempVariables: temps } = extractNestedMaps(val, generateName, nestingLevel);
+            acc.tempVariables.push(...temps);
+            acc.elements.push(transformedExpression);
         }
         else {
-            return Unmodified;
+            const { transformed, tempVariables: temps } = extractNestedMapPrimitiveRecursive(val, generateName, nestingLevel);
+            acc.tempVariables.push(...temps);
+            acc.elements.push(transformed);
+        }
+        return acc;
+    }, {
+        tempVariables: [],
+        elements: [],
+    });
+    return {
+        tempVariables,
+        transformed: elements,
+    };
+}
+function extractMapsInMap(primitiveEx, generateName, nestingLevel) {
+    const { tempVariables, properties } = Object.entries(primitiveEx).reduce((acc, [key, val]) => {
+        if (isExpression(val)) {
+            const { transformedExpression, tempVariables: temps } = extractNestedMaps(val, generateName, 0);
+            acc.tempVariables.push(...temps);
+            acc.properties[key] = transformedExpression;
         }
+        else {
+            const { transformed, tempVariables: temps } = extractNestedMapPrimitiveRecursive(val, generateName, 0);
+            acc.tempVariables.push(...temps);
+            acc.properties[key] = transformed;
+        }
+        return acc;
+    }, {
+        tempVariables: [],
+        properties: {},
+    });
+    let newValue;
+    if (nestingLevel === 0) {
+        newValue = properties;
+    }
+    else {
+        const name = generateName();
+        tempVariables.push([name, new PrimitiveExpression(properties)]);
+        newValue = new VariableReferenceExpression(name);
     }
-    const assignSteps = [];
     return {
-        transformedExpression: transformExpression(expression, replace),
-        assignSteps,
+        transformed: newValue,
+        tempVariables,
+    };
+}
+function extractNestedMapFunctionInvocation(ex, generateName, nestingLevel) {
+    const { expressions, temps } = ex.arguments.reduce((acc, arg) => {
+        const { transformedExpression, tempVariables } = extractNestedMaps(arg, generateName, nestingLevel + 1);
+        acc.expressions.push(transformedExpression);
+        acc.temps.push(...tempVariables);
+        return acc;
+    }, { expressions: [], temps: [] });
+    return {
+        transformedExpression: new FunctionInvocationExpression(ex.functionName, expressions),
+        tempVariables: temps,
+    };
+}
+function extractNestedMapBinary(ex, generateName, nestingLevel) {
+    const left = extractNestedMaps(ex.left, generateName, nestingLevel + 1);
+    const right = extractNestedMaps(ex.right, generateName, nestingLevel + 1);
+    return {
+        transformedExpression: new BinaryExpression(left.transformedExpression, ex.binaryOperator, right.transformedExpression),
+        tempVariables: left.tempVariables.concat(right.tempVariables),
+    };
+}
+function extractNestedMapMember(ex, generateName, nestingLevel) {
+    const obj = extractNestedMaps(ex.object, generateName, nestingLevel + 1);
+    const pr = extractNestedMaps(ex.property, generateName, nestingLevel + 1);
+    return {
+        transformedExpression: new MemberExpression(obj.transformedExpression, pr.transformedExpression, ex.computed),
+        tempVariables: obj.tempVariables.concat(pr.tempVariables),
+    };
+}
+function extractNestedMapUnary(ex, generateName, nestingLevel) {
+    const { transformedExpression, tempVariables } = extractNestedMaps(ex.value, generateName, nestingLevel);
+    return {
+        transformedExpression: new UnaryExpression(ex.operator, transformedExpression),
+        tempVariables,
     };
 }
 /**

package/dist/utils.d.ts

@@ -1,2 +1,13 @@
 export declare function isRecord(object: unknown): object is Record<keyof never, unknown>;
+/**
+ * Apply f to values of obj and return the result
+ */
+export declare function mapRecordValues<T, U>(obj: Record<string, T>, f: (t: T) => U): Record<string, U>;
+/**
+ * Like arr.flatMap() but the callback takes two consecutive array elements.
+ *
+ * During the last execution of the callback, the second argument (which would
+ * be element after the last array element) will be undefined.
+ */
+export declare function flatMapPair<T, U>(arr: T[], callback: (val: T, next: T | undefined) => U[]): U[];
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,QAAQ,CACtB,MAAM,EAAE,OAAO,GACd,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE,OAAO,CAAC,CAExC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,QAAQ,CACtB,MAAM,EAAE,OAAO,GACd,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE,OAAO,CAAC,CAExC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,CAAC,EAClC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EACtB,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GACb,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAEnB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAC9B,GAAG,EAAE,CAAC,EAAE,EACR,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,EAAE,GAC7C,CAAC,EAAE,CAaL"}

package/dist/utils.js

@@ -1,3 +1,26 @@
 export function isRecord(object) {
     return object instanceof Object && object.constructor === Object;
 }
+/**
+ * Apply f to values of obj and return the result
+ */
+export function mapRecordValues(obj, f) {
+    return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, f(v)]));
+}
+/**
+ * Like arr.flatMap() but the callback takes two consecutive array elements.
+ *
+ * During the last execution of the callback, the second argument (which would
+ * be element after the last array element) will be undefined.
+ */
+export function flatMapPair(arr, callback) {
+    if (arr.length <= 0) {
+        return [];
+    }
+    const mapped = [];
+    for (let i = 0; i < arr.length - 1; i++) {
+        mapped.push(...callback(arr[i], arr[i + 1]));
+    }
+    mapped.push(...callback(arr[arr.length - 1], undefined));
+    return mapped;
+}

package/language_reference.md

@@ -561,7 +561,7 @@ parallel(
 )
 ```
 
-## Try/catch statements
+## Try/catch/finally statements
 
 The statement
 
@@ -592,13 +592,48 @@ is compiled to the following [try/except structure](https://cloud.google.com/wor
 
 The error variable and other variables created inside the catch block are accessible only in that block's scope (similar to [the variable scoping in Workflows](https://cloud.google.com/workflows/docs/reference/syntax/catching-errors#variable-scope)).
 
+Finally block is also supported:
+
+```javascript
+try {
+  return readFile()
+} catch (err) {
+  return 'Error!'
+} finally {
+  closeFile()
+}
+```
+
+If an exception gets thrown inside a try block, the stack trace in Workflows logs will misleadingly show the exception originating from inside the finally block. This happens because the implementation of the finally block catches the original exception and later throws an identical exception. The original source location of the exception is lost.
+
+⚠️ At the moment, break and continue are not supported in a try or a catch block if there is a related finally block.
+
 ## Retrying on errors
 
 It is possible to set a retry policy for a try-catch statement. Because Typescript does not have `retry` keyword, the retry is implemented by a special `retry_policy` function. It must be called immediately after a try-catch block. A call to the `retry_policy` is ignored elsewhere.
 
-The `retry_policy` function must be called with parameters defining a retry policy. It can be either a policy provided by GCP Workflows or a custom retry policy. See the GCP documentation for the [required parameters for the two policy types](https://cloud.google.com/workflows/docs/reference/syntax/retrying#try-retry).
+Finally and catch blocks are run after possible retry attempts. The following sample retries `http.get()` if it throws an exception and executes `sys.log('Error!')` and `closeConnection()` after retry attempts.
 
-A sample with a GCP-provided retry policy:
+```javascript
+import { http, retry_policy, sys } from 'ts2workflows/types/workflowslib'
+
+function main() {
+  try {
+    http.get('https://visit.dreamland.test/')
+  } catch (err) {
+    sys.log('Error!')
+  } finally {
+    closeConnection()
+  }
+  retry_policy(http.default_retry)
+}
+```
+
+The `retry_policy` function must be called with a parameter that defines the retry policy. It can be either a policy provided by GCP Workflows or a custom retry policy.
+
+### GCP-provided retry policy
+
+GCP retry policy must be either `http.default_retry` or `http.default_retry_non_idempotent`. Their effects are described by the [GCP documentation](https://cloud.google.com/workflows/docs/reference/syntax/retrying#default-retry-policy).
 
 ```javascript
 import { http, retry_policy } from 'ts2workflows/types/workflowslib'
@@ -609,11 +644,15 @@ function main() {
   } catch (err) {
     return 'Error!'
   }
-  retry_policy({ policy: http.default_retry })
+  retry_policy(http.default_retry)
 }
 ```
 
-A sample with a custom retry policy:
+### Custom retry policy
+
+A custom retry policy is an object with the properties shown in the following example. See the GCP documentation for the [explanation of the properties](https://cloud.google.com/workflows/docs/reference/syntax/retrying#try-retry).
+
+The parameter must be a literal map object (not a variable). The values may be literals or expressions.
 
 ```javascript
 import { http, retry_policy } from 'ts2workflows/types/workflowslib'
@@ -766,11 +805,9 @@ The `parallel` function executes code blocks in parallel (using [parallel step](
 ```typescript
 function retry_policy(
   params:
+    | ((errormap: Record<string, any>) => void)
     | {
-        policy: (exception: unknown) => void
-      }
-    | {
-        predicate: (exception: unknown) => boolean
+        predicate: (errormap: Record<string, any>) => boolean
         max_retries: number
         backoff: {
           initial_delay: number
@@ -781,7 +818,7 @@ function retry_policy(
 ): void
 ```
 
-The `retry_policy` function can called right after a `try`-`catch` block to specify a retry policy. See the section on retrying.
+The `retry_policy` function can called right after a `try`-`catch` block to specify a retry policy. See the section on [retrying errors](#retrying-on-errors).
 
 ## Source code comments
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts2workflows",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Transpile Typescript code to GCP Workflows programs",
   "homepage": "https://github.com/aajanki/ts2workflows",
   "repository": {
@@ -57,7 +57,7 @@
   ],
   "devDependencies": {
     "@eslint/js": "^9.10.0",
-    "@types/chai": "^4.3.16",
+    "@types/chai": "^5.0.1",
     "@types/mocha": "^10.0.6",
     "@types/node": "^18",
     "@typescript-eslint/eslint-plugin": "^8.0.0",

package/types/global.d.ts

@@ -10,7 +10,15 @@ declare global {
 
   var Symbol: SymbolConstructor
 
-  interface Iterator<T> {}
+  /**
+   * Iterator types copied from lib.es2015.iterable.d.ts
+   */
+  interface Iterator<T, TReturn = any, TNext = undefined> {
+    // NOTE: 'next' is defined using a tuple to ensure we report the correct assignability errors in all places.
+    next(...args: [] | [TNext]): IteratorResult<T, TReturn>
+    return?(value?: TReturn): IteratorResult<T, TReturn>
+    throw?(e?: any): IteratorResult<T, TReturn>
+  }
 
   interface Iterable<T> {
     [Symbol.iterator](): Iterator<T>