ts2workflows 0.5.0 → 0.7.0

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
 
@@ -561,7 +589,7 @@ parallel(
 )
 ```
 
-## Try/catch statements
+## Try/catch/finally statements
 
 The statement
 
@@ -592,13 +620,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 +672,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'
@@ -699,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'
@@ -766,11 +833,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 +846,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.5.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,25 +39,48 @@ 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(exception: unknown): void
-  export function default_retry_non_idempotent(exception: unknown): void
-  export function default_retry_predicate(exception: unknown): boolean
+  export function default_retry(errormap: Record<string, any>): void
+  export function default_retry_non_idempotent(
+    errormap: Record<string, any>,
+  ): void
+  export function default_retry_predicate(
+    errormap: Record<string, any>,
+  ): boolean
   export function default_retry_predicate_non_idempotent(
-    exception: unknown,
+    errormap: Record<string, any>,
   ): boolean
-  function _delete(
+  function _delete<ResponseType = unknown>(
     url: string,
     timeout?: number,
     body?: unknown,
@@ -68,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>,
@@ -84,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,
@@ -101,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,
@@ -118,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,
@@ -135,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,
@@ -153,7 +178,7 @@ export declare namespace http {
     private_service_name?: string,
     ca_certificate?: string,
   ): {
-    body: unknown
+    body: ResponseType
     code: number
     headers: Record<string, string>
   }
@@ -169,7 +194,8 @@ export declare namespace json {
       | boolean
       | unknown[]
       | Record<string, unknown>
-      | null,
+      | null
+      | undefined,
     indent?:
       | boolean
       | {
@@ -184,7 +210,8 @@ export declare namespace json {
       | boolean
       | unknown[]
       | Record<string, unknown>
-      | null,
+      | null
+      | undefined,
     indent?:
       | boolean
       | {
@@ -233,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,
@@ -342,7 +370,7 @@ export declare namespace googleapis {
       interface Document {
         createTime: string
         fields: Record<string, Value>
-        name: string
+        name?: string
         updateTime: string
       }
       interface DocumentMask {
@@ -553,7 +581,7 @@ export declare namespace googleapis {
         currentDocument?: Precondition
         delete?: string
         transform?: DocumentTransform
-        update?: Document
+        update?: Pick<Document, 'fields' | 'name'>
         updateMask?: DocumentMask
         updateTransforms?: FieldTransform[]
       }
@@ -622,7 +650,7 @@ export declare namespace googleapis {
             export function createDocument(
               collectionId: string,
               parent: string,
-              body: Document,
+              body: Pick<Document, 'fields' | 'name'>,
               documentId?: string,
               mask?: DocumentMask,
             ): Document
@@ -657,7 +685,7 @@ export declare namespace googleapis {
               currentDocument: Precondition,
               mask: DocumentMask,
               updateMask: DocumentMask,
-              body: Document,
+              body: Pick<Document, 'fields' | 'name'>,
             ): Document
             export function rollback(
               database: string,
@@ -709,16 +737,14 @@ export declare function parallel(
 
 export declare function retry_policy(
   params:
+    | ((errormap: Record<string, any>) => void)
     | {
-        policy: (exception: unknown) => void
-      }
-    | {
-        predicate: (exception: unknown) => boolean
-        max_retries: number
+        predicate?: (errormap: Record<string, any>) => boolean
+        max_retries?: number | string | null
         backoff: {
-          initial_delay: number
-          max_delay: number
-          multiplier: number
+          initial_delay?: number | string | null
+          max_delay?: number | string | null
+          multiplier?: number | string | null
         }
       },
 ): void