ts2workflows 0.6.0 → 0.7.0

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;AAgOD,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

@@ -149,6 +149,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 +165,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 +176,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 +332,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 +354,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.js

@@ -49,24 +49,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 +64,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/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.7.0",
   "description": "Transpile Typescript code to GCP Workflows programs",
   "homepage": "https://github.com/aajanki/ts2workflows",
   "repository": {
@@ -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",
@@ -78,4 +78,4 @@
     "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